> 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.
AWS connects through a read-only role; Google Cloud accepts a service-account key.
Registry access is verified before saving the connection. Stored credentials are
encrypted on the server and never returned to the browser. Use the settings button
next to **Disconnect** to manage authentication. A failed replacement leaves the
current connection in place. Each organization can have one active connection per provider.

### Amazon ECR

Enter your AWS region and click **Connect AWS**. Superagent opens a prefilled
CloudFormation setup page in a new tab. Sign in to the AWS account containing your
images, review the template, acknowledge IAM resource creation, and click
**Create stack**. You need permission to create CloudFormation stacks, create and
pass IAM roles, attach role policies, and create and invoke Lambda functions.

The stack creates a role with ECR metadata, scan-finding, and image-pull read
permissions for repositories in the selected region. It trusts Superagent's
platform role and requires a unique external ID for your connection. A small
Lambda function with no AWS API permissions confirms setup automatically. Keep
the Superagent dialog open; no role ARN or access keys need to be copied.
The setup link expires after one hour. If the stack fails, inspect its **Events**
tab, cancel the setup in Superagent, and start again.

Superagent assumes the role to obtain temporary AWS credentials and refreshes
them automatically. AWS sessions stay on the server; the isolated validation
environment receives only a registry pull token. Role setup currently supports
commercial AWS regions.

Existing access-key connections continue to work. Open their settings and use
**Connect AWS** in the same account and region to switch to a role while keeping
tracked images and reports. The old key is replaced only after role verification
succeeds; revoke that key in AWS afterward. **Update existing access keys instead**
still lets you rotate an existing key. For manual key setup, grant an IAM user
the same ECR read and pull permissions. Root keys and pasted 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.

Enhanced scanning also requires `inspector2:ListCoverage` and
`inspector2:ListFindings` with `Resource: "*"` on the reader role. The connection
template includes these read permissions. For an existing role created with an
older template or Terraform, add both actions to its policy and choose
**Refresh advisories**. You do not need to reconnect or disable enhanced scanning.

### 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 enter exact tags such as `production` and `candidate`,
or wildcards such as `staging-*`, directly in **Tracked tags**. Press Enter or comma
to add each entry, or remove it with its close button. Changes save automatically.
You can remove the last tag. With no tags or newest-version limit, tracking and
automatic validation stay off until you choose a new tag, wildcard, or limit.

Adding a wildcard automatically sets **Newest versions** to 1 if no limit is set.
Adjust this always-visible limit from 1 to 20 to track more matching versions.
For deployment tags such as commit SHAs, enter `*` to match all tags or set a newest-version
limit with no wildcards. `*` matches zero
or more tag characters and `?` matches one. Matching is case-sensitive and covers
the entire tag; regular expressions are not supported. With no patterns, newest-N
considers all tagged versions. Untagged images are available as inventory but are
not dynamically tracked.

Exact tags are always included. Dynamic selection adds the newest N versions
matching any pattern. Aliases and multi-platform tags are resolved to Linux amd64
digests and deduplicated before counting N. Ordering uses ECR `imagePushedAt` or
Artifact Registry `uploadTime`, newest first; ties use the source immutable image
URI in ascending order. Missing timestamps sort oldest. Tag text does not set recency.

Review **Currently selected images**, including their tags and pinned digests,
before enabling **Automatically validate advisories**. Changing any tracking rule
pauses automation and clears the previous selection until a successful refresh.
Enable automation again after reviewing the new selection. Future refreshes update
the selection automatically, including moved or deleted tags. Historical reports
retain the tags and digests observed when each run was admitted.

Discovery stops at 10,000 provider records or 100 pages per list. Each refresh
prioritizes exact matches and at most 80 dynamic candidates within a 100-image
import/manifest window. If aliases or unsupported images exhaust that window
before N unique supported versions can be selected, the refresh fails and asks you
to narrow the rule; it never publishes an incomplete selection. No validation is
admitted from a failed refresh.

## 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, a single tracked-tags field accepting exact tags and wildcards, the newest-version limit,
selection preview, daily validation limit, and the validation run history together.
Tag entries save when added or removed; numeric limits save on blur or Enter.
Saved changes refresh advisories and the selected images automatically. The preview
shows refresh progress and updates when it completes; no refresh-button click is needed.
**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.
Starting a validation closes the dialog and adds the run to the history on the same
page. Select the run to open its report.
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
**5 credits per run**, including selected advisories and an optional replacement
comparison. 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.

For a complete setup, including a signed receiver and replacement-image workflow,
see [Validate container images with webhooks](https://www.superagent.sh/docs/use-cases/validate-container-images-with-webhooks).

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 connection credentials,
disables automatic validation, and cancels active runs. Historical reports remain
available. For AWS role connections, a follow-up dialog offers **Remove AWS
resources**. This opens the connection's **SuperagentImages-…** CloudFormation
stack in its AWS region. Sign in to the displayed AWS account, choose **Delete**,
and confirm to remove the reader role, setup function, and function execution
role. ECR repositories and images remain in your account. Superagent does not
delete the stack automatically or verify its deletion. Reconnect with **Connect
AWS** when needed. Revoke unused legacy 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 and AWS role connection setup, before deploying the app. Set
`INTEGRATION_TOKEN_ENCRYPTION_KEY` for encrypted credential storage.
Apply `20261120232915_image_validation_billing.sql` before deploying the
5-credit billing change; it also handles requests from the previous app version
during rollout without changing historical charges.

For **Connect AWS**, configure a Superagent platform IAM role, publish the supplied
CloudFormation template to S3, and set `AWS_IMAGE_PRINCIPAL_ARN` and
`AWS_IMAGE_CLOUDFORMATION_TEMPLATE_URL`. The platform needs `sts:AssumeRole` for
customer `SuperagentImages-*` roles. `NEXT_PUBLIC_APP_URL` must be the public HTTPS
origin reachable by the stack's setup function; deployment protection must allow
the capability-authenticated `/api/images/aws/callback` route.

On Vercel, enable OIDC federation, trust only the intended team, project, and
environment, and set `AWS_IMAGE_PLATFORM_ROLE_ARN` to the same platform role. On
AWS or local development, use the AWS SDK's standard credential chain for the
configured principal. See `infrastructure/aws/README.md` in the repository for
deployment instructions. Role credentials and external IDs are stored privately;
pending setup capabilities are scoped to one connection and expire after an hour.
Legacy AWS key connections and Google service-account keys do not require a
platform AWS identity.

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.


Tracking settings and registry refreshes do not consume image validation credits.
Enabling automatic validation explicitly authorizes billable runs for selected
versions with current active advisories. Each run costs 5 credits. New digests,
advisory revisions, or test-environment revisions can cause another run; unchanged
inputs remain deduplicated across refreshes. Dynamic selection preserves the daily
repository limit, the organization limit of two concurrent image validations, and
normal admission idempotency. A broad pattern cannot increase these limits.

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