Support Center > Search Results > SecureKnowledge Details
CloudGuard Dome9 Retrieve & Search Findings
Solution

This article illustrates how to use the Dome9 API to retrieve and search for findings. Findings are issues discovered in Compliance assessments, whether manually triggered, or continuously run. The Dome9 API has a resource, finding, to retrieve findings, according to rulesets, or other search parameters such as account, time, entity type, rule, etc.

Prerequisites

  • API Key & Secret, to access account using the API; the API uses Basic Authentication, where the key and secret are the user & password.

The examples below show different uses of the finding resource, to retrieve assessment findings.

Get Findings per ruleset

In this example, we will retrieve findings for a specific ruleset. First we will retrieve the list of all rulesets in the account. From this, we can obtain the ruleset id, which is used in the request for findings.

The request for the list of rulesets uses the CompliancePolicy resource.

Request

GET https://api.dome9.com/v2/CompliancePolicy

Response

[ 
{
"rules" : [ ]
"accountId": 7****,
"createdTime": "2018-08-20T05:00:38.276Z",
"updatedTime": "0001-01-01T00:00:00Z",
"id": 30263,
"name": "Bundle3",
"description": "",
"isTemplate": false,
"hideInCompliance": false,
"minFeatureTier": "Premium",
"section": 0,
"tooltipText": "",
"showBundle": true,
"systemBundle": false,
"cloudVendor": "aws",
"version": 1,
"language": "en"
},

The response contains all rulesets and rules, and could be quite large. The id field is the ruleset id.

Next, use the ruleset id with the Findings resource to retrieve findings for a rule in the ruleset. We will need to generate an MD5 hash of the rule GSL statement, which will serve as a rule id.

Page through all Findings (no search parameters)

In this example, we will retrieve all findings, paging through them with successive requests, using the pageSize and searchAfter fields.

Request

POST https://api.dome9.com/v2/Compliance/Finding/Search

Body

{  
"pageSize":20,
"filter":{
},
"searchAfter":[ ]
}

Parameters

Set these parameters in the request block:

pageSize - determines number of findings per response; if there are more findings than this in the response, they will be paged. The total number of findings in the response is given in the totalFindingsCount parameter in the response block; from this, you can determine how many pages of findings there are in the response.

searchAfter - is key to next set of findings, based on pageSize; use the value returned in one response in the next request, to retrieve the next page of findings. Repeat this to page through all the findings.

Response

The response will show the first page, from all the findings for the Dome9 account, across all cloud accounts, regions, rulesets, and cloud entities. The total number of findings could be very large, and as a consequence this request is very impractical.

 

 

 

 

 

click to expand

{  
"searchRequest":{
"pageSize":20,
"sorting":{
"fieldName":null,
"direction":0
},
"filter":{
"freeTextPhrase":null,
"fields":[ ],
"creationTime":{
"from":"0001-01-01T00:00:00",
"to":"2018-09-04T10:49:24.4992132Z"
}
},
"searchAfter":[ ]
},


"findings":

[ {
"id":"dfe63273-19c2-4ef5-b084-43faa89373a8",
"createdTime":"2018-09-04T10:28:49.3Z",
"updatedTime":"2018-09-04T10:28:54.7713788Z",
"cloudAccountType":"Aws",
"comments":[ ],
"cloudAccountId":"b*******-****-****-****-***********7",
"cloudAccountExternalId":"7**********6",
"bundleId":-13,
"ruleName":"Security Groups - with admin ports too exposed to the public internet",
"ruleLogic":"SecurityGroup should not have inboundRules with [scope = '0.0.0.0/0' and port in (20, 21, 22, 23, 115, 137, 138, 139, 2049, 3389)]",
"entityDome9Id":"3*****6",
"entityExternalId":"sg-0***************c",
"entityType":"securityGroup",
"entityName":"stage test",
"severity":"High",
"description":"Security groups provide stateful filtering of ingress/egress network traffic to AWS resources. It is recommended that no security group allows unrestricted ingress access to administrative ports ports.",
"remediation":"Delete any rules allowing unrestricted access to administrative ports - see Dome9 documentation on service related alerts: https://dome9-security.atlassian.net/wiki/spaces/DG/pages/71270411/Alerts.\nUse Dome9 Dynamic Access instead: https://dome9-security.atlassian.net/wiki/display/DG/Dynamic+Access+Leasing",
"tag":"NetworkSecurity",
"region":"Central",
"bundleName":"Dome9 AWS Dashboards",
"acknowledged":false,
"origin":"ComplianceEngine",
"ownerUserName":null
},

...
],
"totalFindingsCount":45851,
"aggregations":{
"severity":[ ],
"cloudAccountId_calc":[
{
"value":"1|b*******-****-****-****-***********7",
"count":7
}, ...
],
"acknowledged":[
{
"value":"false",
"count":45851
}
],
"entityType":[
{
"value":"securityGroup",
"count":4374
}, ...
],
"cloudAccountType":[
{
"value":1,
"count":45027
}
],
"origin":[
{
"value":"0",
"count":45851
}
],
"bundleName":[
{
"value":"Dome9 AWS Dashboards",
"count":157
},
...
],
"ownerUserName":[ ],
"region":[
{
"value":"Ohio",
"count":4701
},
...
]
},
"searchAfter":[
"1536056929300",
"dfe63273-19c2-4ef5-b084-43faa89373a8"
]
}

 

 

 

Use the searchAfter field, in the response, in the next request, to retrieve the next page. Repeat this to page through all the findings.

Request (2nd):

{  
"pageSize":20,
"filter":{
},
"searchAfter":[ "1536056929300",
"dfe63273-19c2-4ef5-b084-43faa89373a8"
]
}

Search for Findings with date range

In this example, the request will have a date/time range to limit the results to today's results.

The request block looks like this:

{  
"pageSize":20,
"filter":{
"creationTime":{
"from"
:"2018-09-04T00:00:00.0000000Z",
"to":"2018-09-04T23:59:59.9999999Z"
}
},
"searchAfter":[ ]
}

Search for Findings for a specific severity

In this example, we will add a search value in filter block, in addition to the time range, to retrieve findings with severity 'High'.

{  
"pageSize":20,
"filter":{
"fields":[
{
"name":"severity",
"value":"High"
}
],
"creationTime":{
"from":"2018-09-04T00:00:00.000Z",
"to":"2018-09-04T23:59:59.999Z"
}
},
"searchAfter":[ ]
}

Search for Findings with filter parameters

In this example, the findings will be filtered. The table below lists the fields that can be filtered, and the values that can be used. The fields and values are case sensitive. You can include a number of fields in a request block, in which case the response will be the findings matching all of the fields (that is, the logical AND of all of them).

Field Value
acknowledged true, false
entityType "securityGroup","iamPolicy",:"iamRole","subnet","networkInterface","instance","region", "vpc", "s3Bucket", "nacl", "iamUser","kms","vminstance", "elb", "elasticIP", "applicationLoadBalancer", "lambda", "ami", "cloudTrail", "iamGroup", "cloudFront", "route53RecordSetGroup","iam", "vpnGateway", "iamServerCertificate", "route53HostedZone","acmCertificate","list<cloudTrail>", "dynamoDbTable"
severity "High", "Medium", "Low"
bundleName  
region "N.Virginia", "Ohio", "Oregon", "us-east1", "us-east2","N. California", "Ireland", "Frankfurt","Central", "Paris", etc
ownerUserName  
cloudAccountType AWS - "1", GCP - "10", Azure - "7"
cloudAccountId_calc <vendor>|<account>, where <vendor>= 1 (AWS), 7 (Azure), or 10 (GCP), and <account> is the account id. Example - "1|8*******-****-****-****-***********1"

Examples

This request block will retrieve all findings related to Security Groups for a specific AWS account in the us-east1 region.

{  
"pageSize":20,
"filter":{
"fields":[
{
"name":"entityType",
"value":"securityGroup"
}
{
"name":"region",
"value":"us-east1"
}
{
"name":"cloudAccountType",
"value":"1|b*******-****-****-****-***********e"
}
],
},
"searchAfter":[ ]
}

Other parameters

Sort

Sort the findings in the response according to a specific field. The direction parameter is >= 0 for ascending, ,<0 for descending.

"sorting": {
    "fieldName": "severity",
    "direction": 1
  }

Date Range

Give us Feedback
Please rate this document
[1=Worst,5=Best]
Comment