Skip to content

Using the GraphQL API

BoostSecurity supports GraphQL APIs for accessing the various data from your account programmatically.

Note that the specific data can be accessed through various specialized services in the BoostSecurity backend. Each service exposes a GraphQL API for querying and mutating the specific data for that service. For example, account-wide summary data over a period of time can be accessed through the Analytics service. Eventually, these service-specific GraphQL APIs will be replaced with a single GraphQL API that will unify all these services GraphQL APIs into one.

To leverage the GraphQL API, an API key can be used. Once the key is created, it can be used to access the API.

Getting an API Key

The first step in using the GraphQL API is to get an API Key. Once the API Key is obtained, it can be used in the GrapQL API calls to get data from the system. To get your API Key, navigate to the Application Keys page and select the API Key.

Accessing the GraphQL API

The API Key created in section Getting and API key, is provided with the Authorization header in order to authenticate the request to the server. The realmApiKey must be used with the Authorization header, when providing the API Key.

As such:

Authorization: ApiKey <api key>

The schema can be obtained from the GraphQL API, for example:

POST /analytics/graphql HTTP/1.1
Authorization: ApiKey <api_key>
Content-type: application/json
Accept: application/json
Content-Length: <length>

{
    "query":"{
        __schema {
            queryType {
                fields {
                    name
                }
            }
            mutationType {
                fields {
                    name
                }
            }
        }
    }",
    "variables":{}
}

Which returns:

{
    "data": {
        "__schema": {
            "queryType": {
                "fields": [
                    {
                        "name": "insights"
                    },
                    {
                        "name": "projectsPosture"
                    }
                ]
            },
            "mutationType": null
        }
    }
}

Example using analytics API

For example, in order to get daily activities from the analytics service, between 2022-12-01 and 2022-12-03:

query(
    $from_day: Date
    $to_day: Date
    $scannerIdsFilter: [String!]
    $assetIdsFilter: [String!]
    $max_rules: Int
){
    insights(
        fromDay: $from_day,
        toDay: $to_day,
        maxRules: $max_rules,
        filters: {
            scannerIds:$scannerIdsFilter
            assetIds:$assetIdsFilter
        }
    ) {
        dailyMetric {
            timeStamp,
            violations,
            findings
        }
        dailyActivity {
            timeStamp,
            fixedViolations,
            mergedViolations
        }
        summary {
            findings {
                previous
                current
            }
        violations {
            previous
            current
        }
        fixes
        mergedViolations
    }
  }
}

with variables:
{
    "from_day":"2022-12-01",
    "to_day":"2022-12-03",
    "scannerIdsFilter":[],
    "assetIdsFilter":[]
}

Which would return:

{
  "data": {
    "insights": {
      "dailyMetric": [
        {
          "timeStamp": "2022-12-01T00:00:00",
          "violations": 397,
          "findings": 104
        },
        {
          "timeStamp": "2022-12-02T00:00:00",
          "violations": 397,
          "findings": 104
        },
        {
          "timeStamp": "2022-12-03T00:00:00",
          "violations": 397,
          "findings": 104
        }
      ],
      "dailyActivity": [
        {
          "timeStamp": "2022-12-01T00:00:00",
          "fixedViolations": 0,
          "mergedViolations": 0
        },
        {
          "timeStamp": "2022-12-02T00:00:00",
          "fixedViolations": 0,
          "mergedViolations": 0
        },
        {
          "timeStamp": "2022-12-03T00:00:00",
          "fixedViolations": 0,
          "mergedViolations": 0
        }
      ],
      "summary": {
        "findings": {
          "previous": 104,
          "current": 104
        },
        "violations": {
          "previous": 397,
          "current": 397
        },
        "fixes": 0,
        "mergedViolations": 0
      },
      "filters": {
        "scannerId": [
          {
            "value": "boostsecurityio/codeql",
            "displayValue": "Boost CodeQL"
          },
          ...
        ],
        "assetId": [
          {
            "value": "...<some uuid value>...",
            "displayValue": "acme-storesrus"
          },
          {
            "value": "...<some other uuid value>...",
            "displayValue": "acme-storesrus / account-management"
          },
          {
            "value": "...<some other uuid value>...",
            "displayValue": "acme-storesrus / cart-service"
          },
          {
            "value": "...<some other uuid value>...",
            "displayValue": "acme-storesrus / fidelity-service"
          },
          {
            "value": "...<some other uuid value>...",
            "displayValue": "acme-storesrus / inventory-service"
          },
          {
            "value": "...<some other uuid value>...",
            "displayValue": "acme-storesrus / payment-service"
          },
          {
            "value": "...<some other uuid value>...",
            "displayValue": "acme-storesrus / services-analytics"
          }
        ]
      }
    }
  }
}