SysQL API

SysQL provides a powerful yet easy-to-use query language for interacting with the Sysdig Secure datastore. The SysQL public API enables you to execute standard SysQL statements and query resource metadata stored in the Sysdig Secure datastore. The API supports both GET and POST methods, primarily facilitating read-only operations for programmatic resource access. It processes SysQL statements provided either as URL query parameters or within a JSON document, executes them, and returns the results.

The SysQL public API supports the following operations:

Execute SysQL statements and get the results
Query the schema information about graph entities

For more information on using the SysQL statements, see the SysQL Reference Library.

API Endpoints

To execute a SysQL statement and retrieve the results, SysQL public API supports the following API endpoints:

GET /api/sysql/v2/query
POST /api/sysql/v2/query
GET /api/sysql/v2/schema

Prerequisites

Retrieve the Sysdig API Token from the Sysdig UI to use with the API
Identify the Sysdig domain associated with your region

GET Graph Resources

You can send a SysQL statement and retrieve the resource results using the /api/sysql/v2/query endpoint. Use GET method for simple queries where you can pass the parameters in the URL.

Request Body

GET /api/sysql/v2/schema

To authenticate the API request, set an Authorization header and provide a Bearer token:

curl -X GET -H 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>' https://<HOSTNAME>/api/sysql/v2/schema

Replace the following:

<SYSDIG_SECURE_API_TOKEN> with the token you retrieved
<HOSTNAME> with the Sysdig domain associated with your region

Query Parameters

Parameter	Description
`q` OR `query`	Required parameter Specifies the statement to execute. Include the SysQL statement in the URL query using either the `q` or `query` parameter, but not both simultaneously. If both are provided, a 400 Bad Request error will be returned.
`limit`	Optional parameter The `limit` parameter defines the maximum number of items returned in the result set, specifically within the `items` array in the response. The preferred and most idiomatic approach is to define the limit directly in the SysQL statement using the `LIMIT` clause. However, if you need to override the statement’s limit, you can specify it in the request URL, which will take precedence.
`offset`	Optional parameter The `offset` parameter determines the number of result set objects to skip in a `MATCH` statement. Use this parameter when you want to omit the first few items in the resulting `items` array. The preferred and most idiomatic approach is to specify the offset directly in the SysQL statement using the `OFFSET` clause. However, if you need to override the statement’s offset, you can specify it in the request URL, which will take precedence. You can use both the `limit` and `offset` parameters or clauses in SysQL to paginate results—splitting the result set into pages, each containing a specified number of items for display purposes.
`deterministic_order`	Optional parameter The deterministic_order parameter controls whether consistent ordering is enforced in the result set. Ordering is implicitly applied when pagination options, such as limit and offset, are specified in the request.

Sample Request

To get vulnerabilities with high CVSS Score and Severity, run the following query encoded in URL format:

curl -X GET -H 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>' https://<HOSTNAME>/api/sysql/v2/query?q=MATCH%20Vulnerability%20AS%20v%20RETURN%20v.name%20AS%20name%2C%20v.cvssScore%20AS%20cvssScore%2C%20v.severity%20AS%20severity%3B"| jq

Sample Response

If the execution is successful:

The response body contains an items JSON array with the requested data
An entities JSON map with metadata about the returned data

{
  "entities": {
    "name": {
      "type": "Field",
      "alias": "name",
      "definition": {
        "def_type": "Field",
        "name": "name",
        "type": "String",
        "hidden": false
      }
    },
    "cvssScore": {
      "type": "Field",
      "alias": "cvssScore",
      "definition": {
        "def_type": "Field",
        "name": "cvssScore",
        "type": "Float",
        "hidden": false
      }
    },
    "severity": {
      "type": "Field",
      "alias": "severity",
      "definition": {
        "def_type": "Field",
        "name": "severity",
        "type": "Enum",
        "hidden": false
      }
    }
  },
  "items": [
    {
      "severity": "Medium",
      "cvssScore": 7.5,
      "name": "CVE-2024-45491"
    },
    {
      "severity": "Medium",
      "name": "CVE-2024-45492",
      "cvssScore": 6.2
    }
  ]
}

Response Codes

The operation can return the following response codes:

HTTP Code	Description
200	The operation was successful.
400	Bad Request. The request cannot be processed for one of the following reasons: the statement contains a SysQL syntax error the request has a missing or unrecognized HTTP parameter the request is badly formatted — for example, the request body contains a JSON syntax error.
401	Unauthorized. The credentials provided with the request are missing or invalid.
408	Request Timeout. The execution of the SysQL statement exceeded the timeout period. The execution of the statement was cancelled.
422	The 422 error typically occurs due to issues in constructing the SysQL statement, preventing the server from executing the query and retrieving results from the data store.
429	Too Many Requests. The request rate has exceeded the allowed limit. The application must reduce the frequency of requests to the API endpoints and implement retry logic with backoff. Using exponentially jittered backoff is recommended. This response may also occur if the server receives an excessive number of concurrent requests. API concurrency limits are governed by the restrictions enforced by Sysdig.

POST Graph Resources

Use POST for larger and more complex queries in the request body. If you need to secure sensitive query parameters, use POST as it provides better security by keeping them out of the URL.

You can send a POST request to the /api/sysql/v2/query to retrieve the result .

Request Body

POST /api/sysql/v2/query

To authenticate the API request, set an Authorization header and provide a Bearer token:

curl -X POST -H 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>' https://<HOSTNAME>/api/sysql/v2/query

Replace the following:

<SYSDIG_SECURE_API_TOKEN> with the token you retrieved
<HOSTNAME> with the Sysdig domain associated with your region

Query Parameters

See Query Parameters.

Sample Request

Retrieve vulnerabilities in a Kubernetes workload that have exploits, ranked in descending order of high CVSS score:

curl -v -X POST "https://<HOSTNAME>/api/sysql/v1/query" \
  --header "content-type: application/json" \
  --header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>" \
  --data '{"query": "MATCH Vulnerability AS v AFFECTS KubeWorkload WHERE v.hasExploit = true and (v.cvssVersion = 1 or v.cvssScore > 7) RETURN v.customerId as customerId,v.name as name, v.cvssScore as cvssScore ORDER BY v.cvssScore DESC LIMIT 2;"}' \
  | jq

Replace the following:

<SYSDIG_SECURE_API_TOKEN> with the token you retrieved
<HOSTNAME> with the Sysdig domain associated with your region

Sample Response

If the execution is successful:

The response body contains an items JSON array with the requested data
An entities JSON map with metadata about the returned data

{
  "entities": {
    "customerId": {
      "type": "Field",
      "alias": "customerId",
      "definition": {
        "def_type": "Field",
        "name": "customerId",
        "type": "BigInt",
        "hidden": true
      }
    },
    "name": {
      "type": "Field",
      "alias": "name",
      "definition": {
        "def_type": "Field",
        "name": "name",
        "type": "String",
        "hidden": false
      }
    },
    "cvssScore": {
      "type": "Field",
      "alias": "cvssScore",
      "definition": {
        "def_type": "Field",
        "name": "cvssScore",
        "type": "Float",
        "hidden": false
      }
    }
  },
  "items": [
    {
      "customerId": 121517,
      "cvssScore": 10.0,
      "name": "CVE-2021-44228"
    },
    {
      "cvssScore": 9.9,
      "customerId": 121517,
      "name": "CVE-2024-41110"
    }
  ],
  "id": "06261436-4083-4d21-af4d-1611596971da",
  "summary": {
    "available_after": 65,
    "consumed_after": 6,
    "total_time": 73
  }
}

The sample schema response has been abbreviated due to its length.

Response Codes

See Response Codes.

GET Graph Resource Schema

You can send a GET request to the /api/sysql/v2/schema to retrieve the complete schema of the resources stored in the Graph database.

Request Body

GET /api/sysql/v2/schema

To authenticate the API request, set an Authorization header and provide a Bearer token:

curl -X POST -H 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>' https://<HOSTNAME>/api/sysql/v2/schema

Sample Response

A successful response provides a YAML document that fully represents the Graph schema of the resources, including entities, fields, and relationships.

A sample response is shown below:

index:
  - type: Entity
    name: KubeNode
    category: Kubernetes
    provider: Kubernetes
    description: A KubeNode represents a node in a Kubernetes cluster.
    fields:
      - name: category
        type: String
        description: The category of the node.
      - name: clusterName
        type: String
        description: The name of the cluster.
      - name: distribution
        type: String
      - name: externalDNS
        type: String
        description: The external DNS of the node.
      - name: isMaster
        type: Boolean
        description: Whether the node is a master node.
      - name: name
        type: String
        description: The name of the node.
      - name: operatingSystem
        type: String
        description: The operating system of the node.
      - name: osImage
        type: String
        description: The OS image of the node.
      - name: platform
        type: String
        description: The platform of the node.
      - name: type
        type: String
        description: The type of the node.
      - name: version
        type: String
        description: The version of the node.
    relationships:
      zones:
        entity: Zone
        relationship_name: IN
        display_name: With
        direction: out
      kubeClusters:
        entity: KubeCluster
        relationship_name: IN
        display_name: That Is In
        direction: out
      deployedOnCloudResource:
        entity: CloudResource
        relationship_name: DEPLOYED_ON
        display_name: That Is Deployed On
        direction: out
      regions:
        entity: Region
        relationship_name: IN
        display_name: That Is In
        direction: out
        is_virtual: true
        path:
          - deployedOnCloudResource
          - regions
...

Response Codes

The operation can return the following response codes:

HTTP Code	Description
200	The operation was successful.
401	Unauthorized. The credentials provided with the request are missing or invalid.
408	Request Timeout. The execution of the SysQL statement exceeded the timeout period. The execution of the statement was cancelled.
429	Too Many Requests. The request rate has exceeded the allowed limit. The application must reduce the frequency of requests to the API endpoints and implement retry logic with backoff. Using exponentially jittered backoff is recommended. This response may also occur if the server receives an excessive number of concurrent requests. API concurrency limits are governed by the restrictions enforced by Sysdig.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.