Scanners tell you about known CVEs. Red Team shows how an attacker could break what you built. Superagent runs adversarial campaigns against your real surface: black-box against public applications and installable packages, gray-box with repository context. Every finding ships with repro steps and the payload that worked, ranked by severity against your architecture rather than a generic checklist. All reports live under [Red team](/app/reports) in the dashboard, in one list across every target type. ## Pick a target | Target | What it tests | Access needed | | --- | --- | --- | | [Repository](/docs/security-workers/red-team/repositories) | A GitHub codebase, scanned for vulnerabilities, unsafe patterns, and config issues | Superagent Security installed on the repo | | [Application](/docs/security-workers/red-team/applications) | A live application, probed by browser-driven DAST | A public HTTP or HTTPS URL | | [Agent](/docs/security-workers/red-team/agents) | A deployed AI agent tested for jailbreaks, policy gaps, and unsafe behavior | A description of the agent under test | | [Package](/docs/security-workers/red-team/packages) | Installable software or a CLI, installed in a sandbox and adversarially tested | Installation instructions | ## Start a Red Team run Start from **Red team → New report** (`/app/reports/new`), pick a target type, and fill in the details. The Red Team run proceeds asynchronously in an isolated sandbox. Its red-team report stores status, evidence, findings, and the final result. You can also start repository, application, Agent, and Package runs from the [Reports API](/docs/api/reports) or the [MCP server](/docs/mcp). Both consume organization credits. ## Follow the run Red Team runs execute asynchronously in an isolated sandbox. Starting one returns immediately, and its red-team report detail page shows progress and results. Three status fields tell you where a run stands: | Field | Values | | --- | --- | | Report status | In progress, In review, Done, Failed | | Sandbox status | Pending, Provisioning, Ready, Failed | | Agent status | Pending, Installing, Running, Completed, Needs Review, Failed | A healthy run moves from provisioning to running to **In review**, where results wait for your decision. Failures in provisioning or execution land on **Failed** with safe error context. Repository runs can also trigger automatically on a GitHub release, a tag, or a schedule instead of manual creation. ### Reviewing results | Signal | Where to look | | --- | --- | | Overall status | Report detail header and the **Red team** list | | Agent activity | The live event feed on the detail page | | Findings | The report's findings section and the org-wide [Findings](/docs/concepts/findings-and-reports) queue | | Evidence | Recordings and screenshots on application reports | Application reports also show the browser session live while the agent works, and a recording afterwards. See [Applications](/docs/security-workers/red-team/applications). ### Rerun or automate Application runs can be started again from the detail page. To wire the lifecycle into your own systems, subscribe to `report.started` and `report.finished` [webhooks](/docs/webhooks). `report.finished` fires once per report, with the outcome and a link back to the dashboard. ### When a report fails - Confirm the GitHub App still has access to the repository. - Verify the repository exists and is selected in the app installation. - For application reports, check that the target URL is public and your WAF allows the scanner. - For agent reports, check that the description and type match the target you intend to test. - See [Troubleshooting](/docs/reference/troubleshooting). ## From report to fix Findings from repository and application reports land in the [Findings](/docs/concepts/findings-and-reports) queue with repro context. Automated triage verifies them, and confirmed findings can become fix PRs without leaving the queue. ## Next steps - [Run repository Red Team](/docs/security-workers/red-team/repositories) - [Run application Red Team](/docs/security-workers/red-team/applications) - [Run Agent Red Team](/docs/security-workers/red-team/agents) 3a:Tc2a,An application Red Team run points a security agent at a running application. The agent drives a real browser against the application, probing for exploit paths the way an external attacker would: no source code, just the public surface. This is the black-box option. Results stream to a live report page, and confirmed issues land in the [Findings](/docs/concepts/findings-and-reports) queue. ### Start an Application run 1. Open **Red team** and select **New report**, or go to `/app/reports/new`. 2. Choose **Application**. 3. Enter the target URL and any optional configuration below. 4. Submit. The sandbox provisions and the run starts in the background. | Field | Required | Notes | | --- | --- | --- | | Target URL | Yes | Public HTTP or HTTPS URL. Localhost, private IPs, and metadata hostnames are rejected | | Generated credentials | No | Login email and password for a test account, auto-generated and editable. Encrypted at rest and injected only into the sandbox | | Headers | No | Up to 20 custom browser headers. Encrypted at rest, applied only to requests to the application's hosts | | Request throttle | No | Cap requests between 1 and 600 per minute | | Specific prompt | No | A per-report goal prompt, up to 8,000 characters | | Additional files | No | Source archives, documents, or images for context. Dashboard only; not available through the API | If your WAF would block the scanner, the dashboard shows a static egress IP to allowlist when one is configured for your deployment. ### Scope and safety The run is scoped to the target URL's host, including its `www.` variant and subdomains. Credentials, custom headers, and the throttle apply only to requests to those hosts, never to third-party origins. Credentials and headers are encrypted at rest and are never returned by the API. ### Follow the run Application red-team reports open at `/app/reports/web-app/[id]`. While the agent works you can watch: - **Logs**: the live event feed of the agent's actions and reasoning - **Live browser**: the browser session in real time, or the recording afterwards - **Evidence**: recordings and screenshots captured during the run - **Findings**: issues as they are confirmed, linked to the full finding page From the report page you can **Rerun** the engagement or **Delete** the report. ### Findings Application findings appear in the [Findings](/docs/concepts/findings-and-reports) queue with kind `web_app_red_team`, alongside findings from repository reports and GitHub advisories. Triage and remediation work the same way for every kind. ### API and MCP `POST /api/v1/reports/web-app` starts a run programmatically with the same target, credential, header, throttle, and prompt fields, minus file attachments. The `create_web_app_report` [MCP tool](/docs/mcp) does the same from your coding agent. Both consume organization credits. See [Reports API](/docs/api/reports). ## Next steps - [Review findings and reports](/docs/concepts/findings-and-reports) - [Start runs with the Reports API](/docs/api/reports) - [Subscribe to report events with Webhooks](/docs/webhooks) 3b:Ta40,A repository Red Team run points a security agent at your codebase. The agent clones the repo into an isolated sandbox, chains findings together the way an attacker builds a kill chain, and records exploit paths with repro steps in the red-team report. Because the run uses the full repo as context, this is the gray-box option: it sees your code, not just your public surface. When the repository exposes a Web or network service that can run in the sandbox, Prime can use the upstream FuzzingLabs Nuclei MCP server against that live service. Nuclei results remain candidates until Prime reproduces them and connects them to repository evidence. ### Start a repository run 1. Open **Red team** and select **New report**, or go to `/app/reports/new`. 2. Choose **Repository**. 3. Select one or more repositories from the repos where Superagent Security is installed. 4. Optionally add a goal prompt to focus the engagement, then submit. Private repositories require the security app with repository contents access. Beyond manual creation, repository runs can trigger automatically on a GitHub release, a tag, or a schedule. ### Configure recurring runs 1. Open **Repository** and select a connected repository. 2. Enable **Red teaming** in its settings. 3. Choose releases, prereleases, release tags, or a daily, weekly, or monthly schedule. 4. Add a repository-specific goal when the campaign needs a narrower scope. 5. Select **New run** once to confirm repository access and the goal before relying on the trigger. ### The report detail page Repository red-team reports open at `/app/reports/repository/[id]`. The detail view includes: - Run status and the live agent event feed - Linked **findings** discovered during the run, each with repro context - Assignees and status updates for your team's review workflow - Cost and timing for the engagement ### Findings Discovered issues land in the [Findings](/docs/concepts/findings-and-reports) queue as `repository_red_team` findings. From there you can run automated triage to verify exploitability and turn confirmed issues into fix PRs. ### Relationship to PR scans Repository Red Team uses the same GitHub App installation as [PR Security](/docs/security-workers/pr-security). PR scans check every pull request before merge; Red Team runs are deeper engagements you start on demand or on a trigger. ## Next steps - [Review findings and reports](/docs/concepts/findings-and-reports) - [Add continuous PR Security](/docs/security-workers/pr-security) - [Automate remediation with Cursor](/docs/use-cases/continuous-adversarial-testing-with-cursor) 3c:T10fc,Agent Red Team runs perform automated black-box adversarial testing against a deployed AI agent. They discover capabilities, exercise relevant attack hypotheses, preserve evidence, and write verified security-boundary failures to a red-team report without requiring source-code access. ### Create and configure an Agent 1. Open **Agents → Connected** and select **Add new**. 2. Enter a name and select an agent type. 3. Optionally associate a connected repository. 4. For Coding Agents, copy the one-time Runtime Guardrails pairing command. 5. Open the Agent detail page and enable **Red teaming**. 6. Configure the application or API target, credentials, headers, throttle, schedule, and optional specific prompt. 7. Select **New run**, or allow the daily, weekly, or monthly schedule to start it. Each run is linked to the persistent Agent. Manual, scheduled, and API-triggered runs appear together on the Agent detail page and retain their full report detail. ### Start an ad hoc agent run 1. Open **Red team** and select **New report**, or go to `/app/reports/new`. 2. Choose **Agent**. 3. Select an **agent type** (chatbot, voice agent, coding agent, AI workflow, data pipeline, or other). 4. Choose the target type: **Application** or **API**. 5. Enter the public target URL, configure optional encrypted headers, and add a specific prompt when needed. 6. Submit to provision the isolated runner and open the live detail page. The report name defaults to the target host. Agent reports created in the dashboard are labeled **Manual** in the report list. Reports created through REST or MCP are labeled **API**. ### Application targets Use **Application** when the AI agent is accessed through a browser interface. Superagent generates test credentials that you can view, edit, or copy before starting the report. You can also add encrypted headers for staging gates, tenant selection, or authentication. The isolated runner interacts only with the configured origin. Browser interaction evidence can appear in the **Evidence** tab when recording is available. ### API targets Use **API** when the AI agent is exposed through an HTTP or WebSocket endpoint. Enter only the endpoint URL. Add authentication or tenant headers under **Headers**. Describe the API contract in **Specific prompt**, including: - HTTP method and example JSON payload - Where the attack prompt belongs - Required model or deployment identifier - Expected response or streaming shape For example: ```text POST JSON like: { "model": "qwen/qwen3.7-flash", "stream": false, "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "" } ] } ``` API reports expose **Logs** and **Findings**. They do not show browser evidence. ### REST API and MCP Programmatic clients can create and configure persistent Agents with: - `POST /api/v1/agents` and `PATCH /api/v1/agents/{agent_id}` - MCP tools `create_agent` and `update_agent` Use the Agent endpoints for reusable identity and scheduled configuration. For an ad hoc run, use: - `POST /api/v1/reports/agent` - MCP tool `create_agent_report` Both report operations accept `target_type` as `web_app` or `api`. See the [Agents API](/docs/api/agents) and [Reports API](/docs/api/reports) for request fields and examples. ### The agent detail page Each automated Agent report lives at `/app/reports/agent/[id]`. From there you can: - Follow expandable runner logs - Review findings and risk counts - Inspect the target, assignees, cost, and runtime status - Delete or rerun the report - Review browser evidence for application targets ### Test agents safely - Use dedicated test credentials and scoped API keys - Rotate any key pasted into logs or chat - Describe API payloads precisely in the specific prompt - Apply a request throttle when testing shared or metered targets - Pair agent tests with [repository reports](/docs/security-workers/red-team/repositories) when the agent depends on specific code or tools in a repo - Re-run tests after material model or policy changes ## Next steps - [Run an OWASP and MITRE ATLAS campaign](/docs/use-cases/red-team-agents-against-owasp-mitre) - [Manage persistent agents through the API](/docs/api/agents) - [Subscribe to report events with Webhooks](/docs/webhooks) 3d:T966,Package Red Team runs perform automated black-box adversarial testing against installable software. You supply installation instructions; Superagent provisions an isolated sandbox, follows those instructions, discovers the local attack surface, and tries to breach the installed package. ### Start a package run 1. Open **Red team** and select **New report**, or go to `/app/reports/new`. 2. Choose **Package**. 3. Enter **Installation instructions** (required): how to install and, if needed, start the package. 4. Optionally add a **Specific prompt** to steer the campaign. 5. Submit to provision the isolated runner and open the live detail page. Examples of installation instructions: ```text brew install foo ``` ```text npm i -g bar@1.2.3 bar --serve --port 8080 ``` ```text pip install baz==1.0.0 baz serve --host 127.0.0.1 ``` Package reports created in the dashboard are labeled **Manual** in the report list. Reports created through REST or MCP are labeled **API**. ### What the runner does In the sandbox, Superagent: 1. Follows your installation instructions 2. Discovers local surfaces such as CLIs, local ports, config files, and privilege boundaries 3. Runs adaptive attacks against those surfaces 4. Emits findings with reproduction steps and evidence The install instructions and any specific prompt are treated as untrusted input and execute only inside the isolated sandbox. Organization secrets are not injected. ### REST API and MCP Programmatic clients can start Package runs with: - `POST /api/v1/reports/package` - MCP tool `create_package_report` Both accept `installation_instructions` (required) and `custom_goal_prompt` (optional). See the [Reports API](/docs/api/reports) for request fields and examples. ### The package detail page Each Package report lives at `/app/reports/package/[id]`. From there you can: - Follow expandable runner logs - Review findings and risk counts - Inspect installation instructions, optional prompt, cost, and runtime status - Delete or rerun the report Findings also appear in the shared [Findings](/docs/concepts/findings-and-reports) queue. ## Next steps - [Review findings and reports](/docs/concepts/findings-and-reports) - [Understand supply chain scanning](/docs/security-workers/pr-security/supply-chain-scanning) - [Scan packages before installation](/docs/security-workers/agent-guardrails/extensions-and-packages) 3e:Te9f,Agents fetch packages, load web pages, install MCP servers, and clone repositories without reviewing any of it. Context Guardrails score every piece of external context before the agent trusts it, so agents keep full capability without inheriting untrusted input. This feature complements **Runtime Guardrails**, which decide what an agent may do. Context Guardrails decide what an agent may consume. PII and PHI use cases are excluded. Apply data classification and filtering before sending content to Context Guardrails. ## What gets scored | Entity | Status | What Superagent checks | | --- | --- | --- | | [Web pages](/docs/security-workers/agent-guardrails/web-and-files) | Available | Domain identity, page behavior, and page content before the agent reads the page | | [Email](/docs/security-workers/agent-guardrails/email-and-messages) | Available | Sender identity, phishing and injection patterns, attachments, and outbound links | | [Messages](/docs/security-workers/agent-guardrails/email-and-messages) | Available | Text and outbound HTTPS links from SMS, WhatsApp, and social messages; media and attachments are not scanned | | [Files](/docs/security-workers/agent-guardrails/web-and-files) | Available | Text and PDF contents, source identity, redirects, type consistency, encoded instructions, and prompt injection | | [Agent skills](/docs/security-workers/agent-guardrails/extensions-and-packages) | Available | GitHub publisher identity, requested capabilities, scripts, hidden instructions, exfiltration, and prompt injection | | [MCP repositories](/docs/security-workers/agent-guardrails/extensions-and-packages) | Available | Identity, tool descriptions, schemas, instructions, hooks, secrets, and executable behavior in a public GitHub repository | | [Packages](/docs/security-workers/agent-guardrails/extensions-and-packages) | Available | Registry artifacts for npm, PyPI, Go, RubyGems, and GitHub Actions, using the same supply chain pipeline as pull request scans | | Repositories | Covered by [repository red teaming](/docs/security-workers/red-team/repositories) | Agent-driven source review for vulnerabilities, backdoors, and unsafe behavior | MCP scans inspect repository contents only. They do not connect to a live MCP endpoint or execute the server. ## How scoring works Every entity is scored across three dimensions: who published it, how it behaves, and what it contains. Each check returns a score from 0–100, a verdict of `safe`, `caution`, `suspicious`, or `dangerous`, and a confidence level. Cached results are reused across organizations. New lookups return a preliminary identity score immediately and finish the deep scan in the background. Pass `mode=full` when you need the completed result in one request. See the page for each entity for the exact tiers, limits, and threat types. ## Use it - **Dashboard**: open **Agents** in the sidebar, then [Context](/app/agents/context). Submit a web page, email, message, file URL, skill target, public GitHub MCP repository, or package coordinate and open a result to see subscores, tiers, and threats. - **REST API**: see the [Context Guardrails API](/docs/api/context-guardrails). - **MCP**: `get_context_score` for pages, `scan_email` for raw RFC 822 email, `scan_message` for SMS and WhatsApp text, `scan_file` for file URLs, `scan_skill` for agent skills, `scan_mcp` for public GitHub MCP repositories, and `scan_package` for registry packages. ## Next steps - [Check Web pages and files](/docs/security-workers/agent-guardrails/web-and-files) - [Check email and messages](/docs/security-workers/agent-guardrails/email-and-messages) - [Check extensions and packages](/docs/security-workers/agent-guardrails/extensions-and-packages) 3f:T10ee,## Web pages Score a URL before an agent fetches or summarizes the page. Superagent checks who owns the domain, how the page behaves, and what the visible and hidden text says. ### How scoring works A page scan runs in three tiers: 1. **Identity** — domain age (RDAP), TLS certificate, registrar reputation, hosting ASN, and optional blocklists (URLhaus, Google Web Risk, PhishTank). 2. **Static analysis** — redirect chains, hidden DOM, deceptive links, prompt-injection and exfiltration patterns, and obfuscated JavaScript. 3. **Rendered review** — Kernel headless Chrome renders the page, then GPT-5.6 Luna Pro via OpenRouter scores the visible and hidden text. This tier runs when deterministic checks are uncertain. If Kernel is not configured, the LLM still reviews the static HTML. A blocklisted host short-circuits to score `0` / `dangerous`. New lookups return a preliminary identity score immediately and finish the deep scan in the background. Pass `mode=full` when you need the completed result in one request. ### Identifier The identifier is a hostname (`example.com` fetches `https://example.com/`) or a hostname plus path (`example.com/docs`). Hostnames are case-insensitive. Paths may include additional `/` segments. ### Use it - **Dashboard**: open **Agents → Context**, paste a URL, and open the result for identity, behavior, and content scores. - **REST API**: `GET /api/v1/context/web_page/{identifier}`. See the [Context Guardrails API](/docs/api/context-guardrails). - **MCP**: `get_context_score`. ```bash curl "https://superagent.sh/api/v1/context/web_page/example.com?details=true" \ -H "Authorization: Bearer sk_live_..." ``` ```bash curl "https://superagent.sh/api/v1/context/web_page/example.com/docs?mode=full&details=true" \ -H "Authorization: Bearer sk_live_..." ``` ## Files Score a public HTTP or HTTPS file before an agent opens it, embeds it, or treats it as instructions. Superagent checks the source, extracts a bounded text representation, and reviews that text for injection and exfiltration. ### How scoring works A file scan runs in three tiers: 1. **Identity** — source domain age, TLS, hosting, and blocklists. 2. **Secure extraction** — DNS pinned download with redirect validation, type consistency checks, and bounded extraction for text formats and PDFs. 3. **Content review** — deterministic prompt injection, exfiltration, social engineering, and encoded payload checks followed by chunked LLM review. File bytes are never stored. The identifier is the lowercase SHA-256 hex digest of the normalized URL. ### Supported files Supported files include UTF-8 text, HTML, JSON, XML, CSV, CSS, JavaScript, Markdown, YAML, SQL, and PDFs with extractable text. Downloads are limited to 25 MB. Images, Office documents, archives, encrypted PDFs, and PDFs that require OCR are reported as unscannable instead of safe. Invalid URLs and unsupported types return a dangerous result or `400 invalid_request`, depending on whether validation fails before the scan starts. ### Threats When `details=true` or the verdict is `suspicious` / `dangerous`, file scans may emit `file_unscannable`, `mime_mismatch`, `encoded_payload`, `redirect_chain`, extraction errors, and prompt-injection or exfiltration types shared with other origins. ### Use it - **Dashboard**: open **Agents → Context**, paste a public file URL, and open the result for identity, behavior, and content scores. - **REST API**: `POST /api/v1/context/file` to score a URL and `GET /api/v1/context/file/{identifier}` to look up a previous result by SHA-256. See the [Context Guardrails API](/docs/api/context-guardrails). - **MCP**: `scan_file`. ```bash curl "https://superagent.sh/api/v1/context/file?mode=full&details=true" \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ --data '{"url":"https://example.com/security-guidance.pdf"}' ``` ```bash curl "https://superagent.sh/api/v1/context/file/?details=true" \ -H "Authorization: Bearer sk_live_..." ``` `GET` never starts a new scan. ## Next steps - [Check email and messages](/docs/security-workers/agent-guardrails/email-and-messages) - [Use the Context Guardrails API](/docs/api/context-guardrails) - [Return to Context Guardrails](/docs/security-workers/agent-guardrails/context) 40:T518,Integrate Superagent Context Guardrails into this app's Resend inbound email pipeline. Read https://www.superagent.sh/docs/security-workers/agent-guardrails/email-and-messages and follow it. Do not send email or messages containing PII or PHI to Superagent. Apply the application's data classification and filtering before this integration. When Resend sends an email.received webhook: 1. Verify the webhook signature before trusting the payload. 2. Fetch the raw RFC 822 message from Resend's Receiving API. The webhook body is metadata only. 3. POST the raw bytes to https://superagent.sh/api/v1/context/email?mode=full&details=true with Authorization: Bearer $SUPERAGENT_API_KEY and Content-Type: message/rfc822. If the webhook timeout is too short, POST without mode=full, return 200, and poll GET /api/v1/context/email/{identifier} until pending_deep_scan is false. 4. If verdict is suspicious or dangerous, discard the message or alert. Treat caution as review before use. Process safe messages with the existing application logic. 5. Return 2xx for both processed and blocked messages so Resend does not retry. Use SUPERAGENT_API_KEY and RESEND_API_KEY from the environment. Do not hardcode secrets. Match this repository's language and framework. Ask before changing files I have not mentioned.41:T6660,Use this capability only for approved content that does not contain PII or PHI. Apply data classification and filtering before sending raw email or message text to Superagent. ## Email Score a raw RFC 822 / `.eml` message before an agent reads it, summarizes it, or follows links inside it. ### How scoring works An email scan runs in three tiers: 1. **Identity** — From domain RDAP/TLS/blocklists, SPF/DKIM/DMARC from `Authentication-Results`, display-name mismatch, and Reply-To divergence. A blocklisted sender short-circuits to score `0`. 2. **Body and attachments** — prompt injection, exfiltration, urgency, brand impersonation, hidden HTML, encoded payloads, and dangerous attachment types. Up to eight public `https` links are followed with the [web-page scanner](/docs/security-workers/agent-guardrails/web-and-files). 3. **LLM review** — always runs unless the sender is blocklisted. Looks for phishing, brand impersonation, and hidden agent instructions. The raw message is not stored on the artifact. Cache lookup uses the SHA-256 of the raw bytes. Invalid identifiers or RFC 822 bodies return `400 invalid_request`. Unknown email identifiers return `404 not_found`. ### Threats When `details=true` or the verdict is `suspicious` / `dangerous`, email scans may emit `spf_fail`, `display_name_mismatch`, `brand_impersonation`, `malicious_attachment`, `phishing`, and prompt-injection or exfiltration types shared with other origins. ### Use it - **Dashboard**: open **Agents → Context**, paste a raw message, and open the result for identity, behavior, and content scores. - **REST API**: `POST /api/v1/context/email` to score raw email and `GET /api/v1/context/email/{identifier}` to look up a previous result. See the [Context Guardrails API](/docs/api/context-guardrails). - **Resend**: scan inbound mail from a receiving domain. See [Resend](/docs/security-workers/agent-guardrails/email-and-messages). - **Bird**: handle `email.received`, fetch the stored raw RFC 5322 message, and run the full email scan. See [Bird](/docs/security-workers/agent-guardrails/email-and-messages). - **MCP**: `scan_email`. ### Submit an email Use `Content-Type: message/rfc822` or `text/plain`. Raw bodies larger than 1 MB are rejected. ```bash curl "https://superagent.sh/api/v1/context/email?details=true" \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: message/rfc822" \ --data-binary @message.eml ``` ```bash curl "https://superagent.sh/api/v1/context/email/?details=true" \ -H "Authorization: Bearer sk_live_..." ``` To rescan an email, `POST` the raw body again. `GET` never starts a new scan. ## Messages Score a normalized SMS, WhatsApp, or social message before an agent reads it or follows a link inside it. The message endpoint scans text and outbound `https` links. It does not scan media or attachments. Use the [email endpoint](/docs/security-workers/agent-guardrails/email-and-messages) instead for email. Email scans can inspect sender identity and, when you submit raw RFC 822, authentication headers, MIME structure, and attachments. ### Request Send `application/json` to `POST /api/v1/context/message`: | Field | Type | Required | Description | | --- | --- | --- | --- | | `text` | string | yes | Message text to scan | | `channel` | string | no | Provider-neutral channel label such as `sms`, `whatsapp`, or `instagram` | | `links` | string[] | no | Outbound `https` links associated with the message | ```bash curl "https://superagent.sh/api/v1/context/message?mode=full&details=true" \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ --data '{ "text": "Review the account notice at https://login.example.net/reset", "channel": "whatsapp", "links": ["https://login.example.net/reset"] }' ``` The response uses the standard [Context Guardrails API envelope](/docs/api/context-guardrails). Use `mode=full` when you need the completed verdict in the same request, and use `details=true` to include all detected threats. The artifact identifier is the SHA-256 digest of the canonical channel, text, and link fields. Look up a completed result without starting another scan: ```bash curl "https://superagent.sh/api/v1/context/message/?details=true" \ -H "Authorization: Bearer sk_live_..." ``` ### What gets scanned Message scans evaluate untrusted text for phishing, credential harvesting, social engineering, prompt injection, and exfiltration patterns. Outbound `https` links are checked as web content. Identity is not scored for social messages. The identity sub-score is a neutral compatibility value with zero weight, and the identity tier is reported as skipped. Completed message confidence is capped at `medium`. The endpoint is intentionally text only. Images, audio, video, documents, stickers, and other media are out of scope. Do not treat a safe message verdict as a verdict on omitted media or attachments. ### Integrate a provider Verify the provider's webhook signature against the raw request before parsing or normalizing the payload. Then map its text, channel name, and outbound `https` links into the provider-neutral request above. For Bird Channels webhooks, see the [Bird integration](/docs/security-workers/agent-guardrails/email-and-messages). ## Resend [Resend](https://resend.com/docs/introduction) is an email API for developers. Wire Context Guardrails into Resend's inbound webhook pipeline to scan approved inbound messages for phishing, credential harvesting, prompt injection, and social engineering before your application processes them. This configuration excludes messages containing PII or PHI. Apply the application's data classification and filtering before fetching or sending raw email to Superagent. Do not log sender addresses, message bodies, or other personal data. ### Prerequisites - a Superagent organization API key from [Settings](/docs/reference/settings) - a [Resend account](https://resend.com) and API key - a [receiving domain](https://resend.com/docs/dashboard/receiving/introduction) restricted to synthetic or approved messages without PII or PHI - a publicly reachable HTTPS endpoint to receive webhooks ### How it works ```mermaid flowchart TD A[Incoming email] --> B[Resend inbound] B --> C["email.received webhook"] C --> D["Fetch raw email via Receiving API"] D --> E["POST /api/v1/context/email"] E -->|safe or caution| F[Process email] E -->|suspicious or dangerous| G[Discard / alert] ``` Resend fires an `email.received` webhook when a message arrives at your receiving domain. The webhook payload contains metadata only (`from`, `to`, `subject`, `email_id`) — not the email body. Your handler fetches the raw email via Resend's [Receiving API](https://resend.com/docs/api-reference/emails/retrieve-received-email) and POSTs it to Superagent's [`/context/email`](/docs/api/context-guardrails) endpoint. Sending the raw RFC 822 content preserves headers, MIME structure, and authentication signals (SPF, DKIM) for more accurate phishing and identity checks. If the verdict is `suspicious` or `dangerous`, the handler discards the email or triggers an alert. Treat `caution` as review-before-use. ### Setup **1. Configure an `email.received` webhook** In the [Resend dashboard](https://resend.com/webhooks), add a webhook subscribed to the `email.received` event pointing at your handler URL. Verify webhook signatures before you trust the payload. You can also create the webhook via the SDK: ```python import resend resend.api_key = "re_..." resend.Webhooks.create({ "url": "https://your-server.com/webhooks/resend", "events": ["email.received"], }) ``` ```typescript import { Resend } from "resend"; const resend = new Resend("re_..."); await resend.webhooks.create({ url: "https://your-server.com/webhooks/resend", events: ["email.received"], }); ``` **2. Build a webhook handler that scans with Superagent** When an `email.received` event arrives, fetch the raw email from the Receiving API and POST it to Superagent. Use `mode=full` so the handler waits for the completed score (up to 90 seconds) instead of a preliminary identity result. Set your HTTP client timeout accordingly. If your platform's webhook timeout is shorter than that, POST without `mode=full`, return `200` to Resend, and poll `GET /api/v1/context/email/{identifier}` until `pending_deep_scan` is `false`. ```python import os import httpx import resend from fastapi import FastAPI, Request app = FastAPI() resend.api_key = os.environ["RESEND_API_KEY"] @app.post("/webhooks/resend") async def handle_email_received(request: Request): # Bind this handler only to the restricted receiving domain described above. event = await request.json() if event.get("type") != "email.received": return {"status": "ignored"} email = resend.Emails.Receiving.get(email_id=event["data"]["email_id"]) download_url = (email.get("raw") or {}).get("download_url") if not download_url: return {"status": "error", "message": "raw email not available"} async with httpx.AsyncClient(timeout=90.0) as http: eml = await http.get(download_url) eml.raise_for_status() scan = await http.post( "https://superagent.sh/api/v1/context/email?mode=full&details=true", content=eml.content, headers={ "Authorization": f"Bearer {os.environ['SUPERAGENT_API_KEY']}", "Content-Type": "message/rfc822", }, ) scan.raise_for_status() artifact = scan.json()["data"] verdict = artifact.get("verdict", "safe") if verdict in ("suspicious", "dangerous"): print( f"Blocked email: verdict={verdict}, score={artifact.get('score')}" ) return {"status": "blocked", "verdict": verdict} # Deliver the message to your agent or application. return {"status": "processed"} ``` ```typescript import { Resend } from "resend"; import type { NextRequest } from "next/server"; import { NextResponse } from "next/server"; const resend = new Resend(process.env.RESEND_API_KEY); export const POST = async (request: NextRequest) => { // Bind this handler only to the restricted receiving domain described above. const event = await request.json(); if (event.type !== "email.received") { return NextResponse.json({ status: "ignored" }); } const { data: email } = await resend.emails.receiving.get( event.data.email_id, ); const downloadUrl = email?.raw?.download_url; if (!downloadUrl) { return NextResponse.json( { status: "error", message: "raw email not available" }, { status: 500 }, ); } const eml = await fetch(downloadUrl); const emlBody = await eml.text(); const scan = await fetch( "https://superagent.sh/api/v1/context/email?mode=full&details=true", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUPERAGENT_API_KEY}`, "Content-Type": "message/rfc822", }, body: emlBody, signal: AbortSignal.timeout(90_000), }, ); const payload = await scan.json(); const artifact = payload.data; const verdict = artifact.verdict ?? "safe"; if (verdict === "suspicious" || verdict === "dangerous") { console.log( `Blocked email: verdict=${verdict}, score=${artifact.score}`, ); return NextResponse.json({ status: "blocked", verdict }); } // Deliver the message to your agent or application. return NextResponse.json({ status: "processed" }); }; ``` Return `2xx` for both processed and blocked messages so Resend does not retry a scan you already completed. **3. Deploy and test** Deploy your webhook handler and send a test email to your Resend receiving address. Check the logs to confirm Superagent is scanning each message and returning a verdict. ### What gets detected Context Guardrails checks sender identity, the body and attachments, and outbound links. See [email scoring](/docs/security-workers/agent-guardrails/email-and-messages) for the full scan model. | Threat | Description | | --- | --- | | **phishing** | Credential harvesting, urgency lures, or dangerous followed links | | **social_engineering** | Deceptive content designed to manipulate a person or agent | | **prompt_injection** | Hidden instructions aimed at an agent that reads the message | | **exfiltration** | Patterns designed to leak session data or secrets | | **brand_impersonation** | Message impersonates a known brand from an unrelated sender domain | | **malicious_attachment** | Dangerous attachment types | | **spf_fail** / **display_name_mismatch** | Sender authentication or display-name problems | Each threat is assigned a severity (`critical`, `high`, `medium`, `low`). Pass `details=true` to include `threats` even when the verdict is `safe`. ### Using the response The Superagent response follows the standard [API envelope](/docs/api/context-guardrails): ```json { "data": { "object": "context_artifact", "id": "00000000-0000-4000-8000-000000000001", "origin": "email", "identifier": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "url": "email:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "score": 15, "verdict": "dangerous", "confidence": "high", "tolerance": "conservative", "scanned_at": "2026-09-01T12:00:00.000Z", "pending_deep_scan": false, "threats": [ { "type": "phishing", "severity": "critical", "detail": "Credential harvesting form targeting Google login" } ] } } ``` Verdicts are `safe`, `caution`, `suspicious`, and `dangerous`. You can also read them from response headers (`x-superagent-verdict`, `x-superagent-score`, `x-superagent-confidence`, `x-superagent-tolerance`) for lightweight checks without parsing JSON. ## Bird [Bird](https://bird.com) provides email, SMS, WhatsApp, and social messaging APIs. Put Context Guardrails between Bird and your agent so untrusted content is scored before the agent reads it or follows links. This guide uses Bird's current Standard Webhooks contract consistently for `email.received`, `sms.received`, and `whatsapp.received`. ### Agent prompt Copy this prompt into your coding agent to wire up the Bird flow: ```text Integrate Superagent Context Guardrails into this app's Bird inbound messaging pipeline. Read https://www.superagent.sh/docs/security-workers/agent-guardrails/email-and-messages and follow it. Do not send email or messages containing PII or PHI to Superagent. Apply the application's data classification and filtering before this integration. 1. Subscribe one Bird Standard Webhooks endpoint to email.received, sms.received, and whatsapp.received. 2. Verify webhook-id, webhook-timestamp, and webhook-signature against the raw request body with BIRD_WEBHOOK_SECRET. 3. Deduplicate on webhook-id, persist the verified event, enqueue processing, and return 2xx within five seconds. 4. For email.received, fetch GET /v1/email/inbound-messages/{inbound_message_id}/raw and POST the RFC 5322 bytes to https://superagent.sh/api/v1/context/email?mode=full&details=true with Content-Type: message/rfc822. 5. For sms.received and whatsapp.received, extract the text content and POST it to https://superagent.sh/api/v1/context/message?mode=full&details=true with the channel name. 6. Do not claim media or attachments were scanned by the message endpoint. Block or alert on suspicious or dangerous. Treat caution as review before use. Use SUPERAGENT_API_KEY, BIRD_API_KEY, BIRD_API_BASE_URL, and BIRD_WEBHOOK_SECRET from the environment. Do not hardcode secrets. ``` ### Prerequisites - a Superagent organization API key from [Settings](/docs/reference/settings) - a Bird workspace with inbound email or messaging channels configured - a Bird regional API key - a publicly reachable HTTPS webhook endpoint - a stored Standard Webhooks signing secret ### How it works ```mermaid flowchart TD A[Inbound Bird content] --> C["Standard Webhook"] C --> D[Verify signature] D --> E["Fetch /v1/email/inbound-messages/{id}/raw"] D --> I["Extract SMS or WhatsApp text"] E --> F["POST /api/v1/context/email"] I --> messageApi["POST /api/v1/context/message"] F --> K{Verdict} messageApi --> K K -->|safe| L[Deliver to agent] K -->|caution| M[Review] K -->|suspicious or dangerous| N[Quarantine or alert] ``` ### Standard Webhooks setup #### 1. Subscribe to inbound events Create a Standard Webhooks endpoint in **Developers → Webhooks**, with the Bird CLI, or through `POST /v1/webhooks`. Use the regional host and matching key for your workspace, such as `https://us1.platform.bird.com` or `https://eu1.platform.bird.com`. ```bash curl --request POST "$BIRD_API_BASE_URL/v1/webhooks" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "url": "https://your-server.com/webhooks/bird", "events": ["email.received", "sms.received", "whatsapp.received"], "description": "Scan inbound messages before agent delivery" }' ``` The response returns a `whsec_...` secret once. Store it as `BIRD_WEBHOOK_SECRET`. #### 2. Verify and queue the webhook Bird Standard Webhooks sends `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Verify the signature over the untouched request body and reject timestamps more than five minutes old. Bird requires a response within five seconds, so durably enqueue the verified event before returning `2xx`. ```typescript import { createHmac, timingSafeEqual } from "node:crypto"; function verifyBirdWebhook( rawBody: string, headers: Headers, secret: string, ) { const id = headers.get("webhook-id") ?? ""; const timestamp = headers.get("webhook-timestamp") ?? ""; const signatures = headers.get("webhook-signature") ?? ""; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key) .update(`${id}.${timestamp}.${rawBody}`) .digest(); return signatures.split(" ").some((part) => { const received = Buffer.from(part.replace(/^v1,/, ""), "base64"); return ( received.length === expected.length && timingSafeEqual(received, expected) ); }); } export async function POST(request: Request) { const rawBody = await request.text(); if ( !verifyBirdWebhook( rawBody, request.headers, process.env.BIRD_WEBHOOK_SECRET ?? "", ) ) { return Response.json({ error: "invalid signature" }, { status: 401 }); } const event = JSON.parse(rawBody); const supported = new Set([ "email.received", "sms.received", "whatsapp.received", ]); if (!supported.has(event.type)) { return Response.json({ status: "ignored" }); } // Atomically deduplicate on webhook-id and persist before acknowledging. await enqueueInboundEvent({ webhookId: request.headers.get("webhook-id"), event, }); return Response.json({ status: "queued" }, { status: 202 }); } ``` The handler only depends on the stable envelope fields needed for scanning: ```json { "type": "email.received", "timestamp": "2026-09-03T12:00:00Z", "data": { "inbound_message_id": "inm_01k4example", "subject": "Account review", "authentication": "pass", "spf": "pass", "dkim": "pass", "dmarc": "pass" } } ``` ### Inbound email Bird's [receiving email documentation](https://docs.bird.com/api/channels-api/supported-channels/programmable-email/receiving-messages) defines the email-specific processing flow: 1. Bird emits `email.received` after storing and parsing the message. 2. `data.inbound_message_id` identifies the stored inbound email. 3. `GET /v1/email/inbound-messages/{id}/raw` returns the original RFC 5322 MIME message. Fetching the raw message preserves sender headers, SPF/DKIM/DMARC results, MIME structure, attachment names, HTML, text, and links for the full Superagent email scan. #### Fetch the raw email and scan it Run this in the queued worker: ```typescript async function processInboundEmail(inboundMessageId: string) { const rawEmail = await fetch( `${process.env.BIRD_API_BASE_URL}/v1/email/inbound-messages/${encodeURIComponent(inboundMessageId)}/raw`, { headers: { Authorization: `Bearer ${process.env.BIRD_API_KEY}`, }, }, ); if (!rawEmail.ok) { throw new Error(`Bird raw email fetch failed: ${rawEmail.status}`); } const scan = await fetch( "https://superagent.sh/api/v1/context/email?mode=full&details=true", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUPERAGENT_API_KEY}`, "Content-Type": "message/rfc822", }, body: await rawEmail.arrayBuffer(), signal: AbortSignal.timeout(90_000), }, ); if (!scan.ok) { throw new Error(`Superagent email scan failed: ${scan.status}`); } const artifact = (await scan.json()).data; if ( artifact.verdict === "suspicious" || artifact.verdict === "dangerous" ) { return { status: "blocked", artifact }; } if (artifact.verdict === "caution") { return { status: "review", artifact }; } // Deliver the raw email or approved extracted content to the agent. return { status: "processed", artifact }; } ``` Python uses the same sequence: ```python import os import httpx async def process_inbound_email(inbound_message_id: str): async with httpx.AsyncClient(timeout=90.0) as client: raw = await client.get( ( f"{os.environ['BIRD_API_BASE_URL']}/v1/email/" f"inbound-messages/{inbound_message_id}/raw" ), headers={"Authorization": f"Bearer {os.environ['BIRD_API_KEY']}"}, ) raw.raise_for_status() scan = await client.post( ( "https://superagent.sh/api/v1/context/email" "?mode=full&details=true" ), content=raw.content, headers={ "Authorization": ( f"Bearer {os.environ['SUPERAGENT_API_KEY']}" ), "Content-Type": "message/rfc822", }, ) scan.raise_for_status() artifact = scan.json()["data"] if artifact["verdict"] in ("suspicious", "dangerous"): return {"status": "blocked", "artifact": artifact} if artifact["verdict"] == "caution": return {"status": "review", "artifact": artifact} return {"status": "processed", "artifact": artifact} ``` ### SMS and WhatsApp Bird's current [SMS events](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/receiving-messages) and [WhatsApp events](https://docs.bird.com/api/channels-api/supported-channels/programmable-whatsapp/receiving-messages) use the same Standard Webhooks envelope and verifier as email. `sms.received` carries the inbound body, both phone numbers, and segment metadata. `whatsapp.received` carries one content arm such as `text`, `interactive_reply`, `image`, `document`, or another supported WhatsApp type. Send only textual content to the message endpoint: ```typescript function receivedText(event: { type: string; data?: Record; }) { if (event.type === "sms.received") { const body = event.data?.body; return typeof body === "string" ? body : body?.text; } if (event.type === "whatsapp.received") { const text = event.data?.text; return typeof text === "string" ? text : text?.text; } return undefined; } async function processInboundMessage(event: { type: "sms.received" | "whatsapp.received"; data: Record; }) { const text = receivedText(event); if (!text) { return { status: "ignored", reason: "media and attachments are not scanned", }; } const scan = await fetch( "https://superagent.sh/api/v1/context/message?mode=full&details=true", { method: "POST", headers: { Authorization: `Bearer ${process.env.SUPERAGENT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ text, channel: event.type.replace(/\.received$/, ""), }), }, ); if (!scan.ok) { throw new Error(`Superagent message scan failed: ${scan.status}`); } const artifact = (await scan.json()).data; if ( artifact.verdict === "suspicious" || artifact.verdict === "dangerous" ) { return { status: "blocked", artifact }; } if (artifact.verdict === "caution") { return { status: "review", artifact }; } return { status: "processed", artifact }; } ``` The message verdict covers text and outbound HTTPS links only. It does not cover images, audio, video, documents, stickers, or attachments. For another social platform, first confirm its current inbound event in the workspace event catalog and subscribe to that exact event type. Keep the same Standard Webhooks verification and normalization flow; do not fall back to the legacy signature contract in this integration. ### Test it 1. Use Bird's webhook test send to verify connectivity and signature handling. Test sends contain only a minimal event stub. 2. Send a real message to a Bird forwarding address or receiving domain for an end-to-end email test. 3. Confirm the worker fetches `/raw`, Superagent reports `origin: "email"`, and the email artifact includes authentication, MIME, attachment, and link evidence. 4. Send a test SMS or social message and confirm it produces `origin: "message"`. Verdicts are `safe`, `caution`, `suspicious`, and `dangerous`. Return `2xx` only after the webhook event is durably queued. Bird retries failed Standard Webhook deliveries up to eight times. ## Next steps - [Use the Context Guardrails API](/docs/api/context-guardrails) - [Quarantine hostile email before agent delivery](/docs/use-cases/quarantine-hostile-email-before-agent-delivery) - [Monitor resulting actions with Runtime Guardrails](/docs/security-workers/agent-guardrails/runtime) 42:T1e74,## Agent skills Score a GitHub hosted agent skill before an agent installs it or follows its instructions. Superagent treats every skill file as untrusted data and never executes fetched code. ### How scoring works A skill scan accepts a skills.sh URL, a GitHub URL pointing to a skill directory, or an `owner/repository/skill` identifier. The scan runs in three tiers: 1. **Identity** — GitHub owner and repository age, stars, contributors, license, and archive or fork status. 2. **Static analysis** — bounded retrieval of `SKILL.md`, scripts, rules, and references followed by checks for secret access, remote execution, install hooks, shadow chaining, and excessive scope. 3. **Content review** — deterministic instruction manipulation and exfiltration checks followed by semantic review of each bounded text chunk. The identifier is the lowercase SHA-256 digest of the canonical skill identity. The scanner resolves the current Git commit and never executes fetched code. ### Limits Your organization must install the Superagent Security GitHub App before scanning skills. Superagent uses short lived installation credentials and does not require a personal access token. Private skill repositories are not supported. A scan reads at most 200 files, 512 KB per file, and 2 MB in total. ### Threats When `details=true` or the verdict is `suspicious` / `dangerous`, skill scans may emit `skill_description_injection`, `skill_credential_parameter_extraction`, `skill_output_poisoning`, `skill_shadow_chaining_external_installation`, `skill_scope_violation`, `skill_hidden_encoded_instructions`, `skill_remote_execution`, `skill_secrets`, `skill_install_hooks`, and `skill_unscannable`. ### Use it - **Dashboard**: open **Agents → Context**, paste a skill target, and open the result for identity, behavior, and content scores. - **REST API**: `POST /api/v1/context/skill` to score a skill and `GET /api/v1/context/skill/{identifier}` to look up a previous result by SHA-256. See the [Context Guardrails API](/docs/api/context-guardrails). - **MCP**: `scan_skill`. The `target` may be a skills.sh URL, `owner/repository/skill`, or a GitHub tree URL pointing to the skill directory. ```bash curl "https://superagent.sh/api/v1/context/skill?mode=full&details=true" \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ --data '{"target":"https://skills.sh/vercel-labs/skills/find-skills"}' ``` `GET` never starts a new scan. ## MCP repositories Score a public GitHub repository that contains an MCP server before an agent installs or connects to it. Superagent inspects repository contents only. It does not connect to a live MCP endpoint or execute the server. ### How scoring works An MCP scan accepts `owner/repository` or a repository URL in the form `https://github.com/owner/repository` with an optional `.git` suffix. The scan runs in three tiers: 1. **Identity** — GitHub owner and repository age, stars, contributors, license, and archive or fork status. 2. **Static analysis** — bounded retrieval of manifests, MCP configuration, tool definitions, schemas, source, scripts, and install hooks. The scanner checks for tool shadowing, credential harvesting, exfiltration, excessive scope, secrets, remote execution, and hidden instructions. 3. **Semantic analysis** — reviews tool names, descriptions, schemas, instructions, and relevant source for description injection, instruction injection, output poisoning, schema abuse, and silent capability escalation. The identifier is the lowercase SHA-256 digest of the canonical `owner/repository` identity. Superagent resolves the current Git commit and treats every fetched file as untrusted data. ### Limits MCP scans are GitHub only and require the Superagent Security GitHub App. Only public repositories are supported. A scan reads at most 200 files, 512 KB per file, and 2 MB in total. Materialization and scan failures fail closed, producing `mcp_unscannable` rather than a safe result. ### Threats When `details=true` or the verdict is `suspicious` / `dangerous`, MCP scans may emit `mcp_tool_shadowing`, `mcp_description_injection`, `mcp_instruction_injection`, `mcp_schema_abuse`, `mcp_output_poisoning`, `mcp_silent_capability_escalation`, `mcp_credential_harvesting`, `mcp_exfiltration`, `mcp_excessive_scope`, `mcp_hidden_encoded_instructions`, `mcp_remote_execution`, `mcp_secrets`, `mcp_install_hooks`, and `mcp_unscannable`. ### Use it - **Dashboard**: open **Agents → Context**, paste a public GitHub MCP repository, and open the result for identity, behavior, and content scores. - **REST API**: `POST /api/v1/context/mcp` to score a repository and `GET /api/v1/context/mcp/{identifier}` to look up a previous result by SHA-256. See the [Context Guardrails API](/docs/api/context-guardrails). - **MCP**: `scan_mcp`. ```bash curl "https://superagent.sh/api/v1/context/mcp?mode=full&details=true" \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ --data '{"target":"modelcontextprotocol/servers"}' ``` ```bash curl "https://superagent.sh/api/v1/context/mcp/?details=true" \ -H "Authorization: Bearer sk_live_..." ``` `GET` never starts a new scan. ## Registry packages Score a registry package before an agent installs it. Superagent uses the same supply chain pipeline as [pull request supply chain scanning](/docs/security-workers/pr-security) and maps that intelligence into identity, behavior, and content scores. ### How scoring works A package scan accepts `ecosystem:name@version`, for example `npm:lodash@4.17.21` or `pypi:requests@2.32.3`. The scan runs in three tiers: 1. **Identity** — package age, weekly downloads, maintainers, quality, and maintenance signals from package intelligence. 2. **Behavior** — install hooks, network access, and other package-scoped alerts. 3. **Content** — the same LLM risk assessment used by supply chain scanning on pull requests, inverted into a 0–100 safety score. The identifier is the lowercase SHA-256 digest of the canonical coordinate. Aliases `pip` (PyPI), `gem` (RubyGems), and `actions` (GitHub Actions) are accepted. ### Supported ecosystems Supported ecosystems are npm, PyPI, Go, RubyGems, and GitHub Actions. Scan failures fail closed, producing `package_unscannable` rather than a safe result. Pull request dependency checks continue to use this pipeline automatically when a supported lockfile changes. ### Threats When `details=true` or the verdict is `suspicious` / `dangerous`, package scans may emit `package_network_access`, `package_install_hooks`, `package_credential_access`, and `package_unscannable` when package intelligence or the risk assessment reports those behaviors. ### Use it - **Dashboard**: open **Agents → Context**, paste a package coordinate, and open the result for identity, behavior, and content scores. - **REST API**: `POST /api/v1/context/package` to score a coordinate and `GET /api/v1/context/package/{identifier}` to look up a previous result by SHA-256. See the [Context Guardrails API](/docs/api/context-guardrails). - **MCP**: `scan_package`. ```bash curl "https://superagent.sh/api/v1/context/package?mode=full&details=true" \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ --data '{"target":"npm:lodash@4.17.21"}' ``` ```bash curl "https://superagent.sh/api/v1/context/package/?details=true" \ -H "Authorization: Bearer sk_live_..." ``` `GET` never starts a new scan. ## Next steps - [Understand supply chain scanning](/docs/security-workers/pr-security/supply-chain-scanning) - [Red-team a package](/docs/security-workers/red-team/packages) - [Return to Context Guardrails](/docs/security-workers/agent-guardrails/context) 43:T20a6,Runtime Guardrails run on each endpoint. Events are normalized and evaluated locally. By default, only findings, enforcement decisions, and client health are delivered to Superagent; the full normalized event stream stays on the endpoint. This feature is separate from **Agent reports**, which perform black-box adversarial tests against a deployed AI agent. For scoring external content before agents consume it, see [Context Guardrails](/docs/security-workers/agent-guardrails/context). ## Register and pair a client Organization owners can register clients. When an organization has no clients, **Agents** opens a three-step introduction to monitoring and enforcement, supported coding agents, and webhook delivery. Owners can continue directly into client registration. Other members can review the same overview and ask an organization owner to complete setup. 1. Open **Agents** in the sidebar, then **Runtime**. 2. Select **Register client** and give the installation a recognizable name. 3. Copy the one-time pairing command. The token expires after 15 minutes and is consumed by the first successful pairing. 4. Run the command on the local workstation, cloud runner, or agent host. ```bash curl -fsSL https://superagent.sh/install.sh | sh -s -- connect \ --client-id CLIENT_ID \ --pairing-token ONE_TIME_TOKEN \ --api-url https://www.superagent.sh ``` The installer downloads the standalone executable for the current platform from the latest GitHub Release, verifies its SHA-256 checksum, and installs it to `~/.local/bin` without `sudo`. It then passes the remaining arguments to the installed `superagent` executable. Node.js, npm, and npx are not required. Installation is required only once per machine. The background shipper checks for CLI updates when it starts and every six hours. It verifies the release checksum, atomically replaces the executable, and restarts itself on the new version without interrupting record delivery. Run `superagent update` to check immediately, or set `SUPERAGENT_AUTO_UPDATE=0` in the shipper environment to disable automatic updates. Clients installed before auto-update support must rerun the installer once; the installer restarts an already-running shipper after upgrading it. The pairing token is exchanged for a revocable client credential. Superagent stores only credential hashes. The CLI stores the plaintext credential in its local configuration with owner-only file permissions. The same command syncs the effective rules, installs Claude monitoring, and starts a detached record shipper. No additional setup command is required. Claude is the safe default. To monitor another supported agent, add `--agent NAME`, for example: ```bash curl -fsSL https://superagent.sh/install.sh | sh -s -- connect \ --client-id CLIENT_ID \ --pairing-token ONE_TIME_TOKEN \ --api-url https://www.superagent.sh \ --agent cursor ``` For self-hosted deployments, pass the control-plane origin: ```bash curl -fsSL https://superagent.example.com/install.sh | sh -s -- connect \ --client-id CLIENT_ID \ --pairing-token ONE_TIME_TOKEN \ --api-url https://superagent.example.com ``` ## Groups and effective rules A client can belong to multiple groups. Its effective rule catalog is the deterministic union of rules assigned to those groups. Rule IDs are unique within an organization. Assigning the same rule to multiple groups does not duplicate it. A custom rule with the same ID as a built-in rule replaces that built-in rule. Use the **Groups** tab to create groups and the client table to manage membership. Use the **Rules** tab to write YAML security rules and assign them to groups. ```yaml id: acme.secrets.env_read version: "1.0" title: Environment file read severity: high expr: |- event.event_type == "file.read" && event.file_path.matches("(^|/)\\.env$") ``` Superagent validates the YAML structure when it is saved. The endpoint performs authoritative rule validation before activation. Invalid updates are rejected locally and the last known-good catalog remains active. See [Creating rules](/docs/security-workers/agent-guardrails/rules) for the rule assistant, YAML schema, sequence rules, and enforcement behavior. ## Programmatic management Organization API keys can manage clients, groups, rules, pairing tokens, and alerts through the REST API or MCP. See the [Agents API](/docs/api/agents) for endpoints and examples. ## Review activity and alerts Durable rule findings and enforcement decisions appear under **Agents → Findings** and in **Notifications**. Select the **Agent monitoring** notification filter to review them across pages. A blocked action produces one notification that unifies the finding and enforcement decision instead of separate finding and deny notifications. Organization webhooks can send the same durable alerts to external systems. Subscribe to `agent.finding_created` for detections and `agent.action_blocked` for denied actions from **Webhooks** in the sidebar. See [Webhooks](/docs/webhooks) for payloads, signatures, and retries. Notification details show only the redacted evidence included in a finding or enforcement decision. Superagent does not upload or expose the full normalized endpoint event stream. ## Manage live monitoring The pairing command installs and starts live Claude monitoring automatically. Check both the hook and background shipper: ```bash superagent monitor status --agent claude ``` The CLI writes findings and enforcement decisions to `~/.config/superagent/records.ndjson`. The detached shipper checkpoints acknowledged offsets, retries failed delivery with exponential backoff, sends a heartbeat, polls Superagent for rule updates, and installs checksum-verified CLI updates. Its PID state and log are private files in the same Superagent configuration directory. Start or stop background shipping explicitly with: ```bash superagent monitor start superagent monitor stop ``` `superagent monitor start` is idempotent: it reports an already-running shipper instead of starting a duplicate, and replaces stale PID state. To run shipping in the foreground under your own process manager, keep using: ```bash superagent monitor ship ``` For a manual agent override after connecting, install that agent's hooks and ensure the shipper is running: ```bash superagent monitor install --agent codex superagent monitor start ``` Remove hooks with `superagent monitor uninstall --agent codex`. Stopping the shipper is separate because another installed agent may still be writing records. ## Monitor and enforce modes Hook installs enable enforce capability by default. Per-rule Mode controls the outcome: - **Monitor** (default) — record a finding when the rule matches; do not block. - **Enforce** — deny the matching action and record the finding plus enforcement decision. Set Mode in the Rules UI, or set `enforce: true` in the rule YAML. Severity does not enable blocking; it only prioritizes the resulting alert. ```yaml enforce: true deny_message: Contact your security team before accessing this file. ``` ## Scan existing artifacts Read-only scans use the same effective rule catalog: ```bash superagent scan superagent scan --agent codex ``` ## Supported platforms The standalone `superagent` executable contains the pinned Numbat engine and supports: - macOS arm64 and x64 - Linux arm64 and x64 Release assets are named `superagent--`. The release pipeline publishes SHA-256 checksums, signs the checksum manifest, and signs and notarizes macOS executables. Windows and managed fleet/MDM deployment are not included in the initial release. ## Revocation and local cleanup Use **Revoke** on the client in the Agents UI to invalidate all of its credentials immediately. Creating a new pairing token does not by itself revoke an active credential; completing the new pairing rotates the credential. `superagent disconnect` removes local credentials and synced rules. It does not revoke the server credential, so revoke the client in the UI when decommissioning an endpoint. ## Next steps - [Write and enforce runtime rules](/docs/security-workers/agent-guardrails/rules) - [Protect Pi agents from PII and PHI leaks](/docs/use-cases/protect-pi-agents-from-pii-phi-leaks) - [Add Context Guardrails](/docs/security-workers/agent-guardrails/context)

Infrastructure