Skip to content
GitHub

VECTR GraphQL API

You can use the VECTR GraphQL API to create precise and flexible queries for the data you need to integrate with VECTR.

Overview

Here are some quick links to get you up and running with the GraphQL API:

Authentication

To communicate with the GraphQL API, you'll need an API key. Follow the steps in "Create an API Key" to create an API Key.

The GraphQL Endpoint

Unlike the REST API, the GraphQL API has just a single endpoint:

https://<vectr_hostname>/sra-purpletools-rest/graphql

For example, using the default VECTR hostname:

https://sravectr.internal:8081/sra-purpletools-rest/graphql

The endpoint remains constant no matter what operation you perform.

Communicating with GraphQL

Because GraphQL operations consist of multiline JSON, we recommend using a GraphQL explorer such as GraphiQL to make GraphQL calls. You can also use any other HTTP library, GraphQL client library, or even cURL.

In GraphQL, you'll provide a JSON-encoded body using the HTTP POST method. The exception is when making an introspection query, which will use the GET method on the endpoint.

To query GraphQL, make a POST request with a JSON payload. The payload must contain a string called query. For example, using cURL:

curl -H "Authorization: VEC1 B41IHHZBJIAZMB5E10Q58C:+eHRa6h4byAMcHe1FQKLlnv/4h8=" -H "Content-Type: application/json" \
-d " \
 { \
   \"query\": \"testcases(db: \\\"DEMO_PURPLE\\\") { nodes { id, name }}\" \
 } \
" -X POST https://sravectr.internal:8081/sra-purpletools-rest/graphql

About Queries

GraphQL queries return only the data you specify. To form a query, you must specify fields (within fields if necessary) until the desired data is a scalar type. Scalars are primitive values: Int, Float, String, Boolean, or ID. View supported scalar types in the schema reference guide.

Each query must specify the environment name to query against. Provide the environment name to the db argument.

Queries are structured like this:

query {
  object(db: "the_environment_name") {
    JSON objects to return
  }
}

See real-world example queries below.

Query Examples

Query for a Single Object

query {
  testcase(id:"01c30e77-7687-4e86-8c2f-e85650f48ccd", db:"DEMO_PURPLE") {
    id, name
  }
}
curl -H "Authorization: VEC1 B41IHHZBJIAZMB5E10Q58C:+eHRa6h4byAMcHe1FQKLlnv/4h8=" \
-d '{"query":"{testcase(id: \"01c30e77-7687-4e86-8c2f-e85650f48ccd\", db: \"DEMO_PURPLE\") {id name}}"}' \
-X POST https://sravectr.internal:8081/sra-purpletools-rest/graphql
{
  "data": {
    "testcase": {
      "id": "01c30e77-7687-4e86-8c2f-e85650f48ccd",
      "name": "8 - Macro - LuckyStrike PowerShell CellEmbed"
    }
  }
}

Query with Pagination

query{
  testcases(db: "DEMO_PURPLE", first: 5, after: "100") {
    nodes {
      id, name
    },
    pageInfo { 
      endCursor, hasNextPage 
    }
  }
}
curl -H "Authorization: VEC1 B41IHHZBJIAZMB5E10Q58C:+eHRa6h4byAMcHe1FQKLlnv/4h8=" -H "Content-Type: application/json" \
-d 'query{ testcases(db: \"DEMO_PURPLE\", first: 5, after: \"100\") { nodes { id, name }, pageInfo { endCursor, hasNextPage } } }' \
-X POST https://sravectr.internal:8081/sra-purpletools-rest/graphql
{
  "data": {
    "testcases": {
      "nodes": [
        {
          "id": "01b28240-4428-4507-9915-e03778606ef4",
          "name": "17 - Link - Macro - LuckyStrike PowerShell CellEmbed + Sandbox Evasion"
        },
        {
          "id": "27a26f87-7a75-4d67-bddb-4f3076bd83d9",
          "name": "17 - Link - Macro - LuckyStrike PowerShell CellEmbed + Sandbox Evasion"
        },
        {
          "id": "60939556-3c04-431d-accc-a0f01fbb9619",
          "name": "17 - Link - Macro - LuckyStrike PowerShell CellEmbed + Sandbox Evasion"
        },
        {
          "id": "e0210589-c167-41fe-b5f6-82563c62ff2b",
          "name": "17 - Link - Macro - LuckyStrike PowerShell CellEmbed + Sandbox Evasion"
        },
        {
          "id": "f9cff386-3f75-474c-8673-9555d187c59a",
          "name": "17 - Link - Macro - LuckyStrike PowerShell CellEmbed + Sandbox Evasion"
        }
      ],
      "pageInfo": {
        "endCursor": "105",
        "hasNextPage": true
      }
    }
  }
}

Query with Variables

query CampaignsByIds($ids: [String]!) {
  campaignsByIds(db: "DEMO_PURPLE", ids: $ids) {
    nodes {
      id, name, testCases { id, name, mitreId, outcomes, createTime, updateTime }
    } 
  }
}
{
  "ids": [
    "51d244ad-0535-441d-a76e-6234f3559c9e",
    "c3d9f753-18e1-430d-9367-a07974e50c5a"
  ]
}
curl -H "Authorization: VEC1 B41IHHZBJIAZMB5E10Q58C:+eHRa6h4byAMcHe1FQKLlnv/4h8=" -H "Content-Type: application/json" \
-d '{"operationName":"CampaignsByIds","variables":{"ids":["51d244ad-0535-441d-a76e-6234f3559c9e","c3d9f753-18e1-430d-9367-a07974e50c5a"]},"query":"query CampaignsByIds($ids: [String]!) {campaignsByIds(ids: $ids, db: \"DEMO_PURPLE\") {nodes {id name testCases {id name mitreId outcomes createTime updateTime}}}}"}' \
-X POST https://sravectr.internal:8081/sra-purpletools-rest/graphql
{
  "data": {
    "campaignsByIds": {
      "nodes": [
        {
          "id": "51d244ad-0535-441d-a76e-6234f3559c9e",
          "name": "External Port Scans",
          "testCases": [
            {
              "id": "14e1a181-3b20-4a59-8fd4-8457e471eab2",
              "name": "External - Moderate Port Scan with 10 ports, service enumeration, and NSE's",
              "mitreId": "T1046",
              "outcomes": [
                "NotDetected"
              ],
              "createTime": 1548452014206,
              "updateTime": 1548757406350
            },
            ...          
          ]
        },
        {
          "id": "c3d9f753-18e1-430d-9367-a07974e50c5a",
          "name": "External Web App Profiling",
          "testCases": [
            {
              "id": "44083fd2-983c-4047-adfe-4a380da9819e",
              "name": "Directory Brute Force - Enterprise Portal",
              "mitreId": null,
              "outcomes": [
                "NotDetected"
              ],
              "createTime": 1509138281061,
              "updateTime": 1548755383809
            },
            ...          
          ]
        }
      ]
    }
  }
}

Complete Application Example

A complete python terminal application that demonstrates importing CSV data with the GraphQL API is available at https://github.com/SecurityRiskAdvisors/vectr-tools under vectr_tools/csv_import_example