Catalog OneModel GraphQL

Introduction

The Catalog OneModel GraphQL API enables you to search and inspect packages, versions, vulnerabilities, licenses, and operational risk, and to govern packages with your organization's Custom Catalog labels and custom assigned licenses. This API follows the OneModel GraphQL conventions and supports pagination, filtering, and cross-service queries. For Catalog product documentation, see JFrog Catalog.

Catalog queries and mutations use the unified OneModel endpoint:

POST <YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql

You can also explore the live schema and run queries in the JFrog Platform UI under Integrations > GraphQL Playground. For more information, see Explore Schema With GraphQL Playground.

Prerequisites

JFrog Catalog must be installed, enabled, and included in your subscription.
Set the access token audience to wildcard (*@*) so OneModel can resolve cross-service queries.
Use a JFrog access token with permission to view the requested data.
Custom Catalog label and custom assigned license mutations require an admin-scoped access token.

Service Entities

The Catalog service is organized around these core entities and relationships:

Packages and versions: A PublicPackage, identified by type, name, and ecosystem, can have many PublicPackageVersion records. Each version exposes security, legal, and operational information.
Vulnerabilities: A PublicVulnerability describes a security issue, including CVSS and EPSS scores, advisories, and known-exploit status. Vulnerabilities link to the package versions they affect.
Licenses: A PublicLicense describes license terms and risk scores. Package versions expose the licenses detected in their contents.
Operational risk: Packages and versions expose OpenSSF Scorecard results, popularity metrics, and end-of-life information.
Custom Catalog labels: A CustomCatalogLabel represents an organization-defined classification that you can assign to packages and versions, optionally with an expiration date.
Custom assigned licenses: A CustomAssignedLicense represents an organization-defined license that you can assign to packages and versions.

Catalog data is exposed through namespaces such as publicPackages, publicSecurityInfo, publicLegalInfo, customCatalogLabels, and customLegalInfo. For field-level details and the complete list of operations, use the GraphQL Playground.

Common Use Cases

Assess a Package Version's Risk

Use this query to review a package version end to end—its known vulnerabilities, detected licenses, and OpenSSF operational score—in one request. This is useful when deciding whether a specific version is safe to consume.

GraphQL

query {
  publicPackages {
    getPackageVersion(
      type: "npm"
      name: "lodash"
      version: "4.17.20"
    ) {
      version
      isLatest
      securityInfo {
        vulnerabilitiesConnection(first: 5) {
          totalCount
          edges {
            node {
              name
              severity
              cvss {
                preferredBaseScore
              }
            }
          }
        }
      }
      legalInfo {
        licenseInfo {
          expression
          licenses {
            name
            licenseCategory
          }
        }
      }
      operationalInfo {
        openSsf {
          aggregatedScore
        }
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"query { publicPackages { getPackageVersion(type: \"npm\", name: \"lodash\", version: \"4.17.20\") { version isLatest securityInfo { vulnerabilitiesConnection(first: 5) { totalCount edges { node { name severity cvss { preferredBaseScore } } } } } legalInfo { licenseInfo { expression licenses { name licenseCategory } } } operationalInfo { openSsf { aggregatedScore } } } } }"}'

Response

{
  "data": {
    "publicPackages": {
      "getPackageVersion": {
        "version": "4.17.20",
        "isLatest": false,
        "securityInfo": {
          "vulnerabilitiesConnection": {
            "totalCount": 3,
            "edges": [
              {
                "node": {
                  "name": "CVE-2021-23337",
                  "severity": "HIGH",
                  "cvss": { "preferredBaseScore": 7.2 }
                }
              },
              {
                "node": {
                  "name": "CVE-2020-28500",
                  "severity": "MEDIUM",
                  "cvss": { "preferredBaseScore": 5.3 }
                }
              }
            ]
          }
        },
        "legalInfo": {
          "licenseInfo": {
            "expression": "MIT",
            "licenses": [
              { "name": "MIT", "licenseCategory": "Permissive" }
            ]
          }
        },
        "operationalInfo": {
          "openSsf": { "aggregatedScore": 4.8 }
        }
      }
    }
  }
}

Find Critical Vulnerabilities with Known Exploits

Use this query to find critical-severity vulnerabilities with a known active exploit, ordered by publication date. This is useful for prioritizing vulnerability triage and monitoring newly disclosed threats.

GraphQL

query {
  publicSecurityInfo {
    searchVulnerabilities(
      first: 5
      where: {
        severity: CRITICAL
        hasKnownExploit: true
      }
      orderBy: {
        field: PUBLISHED_AT
        direction: DESC
      }
    ) {
      totalCount
      edges {
        node {
          name
          ecosystem
          severity
          publishedAt
          cvss {
            preferredBaseScore
          }
          knownExploit {
            addedAt
            dueDateAt
          }
        }
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"query { publicSecurityInfo { searchVulnerabilities(first: 5, where: { severity: CRITICAL, hasKnownExploit: true }, orderBy: { field: PUBLISHED_AT, direction: DESC }) { totalCount edges { node { name ecosystem severity publishedAt cvss { preferredBaseScore } knownExploit { addedAt dueDateAt } } } } } }"}'

Response

{
  "data": {
    "publicSecurityInfo": {
      "searchVulnerabilities": {
        "totalCount": 128,
        "edges": [
          {
            "node": {
              "name": "CVE-2024-3094",
              "ecosystem": "generic",
              "severity": "CRITICAL",
              "publishedAt": "2024-03-29",
              "cvss": { "preferredBaseScore": 10.0 },
              "knownExploit": {
                "addedAt": "2024-04-01",
                "dueDateAt": "2024-04-22"
              }
            }
          }
        ]
      }
    }
  }
}

totalCount is the full match count. edges returns only the first five results, matching the first: 5 argument in the query.

Search Packages and View Their Custom Catalog Labels

Use this query to find packages by name and type and see which Custom Catalog labels your organization has applied. This is useful for auditing governance coverage, such as confirming that packages are labeled before they enter your builds.

GraphQL

query {
  publicPackages {
    searchPackages(
      first: 3
      where: {
        nameContainsFold: "log4j"
        type: "maven"
      }
      orderBy: {
        field: NAME
        direction: ASC
      }
    ) {
      totalCount
      edges {
        node {
          name
          type
          ecosystem
          customCatalogLabelsConnection(first: 5) {
            edges {
              node {
                name
              }
              assignmentInfo {
                expirationAt
              }
            }
          }
        }
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"query { publicPackages { searchPackages(first: 3, where: { nameContainsFold: \"log4j\", type: \"maven\" }, orderBy: { field: NAME, direction: ASC }) { totalCount edges { node { name type ecosystem customCatalogLabelsConnection(first: 5) { edges { node { name } assignmentInfo { expirationAt } } } } } } } }"}'

Response

{
  "data": {
    "publicPackages": {
      "searchPackages": {
        "totalCount": 2,
        "edges": [
          {
            "node": {
              "name": "log4j-core",
              "type": "maven",
              "ecosystem": "maven",
              "customCatalogLabelsConnection": {
                "edges": [
                  {
                    "node": { "name": "approved" },
                    "assignmentInfo": { "expirationAt": null }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Assign a Custom Catalog Label to a Package

Use this mutation to apply an existing Custom Catalog label to a package. You can optionally set expirationAt to make the assignment temporary. This mutation requires an admin-scoped access token.

GraphQL

mutation {
  customCatalogLabel {
    assignCustomCatalogLabelsToPublicPackage(
      publicPackageLabels: {
        publicPackage: {
          name: "lodash"
          type: "npm"
        }
        labelNames: ["approved"]
        expirationAt: "2027-01-01T00:00:00.000Z"
      }
    )
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ADMIN_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"mutation { customCatalogLabel { assignCustomCatalogLabelsToPublicPackage(publicPackageLabels: { publicPackage: { name: \"lodash\", type: \"npm\" }, labelNames: [\"approved\"], expirationAt: \"2027-01-01T00:00:00.000Z\" }) } }"}'

Response

{
  "data": {
    "customCatalogLabel": {
      "assignCustomCatalogLabelsToPublicPackage": true
    }
  }
}

Create and Assign a Custom License

Use these mutations to create an organization-defined license and assign it to one or more package versions. The license category must already exist in the Custom Catalog. These mutations require an admin-scoped access token.

GraphQL

mutation {
  customLegalInfo {
    customAssignedLicense {
      createCustomAssignedLicense(
        license: {
          name: "My-Internal-License"
          text: "Full license agreement text..."
          category: "Proprietary"
        }
      ) {
        name
        text
        category {
          name
        }
      }
    }
  }
}

Response

{
  "data": {
    "customLegalInfo": {
      "customAssignedLicense": {
        "createCustomAssignedLicense": {
          "name": "My-Internal-License",
          "text": "Full license agreement text...",
          "category": { "name": "Proprietary" }
        }
      }
    }
  }
}

After creating the license, assign it to package versions:

mutation {
  customLegalInfo {
    customAssignedLicense {
      assignCustomAssignedLicensesToPublicPackageVersions(
        assignments: [
          {
            licenseName: "My-Internal-License"
            publicPackage: {
              name: "lodash"
              type: "npm"
            }
            versions: ["4.17.20", "4.17.21"]
          }
        ]
      )
    }
  }
}

Response

{
  "data": {
    "customLegalInfo": {
      "customAssignedLicense": {
        "assignCustomAssignedLicensesToPublicPackageVersions": true
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ADMIN_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"mutation { customLegalInfo { customAssignedLicense { assignCustomAssignedLicensesToPublicPackageVersions(assignments: [{ licenseName: \"My-Internal-License\", publicPackage: { name: \"lodash\", type: \"npm\" }, versions: [\"4.17.20\", \"4.17.21\"] }]) } } }"}'

For the UI workflow, see Create and Assign Custom Licenses.