This article illustrates how to use the CloudGuard Dome9 API to create a new compliance bundle and then run an assessment with it on a cloud account. This will use the Dome9 API CompliancePolicy and Assessment resources.
This example runs a single assessment. Use the ContinuousCompliancePolicy resource to run assessments continuously.
See also
Compliance
Continuous Compliance
Prerequisite steps
You will need the following information
- the GSL statements for the rules in the bundle
- the cloud account id to be assessed by the bundle (use the GET CloudAccounts method for this)
Create a Bundle
Use the CompliancePolicy method.
Request
POST https://api.dome9.com/v2/CompliancePolicy
This is an example of the request block.
{
"name":"Example Bundle",
"description":"Test bundle",
"rules":[
{
"name":"RDS storage should be encrypted",
"description":"You should encrypt your Amazon RDS instances and snapshots at rest by ena bling the encryption option for your Amazon RDS DB instance.",
"severity":"High",
"logic":"RDS should have isStorageEncrypted = 'true' and kmsKeyId",
"remediation":"Consider migrating your RDS to an at rest encrypted RDS; Follow AWS recommendations at: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html",
"complianceTag":"Encryption and Key Management"
}
],
"cloudVendor":"aws"
}
Parameters
Set these fields
name and (optionally) description of the bundle
For each rule:
name & (optionally) description of the rule
severity - the severity of the rule (High/Medium/Low)
logic - the GSL statement for the rule, as a text string
remediation - free text of the remediation instructions.
Ignore these parameters:
complianceTag, domain,priority, controlTitle, ruleId, id, logicHash
Response
This is an example of the response. The bundle id value (in the exampe above, 30263) is used to run assessments with the bundle.
{
"rules":[
{
"name":"RDS storage should be encrypted",
"severity":"High",
"logic":"RDS should have isStorageEncrypted = 'true' and kmsKeyId",
"description":"You should encrypt your Amazon RDS instances and snapshots at rest by enabling the encryption option for your Amazon RDS DB instance.",
"remediation":"Consider migrating your RDS to an at rest encrypted RDS; Follow AWS recommendations at: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html",
"complianceTag":"Encryption and Key Management",
"domain":"",
"priority":"",
"controlTitle":"",
"ruleId":"",
"logicHash":"HtVz32xiB0iFPv74rGyirg",
"isDefault":false
}
],
"accountId":*****,
"createdTime":"2018-08-20T05:00:38.2769723Z",
"updatedTime":"0001-01-01T00:00:00",
"id":30263,
"name":"Example Bundle",
"description":"Test bundle",
"isTemplate":false,
"hideInCompliance":false,
"minFeatureTier":"Premium",
"section":0,
"tooltipText":"",
"showBundle":true,
"systemBundle":false,
"cloudVendor":"aws",
"version":1,
"language":"en"
}
Code sample
curl -X POST https://api.dome9.com/v2/CompliancePolicy \
--basic -u <key-id>:<key-secret> \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-d '{
"name":"Example Bundle",
"description":"Test bundle",
"rules":[
{
"name":"RDS storage should be encrypted",
"description":"You should encrypt your Amazon RDS instances and snapshots at rest by ena bling the encryption option for your Amazon RDS DB instance.",
"severity":"High",
"logic":"RDS should have isStorageEncrypted = 'true' and kmsKeyId",
"remediation":"Consider migrating your RDS to an at rest encrypted RDS; Follow AWS recommendations at: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html",
"complianceTag":"Encryption and Key Management"
}
],
"cloudVendor":"aws"
} '
curl -X POST https://api.dome9.com/v2/CompliancePolicy \
--basic -u <key-id>:<key-secret> \
-H 'Content-Type: application/json' \
-H 'Accept: application/json
{
"name":"Example Bundle",
"description":"Test bundle",
"rules":[
{
"name":"RDS storage should be encrypted",
"description":"You should encrypt your Amazon RDS instances and snapshots at rest by enabling the encryption option for your Amazon RDS DB instance.",
"severity":"High",
"logic":"RDS should have isStorageEncrypted = 'true' and kmsKeyId",
"remediation":"Consider migrating your RDS to an at rest encrypted RDS; Follow AWS recommendations at: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html",
"complianceTag":"Encryption and Key Management"
}
],
"cloudVendor":"aws"
}
Run an Assessment with the bundle
Use the AssessmentBundleV2 method.
Request
POST https://api.dome9.com/v2/assessment/bundleV2
{
"id":30263,
"name":"Example Bundle",
"description":"Test bundle",
"isCft":false,
"dome9CloudAccountId":"********-****-****-****-************",
"externalCloudAccountId":"************",
"cloudAccountId":"************",
"region":"us_east_1",
"cloudAccountType":"Aws",
"requestId":"00000000-0000-0000-0000-000000000000"
}
Parameters
id - this is the bundle id, returned from the POST CompliancePolicy request, above (in this example, 30263)
dome9CloudAccountId - is the Dome9 acccount number (can be retrieved using the GET CloudAccounts)
externalCloudAccountId and cloudAccountId - these are both the cloud account id in the cloud provider (in this case, the AWS account id)
region - the region (in the cloud provider) to test the bundle, as a text string.
Response
The response shows the results of the tests (in this case, one test) when the bundle was run on the selected account and region. In this example, the test passed.
{
"request":{
"id":30263,
"name":"Example Bundle",
"description":"Test bundle",
"cft":null,
"isCft":false,
"dome9CloudAccountId":"********-****-****-****-************",
"externalCloudAccountId":"************",
"cloudAccountId":"************",
"region":"us_east_1",
"cloudNetwork":"string",
"cloudAccountType":"Aws",
"requestId":"85742614-360b-4b53-b51d-afe57acb41f5"
},
"tests":[
{
"error":null,
"testedCount":0,
"relevantCount":0,
"nonComplyingCount":0,
"entityResults":[
],
"rule":{
"name":"RDS storage should be encrypted",
"severity":"High",
"logic":"RDS should have isStorageEncrypted = 'true' and kmsKeyId",
"description":"You should encrypt your Amazon RDS instances and snapshots at rest by enabling the encryption option for your Amazon RDS DB instance.",
"remediation":"Consider migrating your RDS to an at rest encrypted RDS; Follow AWS recommendations at: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html",
"complianceTag":"Encryption and Key Management",
"domain":"",
"priority":"",
"controlTitle":"",
"ruleId":"",
"logicHash":"HtVz32xiB0iFPv74rGyirg",
"isDefault":false
},
"testPassed":true
}
],
"locationMetadata":{
"account":{
"srl":"",
"name":"AWS",
"id":"********-****-****-****-************",
"externalId":"************"
},
"region":{
"srl":"",
"name":"N. Virginia",
"id":"us_east_1",
"externalId":"us-east-1"
},
"cloudNetwork":{
"srl":"",
"name":"",
"id":"string",
"externalId":"string"
}
},
"testEntities":{
"rds":[
]
},
"assessmentPassed":true,
"hasErrors":false,
"id":35673387
}
Code sample
curl -X POST https://api.dome9.com/v2/assessment/bundleV2 \
--basic -u <key-id>:<key-secret> \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-d '
{
"id":30263,
"name":"Example Bundle",
"description":"Test bundle",
"isCft":false,
"dome9CloudAccountId":"********-****-****-****-************",
"externalCloudAccountId":"************",
"cloudAccountId":"************",
"region":"us_east_1",
"cloudAccountType":"Aws",
"requestId":"00000000-0000-0000-0000-000000000000"
}'
Python example
this Python script will run an assessment (identified by id) on a cloud account (identified by CloudAccountId).
import requests
import json
# Your API key
apiKey = "********-****-****-****-************"
# Your API secret
apiSecret = "************************"
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
body = {
"CloudAccountType": "Aws",
"CloudAccountId": "********-****-****-****-************",
"id": -15
}
r = requests.post('https://api.dome9.com/v2/assessment/bundleV2', data=json.dumps(body), headers = headers, auth=(apiKey, apiSecret))
print(r.status_code)
print(r.content)