Export Assets and Controls in CSV via SAFE APIs
  • 4 Minutes to read
  • PDF

Export Assets and Controls in CSV via SAFE APIs

  • PDF

About this document


This document explains the procedure to download 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.
      Accessing SAFE REST 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.
      Asset and Control CSV 1
  3. Use <instance_url>/api/v3/reportsAPI with the following body parameters:
    1. {
          "vector": "technology",  //Denotes for which vector we are generating the report
          "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": [0, 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.
      Asset and Control CSV 2
  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.
      Asset and Control CSV 3
  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

Filter Asset ByAttributeOperatorsValueSupported ValuesAPI to get attribute values

Asset Type

assetType

  1. In
  2. Equals
  1. Array of Asset Type ids
  2. Single Asset Type id

NA

api/v3/asset-types

Returns id for each asset types

Technology Vertical

technologyVertical

  1. In
  2. Equals
  1. Array of Asset Head ids
  2. Single Asset Head id

NA

NA

Asset Owner

assetOwner

  1. In
  2. Equals
  1. Array of Asset Owner ids
  2. Single Asset Owner id

NA

NA

Confidence

confidence

  1. In
  2. Equals
  1. Array of confidence values
  2. Single confidence value

Very High, High, Medium, Low & null

NA

Asset Score

score

  1. Greater Than
  2. Less Than
  3. Equals
  4. Between
  1. Number
  2. Number
  3. Number
  4. Array of two numbers

Range 0-5

NA

Agent Type

agentType

  1. In
  2. Equals
  1. Array of agent type ids
  2. Single agent type id

Agentless Id: 0

Agentbased Id: 1

Manual Id: -1

NA

Asset Criticality

assetCriticality

  1. In
  2. Equals
  1. Array of asset criticality ids
  2. Single asset criticality id

Critical: 1

High: 2

Medium-Low: 3

NA

Last Assessed Date

lastAssessedDate

  1. Greater Than
  2. Less Than
  3. Equals
  4. Between
  1. ISO string
  2. ISO string
  3. ISO string
  4. Array of ISO strings

NA

NA




Was this article helpful?