Retrieve & Search Findings

In this topic:

     

    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 bundles, 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 bundle 

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

    The request for the list of bundles 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 bundles and rules, and could be quite large. The id field is the bundle id.

    Next, use the bundle id with the Findings resource to retrieve findings for a rule in the bundle. 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, bundles, 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