Write GraphQL queries¶

GraphQL is a query language and runtime for APIs that enables you to request data. Instead of multiple REST endpoints, you use a single GraphQL endpoint to write expressive queries. For more on GraphQL fundamentals, see the documentation from GraphQL.org.

With ONEKEY, GraphQL is a powerful tool that allows you to interact directly with the platform’s API, perform advanced queries, and customize data extraction.

Getting Started¶

The complete schema is documented in the GraphQL schema documentation.

You can practice writing GraphQL queries by enabling the GraphQL console on the platform:

Click on your profile in the top-right corner:
Enable GraphQL console access.
Click GQL next to the Upload firmware button.

Writing Your First Query¶

A basic GraphQL query is structured as follows:

query {
  allFirmwares {
    id
    name
    version
  }
}

This will return a list of all firmware with their IDs, names, and versions.

Tip

Use Ctrl+Space to get auto-complete suggestions.

Response:

{
  "data": {
    "allFirmwares": [
      {
        "id": "204dac2f-070e-4008-9cb5-105788928y43",
        "name": "Gateway",
        "version": "3.0"
      },
      {
        "id": "faa6e8c4-ded7-42ae-bcf6-b58617e2bb56",
        "name": "Gateway",
        "version": "4.0"
      },
      {
        "id": "39bb3318-1bbb-4e96-9530-a95717f1eyxf",
        "name": "Gateway",
        "version": "5.0"
      }
    ]
  }
}

Nested Queries¶

GraphQL allows you to traverse relationships in a single query:

query {
  allFirmwares {
    name
    latestIssues {
      severity
      summary
      file {
        path
      }
    }
  }
}

This returns all security issues from the latest successful analysis, along with their severity, summary, and associated file path for all uploaded firmware.

Filters¶

ONEKEY's GraphQL API uses a filter system to narrow down query results. These are type-safe shortcuts for widely used queries with an easy-to-use syntax.

Filters are specified as follows:

query {
  firmware(id: "abc123") {
    components(filter: { tag: CRYPTOGRAPHY }) {
      name
      version
    }
  }
}

This returns only cryptographic component names and versions in the selected firmware.

You can also combine multiple criteria within a filter.

query {
  firmware(id: "abc123") {
    latestIssues(filter: {
      severity: CRITICAL
      confidence: HIGH
      status: {
        exclude: [FALSE_POSITIVE, ACCEPTED_RISK]
      }
    }) {
      id
      summary
      severity
    }
  }
}

Combined filters use AND logic, so this query returns only critical issues with a high confidence level, excluding false positives and accepted risks.

For a complete list of available filters and their parameters, see the GraphQL schema documentation. You can also use auto-complete (Ctrl+Space) to discover available filters as you write your queries.

ONEKEY Query Language (OQL)¶

For advanced querying beyond what filters provide, use ONEKEY Query Language (OQL).

query {
  allFirmwares(query: "uploader = \"user@example.com\"") {
    name
    uploadTime
  }
}

This returns all firmware uploaded by a specific user, along with the firmware names and upload times.

You can combine multiple conditions with keywords:

query {
  firmware(id: "abc123") {
    latestIssues(query: "severity = \"HIGH\" and file.path contains \"/bin/\"") {
      summary
      severity
      file {
        path
      }
    }
  }
}

This returns high-severity issues found in a specific firmware in files under the /bin/ directory.

For complete OQL syntax, see the OQL documentation.

Using Variables¶

GraphQL variables make queries reusable and safer by separating query structure from values. Declare variables in the query signature with $variableName: Type!, then use them in the query body with the $ prefix and pass their values separately as JSON.

query GetIssuesBySeverity($firmwareId: ID!, $minSeverity: Severity!) {
  firmware(id: $firmwareId) {
    latestIssues(filter: {
      severity: $minSeverity
    }) {
      id
      severity
      summary
    }
  }
}

Variables .json:

{
  "firmwareId": "abc123",
  "minSeverity": "HIGH"
}

Using Fragments¶

Fragments let you reuse common field selections. There are two types: named fragments and inline fragments.

Named Fragments¶

Define a fragment with fragment Name on Type { fields }, then use it in queries with ...FragmentName.

fragment CveDetails on CVEEntry {
  id
  name
  severity
  cvss3 {
    baseScore
    vector
    attackVector
  }
  cwes {
    id
    name
  }
}

query {
  firmware(id: "abc123") {
    cveMatches {
      score
      component {
        name
        version
      }
      cve {
        ...CveDetails
      }
    }
  }
}

Inline Fragments¶

Inline fragments are used directly in queries without prior definition to access type-specific fields on interfaces or unions. Use ... on TypeName when you need fields that only exist on specific implementations.

query {
  firmware(id: "abc123") {
    files {
      path
      name
      ... on RegularFile {
        size
        hash {
          sha256
        }
      }
    }
  }
}

Since File is an interface with multiple implementations (RegularFile, Directory, Symlink), inline fragments let you request fields like size and hash that only exist on RegularFile.

Using Directives¶

ONEKEY supports the standard GraphQL directives @include and @skip for conditional fields. Add @include(if: Boolean) to include a field only when true, or @skip(if: Boolean) to exclude it when true.

query {
  firmware(id: "abc123") {
    latestIssues {
      id
      severity
      summary
      file @include(if: true) {
        path
      }
    }
  }
}

Example queries¶

Finding Unresolved Critical Vulnerabilities¶

Search for CVEs that haven't been triaged yet and list some of their most important properties:

query {
  firmware(id: "abc123") {
    cveMatches(filter: {
      status: {
        include: [NONE, TRIAGE]
      }
    }) {
      id
      score
      component {
        name
        version
      }
      cve {
        id
        name
        severity
        cvss3 {
          baseScore
        }
      }
    }
  }
}

Auditing Configuration Files¶

Search for configuration files in common system directories:

query {
  firmware(id: "abc123") {
    files(filter: {
      path: {
        parentDirectory: "/etc"
      }
      name: {
        contains: "conf"
        caseSensitive: false
      }
    }) {
      path
      name
      ... on RegularFile {
        size
        hash {
          sha256
        }
      }
    }
  }
}

Checking Cryptographic Library Vulnerabilities¶

List cryptographic components with known vulnerabilities:

query {
  firmware(id: "abc123") {
    components(filter: {
      tag: CRYPTOGRAPHY
    }) {
      name
      version
      cveMatches(filter: {
        status: {
          exclude: [NOT_AFFECTED, FALSE_POSITIVE]
        }
      }) {
        cve {
          name
          severity
        }
      }
    }
  }
}

Limiting Results¶

For queries that may return large result sets, use the count parameter to limit the results:

query {
  allFirmwares(count: 10) {
    name
    uploadTime
  }
}

Tips and Best Practices¶

Use auto-complete - Press Ctrl+Space at any point in your query to see available fields, filters, arguments, and types. This helps you discover what's available and prevents syntax errors.
Request only what you need - GraphQL allows you to specify exactly which fields you want. Requesting fewer fields improves performance.
Use filters before OQL - Filters are optimized and type-safe. Use OQL only for complex queries that filters cannot express.
Combine filters - Multiple filter criteria use AND logic, making it easy to narrow results precisely.
Use variables for dynamic values - Variables make queries reusable and prevent injection issues.
Check permissions - Some fields require specific permissions. If a field returns null or an error, verify your user has the required permission.
Use the GraphQL Playground - ONEKEY provides an interactive GraphQL playground where you can explore the schema and test queries.