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


Connect a cloud registry, test image vulnerability advisories, and send signed validation results to your remediation workflow.

# Validate container images with webhooks

Turn cloud container advisories into an evidence-based remediation workflow.
Superagent runs an affected image in an isolated environment, investigates its
advisories, and sends the final result to your webhook. Your workflow routes
demonstrated exposure to the team that owns the image, then requests a comparison
run when a replacement is ready.

For example, track an API service's `production` and `candidate` tags. Validate
exposure in `production`, build a patched `candidate`, and test whether that
replacement blocks the same exploit before reviewing a deployment.

## Prerequisites

- An organization owner to connect the registry and configure validation
- An Amazon ECR or Google Artifact Registry repository with vulnerability scanning enabled
- A Linux amd64 image that can start with isolated test configuration
- Available red-team report credits
- A public HTTPS webhook receiver and a durable queue for remediation work
- An organization API key if your workflow will start runs or retrieve reports

## 1. Connect the registry and select an image

1. Open **Integrations** and connect **Amazon ECR** or **Google Artifact Registry**.
2. Complete the provider's credential setup and confirm the connection succeeds.
   See [Image Validation](https://www.superagent.sh/docs/products/image-validation#connect-a-registry) for
   permissions and scanner prerequisites.
3. Open **Images → Add new**, choose the connected provider, select the
   repository, and click **Add image**.
4. In the image's **Image validation** tab, add `production` and `candidate` as
   tracked tags, replacing them with your own tag names as needed.
5. Wait for the first import, then check **Advisories** for cloud findings.
   Use **Refresh advisories** after publishing a version if needed.

Tracked tags prioritize versions during imports. Each validation pins an
immutable digest, so moving a tag later does not change what that run tested.
Check scanner status as well as the advisory list: an unavailable scan or empty
list does not establish that an image is clean.

## 2. Configure a working test environment

In **Image validation**, select **Edit settings** next to **New run**. Configure
the port, health path, optional startup command, variables, and supporting
services needed to exercise the application. For an API listening on port 8080:

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

Adapt this to the image's actual startup and health endpoint. Use isolated test
credentials and digest-pinned supporting services. The affected and replacement
images receive equivalent configuration on separate internal networks. Missing
dependencies or failed health checks leave the result inconclusive.

Keep **Automatically validate advisories** off for the initial manual run.
Once setup works, enable it to validate tracked images when digests, advisory
revisions, or the test environment change. Automatic runs consume report credits
within the configured daily limit; they do not automatically select and compare
a replacement image.

## 3. Subscribe to image validation results

Open **Webhooks** and select **Add webhook**:

1. Name the target, for example `Container remediation`.
2. Enter your receiver's HTTPS URL, such as
   `https://app.example.com/api/webhooks/superagent-images`.
3. Subscribe to `image_validation.finished`.
4. Under **Sources → Images**, select the exact image repository configured
   above. Use **All images** only if this workflow owns every monitored image.
5. Add an authentication header if your receiver requires one.
6. Save the target and store its signing secret as
   `SUPERAGENT_WEBHOOK_SECRET` in the receiver's environment.

Both new and existing targets must explicitly subscribe to
`image_validation.finished`; it is excluded from the default event selection.
Subscribe before starting a run. Source filters are captured when the final
event is enqueued, and retries use the same matched targets.

## 4. Verify and persist incoming events

Verify the untouched body before parsing JSON. For a Next.js receiver, create
`app/api/webhooks/superagent-images/route.ts` in your application:

```typescript-example
import { createHmac, timingSafeEqual } from "node:crypto";
import { enqueueImageValidation } from "@/lib/queues/image-validation";

export const runtime = "nodejs";

export async function POST(request: Request) {
  const secret = process.env.SUPERAGENT_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("Webhook secret unavailable", { status: 503 });
  }

  const rawBody = await request.text();
  const timestamp = request.headers.get("x-superagent-timestamp") ?? "";
  const signature = request.headers.get("x-superagent-signature") ?? "";
  const seconds = Number(timestamp);
  if (
    !/^\d+$/.test(timestamp) ||
    !Number.isSafeInteger(seconds) ||
    Math.abs(Date.now() / 1000 - seconds) > 300
  ) {
    return new Response("Invalid webhook timestamp", { status: 401 });
  }

  const digest = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const expected = Buffer.from(`t=${timestamp},v1=${digest}`);
  const actual = Buffer.from(signature);
  if (
    actual.length !== expected.length ||
    !timingSafeEqual(actual, expected)
  ) {
    return new Response("Invalid webhook signature", { status: 401 });
  }

  let event;
  try {
    event = JSON.parse(rawBody);
  } catch {
    return new Response("Invalid JSON", { status: 400 });
  }
  if (event?.type !== "image_validation.finished") {
    return Response.json({ status: "ignored" });
  }
  if (typeof event.id !== "string" || !event.id) {
    return new Response("Missing event ID", { status: 400 });
  }
  if (event.id.startsWith("evt_test_")) {
    return Response.json({ status: "test accepted" });
  }

  try {
    await enqueueImageValidation({ eventId: event.id, event });
  } catch {
    return new Response("Queue unavailable", { status: 503 });
  }
  return Response.json({ status: "accepted" }, { status: 202 });
}
```

`enqueueImageValidation` is an application adapter you implement using your own
durable queue or database. It must atomically persist the event and schedule
work, using the envelope `id` as a unique key. An already-persisted event should
be a successful no-op. Return `2xx` only after durable acceptance; a `503` lets
Superagent retry if persistence fails. Run remediation in the worker, after the
receiver responds.

The receiver acknowledges signed `evt_test_` fixtures without enqueuing
remediation. A webhook test checks delivery and authentication; it does not
represent an actual image assessment.

The five-minute timestamp window above is the receiver's replay policy.
Superagent signs each delivery attempt with a fresh timestamp; retries preserve
the event ID and payload. Keep the receiver's clock synchronized.

## 5. Run validation and route the assessment

Open **Image validation → New run**, select the affected `production` version,
choose advisories, and select **Start validation**. Leave the replacement empty
for this first exposure check.

When the run completes, fails, or is cancelled, your receiver gets
`image_validation.finished`. The signed envelope's `data.object` contains the
run ID, repository ID, status, pinned image and optional candidate, environment
revision, result, and error. See the
[Image Validation payload](https://www.superagent.sh/docs/webhooks#image-validation-payload) for field details.

Have the worker validate the payload schema and confirm `organization_id` and
`data.object.repository_id` belong to its configured workflow. Route each
assessment in `data.object.result.assessments` using this policy:

| Result | Workflow action |
| --- | --- |
| Run is `failed` or `cancelled`, or has no result | Record the error or cancellation and request follow-up; do not mark advisories resolved. |
| `exposure: "exploitable"` | Open or update remediation work with the pinned digest, advisory `targetKey`, impact, and report evidence. |
| `exposure: "not_applicable"` | Record the demonstrated missing precondition for this digest and environment. |
| `exposure: "inconclusive"` | Request missing setup or evidence and keep the advisory under review. |
| `fix: "still_exploitable"` | Keep remediation open; the replacement still permits the exploit. |
| `fix: "verified"` | Attach the comparison evidence for deployment review after checking the candidate identity and health. |
| `fix: "inconclusive"` or `"not_tested"` | Keep replacement verification pending. |

A completed run alone does not establish a fix. A verified fix requires a
demonstrated exploit on the affected image, the same reproduction blocked for
the expected security reason on a healthy replacement, independent verification,
and no verification gaps. Review every selected advisory and any limitations.

Retrieve the full report with `GET /api/v1/reports/{run_id}` and an organization
bearer API key when the worker needs more context. Deduplicate deliveries by
event ID, and group remediation work by repository, digest, and advisory key
to avoid opening a new ticket for every validation run.

## 6. Test the replacement image

Build and push the patched image to the same registry repository, then refresh
advisories and wait for its scan to complete. Start another **New run** with the
original affected version and the new `candidate` as the replacement.

Your workflow can also start the comparison through the [Images API](https://www.superagent.sh/docs/api/images).
Use version IDs returned by `GET /api/v1/images/{image_id}/versions`:

```bash
curl https://superagent.sh/api/v1/reports/image \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": "00000000-0000-4000-8000-000000000001",
    "candidate_version_id": "00000000-0000-4000-8000-000000000002",
    "idempotency_key": "00000000-0000-4000-8000-000000000003",
    "target_keys": []
  }'
```

Replace the example IDs and generate a fresh UUID idempotency key for each new
comparison. Persist that key before submitting and reuse it when retrying the
same request. An empty `target_keys` tests all current active advisories on the
affected version. Runs use report credits and the same daily and concurrency
limits as dashboard runs.

The comparison emits its own completion event. Before acting on it, confirm
`image.digest`, `candidate.digest`, and `environment_revision` match the intended
comparison and current deployment plan. A later tag change or an older event
must not approve a different image. Keep deployment subject to your application
checks and normal review.

## 7. Verify the complete loop

1. Send a webhook test to check HTTPS delivery and signature verification.
   Use a real validation run to verify the image-specific payload and routing.
2. Complete a manual exposure run and confirm its event reaches the queue once.
3. Replay a signed delivery within the timestamp window and confirm the same
   event ID creates no duplicate work. Confirm a modified body is rejected.
4. Make the queue temporarily unavailable and confirm a retry succeeds after
   recovery without starting another validation.
5. Complete a replacement comparison and confirm the worker checks digests,
   candidate health, evidence, and all advisory outcomes before requesting review.
6. Confirm failed, cancelled, and inconclusive runs leave remediation open.
7. Enable automatic validation when the environment and routing work, and set
   a daily limit appropriate for your tracked images.

## Next steps

- [Configure Image Validation](https://www.superagent.sh/docs/products/image-validation)
- [Manage images and reports through the API](https://www.superagent.sh/docs/api/images)
- [Configure webhook delivery and signatures](https://www.superagent.sh/docs/webhooks)

---
Source: https://www.superagent.sh/docs/use-cases/validate-container-images-with-webhooks
Index: https://www.superagent.sh/llms.txt
