API Documentation

Threatrix GraphQL API provides fast and efficient queries to access your data.

Graphql

More details about GraphQL are available here: https://graphql.org/learn/queries/

GraphQL API Endpoint

Threatrix cloud graphQL API is available at https://app.threatrix.io/graphql

Hybrid GraphQL API is available at {HYBRID_SERVER}/graphql

Create Organization Account

This mutation allows you to create a user and organization through the API. The response to the mutation will include a temporary JWT token that can be used to request organization or entity data and may also be used to create service tokens for use by your application to access the GraphQL API.

type: mutation

mutation NewAccountMutation($formAccountRequest: FormAccountRequestInput) {
    createAccount(formAccountRequest: $formAccountRequest) {
      jwt,
      user {
          username,
          enabled,
          credentialsNonExpired,
          accountNonExpired,
          accountNonLocked
      }
    }
}

Typescript example

createAccount(email: string, fullName: string, phone: string, password: string,
              companyName: string, position: string, coverLetter: string, inviteHash: string): Observable<AuthenticationResponse> {
  const formAccountRequest = new FormAccountRequest(email, fullName, phone, password, companyName, position, coverLetter, inviteHash);
  return this.coreGraphQLService
    .coreGQLReqForMutation<AccountCreateMutation>(gql(`mutation NewAccountMutation($formAccountRequest: FormAccountRequestInput) {
createAccount(formAccountRequest: $formAccountRequest) {
  jwt,
  user {
      username,
      enabled,
      credentialsNonExpired,
      accountNonExpired,
      accountNonLocked
  }
}
    }`), { formAccountRequest })
    .pipe(
      map(
        response => {
          this.authService.setInSessionStorageBasedEnv('jwt', response.data.createAccount.jwt);
          this.authService.setCurrentUser(response.data.createAccount.user);
          this.cookieService.delete('invite');

          return response.data.createAccount;
        },
        (error: any) => {
          console.error(`AUTH SERVICE ERROR: ${error}`);
        }
      )
    );

Create User Account

Create a new user account which will generate a welcome email for this user with a link to login.

mutation createUser($user: UserRequestInput) {
  createUser(user: $user) {
    orgId
    username
    email
    fname
    lname
    userRoles {
      roleId
      description
      permissions
    }
    permissions
  }
}
variables {
  "user": {
    "email": "[email protected]",
    "fname": "Firstname",
    "lname": "Lastname",
    "entities": [
      "0c71285d-af50-4dea-81bb-50c328b69f5c"
    ],
    "roles": [
      "ROLE_USER"
    ],
    "permissions": [],
    "defaultEntityId": "0c71285d-af50-4dea-81bb-50c328b69f5c",
    "hostUrl": "https://app.threatrix.io"
  }
}

Remove User Account

Remove an existing user account

mutation deleteUser($username: String) {
  deleteUser(username: $username)
}
varaibles {
  "username": "[email protected]"
}

Create Service Token

Service tokens are JWTs that can be used to access to the Threatrix API from external services. They can be configured with a description, expiration date and, if necessary, custom roles to suit the purpose of the token.

mutation ($apiKeyRequest: ApiKeyRequestInput) {
  generateApiKey(apiKeyRequest: $apiKeyRequest) {
    keyId
    apiKey
  }
}

Typescript example ApiKey Class

export class ApiKey {
  orgId: string;
  username: string;
  keyId: string;
  apiKey: string;
  title: string;
  description: string;
  createdDate: Date;
  expiredDate: Date;
  roleIds: string[];
  permissions: string[];
}

Request Generated Service Key

This query is only necessary if you did not include the apiKey column in the Create Service Token query.

query {
    apiKey(username: "${username}", keyId: "${keyId}") {
        apiKey,
        username,
        keyId,
        title,
        description,
        createdDate,
        expiredDate
        roleIds
        permissions
    }
}

Add Github Personal Access Token

This query adds a Github personal access token to the account which grants Threatrix the appropriate permissions to access Github repositories for scanning and scan setup.

mutation {
    setRepositoryAccount(token: "${token}" , type: "github") {
        accountName,
        type,
        accessToken
    }
}

List GitHub accounts

Use this query to retrieve a list of both User and Organization Github accounts for which the user has access rights.

query {
    githubUserAndOrgs {
        id
        avatarUrl
        name
        login
        organizations {
            totalCount
            edges {
                node {
                    id
                    name
                    login
                    avatarUrl
                }
            }
        }
    }
}

List GitHub User repositories

Use this query to retrieve a list of available repositories for the Github user account

 query {
    githubUserRepos {            
        repositories {
            edges {
                node {            
                    id,
                    name,
                    archived,
                    fork,
                    private,
                    resourcePath,
                    sshUrl,
                    url,
                    primaryLanguage{
                        color,
                        name
                    },
                    defaultBranchRef {
                        name
                    }
                    refs {
                        totalCount
                        edges {
                            node {
                                ... on Ref {
                                    id
                                    name
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

List GitHub Organization Repositories

Use this query to retrieve a list of available repositories for the GitHub organization account to which the user has access rights. The login must be provided

query {
    githubOrgRepos(login: "${login}") {
        repositories {
            edges {
                node {            
                    id,
                    name,
                    archived,
                    fork,
                    private,
                    resourcePath,
                    sshUrl,
                    url,
                    primaryLanguage{
                        color,
                        name
                    },
                    defaultBranchRef {
                        name
                    }
                    refs {
                        totalCount
                        edges {
                            node {
                                ... on Ref {
                                    id
                                    name
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Create GitHub Action workflow for the repository

User this query to create the workflow in GitHub necessary to run scans based on a GitHub workflow event(Pull Request, Push or Manual)

query {
  createScanWorkflow(
    appName: "${scanWorkflowRequest.appName}", 
    repoUrl: "${scanWorkflowRequest.repoUrl}", 
    repoOwner: "${scanWorkflowRequest.repoOwner}", 
    repository: "${scanWorkflowRequest.repository}", 
    branch: "${scanWorkflowRequest.branch}", 
    repoType: "${scanWorkflowRequest.repoType}", 
    entityId: "${scanWorkflowRequest.entityId}", 
    triggerEvent: [${scanWorkflowRequest.triggerEvent}],
    trxUrl: "${scanWorkflowRequest.trxUrl}"
    ) {
      appName,
      errorMessage,
      success,
      owner,
      repository,
      secretCreated
    }
}

Project List

Get a list of projects for the given entity

query {
  entity(entityId: "74d55ca6-8cd5-4782-85c2-66165d6992bf") {
    projects {
      
      edges {
        node {
          projectId
          name
          created
          tags

          latestScan {
            created
          }

          projectMetricsSummaryComposite {
            measureDateTime
            vulnerabilityMetrics {
              critical
              high
              medium
              low
              info
            }
            licenseMetrics {
              copyleftStrong
              copyleftWeak
              copyleftPartial
              copyleftLimited
              copyleft
              custom
              dual
              permissive
              proprietary
              proprietaryFree
            }
            supplyChainMetrics {
              risk
              quality
            }
            assetMetrics {
              embedded
              openSource
              unique
            }
            componentCountMetrics {
              totalCount
              riskyLicenses
              vulnerableComponents
            }
          }
        }
      }
    }
  }
}

Project Summary

This query provides project summary data as displayed at the top of your project as illustrated in the image below

{
  project(projectId: "{PROJECTID}") {
    projectId
    parentProjectId
    entityId
    orgId
    name
    scans {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          scanId
          projectId
          branch
          tag
          version
          versionHash
          created
          status
          errorMsg
          log
          components {
            totalCount
          }
          scanMetricsSummary(isComposite: true) {
            vulnerabilityMetrics {
              critical
              high
              medium
              low
              info
            }
            licenseMetrics {
              copyleftStrong
              copyleftWeak
              copyleftPartial
              copyleftLimited
              copyleft
              custom
              dual
              permissive
            }
            supplyChainMetrics {
              risk
              quality
            }
            assetMetrics {
              embedded
              openSource
              unique
            }
          }
        }
      }
    }
    projectMetricsGroup {
      projectMetrics {
        measureDate
        vulnerabilityMetrics {
          severityMetrics
        }
        assetMetrics {
          assetCompositionMetrics
        }
        componentMetrics {
          vulnerabilityMetrics
          licenseCategoryMetrics
          licenseFamilyMetrics
          licenseNameMetrics
        }
        licenseMetrics {
          licenseCategoryMetrics
          licenseFamilyMetrics
          licenseNameMetrics
        }
        supplyChainMetrics {
          supplyChainMetrics
        }
      }
    }
  }
}

Components

Returns an unpaged list of components for the requested scan ID, limited to 1000 results

query {
  scan(scanId: "{SCANID}") {
    scanId
    components(isComposite: true first: 1000) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          componentId
          name
          group
          version
          isInternal
          lastInheritedRiskScore
          componentType
          componentLocation
          componentDiscoveryMethod
          dependencyManagerType
          workspaceRelativeFilePath
          licenses {
            edges {
              node {
                licenseId
                name
                category
              }
            }
          }
          resolvedLicense {
            licenseId
            name
          }
          vulnerabilities {
            edges {
              node {
                vulnerabilityId
                vulnId
                severity
                patchedVersions
              }
            }
          }
          metrics {
            critical
            high
            medium
            low
            unassigned
            vulnerabilities
            suppressed
            findingsTotal
            findingsAudited
            findingsUnaudited
            inheritedRiskScore
            firstOccurrence
            lastOccurrence
          }
        }
      }
    }
  }
}

Vulnerabilities

Returns an unpaged list of vulnerabilities for the requested scan ID, limited to 1000 results

query {
  scan(scanId: "{SCANID}") {
    scanId
    isScmActionsAvailableForScan
    vulnerabilities(isComposite: true first: 1000) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          components {
            edges {
              node {
                group
                name
                version
                componentId
              }
            }
          }
          vulnerabilityId
          vulnId
          source
          recommendation
          vulnerableVersions
          patchedVersions
          published
          cwe {
            cweId
            name
          }
          cvssV2BaseScore
          cvssV3BaseScore
          severity
        }
      }
    }
  }
}

Licenses

Returns an unpaged list of licenses for the requested scan ID, limited to 1000 results

query {
  scan(scanId: "{SCANID}") {
    scanId
    repositoryId
    isScmActionsAvailableForScan
    licenses(isComposite: true first: 1000) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          licenseId
          spdxId
          name
          category
          style
          type
          spdxId
          publicationYear
          isOsiApproved
          isFsfLibre
          licenseDiscovery
          licenseOrigin
          trustLevel
          licenseAssetAttribution {
            attributionStatus
            attributedDate
            attributedBy
            attributedComment
          }
        }
      }
    }
  }
}

License Components

Returns a list of components associated with the license

query{
  scanLicense(
    projectId: "{PROJECT_ID}"
    scanId: "{SCAN_ID}"
    licenseId: "{LICENSE_ID}"
    licenseDiscovery: "DECLARED"
    licenseOrigin: "COMPONENT"
    isComposite: true
  ) {
    orgId
    licenseOrigin
    licenseDiscovery
    license {
      licenseId
      name
      spdxId
      body
      category
      style
      type
      publicationYear
      description
      notes
      isOsiApproved
      isFsfLibre
      isDeprecated
      compatible
      incompatible
      attributes {
        name
        type
        description
      }
    }
    scanComponents(
      first: 100
      projectId: "{PROJECT_ID}"
      isComposite: true
    ) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          componentId
          name
          group
          version
          isInternal
          lastInheritedRiskScore
          componentLocation
          componentDiscoveryMethod
        }
      }
    }
  }
}

Assets (root)

Returns an unpaged list of project root (no parent folder) scan assets for the requested scan ID, limited to 1000 results

query {
  scan(scanId: "{SCANID}") {
    scanId
    scanOpenSourceProject {
      owner
      name
      repoWebsite
    }
    scanAssetsTree(isComposite: true first: 1000) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          orgId
          name
          size
          assetSize
          projectId
          scanAssetId
          originAssetId
          workspacePath
          status
          scanAssetType
          parentScanAssetId
          attributionStatus
          matchType
          percentEmbedded
          averagePercentCopied
          matchCount
          otCount
          component {
            componentId
            name
            group
            version
            isInternal
            cpe
            description
            usedBy
          }
        }
      }
    }
  }
}

Assets (parent)

Returns an unpaged list of project assets associated with provided parent folder for the requested scan ID, limited to 1000 results

graquery {
  scan(scanId: "{SCANID}") {
    scanId
    scanOpenSourceProject {
      owner
      name
      repoWebsite
    }
    scanAssetsTree(isComposite: true,  parentScanAssetId: "{PARENT_SCAN_ASSET_ID}" first: 1000) {
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
      edges {
        node {
          orgId
          name
          size
          assetSize
          projectId
          scanAssetId
          originAssetId
          workspacePath
          status
          scanAssetType
          parentScanAssetId
          attributionStatus
          matchType
          percentEmbedded
          averagePercentCopied
          matchCount
          otCount
          component {
            componentId
            name
            group
            version
            isInternal
            cpe
            description
            usedBy
          }
        }
      }
    }
  }
}

Reports

CodeCertify Reports

CodeCertify SPDX 2.2

Returns an SPDX version 2.2 report for the modules included in the projectIdToScanIdMap

Query

query SupplyChainDashboardSpdxV22SbomReport(
  $entityId: UUID
  $projectIdToScanIdMap: Map_UUID_UUIDScalar
) {
  supplyChainDashboardSpdxV22SbomReport(
    entityId: $entityId
    projectIdToScanIdMap: $projectIdToScanIdMap
  ) {
    data
  }
}

Variables

query SupplyChainDashboardCycloneDxSbomReport($entityId: UUID, $projectIdToScanIdMap: Map_UUID_UUIDScalar) {
  supplyChainDashboardCycloneDxSbomReport(
    entityId: $entityId
    projectIdToScanIdMap: $projectIdToScanIdMap
  ) {
    data
  }
}

GraphQL

Variables

{
  "entityId": "60266a1b-0168-4db5-9893-46e92bc7c1b5"
  "projectIdToScanIdMap": {
    "54c0171b-492e-4f7c-b9e2-5983afda9f00": "706737e6-1aeb-4d83-a1f5-76abc2b96df3"
  }
}

• entityId here is CodeCertify project ID

• projectIdToScanIdMap - map of module id - module scan id (optional)

query {
  "entityId": "60266a1b-0168-4db5-9893-46e92bc7c1b5"
  "projectIdToScanIdMap": {
    "54c0171b-492e-4f7c-b9e2-5983afda9f00": "706737e6-1aeb-4d83-a1f5-76abc2b96df3"
  }
}

CodeCertify SPDX 2.3

Returns an SPDX version 2.3 report for the modules included in the projectIdToScanIdMap

Query

query SupplyChainDashboardSpdxV23SbomReport($entityId: UUID, $projectIdToScanIdMap: Map_UUID_UUIDScalar) {
  supplyChainDashboardSpdxV23SbomReport(
    entityId: $entityId
    projectIdToScanIdMap: $projectIdToScanIdMap
  ) {
    data
  }
}

Variables

• entityId here is CodeCertify project ID

• projectIdToScanIdMap - map of module id - module scan id (optional)

{
  "entityId": "60266a1b-0168-4db5-9893-46e92bc7c1b5"
  "projectIdToScanIdMap": {
    "54c0171b-492e-4f7c-b9e2-5983afda9f00": "706737e6-1aeb-4d83-a1f5-76abc2b96df3"
  }
}

CodeCertify CycloneDX SBOM

Returns a CycloneDX report for the modules included in the projectIdToScanIdMap

Query

query SupplyChainDashboardCycloneDxSbomReport($entityId: UUID, $projectIdToScanIdMap: Map_UUID_UUIDScalar) {
  supplyChainDashboardCycloneDxSbomReport(
    entityId: $entityId
    projectIdToScanIdMap: $projectIdToScanIdMap
  ) {
    data
  }
}

Variables

{
  "entityId": "60266a1b-0168-4db5-9893-46e92bc7c1b5"
  "projectIdToScanIdMap": {
    "54c0171b-492e-4f7c-b9e2-5983afda9f00": "706737e6-1aeb-4d83-a1f5-76abc2b96df3"
  }
}

CodeCertify PDF report

Returns a a summary report

Note that this report is available only through the following REST endpoint

REST API Query

POST: https://app.threatrix.io/rest/compliance/report/supplychain/pdf

Body (JSON):

{"scpProjectId":"60266a1b-0168-4db5-9893-46e92bc7c1b5"}

CodeCertify License Attribution

Returns a text file with complete license attribution with license text and copyrights.

Query

query GenerateSupplyChainLicenseAttributionReport($entityId: UUID, $projectIdToScanIdMap: Map_UUID_UUIDScalar) {
  generateSupplyChainLicenseAttributionReport(
    entityId: $entityId
    projectIdToScanIdMap: $projectIdToScanIdMap
  ) {
    data
  }
}

Variables

{
  "entityId": "60266a1b-0168-4db5-9893-46e92bc7c1b5"
}