Export Assets and Controls in CSV via SAFE APIs

About this document

This document explains the procedure for downloading the assets and controls in CSV via SAFE REST APIs.

Introduction

Downloading the Asset and Control in CSV via SAFE REST APIs has the following capabilities:

• Users can download the following CSVs:
  • List of assets and their associated details
  • List of controls associated with the Assets
  • Assets along with controls with a specific status (e.g. Accepted Failed, Failing, etc.)
• You can download details of up to 50K assets directly from the UI.
• You can download controls associated with these assets with an easy-to-use API functionality. Data can further be filtered as per your business requirements.
• Download CSV for All Assets or Assets for a particular vertical or asset group. Filters can further be applied for Assets Types, Criticality, Score, etc.
• You can apply all the filters supported on the UI, e.g. download only CA controls for the Assets or Controls in a specific status (e.g. Accepted Failed or Failed)
• You can download the Assets and Controls CSVs for a maximum of 2000 assets in one go (beyond this number, the size of the CSV becomes too heavy to use.
• If you wish to download all the data, we provide a sample function to run the API command in the loop.
• Actionable Insights at different levels (Inside out or specific verticals) will allow users to download the top 100 failing controls along with their list of impacted assets.

Use APIs to download the Assets and Controls in CSV

1. Go to the SAFE REST APIs as follows:
   1. Login in SAFE.
   2. Click the Help icon available at the top-right corner of the dashboard.
   3. Click the SAFE APIs option. The system opens the SAFE APIs in a new tab.
      
      For more details on SAFE APIs, refer to Accessing SAFE APIs.
2. Get the ID for the Vertical or Asset Group you wish to download the data for.
   1. Use <instance_url>/api/v3/groups with query param name=<group/vertical name>.
   2. Note down the id in response.
      
3. Use <instance_url>/api/v3/reportsAPI with the following body parameters:

   1. {
          "attackSurfaceType": "technology",  //Denotes for which attack surface type the report is mapped we are generating the report e.g. 'technology' or 'people'
          "password": "123",       //Password you want to set for zip file. Minimum 3 characters
          "reportAlias": "assetListWithControls", //Data the report should have
          "assetGroupId": 222,     //Optional; If defined generate report for assets of that group. Use the id noted in above step here
          "page": 2,               //Optional; Table page for which you want to download report. If not defined it generates report for first page
          "pagelen": 100,          //Optional; How many asset rows to be taken in report. Max 2000 allowed. If not defined it generates report for first 2000 assets
          "controlStatus": ["Qualified", "Failed"]. //Optional; What controls you want to download in report. If not defined it generates report for all CA & VA controls for selected assets
          "criteria" : [{"attribute": "assetType", "operator": "In", "value": [1]}]
                                   //Optional; Filters to be used to filter assets while generating report
          "matchCriteria": "MATCH_ALL"  //Required if criteria is defined. Supported values: MATCH_ALL & MATCH_ANY
      }

      
      
   2. When the API is called, it will trigger report generation in the background and you will get a UUID in response. Note down this UUID as this is a unique identifier of your report.
      
4. Next use <instance_url>/api/v3/reports/<reportUUID>/status to check if your report is generate. You can get the below generationStatusin the response:
   1. PENDING: This means that the generation has not yet started and your report is queued.
   2. IN PROGRESS: This means that the report generation is ongoing.
   3. FAILURE: The report generation failed due to some issues. You can re-trigger the report.
   4. COMPRESSION_IN_PROGRESS: This means the CSV is generated successfully and is getting compressed & encrypted.
   5. SUCCESS: This means that the report is generated successfully and you can use the signedUrl in the response to get the report.
      
5. In case you need all the data to be downloaded, the following commands can be used instead.
   1. You can use <instance_url>/api/v3/reports in the loop to generate the assets in batches of 2000. Every time the page value will have to be incremented by 1. 
   2. You can note down the reportUUID of each report in order to download the CSV using <instance_url>/api/v3/reports/<reportUUID>/status
6. We recommend you use filters to download data in sets of 2000 assets. But you can always use Page Numbers and #Rows per Page to download all the data.
7. You can use all the filters available in the SAFE UI asset list, such as:
   1. Filter control with status: [key: controlStatus, type: Array]
      1. Download assets with Controls information only falling in these control status
      2. Assets with no control matching the applied criteria will not come in the list
      3. Supported control status values: Not Assessed, Failed, Qualified, Not Applicable and  Accepted Failed.
   2. Filter assets by asset groups: [key: assetGroupId, type: number]
      1. AssetGroupIds can be fetched using /api/v3/groups API
   3. Filter assets [key: criteria, type: array of {"attribute": "", "operator": "", "value": ""}]
      1. Supported criteria attributes: assetType, technologyVertical, assetOwner, confidence, score, agentType, assetCriticality and lastAssessedDate
      2. Supported operators: In, Not In, Equals, Less Than, Greater Than, Between
      3. Note: If criteria are defined matchCriteriais required
         1. Supported values: MATCH_ALL and MATCH_ANY

List of supported criteria