Query for Active and Public Hosts

This article provides an example demonstrating how to query for active hosts with public IP addresses using the BQL API. While this example focuses on a specific set of attributes, you can tailor the query to include the attributes that fit your needs. For more details on the BQL API, see the BQL API documentation.

Start the query

Send a POST request to start the query. This example retrieves active, critical-risk hosts that have public IP addresses, including a nested relationship projection for the host owners.

curl -X POST 'https://<your-brinqa-instance>/v1/api/bql' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey <your-api-token>' \
  -d '{
    "query": "FIND Host WHERE status = \"Active\" AND riskRating = \"Critical\" AND publicIpAddresses EXISTS",
    "returningFields": ["id", "baseRiskScore", "dataIntegrationTitles", "displayName", "firstSeen", "macAddresses", "openFindingCount", "os", "owners(emails, name)"],
    "limit": 10
  }'

note

Replace <your-brinqa-instance> with the URL of your Brinqa Platform and <your-api-token> with your API token.

The API returns a 202 Accepted response with a Location header:

HTTP/2 202
Location: /v1/api/bql/eyJqb2JI...
Retry-After: 2

Fetch results

Use the Location value from the previous response to poll for results:

curl 'https://<your-brinqa-instance>/v1/api/bql/eyJqb2JI...' \
  -H 'Authorization: ApiKey <your-api-token>'

If the query is still processing, the response has status "processing". Poll again after the number of seconds indicated in the Retry-After header. When the query completes, the response contains the matching hosts. Note how the owners relationship is returned as a nested array of objects:

{
  "status": "completed",
  "state": "success",
  "message": "Query completed successfully.",
  "results": [
    {
      "id": 1624846130314362889,
      "baseRiskScore": 10,
      "dataIntegrationTitles": ["Armis", "Crowdstrike", "Qualys VM", "ServiceNow"],
      "displayName": "QQNS9715.brinqa.com",
      "firstSeen": "2023-02-12T19:06:55.205Z",
      "macAddresses": ["B0:B1:36:1B:74:AF"],
      "openFindingCount": 52,
      "os": "Windows Server 2022",
      "owners": [
        { "emails": ["felipe.gould@example.com"], "name": "Felipe Gould" },
        { "emails": ["teodoro.gaboury@example.com"], "name": "Teodoro Gaboury" },
        { "emails": ["maryanne.whyman@example.com"], "name": "Maryanne Whyman" }
      ]
    },
    {
      "id": 1624846130314362896,
      "baseRiskScore": 10,
      "dataIntegrationTitles": ["Armis", "Crowdstrike", "Qualys VM", "ServiceNow"],
      "displayName": "EWRQ3377.brinqa.com",
      "firstSeen": "2023-02-12T19:06:55.247Z",
      "macAddresses": ["B9:49:3D:CE:13:16"],
      "openFindingCount": 38,
      "os": "Windows Server 2022",
      "owners": [
        { "emails": ["maryanne.whyman@example.com"], "name": "Maryanne Whyman" },
        { "emails": ["christa.bodenschatz@example.com"], "name": "Christa Bodenschatz" }
      ]
    }
  ],
  "totalRows": 2,
  "pageRows": 2,
  "cursor": null
}