// products

Image Validation

[ view markdown ]

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

Images connects Amazon ECR and Google Artifact Registry to Superagent. Like 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; 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. For images pushed before scanning was enabled, push the image again to trigger its first scan. See Google's automatic scanning setup.

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.

{
  "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 or matching MCP tools 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.

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.