Findings API

General Overview

VMware Secure State 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.

API Overview

Through the Secure State Findings APIs, users can 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.

Get All 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, a user simply needs to pass in the “continuation_token” 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

Filters on various properties including services, levels, cloud account ids, cloud tags, etc. can be defined.

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

Get Details of a Finding

You can also view all the details of a finding in order to make appropriate improvements in their configuration. Details of the finding including 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 Example: { "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

We have exposed an easy-to-use Swagger interface that documents and provides examples for utilizing our public APIs. The Swagger documentation can be found here: https://api.securestate.vmware.com/rules