> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Test cloud container vulnerability advisories against your images and verify replacement images with exploit evidence.

# Image Validation


**Images** connects Amazon ECR and Google Artifact Registry to Superagent. Like
[Dependency Validation](https://www.superagent.sh/docs/products/dependency-validation), it investigates
known advisories in the application and tests whether a proposed replacement
blocks a demonstrated exploit. Registry tags are resolved to immutable image
digests before an investigation starts.

## Connect a registry

An organization owner opens **Integrations** and chooses **Connect** on the
Amazon ECR or Google Artifact Registry card. Integrations owns connection setup,
verification, reconnecting, and disconnecting. Members can view connection status,
inventory, advisories, and reports. Only owners can configure connections, change
environments, or start and cancel validations.

Each provider card opens its own setup form with the provider already selected.
**Images → Connected → Add new** shows AWS and GCP provider tiles and a searchable
image repository list. Select a connected provider, choose an image, then click
**Add image**. If you
have not completed a connection, it takes you to **Integrations** to finish setup.
The default setup accepts provider credentials and verifies registry access
before saving the connection. Keys are encrypted on the server and are never
returned to the browser. Use the settings button next to **Disconnect**, then
**Update credentials** to rotate a key. A failed replacement leaves the current
key in place. Each organization can have one active connection per provider.

### Amazon ECR

Enter the AWS region and paste an IAM user's access-key ID and secret access key.
Grant that user read access to ECR repositories, image metadata, scan findings,
and registry authorization tokens. Root keys and temporary session credentials
are not supported.

Enable ECR basic or enhanced vulnerability scanning. Superagent reads existing
[ECR scan findings](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeImageScanFindings.html);
it does not enable scanning or modify your images. Basic scanning has narrower
coverage than enhanced scanning. An unavailable scan never counts as a clean image.

### Google Artifact Registry

Paste the service-account JSON key. Superagent reads the project ID from the key,
names the connection automatically, and discovers repositories across all registry
locations. No connection name, project ID, location, or Cloud Shell script is
required. Grant the account **Artifact Registry Reader** and **Container Analysis
Occurrences Viewer** in its project.

Enable Artifact Analysis vulnerability scanning in your project. Superagent reads
the image's [Artifact Analysis occurrences](https://cloud.google.com/artifact-analysis/docs/reference/rest/v1/projects.occurrences/list).
For images pushed before scanning was enabled, push the image again to trigger
its first scan. See Google's [automatic scanning setup](https://docs.cloud.google.com/artifact-analysis/docs/quickstart-scanning-os-automatically).

### Select repositories

After connecting a provider in Integrations, open **Images → Add new**, select
AWS or GCP, and choose an image repository from the searchable list. Open a repository's
**Image validation** tab and add tracked tags, such as `production` and `candidate`.
Press Enter or comma to add each tag, or remove it with its close button. Changes save automatically.
Superagent starts with `latest` for automatic validation. Adding a repository
starts its first import automatically, including up to 100 recent image versions
with tracked versions prioritized. Inventory does not require a `latest` tag.
Saved settings trigger another import, and background reconciliation refreshes
connected repositories hourly. Opening Images also recovers due imports when a
scheduled refresh was missed, including during local development.
Historical digests and observations remain readable when tags move or a scan is
unavailable; they are not proof that an advisory is resolved.

## Image details

Each image detail page uses the same two-column layout as Applications and
Repositories. The left panel shows registry details and tracked tags.
The right panel opens on **Image validation**, with the **Automatically validate advisories**
toggle, tracked tags, daily validation limit, and the validation run history together.
Tags save when added or removed; the daily limit saves on blur or Enter. **Edit settings** next to **New run**
opens the test environment settings. **New run**
opens the version and advisory selection dialog once image versions are available.
The **Advisories** tab lists cloud findings and validation results. Choose affected
and replacement image versions in **New run**, using searchable tag and digest selectors.
**Refresh advisories** in the page header requests an extra refresh when needed.
Image versions remain selectable when vulnerability scanning is unavailable; the
run dialog explains when a version has no completed scan or active advisories. An empty
advisory list does not establish that an image is clean; check the scan status
and enable scanning in your cloud project or account.
**Open in AWS** or **Open in GCP** links directly to the repository in the cloud
console. Tabs have shareable URLs.

## Configure the test environment

In **Image validation**, open **Edit settings** next to **New run** to configure the container port, health path, optional
startup command, environment variables, and supporting services. Environment
values are encrypted at rest. The owner-only JSON input loads the saved values
when opened; edit them and save to replace the complete configuration.

```json
{
  "port": 8080,
  "healthPath": "/health",
  "command": [],
  "variables": { "NODE_ENV": "test" },
  "services": []
}
```

Each supporting service accepts `name`, `image`, and `variables`. Pin its image
with `@sha256:<digest>` and use its name as the hostname. Supply only isolated test
credentials. Base and replacement images run on separate internal Docker networks
with equivalent configuration. Images that require external services may need
local substitutes. Missing setup and failed health checks remain inconclusive.
The initial runtime supports **Linux amd64** images, including the amd64 child of
a multi-platform index.

## Validate advisories

Choose **New run** in **Image validation**, then select an affected image version.
Optionally select a different version from the same repository as the replacement,
choose the advisories to test, then select **Start validation**.
Track both tags to keep both versions prioritized during refreshes. Runs consume
red-team report credits. At most two validations can be active per organization;
the repository's daily limit defaults to five.

The agent investigates the supplied advisories through the running application's
HTTP, CLI, or protocol interfaces. An independent verifier checks material claims.
Reports distinguish:

- **Exploitable:** a safe reproduction demonstrates impact in the affected image.
- **Not applicable:** affirmative evidence establishes a missing precondition.
- **Inconclusive:** setup, coverage, or evidence is insufficient.
- **Verified fix:** the same exploit succeeds on the affected image and is blocked
  for the expected security reason on a healthy replacement.

A failed exploit attempt, startup failure, or cloud advisory disappearing does not
prove safety. Each report includes pinned digests, the environment revision,
reproduction evidence, and verification gaps. Automatic validation is off by
default. Enabling it authorizes running tracked images when advisory revisions or
the test environment change, subject to the same limits.
Manual runs remain available while automatic validation is off.

## Notifications, deleting images, and disconnecting

Organization webhooks can subscribe to `image_validation.finished` and the
**Images** source, optionally restricted to selected repositories. The final
result and delivery intent commit together; delivery retries do not repeat model
work or billing. Existing endpoints must explicitly opt in.

An owner can choose **Delete** in an image's detail page header. Confirming removes
the image from the connected list, stops automatic imports and validations, and
cancels active runs. Existing reports and findings remain available. This removes
monitoring in Superagent; it does not delete the cloud image or disconnect the
registry. Add the image again from **Images → Add new** to resume monitoring.

Disconnecting a registry in **Integrations** deletes stored provider credentials,
disables automatic validation, and cancels active runs. Reconnecting requires
pasting credentials again. Historical reports remain available. Revoke unused
keys in your cloud account.

## API and MCP

Use the [Images API](https://www.superagent.sh/docs/api/images) or matching [MCP tools](https://www.superagent.sh/docs/mcp) to configure
existing images, inspect versions and advisories, refresh registry data, and start,
read, cancel or delete validation reports. Registry credentials remain managed in
Integrations. Public configuration reads expose variable names, while secret
values are write-only.

## Self-hosted configuration

Apply all image migrations, including the single-connection constraint and
atomic sync claims, before deploying the app. Set `INTEGRATION_TOKEN_ENCRYPTION_KEY` for
encrypted credential storage. Registry access uses the keys supplied through
Integrations; no Superagent cloud identity, federation provider, or runtime cloud
credentials are required.

Shared development settings, including the encryption key, belong in the
Armor-encrypted `.env.development`. Customer registry keys belong in Integrations.

```sh
pnpm exec dotenvx armor login
pnpm dev
```

The existing Daytona, OpenRouter, integration encryption key, and cron secret
settings are required for execution. An optional `IMAGE_RED_TEAM_SNAPSHOT` must
include the shared red-team runtime and Docker Engine. `IMAGE_RED_TEAM_MODEL` can
override the focused assessment model. The `/api/images/process` cron route
reconciles pending syncs, queued runs, interrupted collection, and sandbox cleanup.

---
Source: https://www.superagent.sh/docs/products/image-validation
Index: https://www.superagent.sh/llms.txt
