superagent_

Security Factory

Turn security findings into verified remediation pull requests with webhooks, coding agent automations, and the Superagent MCP.

Security Factory is the workflow that turns a security signal into a reviewed fix. Superagent discovers and normalizes findings. Your coding agent investigates exploitability, applies a strict remediation gate, and opens a tested pull request when a fix is justified. GitHub, CI, and your reviewers remain the approval boundary.

This is not blind autofix. The Factory separates finding discovery from remediation, gives the coding agent the evidence and tools it needs, and records the final outcome in Superagent.

The Factory loop

flowchart LR
  Sources["Red team reports and advisories"] --> Queue["Security Factory queue"]
  Queue -->|"finding.created webhook"| Automation["Coding agent automation"]
  Automation -->|"Read and update through MCP"| Queue
  Automation --> Gate{"Critical and externally exploitable?"}
  Gate -->|No| Resolution["Record resolution and reasoning"]
  Gate -->|Yes| PullRequest["Smallest tested remediation PR"]
  PullRequest --> Review["CI, security review, and human approval"]
  Review -->|"Merge and MCP update"| Resolved["Resolved finding"]

The loop has one system of record and one approval boundary:

  • Superagent owns reports, findings, evidence, triage state, and resolution.
  • The webhook starts work when a new finding is created.
  • The coding agent reproduces the issue, checks reachability and impact, and writes the smallest complete fix.
  • The Superagent MCP lets the agent read the finding and record its decision or pull request.
  • GitHub and CI keep code changes reviewable. The agent never bypasses branch protection or merge approval.

Findings and the Factory

A finding is one security issue with evidence, risk, status, and remediation context. The Findings queue is the underlying record of those issues.

The Security Factory is the automation around that queue. It connects finding creation to a coding agent, gives the agent controlled access through MCP, and closes the loop when the agent records a resolution or links a remediation pull request.

Finding names and event payloads remain stable. Automations subscribe to finding.created, read the finding from data.object, and use its id when calling Superagent MCP tools.

What you need

Before the first run:

  1. Install the Superagent Security GitHub App on at least one repository.
  2. Create a dedicated organization API key under Settings (/app/settings#api-keys).
  3. Create a webhook-capable automation in your coding agent platform.
  4. Connect the Superagent MCP server to that automation.
  5. Run a repository red-team report to produce the first findings.

Use a dedicated API key for the automation. Store it in the coding platform's secret manager, expose it to the MCP connection as SUPERAGENT_API_KEY, and never place it in an automation prompt or repository file.

Connect a coding agent

The Copy setup prompt menu on /app/factory generates instructions for Cursor, Claude Code, Codex, and Devin. Each platform has a different inbound automation model.

Cursor

Cursor Automations accept the Superagent webhook body directly. Create a Webhook trigger, copy its generated URL, and use Cursor's generated Authorization bearer value as a custom Superagent webhook header. Cursor appends the JSON payload to the saved automation prompt.

Devin

Devin Automations also accept the payload directly. Create an incoming Webhook trigger with a Start session action, then send Devin's one-time webhook secret in the X-Webhook-Secret custom header. Devin appends the payload to the session prompt.

Claude Code

Claude Code Routines provide an API trigger, but the endpoint accepts run context through a JSON text field. Superagent sends a structured event envelope, so use a small authenticated relay that:

  1. Verifies the Superagent signature and a separate shared secret.
  2. Rejects events whose type is not finding.created.
  3. Sends { "text": JSON.stringify(payload) } to the routine's /fire endpoint.
  4. Keeps the routine bearer token in the relay rather than in Superagent.

The relay must also send the Anthropic API version and current Claude Code Routines beta headers required by the routine endpoint.

Codex

Codex does not currently document an incoming webhook trigger for cloud tasks. Use an authenticated relay or trusted CI runner that verifies and deduplicates the Superagent event, then invokes codex cloud exec for the configured repository with the triage policy and event payload.

Keep Codex credentials on the runner. The custom header sent by Superagent should authenticate only to your relay and must not contain a Codex credential.

Configure the webhook

Create an organization webhook under Settings (/app/settings#webhooks):

  1. Subscribe to the exact event finding.created.
  2. Enter the automation or relay URL.
  3. Add the authentication header required by the receiver.
  4. Save the signing secret in the receiver.
  5. Send a test event and verify that one automation run starts.

Superagent supports encrypted custom headers, including Authorization, X-Webhook-Secret, and a private header for your own relay. Custom headers authenticate Superagent to the destination. The X-Superagent-* signature headers separately let your receiver verify that the payload came from Superagent.

Webhook receivers should return a 2xx response quickly, process work asynchronously, and deduplicate retries by the event id. See Webhooks for delivery behavior, signatures, and payload schemas.

Apply a strict remediation gate

The coding agent should create or modify a pull request only when evidence shows that the finding is both:

  • A critical security vulnerability.
  • Exploitable by an untrusted third party through a realistic, reachable attack path.

If either condition is missing, the agent should not change code. It should record Accepted risk, False positive, or Won't fix through the Superagent MCP, explain why the issue does not meet the threshold, and stop.

If both conditions are met, the agent should search existing pull requests, avoid duplicate work, create the smallest complete fix, add a regression test, run security and code review, and leave the pull request for human approval. After merge, it should mark the finding Resolved and attach the pull request URL.

Run the first loop

Start a repository report through the dashboard or the MCP create_repository_report tool. When the report creates a finding:

  1. Confirm that Superagent delivered one finding.created event.
  2. Confirm that the automation authenticated successfully.
  3. Confirm that the coding agent can retrieve the finding through MCP.
  4. Verify that below-threshold findings stop without code changes.
  5. Verify that a qualifying finding produces a tested pull request and remains subject to normal review.
  6. Confirm that the final status and pull request link appear in the Security Factory.

Next steps