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 an API Key, follow the instructions provided in the 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 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"
}
]
}
}
}
}