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=" -X POST -d " \
 { \
   \"query\": \"testcases(db: \\\"DEMO_PURPLE\\\") { nodes { id, name }}\" \
 } \
" 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 database name to query against. Provide the database name to the db argument.

Queries are structured like this:

query {
  object(db: "the_database_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 Request

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

Response

{
  "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 Request

curl -H "Authorization: VEC1 B41IHHZBJIAZMB5E10Q58C:+eHRa6h4byAMcHe1FQKLlnv/4h8=" -X POST \
-d 'query{ testcases(db: \"DEMO_PURPLE\", first: 5, after: \"100\") { nodes { id, name }, pageInfo { endCursor, hasNextPage } } }' \
https://sravectr.internal:8081/sra-purpletools-rest/graphql

Response

{
  "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 }
    } 
  }
}

Variables

{
  "ids": [
    "51d244ad-0535-441d-a76e-6234f3559c9e",
    "c3d9f753-18e1-430d-9367-a07974e50c5a"
  ]
}

cURL Request

curl -H "Authorization: VEC1 B41IHHZBJIAZMB5E10Q58C:+eHRa6h4byAMcHe1FQKLlnv/4h8=" -X POST \
-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}}}}"}' \
https://sravectr.internal:8081/sra-purpletools-rest/graphql

Response

{
  "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
            },
            ...          
          ]
        }
      ]
    }
  }
}

Schema Reference

View the reference documentation to learn about the data types available in the VECTR GraphQL API schema.