Rules API

General Overview

VMware Secure State provides public APIs documented through a user-friendly Swagger interface for its customers to query configured rules and create new rules for configuring advanced integrations. Users can now build automation to ingest findings and rules details to combine with their internal or external tools.

API Overview

Through the VSS Rules API, users can retrieve rules, edit rules, create custom rules, and retrieve compliance frameworks and controls. Rule details including the rule name, description, suggested action, and documentation link are made available, providing users additional context on the findings. Rule creation allows users to monitor for custom security best practices using the VSS interconnected security model (ICSM).

Get Rules List

Users can view all the rules configured for their organization. curl -X GET \ https://api.securestate.vmware.com/v1/rules \ -H 'Authorization: Bearer {access_token}' \ Response Body: [{ "id": "5c8c...", "orgId": "039...", "name": "administrative-policy-exposed-by-connected-ssh-credential", "displayName": "An SSH key is shared by EC2 instances ...", "description": "An EC2 instance ...", "suggestedAction": "Change your instance ...", "documentationLink": "https://kb.securestate.vmware.com/...", "status": "Enabled", "type": "Violation", "source": "VSS Native", "category": "Security", "provider": "aws", "service": "ec2", "level": "High", "query": "...", "complianceControlIds": [ "12dcb380-f5bd-46cb-bb39-a968537e302b_pr.ac.4", "5f72c1c5-a819-4bcd-876c-05859188b3d4_3.1.6" ], "resources": [], "triggers": { "route_table_association": [ "true" ], ... }, "tags": null, "creationTime": 1564682229929, "lastUpdateTime": 1564682229929 }, ...]

Get Rule by Id

Users can view the details of a rule configured for their organization. Information such as the name of the rule, enabled status, suggested action for remediation, VSS Knowledge Base link, etc. is included to ensure users can understand and act on the associated rule violations. The source property denotes whether the rule is custom or native. curl -X GET \ https://api.securestate.vmware.com/v1/rules/{rule_id} \ -H 'Authorization: Bearer {access_token}' \ Response: Header: { "ETag": "19348..." } Body: { "id": "5c8c2...", "orgId": "039c2087-...", "name": "administrative-policy-exposed-by-connected-ssh-credential", "displayName": "An SSH key is shared by EC2 ...", "description": "An EC2 instance ...", "suggestedAction": "Change your instance configurations ...", "documentationLink":"https://kb.securestate.vmware.com/... ", "status": "Disabled", "type": "Violation", "source": "VSS Native", "category": "Security", "provider": "aws", "service": "ec2", "level": "High", "query": "...", "complianceControlIds": [ "12dcb380-f5bd-46cb-bb39-a968537e302b_pr.ac.4" ], "resources": null, "triggers": { ... }, "tags": null, "creationTime": 1564682229929, "lastUpdateTime": 1566233215730 }

Notice the complianceControlIds that provide the rule to compliance control mapping.

Update Rule by Id

Users can customize the rule set according to what’s suitable for their organization. Rule properties such as status (enabled or disabled), category, severity, tags, and resources can be configured. There are 2 steps involved in updating the rule. First, get the latest Rule by Id (described above) and extract the ETag value from the response header. Next, update the Rule with the desired properties while passing in the ETag value for the If-Match request header. curl -X PATCH \ https://api.securestate.vmware.com/v1/rules/5c8c25bb7a550e1fb6560b78 \ -H 'Authorization: Bearer {access_token}' \ -H 'If-Match: {ETag}' \ -d '{ "level": "Low" }' The following are the properties that can be updated: "status": "Disabled" "category": "Security" "level": "High" "tags": {"Key": "Value"} "resources": {"Resource_Link": "Name_of_Resource"} Note that up to 3 resource links can be added per rule. More details are in the Swagger docs.

Create a Rule

Users can author custom rules according to their internal security best practices. A rich custom rule authoring language is supported in Secure State in the form of the Gremlin graph query language.

A custom rule can be created through a single API call by providing all the rule details: name, description, suggested action, documentation link, status, type, source, category, provider, service, level, queries, linked compliance controls, and resources. The status can be set as “Enabled” or “Disabled” to turn ON the custom rule. Properties such as category, provider, service, etc. are used to organize the rule according to the cloud provider, service it evaluates for, and the kind of security vulnerability it checks for. Refer to the list of Rules in the platform for examples of these configurations. The level property defines the severity (High, Med, Low) of the rule that factors in with the risk score calculation. Other properties such as compliance control ids and documentation link are used to map to the relevant compliance controls and external documentation links respectively.

There are 2 main query components of a rule:

• A rule evaluation query passed in as the query property that runs on the resources monitored by VSS.

• A visualization query that is used to render the graph of resources that are violating. This is passed in as the visualizationQuery property and is used for displaying the UI render of violating resources.

Refer to the example below for a custom rule create API call. The passed in query checks for IAM keys that have not been rotated in the past 30 days.

curl -X POST \ https://api.securestate.vmware.com/v1/rules \ -H 'Authorization: Bearer {access_token}' \ -d '{ "orgId":"{Org Id}", "name":"rule-name", "displayName":"My Custom Rule", "description":"IAM key has not been rotated in the past 30 days", "suggestedAction":"suggested action for addressing findings for this rule", "documentationLink":"documentation link", "status":"Enabled", "type":"Violation", "source":"Custom", "category":"Security", "provider":"aws", "service":"iam", "level":"High", "query":"{\"inventoryQueryType\":\"Graph\",\"queryString\":\"g.V().has('\''entityType'\'', '\''AWS.IAM.User'\'').filter(outE('\''Contains'\'').inV().has('\''entityType'\'', '\''AWS.IAM.AccessKey'\'').has('\''property.Status'\'', eq('\''Inactive'\'')).has('\''property.AccessKeyLastUsedDate'\'', lt(datetime(relative(-30d)))))\"}", "inventoryProvider":"inventory-service", "visualizationQuery":"{\"inventoryQueryType\":\"Graph\",\"queryString\":\"g.V().<entity_id_clause>.outE().inV().tree()\"}", "complianceControlIds":null, "resources":null }'

Note: The displayName must not create spaces. It is suggested to use hyphens in place of spaces. Custom rule create is an advanced capability and requires understanding of the Gremlin query language and the schema of the modeled cloud resources.

Get Compliance Frameworks

Users can view all the compliance frameworks associated with the rules in Secure State. curl -X GET \ https://api.securestate.vmware.com/v1/compliance-frameworks \ -H 'Authorization: Bearer {access_token}' \ Response: { "totalCount": 9, "results": [ { "id": "07f5193c...", "name": "cis-azure-foundations-benchmark", "version": "1.0.0", "publicationDate": "2018-02-20", "author": "CIS", "description": "CIS Microsoft Azure Foundations", "url": "https://www.cisecurity.org", "creationTime": 1564521727413, "lastUpdateTime": 1564521727413 }, ...] }

Swagger Documentation

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