Use the Findings Service API to gather information about security violations in VMware Aria Automation for Secure Clouds

VMware Aria Automation for Secure Clouds provides public Findings APIs documented through a user-friendly Swagger interface for its customers to query for violations and gather insights about connected threats. Users can build automation to ingest findings and rules details to combine with their internal or external tools.

Before you start

To perform the API calls described in this article, you need to have the following:

• A shell terminal with curl installed or an API development tool capable of making REST API calls, such as Postman.
• An API access token for the VMware Aria Automation for Secure Clouds platform.

API overview

You can use the Findings APIs to view violations, events, and anomalies detected in their cloud accounts. The APIs allow for powerful aggregations, filters, sorts, and searches that can be used for cloud resource inventorying, snapshotting, and reporting.

Query Findings

Users can easily view all the findings in their cloud accounts. This enables users to proactively resolve any violations in their cloud configuration and create detailed reports for internal tracking.

curl -X POST \
  https://api.securestate.vmware.com/v2/findings/query \
  -H 'Authorization: Bearer {access_token}' \
  -d '{}'

Response body

{
  "totalCount": 10414,
  "pageCount": 1000,
  "results": [
    {
      "id": "5c64...",
      "type": "violation",
      "ruleId": "5c6...",
      "cloudAccountId": "5c...",
      "cloudProvider": "AWS",
      "objectId": "arn:aws:cloudtrail:...",
      "objectXid": "161866044093_us-east-2_...",
      "service": "user",
      "region": "us-east-2",
      "level": "Medium",
      "creationTime": "2019-05-22T18:01:35Z",
      "lastUpdateTime": "2019-06-04T07:06:17Z",
      "riskScore": 40,
      "cloudTags": {},
      "status": "Open"
    },
    ...
      ],
  "continuationToken": "{continuation_token}"
}

To access the next set of pages, you must pass in the value from the continuationToken field to the query from the previous response.

curl -X POST \
  https://api.securestate.vmware.com/v2/findings/query \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
    "paginationInfo":{
    "continuationToken": "{continuation_token}",
    "pageSize": 1000
    }
}'

Filter, search, and aggregate findings

Users can filter, search, and aggregate on the findings in their cloud accounts. The API allows users to drill deeper into the findings to take appropriate action. Examples of these queries are provided below.

Filter query

You can define filters on various properties including services, levels, cloud account IDs, cloud tags, and so on.

curl -X POST \
  https://api.securestate.vmware.com/v2/findings/query \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
        "filters": {
        "services": ["service_name"],
        "Levels": ["High"]
        }
}'

Search query

Substring search on finding attributes is supported, enabling users to quickly scope to a certain subset of findings.

curl -X POST \
  https://api.securestate.vmware.com/v2/findings/query \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
        "filters": {
        "queryString": "search_string"
        }
    }'

Aggregation query

Powerful aggregations of findings can be created to understand a categorical breakdown of findings over certain findings attributes, such as level, service, and so on.

curl -X POST \
  https://api.securestate.vmware.com/v2/findings/query \
  -H 'Authorization: Bearer {access_token}' \
  -d '{
        "aggregations": {
        "rules": {
        "aggregationType": "Terms",
        "fieldName": "Level"
        }
    }
}'

Get finding details

You can also view all the details of a finding in order to make appropriate improvements in their configuration. Details of the finding include the violating object, associated rule, severity, cloud provider, status, and more are available.

curl -X GET \
  https://api.securestate.vmware.com/v2/findings/{findingId} \
  -H 'Authorization: Bearer {access_token}' \

Response body

{
    "id": "...",
    "type": "violation",
    "ruleId": "5c6...",
    "cloudAccountId": "5c5...",
    "cloudProvider": "AWS",
    "objectId": "arn:aws:cloudtrail:...",
    "objectXid": "16186...",
    "service": "cloudtrail",
    "region": "sa-east-1",
    "level": "Low",
    "creationTime": "2019-05-22T18:01:24Z",
    "lastUpdateTime": "2019-06-04T07:05:18Z",
    "riskScore": 10,
    "cloudTags": null,
    "completeBlob": "{...}",
    "status": "Open"
}

Swagger documentation

Refer to the Entity Data Service API Swagger documentation for interactive examples of these API calls.