superagent_

// use cases

Validate container images with webhooks

[ view markdown ]

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

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

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

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 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. Use version IDs returned by GET /api/v1/images/{image_id}/versions:

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