> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.strix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Containers

> Scan container images for vulnerable packages, secrets, and misconfigurations

export const ScarfPixel = () => <img referrerPolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=831669b6-b4bd-42cb-8832-2122c03e1d5f" alt="" width="1" height="1" style={{
  position: "absolute",
  width: 0,
  height: 0,
  opacity: 0,
  pointerEvents: "none"
}} />;

<ScarfPixel />

With Containers, you connect a registry, add images, and scan each image for vulnerable packages, malicious packages, secrets, misconfigurations, and outdated base images. Strix identifies an image by its digest, so a scan always applies to one immutable image.

Containers is part of the Enterprise plan. Every request in this guide returns `403` with the code `enterprise_plan_required` on other plans.

## How a scan works

1. Strix resolves the image reference to a manifest digest and a platform.
2. Strix pulls the image layers with the registry credential on the trusted orchestrator. The credential never enters the scan sandbox.
3. The scan sandbox receives the image as a read-only OCI layout and runs the package, secret, and configuration checks.
4. Strix stores each finding in the same vulnerability list that the rest of the workspace uses. Findings that appear in a new scan of the same image keep their history. Findings that no longer appear are marked as fixed.

Strix stores only a masked value or a SHA-256 fingerprint for a secret finding. Strix does not store the secret value.

## Connect a registry

Public Docker Hub images do not need a registry. For a private registry, create a registry connection first.

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/containers/registries" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "generic",
    "registry_host": "registry.example.com",
    "label": "Production registry",
    "auth_kind": "basic_token",
    "username": "strix-readonly",
    "secret": "<REGISTRY_TOKEN>"
  }'
```

The `provider` field accepts `ghcr`, `dockerhub`, `ecr`, and `generic`. The `auth_kind` field accepts `basic_token`, `aws_assume_role`, and `none`. For `ghcr`, use `basic_token` with your GitHub username and a personal access token that has the `read:packages` scope.

Strix encrypts the `secret` value and never returns it. Strix verifies the connection when you create it. Call `POST /containers/registries/{registryId}/verify` to check the connection again.

**Required scope:** `containers:write`

Only workspace admins can create, verify, or delete a registry.

## Add an image

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/containers/images" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "registry_id": "<REGISTRY_ID>",
    "reference": "acme/api:1.4.2",
    "platform": "linux/amd64",
    "scan": true
  }'
```

The `reference` field accepts `name:tag` or `name@sha256:<digest>`. Set `registry_id` to `null` for a public Docker Hub image. Set `platform` to `null` to use `linux/amd64`. Strix stores the platform on the image. A later scan uses the stored platform if the scan request does not specify a platform.

Set `scan` to `true` to start the first scan when the image is added. The default is `false`. The response contains the stored image, the resolved digest, and the first scan when `scan` is `true`. If the first scan cannot start, the response contains a `scan_error` message and the image stays in the inventory.

**Required scope:** `containers:write`

Workspace admins and analysts can add, update, scan, and delete images.

### Watch tags

Set `watch_tags` to a tag pattern when you add an image, or change it later with `PATCH /containers/images/{imageId}`. Set `watch_tags` to `null` to stop watching tags.

## Start a scan

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/containers/images/<IMAGE_ID>/scans" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

If the request has no `tag`, the scan resolves the tag from the latest scan. If the image has no tag, the scan resolves the digest from the add request. If the request has no `platform`, the scan uses the platform stored on the image.

Each image has one queued or running scan at a time. A second request returns `409` while that scan runs. List the scan history with `GET /containers/images/{imageId}/scans`.

Each scan has a cost limit. If a scan reaches the limit before the analysis is complete, the scan completes with `stop_reason` set to `budget_exceeded`. If the model provider limits the run, `stop_reason` is `rate_limited`. Strix keeps the findings that the scan filed before the stop. Strix does not mark findings as fixed after a stopped scan. The scan history shows the scan as **Stopped early**.

**Required scope:** `containers:write`

## Read findings

```bash theme={null}
curl "https://app.strix.ai/api/v1/containers/images/<IMAGE_ID>/findings?type=secret&state=open" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

Filter with these query parameters:

* `type`: `known_vulnerability`, `malicious_package`, `secret`, `misconfiguration`, or `base_image_outdated`
* `severity`: one severity level
* `state`: `open`, `fixed`, or `ignored`

Each finding contains the layer digest and the file path when Strix knows them. A package finding also contains the package name, the installed version, and the fixed version when one exists.

A secret finding also contains a `verification` verdict, the `verified_by` explanation, and `verified_at`:

* `active`: the credential's own provider accepted it. Rotate it now.
* `inactive`: the provider rejected it. The credential is revoked or rotated.
* `valid_unverified`: an offline proof succeeded, for example a private key that signs and verifies, but there is no provider to ask.
* `unverified`: Strix could not prove or disprove that the credential is real. `verified_by` says what Strix checked.

Strix checks a credential only against its own provider and only with read-only calls. A network or provider failure never produces `inactive`. Strix does not file example, fixture, or placeholder values.

**Required scope:** `containers:read`

## Read the software bill of materials

```bash theme={null}
curl "https://app.strix.ai/api/v1/containers/images/<IMAGE_ID>/components" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

The response lists the packages of the latest completed scan with the package URL, the ecosystem, the license, and the layer that added the package. Set `scan_id` to read the components of an earlier scan.

To download the same inventory as a standard document, request the export route with `format=spdx` or `format=cyclonedx`:

```bash theme={null}
curl "https://app.strix.ai/api/v1/containers/images/<IMAGE_ID>/sbom?format=cyclonedx" \
  -H "Authorization: Bearer $STRIX_API_KEY" \
  -o image-sbom.json
```

The route returns an SPDX 2.3 or a CycloneDX 1.6 JSON file for the latest completed scan. Set `scan_id` to export an earlier scan. The dashboard uses the same route for the **Export SBOM…** menu on the SBOM tab.

`GET /containers/images/{imageId}` returns the image with its scans, layers, image configuration, findings, and components in one response. `GET /containers/summary` returns the workspace counts of images, critical findings, reachable findings, and secrets.

**Required scope:** `containers:read`

## Delete an image or a registry

```bash theme={null}
curl -X DELETE "https://app.strix.ai/api/v1/containers/images/<IMAGE_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

When you delete an image, Strix closes its open findings. When you delete a registry, Strix deletes every image of that registry and closes their findings. If a scan of an affected image is queued or running, both requests return `409`. Wait until the scan finishes, or cancel the scan, and then send the delete request again.

**Required scope:** `containers:write`