Skip to content

Using the GraphQL API

Boostsecurity supports GraphQL APIs for accessing the various data from your account, programatically. 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 API will be replaced with a single GraphQL API that will unify all these services GraphQL APIs into one.

In order 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 an API Key, follow the instructions provided in section Getting an application 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 realm ApiKey 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"
          }
        ]
      }
    }
  }
}