superagent_

// 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. 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; 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. 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 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.

{
  "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.

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 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 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.

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.