Container Security GraphQL API Documentation

The API exposes the following primary data types:

The data model follows a hierarchical structure:

The API supports two primary access patterns:

Root query entity representing a container security scan.

Fields:

Filtering: Supports filtering via ApiClientScanFilterType

Sorting: Supports sorting via ApiClientScanSortType

Pagination: Supports offset-based pagination on the images field

Represents a container image analyzed during a scan.

Fields:

Filtering: Supports filtering via ApiClientImageFilterType

Sorting: Supported

Pagination: Supports offset-based pagination on packages and vulnerabilities fields

Represents a layer within a container image.

Fields:

Filtering: Supports filtering via ApiClientLayerFilterType

Sorting: Supports sorting via ApiClientLayerSortType

Pagination: No pagination on packages and images (returns all items)

Represents a software package found within an image.

Fields:

Filtering: Supports filtering via ApiClientPackageFilterType

Sorting: Supports sorting via ApiClientPackageSortType

Pagination: No pagination on vulnerabilities (returns all items)

Represents a security vulnerability found in a package.

Fields:

Filtering: Supports filtering via ApiClientVulnerabilityFilterType

Sorting: Supports sorting via ApiClientVulnerabilitySortType

Pagination: No pagination on affectedPackages and affectedImages (returns all items)

scan(id: String!): Scan

Retrieves a scan by its ID.

imagesByScan(scanId: String!): [Image]

Retrieves all images from a specified scan.

packagesByScan(scanId: String!): [Package]

Retrieves all packages across all images in a specified scan.

vulnerabilitiesByScan(scanId: String!): [Vulnerability]

Retrieves all vulnerabilities across all images in a specified scan.

layersByScan(scanId: String!): [Layer]

Retrieves all layers across all images in a specified scan.

packagesByImage(scanId: String!, imageId: String!): [Package]

Retrieves all packages in a specific image.

vulnerabilitiesByImage(scanId: String!, imageId: String!): [Vulnerability]

Retrieves all vulnerabilities in a specific image.

vulnerabilitiesByPackage(scanId: String!, packageId: String!): [Vulnerability]

Retrieves all vulnerabilities in a specific package.

This comprehensive example shows how to retrieve a scan with all its related data, using pagination for images, packages, and vulnerabilities

query GetCompleteScanInfo($scanId: String!) {
  scan(id: $scanId) {
    id
    createdAt
    imagesCount
    fixableCount
    vulnerabilityCounters {
      totalVulnerabilitiesCount
      criticalCount
      highCount
      mediumCount
      lowCount
      noneCount
    }
    
    # Get images with offset pagination
    images(skip: 0, take: 100) {
      # Offset pagination metadata
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
      totalCount
      
      items {
        id
        imageName
        imageTag
        imageId
        baseImage
        imageHash
        size
        runtime
        fixable
        isImageMalicious
        maliciousDescription
        packagesCount
        maliciousPackagesCount
        
        imageLocations { 
          path
          origin
        }
        
        triage {
          status
          snoozeDate
          historyChanges {
            user
            comment
            createDate
            events {
              actionType
              newValue
              oldValue
            }
          }
        }

        recommendations {
          minorRecommendedImages {
            imageId
            lowVulnerabilitiesCount
            mediumVulnerabilitiesCount
            highVulnerabilitiesCount
            criticalVulnerabilitiesCount
          }
          majorRecommendedImages {
            imageId
            lowVulnerabilitiesCount
            mediumVulnerabilitiesCount
            highVulnerabilitiesCount
            criticalVulnerabilitiesCount
          }
          nextRecommendedVersions {
            imageId
            lowVulnerabilitiesCount
            mediumVulnerabilitiesCount
            highVulnerabilitiesCount
            criticalVulnerabilitiesCount
          }
          alternativeRecommendedImages {
            imageId
            lowVulnerabilitiesCount
            mediumVulnerabilitiesCount
            highVulnerabilitiesCount
            criticalVulnerabilitiesCount
          }
          notOutdatedImages {
            imageId
            lowVulnerabilitiesCount
            mediumVulnerabilitiesCount
            highVulnerabilitiesCount
            criticalVulnerabilitiesCount
          }
          alternativeImageTags
        }
        
        vulnerabilityCounters {
          totalVulnerabilitiesCount
          criticalCount
          highCount
          mediumCount
          lowCount
          noneCount
        }
        
        # Get image layers (not paginated)
        layers {
          id
          command
          index
          size
          packagesCount
        }
        
        # Get image packages with offset pagination
        packages(skip: 0, take: 100) {
          # Offset pagination metadata
          pageInfo {
            hasNextPage
            hasPreviousPage
          }
          totalCount

          items {
            id
            packageName
            packageVersion
            distribution
            type
            packageId
            vulnerabilitiesCount
            maxRiskSeverity
            isMalicious
            maliciousDescription
            runtimeUsage
            licenses
            isSource
            
            # Get triage information if available
            triage {
              status
              snoozeDate
              historyChanges {
                user
                comment
                createDate
                events {
                  actionType
                  newValue
                  oldValue
                }
              }
            }
            
            # Get vulnerabilities for this package (not paginated)
            vulnerabilities {
              cve
              cwe
              vulnerabilityLevel
              vulnerabilityScore
              description
              publicationDate
              fixedVersion
              epssScore
              originalScore
              originalSeverityLevel
              status
              firstScanId
              firstFoundDate

              triage {
                state
                historyChanges {
                  user
                  comment
                  createDate
                  events {
                    actionType
                    newValue
                    oldValue
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This example demonstrates how to use flat access to get vulnerabilities directly, with filtering and sorting

query GetFilteredAndSortedVulnerabilities($scanId: String!) {
  vulnerabilitiesByScan(
    scanId: $scanId,
    # Skip the first 0 items and take 100
    skip: 0,
    take: 100,
    # Filter to only critical and high severity vulnerabilities
    where: {
      vulnerabilityLevel: { in: [CRITICAL, HIGH] },
      # Only include vulnerabilities published after 2023-01-01
      publicationDate: { gte: "2023-01-01T00:00:00Z" }
    },
    # Sort by severity level (descending) and then by score (descending)
    order: [
      { vulnerabilityLevel: DESC },
      { vulnerabilityScore: DESC }
    ]
  ) {
    # Pagination metadata
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    totalCount
    
    items {
      cve
      cwe
      description
      vulnerabilityLevel
      vulnerabilityScore
      publicationDate
      status
      
      # Include package information
      affectedPackages {
        packageName
        packageVersion
        type
      }
      
      # Include image information
      affectedImages {
        imageName
        imageTag
      }
      
      # Include triage information
      triage {
        state
        historyChanges {
          user
          comment
          createDate
        }
      }
    }
  }
}

This example shows how to get packages across all images with complex filtering criteria

query GetHighRiskPackages($scanId: String!) {
  packagesByScan(
    scanId: $scanId,
    skip: 0,
    take: 100,
    # Complex filtering using logical operators
    where: {
      or: [
        # High risk packages with vulnerabilities
        {
          and: [
            { maxRiskSeverity: { in: [CRITICAL, HIGH] } },
            { vulnerabilitiesCount: { gt: 0 } }
          ]
        },
        # Any malicious packages
        { isMalicious: { eq: true } },
        # Packages with specific name patterns (e.g., known problematic packages)
        {
          or: [
            { packageName: { contains: "log4j" } },
            { packageName: { contains: "spring" } }
          ]
        }
      ]
    },
    # Sort by risk severity (highest first), then by vulnerability count (highest first)
    order: [
      { maxRiskSeverity: DESC },
      { vulnerabilitiesCount: DESC }
    ]
  ) {
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    totalCount
    
    items {
      id
      packageName
      packageVersion
      type
      distribution
      maxRiskSeverity
      vulnerabilitiesCount
      isMalicious
      maliciousDescription
      runtimeUsage
      licenses
      
      # Include triage information
      triage {
        status
        snoozeDate
      }
      
      # Include the most severe vulnerabilities (limited to top 5)
      vulnerabilities(
        take: 5,
        order: [{ vulnerabilityLevel: DESC }]
      ) {
        cve
        vulnerabilityLevel
        vulnerabilityScore
        description
        triage {
          state
        }
      }
      
      # Show which images contain this package
      images {
        imageName
        imageTag
      }
      
      # Show which layers contain this package
      layers {
        index
        command
      }
    }
  }
}

query GetMaliciousPackages($scanId: String!, $imageId: String!) {
  packagesByImage(
    scanId: $scanId, 
    imageId: $imageId,
    where: { isMalicious: { eq: true } }
  ) {
    totalCount
    items {
      packageName
      packageVersion
      type
      maliciousDescription
      vulnerabilitiesCount
    }
  }
}

query GetPackageVulnerabilities($scanId: String!, $packageId: String!) {
  vulnerabilitiesByPackage(
    scanId: $scanId, 
    packageId: $packageId, 
    order: { vulnerabilityLevel: DESC }
  ) {
    totalCount
    items {
      cve
      vulnerabilityLevel
      vulnerabilityScore
      description
      publicationDate
      triage {
        state
      }
    }
  }
}

query GetImageLayers($scanId: String!) {
  scan(id: $scanId) {
    images {
      imageName
      imageTag
      layers {
        id
        command
        index
        size
        packagesCount
      }
    }
  }
}

query GetImageRecommendations($scanId: String!, $imageId: String!) {
  scan(id: $scanId) {
    images(where: { id: { eq: $imageId } }) {
      imageName
      imageTag
      recommendations {
        minorRecommendedImages {
          imageId
          criticalVulnerabilitiesCount
          highVulnerabilitiesCount
        }
        majorRecommendedImages {
          imageId
          criticalVulnerabilitiesCount
          highVulnerabilitiesCount
        }
        alternativeImageTags
      }
    }
  }
}

query SearchPackages($scanId: String!, $packageName: String!) {
  packagesByScan(
    scanId: $scanId,
    where: { packageName: { contains: $packageName } }
  ) {
    totalCount
    items {
      packageName
      packageVersion
      type
      maxRiskSeverity
      vulnerabilitiesCount
      images {
        imageName
        imageTag
      }
    }
  }
}

query GetRecentVulnerabilities($scanId: String!, $date: DateTime!) {
  vulnerabilitiesByScan(
    scanId: $scanId,
    where: { publicationDate: { gte: $date } },
    order: { publicationDate: DESC }
  ) {
    totalCount
    items {
      cve
      description
      vulnerabilityLevel
      vulnerabilityScore
      publicationDate
      affectedPackages {
        packageName
        packageVersion
      }
    }
  }
}

query GetImageTriageHistory($scanId: String!, $imageId: String!) {
  scan(id: $scanId) {
    images(where: { id: { eq: $imageId } }) {
      imageName
      imageTag
      triage {
        status
        snoozeDate
        historyChanges {
          createDate
          user
          comment
          events {
            actionType
            newValue
            oldValue
          }
        }
      }
    }
  }
}

The API uses custom GraphQL type extensions to define the schema:

The API uses offset-based pagination with the following options:

All queries require the ContainerPermissions.ViewResults permission, which is enforced at the operation level.