Use the Rules Service API to manage existing rules and create new ones in VMware Aria Automation for Secure Clouds

VMware Aria Automation for Secure Clouds 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.

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

Through the Rules Service 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 VMware Aria Automation for Secure Clouds interconnected security model (ICSM).

Get rules list

Use this command to view all the rules configured for your 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, knowledge base link, and so on. 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..."
}

Response 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:

Get the latest rule by ID (described above) and extract the ETag value from the response header.
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 properties can be updated:

"status": "Disabled"
    "category": "Security"
    "level": "High"
    "tags": {"Key": "Value"}
    "resources": {"Resource_Link": "Name_of_Resource"}

Note that up to three 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. VMware Aria Automation for Secure Clouds supports a rich custom rule authoring language through a 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
Resources

The status can be set as Enabled or Disabled to activate the custom rule. Properties such as category, provider, service, and so on 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 two main query components of a rule:

A rule evaluation query passed in as the query property that runs on the resources monitored by VMware Aria Automation for Secure Clouds.
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 VMware Aria Automation for Secure Clouds.

curl -X GET \
  https://api.securestate.vmware.com/v1/compliance-frameworks \
  -H 'Authorization: Bearer {access_token}' \

Body 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

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