Container Scanning API¶

Endpoints for submitting container image scan results and retrieving container vulnerability data.

Submit Container Scan Results¶

Submit Trivy JSON scan results for container images on an agent endpoint.

POST /api/agent/container-scan
X-API-Key: <agent-api-key>
Content-Type: application/json

Request Body¶

The request body should be the raw Trivy JSON output from scanning container images. The agent automatically formats this when container scanning is enabled.

{
  "hostname": "server-01",
  "images": [
    {
      "image_name": "nginx:1.25",
      "image_id": "sha256:abc123...",
      "scan_results": {
        "Results": [
          {
            "Target": "nginx:1.25 (debian 12.4)",
            "Class": "os-pkgs",
            "Type": "debian",
            "Vulnerabilities": [
              {
                "VulnerabilityID": "CVE-2024-1234",
                "PkgName": "openssl",
                "InstalledVersion": "3.0.11-1~deb12u2",
                "FixedVersion": "3.0.13-1~deb12u1",
                "Severity": "HIGH",
                "Title": "OpenSSL vulnerability",
                "Description": "..."
              }
            ]
          }
        ]
      }
    }
  ]
}

Response¶

{
  "status": "accepted",
  "images_processed": 3,
  "vulnerabilities_found": 12,
  "hostname": "server-01"
}

List Container Images¶

Retrieve all container images tracked across endpoints.

GET /api/containers
Authorization: Bearer <token>

Query Parameters¶

Parameter	Type	Description
`severity`	string	Filter by vulnerability severity (`critical`, `high`)
`search`	string	Search by image name or tag
`organization_id`	integer	Filter by organization
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25)

Response¶

{
  "items": [
    {
      "id": 1,
      "image_name": "nginx",
      "image_tag": "1.25",
      "image_id": "sha256:abc123...",
      "hostname": "server-01",
      "organization_id": 1,
      "last_scanned": "2026-02-09T10:30:00Z",
      "vulnerability_count": {
        "critical": 0,
        "high": 3,
        "medium": 7,
        "low": 2
      }
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 25
}

Get Container Image Details¶

Retrieve detailed vulnerability information for a specific container image.

GET /api/containers/<image_id>
Authorization: Bearer <token>

Response¶

{
  "id": 1,
  "image_name": "nginx",
  "image_tag": "1.25",
  "image_id": "sha256:abc123...",
  "hostname": "server-01",
  "organization_id": 1,
  "last_scanned": "2026-02-09T10:30:00Z",
  "vulnerabilities": [
    {
      "cve_id": "CVE-2024-1234",
      "package_name": "openssl",
      "installed_version": "3.0.11-1~deb12u2",
      "fixed_version": "3.0.13-1~deb12u1",
      "severity": "HIGH",
      "title": "OpenSSL vulnerability",
      "description": "..."
    }
  ]
}

Authentication¶

Container scan submission endpoints use the same API key authentication as regular agent endpoints via the X-API-Key header. See Agent API for details.

Container listing and detail endpoints use Bearer token authentication. See Authentication for details.

Rate Limits¶

Endpoint	Limit
`POST /api/agent/container-scan`	30/minute per API key
`GET /api/containers`	60/minute per user
`GET /api/containers/<id>`	60/minute per user

Error Codes¶

Code	Description
200	Success
400	Invalid request body or malformed Trivy JSON
401	Invalid or missing API key / token
403	API key lacks agent permissions
404	Container image not found
429	Rate limit exceeded