# Connecting infrastructure Source: https://docs.antigen.sh/docs/asset-map/connecting-infrastructure Connect your infrastructure providers to build your Asset Map and see your team’s public and private attack surface. ## What to connect Start with the providers that host your applications and manage your team’s identities. Each integration adds a different part of your infrastructure: * **Cloud providers** add compute, storage, networking, and IAM configuration. * **Identity providers** add authentication flows and permission structures. * **Hosting platforms** add domains, deployments, and service relationships. You can connect additional providers at any time to expand your Asset Map. ## Connect a provider Open **Settings → Integrations**, select a provider, and follow the setup instructions. Asset Map integrations perform **read-only** operations; see the [integration guides](/docs/integrations) for each provider’s credential requirements. After you connect a provider, Antigen discovers its assets and relationships and adds them to your Asset Map. The integration keeps the map current as your infrastructure changes. # How agents use Asset Map Source: https://docs.antigen.sh/docs/asset-map/how-agents-use-asset-map Agents use your Asset Map to understand your infrastructure and the relationships between its services, resources, and identities. This context helps them investigate vulnerabilities, assess their impact, and plan fixes. ## One map for your agents Your organization has one Asset Map. Antigen’s pre-built agents - including [tCell](/docs/runs/tcell), [**triage-agent**](/docs/vulnerability-lifecycle/how-triage-works), and [**remediation-agent**](/docs/vulnerability-lifecycle/how-remediation-works) - use it to understand your environment. Custom agents built with the [Antigen SDK](/docs/sdk) can access the same map. Each integration adds context that agents can use. You do not need to connect providers separately for each agent. ## How each agent uses the map **tCell** uses the map to investigate potential attack paths. If an application connects to a database, it can investigate whether a vulnerability in the application could expose the database’s contents. **triage-agent** uses the map to identify the systems involved in a vulnerability and determine what information and access are needed to address it. That helps it decide whether to assign remediation to an agent or request help from your team. **remediation-agent** uses the map to understand the affected systems and their dependencies when preparing a fix. The fix may include a code change in a pull request, a proposed cloud configuration change, or instructions for your team to carry out. **Custom agents** can query your Asset Map through a tool available in the Antigen SDK. During a run, the agent can use the tool to look up assets and explore their relationships. See [Using the Asset Map](/docs/sdk/agents#using-the-asset-map) for details. # How teams use Asset Map Source: https://docs.antigen.sh/docs/asset-map/how-teams-use-asset-map Use the Asset Map to find overlooked infrastructure, investigate individual services, and understand how an issue could affect the rest of your environment. ## Find overlooked infrastructure As your team grows, services can outlive the projects or people that created them. An internal tool may still be running long after anyone remembers deploying it. For example, connecting Railway can bring a forgotten deployment into your Asset Map. Your team can inspect the service, check whether it is publicly accessible, and decide whether it still needs to run. ## Investigate a service Select a service in the map and follow its relationships to understand where it runs, how it is exposed, and which resources and identities connect to it. Start with a question: * Is this service accessible from the public internet? * Which resources does it depend on? * Which identities have access to it? Reviewing these relationships together helps you decide what to investigate or change. ## Assess potential impact When investigating a security issue, follow the affected asset’s relationships to see what else could be at risk. A service connected to a production database may warrant different attention from an isolated test deployment. The map helps you understand what an attacker could reach through an affected asset. During a run, [agents use these relationships](/docs/asset-map/how-agents-use-asset-map) to investigate whether an attack path is exploitable. # Asset Map Source: https://docs.antigen.sh/docs/asset-map/index The Asset Map is a graph of your team's infrastructure: it shows your services, resources, identities, and the relationships between them. ## Explore your infrastructure The platform presents the Asset Map as an interactive graph. You can see what is exposed, inspect a specific asset, and follow its relationships to other parts of your infrastructure. ## How the map stays current Antigen keeps the map current through your connected integrations. When you deploy a service, change a security group, or add an IAM role, Antigen picks up the change through the relevant integration and updates the map. Each integration adds context. AWS adds compute, storage, networking, and IAM configuration. Okta adds authentication flows and permission structures. Vercel adds deployments and domains. ## Permissions Asset Map integrations perform **read-only** operations to discover and map your infrastructure without modifying it. # CI/CD integration Source: https://docs.antigen.sh/docs/cli/ci-cd Run a pentest from GitHub Actions and fail the check if it discovers critical vulnerabilities. This example runs nightly or on demand. ## 1. Configure credentials and targets Add these values to your GitHub repository: | Name | Type | Value | | - | - | - | | `ANTIGEN_API_KEY` | Repository secret | An Antigen API key. | | `ANTIGEN_TARGET` | Repository variable | An approved target, such as `api.example.com`. | The CLI authenticates with the API key automatically. See [Targets](/docs/runs/targets) if you haven’t submitted your target for approval. ## 2. Add the pentest script Create `scripts/pentest.sh`: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} #!/usr/bin/env bash set -euo pipefail : "${ANTIGEN_API_KEY:?Set ANTIGEN_API_KEY}" : "${ANTIGEN_TARGET:?Set ANTIGEN_TARGET}" antigen run \ --targets "$ANTIGEN_TARGET" \ --quiet \ --json > results.json jq -e 'all(.[]; .severity != "critical")' results.json ``` `antigen run` waits until testing completes. `--quiet` suppresses activity, and `--json` writes the vulnerabilities to `results.json`. The last command checks every vulnerability. It exits successfully if none are critical and fails otherwise. If the run itself fails or stops, the script exits before checking results. To include your repository’s skills, add `--skills ./skills/` to the run command. ## 3. Configure GitHub Actions Create `.github/workflows/security.yml`: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} name: Security on: schedule: - cron: "0 2 * * *" workflow_dispatch: permissions: contents: read concurrency: group: antigen-security cancel-in-progress: false jobs: pentest: runs-on: ubuntu-latest timeout-minutes: 350 steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 package-manager-cache: false - name: Install the CLI run: npm install -g @antigen/cli - name: Run pentest run: bash scripts/pentest.sh env: ANTIGEN_API_KEY: ${{ secrets.ANTIGEN_API_KEY }} ANTIGEN_TARGET: ${{ vars.ANTIGEN_TARGET }} - name: Save results if: always() uses: actions/upload-artifact@v7 with: name: pentest-results path: results.json if-no-files-found: ignore ``` The schedule runs at 02:00 UTC. You can also start it manually from the repository’s Actions tab. ## Work with the results The workflow saves `results.json` as a job artifact. You can download it to inspect the vulnerabilities or process it with other tools: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} jq '.[] | select(.severity == "critical")' results.json ``` Vulnerabilities and evidence are also available in the Antigen platform. For testing after a production deployment, see the [SDK example](/docs/sdk/example). # Commands reference Source: https://docs.antigen.sh/docs/cli/commands Use `--help` with any command to see its arguments and options: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run --help ``` ## antigen login Sign in with your Google account through your browser. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen login ``` Follow the authorization instructions printed in your terminal. Credentials are saved in `~/.antigen/credentials`. When `ANTIGEN_API_KEY` is set, the CLI uses that key for API requests. ## antigen logout Clear saved sign-in credentials. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen logout ``` This leaves any `ANTIGEN_API_KEY` environment variable unchanged. ## antigen targets List your organization’s targets and their approval status. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen targets ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} example.com approved *.example.com approved internal.acme.com pending ``` | Option | Description | | - | - | | `--status ` | Filter by `pending`, `approved`, or `rejected`. | | `--json` | Return the targets as a JSON array. | See [Targets](/docs/runs/targets) for submitting targets for approval. ## antigen run Start an agent and follow its progress until the run finishes. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run --targets api.example.com ``` Uses tCell by default. To run an agent your team has registered, pass its name: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run \ --agent our-security-agent \ --targets api.example.com \ --instructions "Investigate authorization across accounts." ``` | Option | Description | | - | - | | `--agent ` | Pre-built or registered agent to run. Defaults to `tcell`. | | `--instructions ` | Task instructions. Defaults to testing the selected targets for vulnerabilities. | | `--model ` | Override the agent’s configured model. | | `--skills ` | Read Markdown files from a directory and append their contents to the agent’s skills. | | `--guardrails ` | Append constraints to the agent’s configured guardrails. | | `--targets ` | Comma-separated approved target values. Defaults to all approved targets. | | `--quiet` | Print vulnerabilities and the final summary, without the activity stream. | | `--json` | Write the final vulnerabilities as a JSON array to standard output. | Configuration options apply to this run. The registered agent’s configuration stays unchanged. For example, add skills from your repository and choose a model: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run \ --model claude-opus-5-cyber \ --skills ./skills/ \ --guardrails "Do not test endpoints under /internal/." \ --targets api.example.com ``` The CLI reads skill files before starting the run. If `--skills` is omitted, it uses the agent’s configured skills. With `--json`, activity and diagnostic messages go to standard error. Add `--quiet` to suppress activity: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run --quiet --json > vulnerabilities.json ``` A completed run exits with code `0`, including when it discovers vulnerabilities. A failed or stopped run exits with a nonzero code. See [CI/CD](/docs/cli/ci-cd) for failing a check based on vulnerability severity. ## antigen runs List your organization’s runs. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen runs --status running ``` | Option | Description | | - | - | | `--status ` | Filter by `creating`, `running`, `stopped`, `completed`, or `failed`. | | `--json` | Return runs as a JSON array. | ## antigen vulnerabilities List vulnerabilities associated with a run. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen vulnerabilities run_abc123 --severity critical ``` | Argument | Description | | - | - | | `` | Run whose vulnerabilities to retrieve. Required. | | Option | Description | | - | - | | `--severity ` | Filter by severity. | | `--status ` | Filter by `open`, `in_progress`, `remediated`, `verified`, or `accepted_risk`. | | `--json` | Return vulnerabilities as a JSON array. | Filters apply together. Results reflect each vulnerability’s current status and assignment. ## antigen evidence List evidence associated with a run. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen evidence run_abc123 ``` | Argument | Description | | - | - | | `` | Run whose evidence to retrieve. Required. | ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} ev_123 capture.pcap 1.0 MB ev_456 traffic.jsonl 512 KB ev_789 admin-bypass.png 200 KB ``` Use `--json` to return evidence metadata as a JSON array. ## antigen download Download an evidence item. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen download ev_123 --output ./capture.pcap ``` | Argument | Description | | - | - | | `` | Evidence item to download. Required. | | Option | Description | | - | - | | `--output ` | Destination file. Defaults to the evidence item’s filename in the current directory. | ## antigen steer Send instructions, context, or a question to an agent. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen steer run_abc123 "Investigate authorization on the GraphQL endpoint." ``` | Argument | Description | | - | - | | `` | Run to send the message to. Required. | | `""` | Instructions, context, or a question for the agent. Required. | You can also continue the conversation after testing finishes: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen steer run_abc123 "Did you test whether read-only users can export data?" ``` The agent uses the conversation and evidence from that run. See [Steering](/docs/sdk/steering) for examples. ## antigen stop Snapshot the run’s sandbox and stop its execution. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen stop run_abc123 ``` | Argument | Description | | - | - | | `` | Run to stop. Required. | The command waits until the snapshot is saved and the sandbox has stopped. Saved vulnerabilities and evidence remain available. ## antigen resume Restore a stopped run’s sandbox and continue with its saved agent configuration. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen resume run_abc123 ``` | Argument | Description | | - | - | | `` | Stopped run to resume. Required. | The run keeps its ID. The CLI streams activity and waits until the run finishes. ## antigen open Open a run in the Antigen platform. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen open run_abc123 ``` | Argument | Description | | - | - | | `` | Run to open in the platform. Required. | ## antigen version Print the installed CLI version. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen version ``` # Overview Source: https://docs.antigen.sh/docs/cli/index The Antigen CLI lets you launch agents, follow runs, and retrieve vulnerabilities and evidence from your terminal. It uses the same API as the [Antigen SDK](/docs/sdk), so you can work with the same resources from scripts, CI pipelines, and the platform. ## Sign in After [installing the CLI](/docs/cli/installation), sign in: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen login ``` Follow the instructions to authorize the CLI in your browser using your Google account. The CLI saves your credentials for subsequent commands. For CI pipelines, set `ANTIGEN_API_KEY` in your environment. The CLI uses that key automatically. See [CI/CD](/docs/cli/ci-cd) for configuring automated runs. ## Start a run Launch tCell against an approved target: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run --targets api.example.com ``` The CLI prints the run ID and streams activity as the agent works: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Run run_abc123 started Agent: tCell Targets: api.example.com Investigating authentication and API endpoints... HIGH SQL injection in /api/users CRITICAL Authentication bypass on /api/admin Run complete. 1 critical, 1 high vulnerability. ``` The command waits until the run finishes. The run continues in its [sandbox](/docs/getting-started/concepts#agents-and-runs) if your terminal disconnects. Targets must be approved before testing. See [Targets](/docs/runs/targets) for the approval process. ## Commands | Command | Purpose | | - | - | | `antigen login` | Sign in through your browser. | | `antigen logout` | Clear saved credentials. | | `antigen targets` | List targets and their approval status. | | `antigen run` | Start an agent and follow its progress. | | `antigen runs` | List runs. | | `antigen vulnerabilities ` | Read vulnerabilities associated with a run. | | `antigen evidence ` | List evidence associated with a run. | | `antigen download ` | Download an evidence item. | | `antigen steer ""` | Give the agent context, direction, or a follow-up question. | | `antigen stop ` | Snapshot the sandbox and stop the run. | | `antigen resume ` | Continue a stopped run from its snapshot. | | `antigen open ` | Open a run in the platform. | | `antigen version` | Print the installed CLI version. | See [Commands](/docs/cli/commands) for arguments, options, and examples. # Installation Source: https://docs.antigen.sh/docs/cli/installation Requires [Node.js](https://nodejs.org/en/download) 22 or later. Install the CLI: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install -g @antigen/cli ``` Check the installed version: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen version ``` Sign in through your browser: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen login ``` For automated environments, set `ANTIGEN_API_KEY` instead. See [CI/CD](/docs/cli/ci-cd) for configuring credentials in your pipeline. You’re ready to [start a run](/docs/cli#start-a-run). # Concepts Source: https://docs.antigen.sh/docs/getting-started/concepts These concepts describe how your infrastructure, agents, and security workflows fit together. The platform and the [Antigen SDK](/docs/sdk) use the same vocabulary. ## Your environment **Organization**
Your team’s workspace in Antigen. It contains your Asset Map, agents, targets, vulnerabilities, and connected integrations. **Asset Map**
A graph of your organization’s infrastructure. It shows services, resources, identities, and the relationships between them. Integrations keep the map current, and agents use it to understand your environment. See [Asset Map](/docs/asset-map). **Asset**
An individual service, resource, or identity in the Asset Map, such as an application, database, or IAM role. **Target**
A domain or IP address submitted for security testing. The Antigen team reviews and approves new targets before agents can test them. See [Targets](/docs/runs/targets). **Expert**
Your Antigen expert helps plan engagements, interpret results, and decide what to do next. ## Agents and runs **Agent**
A configuration that combines a model, skills, guardrails, and tools to perform work. You can use a pre-built agent, customize an existing one, or assemble your own through the SDK. Registering an agent saves its configuration so your team can retrieve it and assign vulnerabilities to it. See [Agents](/docs/sdk/agents). **tCell**
Antigen’s pre-built offensive security agent. It tests approved targets for vulnerabilities and verifies deployed fixes. The Antigen team develops and improves tCell using the same SDK available to your team. See [tCell](/docs/runs/tcell). **Triage agent**
Antigen’s pre-built **triage-agent** investigates a vulnerability and determines how remediation should proceed. It uses the evidence, infrastructure context, and available access to identify next steps or request help from your team. See [How triage works](/docs/vulnerability-lifecycle/how-triage-works). **Remediation agent**
Antigen’s pre-built **remediation-agent** prepares steps to address a vulnerability. These can include a pull request or a recommended infrastructure change for your team to review and carry out. See [How remediation works](/docs/vulnerability-lifecycle/how-remediation-works). **Run**
One execution of an agent. The same agent can perform multiple runs, each with its own progress and results. A tCell run tests targets; a remediation-agent run prepares steps to address a vulnerability. See [Runs](/docs/sdk/runs). **Sandbox**
An isolated environment where an agent executes a run. It provides the workspace and tools the agent uses, with network and target restrictions controlling which systems it can access. ## Vulnerabilities and evidence **Vulnerability**
A security weakness discovered by an agent, with supporting evidence. Its status and assignment track the work to investigate, remediate, and verify it. The same vulnerability remains available as agents and people add evidence and make progress. See [Vulnerabilities](/docs/runs/vulnerabilities). **Evidence**
Artifacts that support a vulnerability or show the result of testing it. Evidence can include HTTP requests and responses, screenshots, network captures, and exploit recordings. Later runs can add evidence showing whether a fix worked. See [Evidence](/docs/runs/evidence). **Report**
A summary of an engagement that captures the relevant vulnerabilities and evidence at the time it is written. The report preserves those results while the vulnerabilities continue through their lifecycle. See [Reports](/docs/runs/reports). ## Coordinating work **Status**
A vulnerability’s position on the board: **Open**, **In progress**, **Remediated**, **Verified**, or **Accepted risk**. Status shows where the work stands; verification establishes whether a deployed fix resolved the issue. See [Vulnerability lifecycle](/docs/vulnerability-lifecycle). **Assignment**
The person or agent responsible for a vulnerability. Assigning a vulnerability to a custom agent can trigger a webhook that your service handles to launch it. **Hook**
An action triggered when a vulnerability’s status or assignment changes. Preconfigured hooks coordinate triage, remediation, and verification. Custom webhooks deliver events to your service, which decides how to respond. See [Hooks](/docs/vulnerability-lifecycle/hooks). **Human task**
A request assigned to a person when an agent needs information, access, a decision, or an action. It explains what is needed and why, and reaches the person through connected messaging or issue-tracking tools. Completion lets the agent continue its work. See [Team workflows](/docs/team-workflows). ## Configuring agents **Model**
The model an agent uses to reason and decide what to do. Agents access available models through Antigen’s model gateway. See [Models](/docs/sdk/models). **Skill**
Instructions that teach an agent a procedure or provide knowledge about your systems. Skills can describe authentication behavior, investigation methods, or how to prepare a particular kind of fix. See [Skills](/docs/sdk/skills). **Guardrail**
An instruction that constrains an agent’s behavior, such as avoiding particular endpoints or stopping when it finds a critical vulnerability. Guardrails work alongside the platform’s enforced target and sandbox restrictions. See [Guardrails](/docs/sdk/guardrails). **Tool**
A capability an agent can invoke, such as querying the Asset Map or creating a human task with **human\_tasks**. **Steering**
A message sent to an active run to adjust the agent’s focus or provide additional context. See [Steering](/docs/sdk/steering). # Quick start Source: https://docs.antigen.sh/docs/getting-started/quick-start Run your first assessment and review the results. Start with one application you want to test. This guide walks through submitting a target, running tCell, and following up on any vulnerabilities it discovers. In **Settings → Targets**, add your application’s hostname, such as `app.example.com`. A [target](/docs/runs/targets) defines what an agent is allowed to test. The Antigen team reviews every new target to confirm that your organization owns it or has permission to test it. You can check its approval status in **Settings → Targets**. While your target is being reviewed, open **Settings → Integrations** and connect the services that support your application. For example, connect AWS for cloud resources, Vercel for deployments, or Okta for identities and permissions. These integrations build your [Asset Map](/docs/asset-map), a graph of your infrastructure and the relationships between its resources. Open the map to see the context available to your agents. Infrastructure connections use read-only access. You can also start with an external assessment and connect your infrastructure later. See [Connecting infrastructure](/docs/asset-map/connecting-infrastructure) for setup details. Once your target is approved, your Antigen expert can plan the engagement and run [tCell](/docs/runs/tcell), Antigen’s pre-built offensive security agent, for your team. Use **Office hours** in the platform sidebar or [schedule a session](https://cal.com/team/antigen/antigen-office-hours) to discuss what you want tested. Open the run in the platform to follow its progress. tCell investigates the approved target and collects evidence as it tests for vulnerabilities. To launch runs from your own code or terminal, start with the [Antigen SDK](/docs/sdk) or [CLI](/docs/cli). Open the run to review what tCell tested and any vulnerabilities it discovered. Each [vulnerability](/docs/runs/vulnerabilities) describes the issue and its severity, with [evidence](/docs/runs/evidence) showing what happened, such as HTTP requests and responses, screenshots, or exploit recordings. Vulnerabilities also appear on the **Vulnerabilities** page, where your team can track their status and assignment as work continues. A [report](/docs/runs/reports) summarizes an engagement and captures the relevant vulnerabilities and evidence at the time it is written. With the default hooks enabled, a new vulnerability starts Antigen’s pre-built **triage-agent**. It investigates the issue and determines what is needed for remediation. When it has enough information and access, it assigns the vulnerability to the pre-built **remediation-agent** to prepare a fix. Connect [GitHub](/docs/vulnerability-lifecycle/connecting-your-code) so remediation-agent can work on the affected code and open a pull request. For infrastructure changes, it can prepare instructions for your team. If an agent needs your help, it creates a human task. Connect your [messaging or issue tracking tools](/docs/team-workflows) to receive and respond to these requests where your team works. Review the proposed changes and deploy the fix. Once it is deployed, move the vulnerability to **Remediated**. The default verification hook starts tCell to test the original exploit again. A successful fix moves the vulnerability to **Verified**; an unresolved issue returns to **Open** with new evidence. ## Next steps Learn how statuses, assignments, and hooks coordinate the work after discovery. Learn the terms used throughout the platform, SDK, and API. # Compare plans Source: https://docs.antigen.sh/docs/help/getting-started/billing/compare-plans Feature matrix across Free, Team, and Enterprise tiers for this demo help center. Plans bundle limits, support, and compliance features. Use this page to shortlist options before legal review—exact numbers change, but the pattern usually holds: pay for seats, automation volume, and the audit artifacts you need. ## Highlights * **Free** — Core projects and limited automation runs. Best for evaluation and tiny teams with light automation. * **Team** — SSO options, higher limits, and priority email support. Common step after product-market fit when coordination overhead grows. * **Enterprise** — Regional options, advanced audit, and dedicated support channels. Typical when procurement, security questionnaires, or data residency enter the conversation. ### Hidden costs Count integrations, API volume, and retained history—not just seats. A team on paper may exceed automation quotas during a busy quarter. ## How to choose Start where your current limits hurt first—usually automation volume or member count—then add Enterprise when procurement or compliance requires it. ### Proof points Before upgrading, reproduce one painful workflow in a trial project and measure time saved. Finance teams respond to minutes per week reclaimed, not feature lists alone. ## Pilot checklist * Confirm how many seats you truly need after removing inactive accounts. * List must-have integrations and confirm they are included or priced as add-ons. * Align legal and security on DPA, subprocessors, and data residency before you sign. ## When to revisit Re-evaluate plans at major milestones: funding rounds, geographic expansion, or a spike in automation usage after a new workflow goes live. Annual true-ups catch drift between contract and reality. # Billing and plans Source: https://docs.antigen.sh/docs/help/getting-started/billing/index Plans, invoices, and upgrades for your workspace. Billing is tied to your organization. This section explains how plans compare, how changes propagate, and where to find invoices. If you need a custom agreement, contact sales from the billing page—dummy numbers here are for demonstration only. Understand the capabilities and support available on each plan. Change plans and understand when updates take effect. Find billing documents and keep finance records current. # Invoices and receipts Source: https://docs.antigen.sh/docs/help/getting-started/billing/invoices-receipts Download invoices, update tax details, and reconcile charges. Finance teams need clean paper trails: invoices for accruals, receipts for reimbursements, and tax IDs that match what is on file with vendors. Keep addresses and VAT numbers current before month-end close. ## Where to find invoices Navigate to **Settings → Billing → Invoices** for PDF copies and line items. Download CSV or structured exports if your ERP ingests them automatically. ### Line items Verify seat counts and add-ons against internal headcount reports. Discrepancies often trace to deactivated users still occupying paid seats until the next true-up. ## Tax and VAT Update tax IDs before renewal to avoid delays. This demo does not constitute tax advice—run final numbers past your accounting partner, especially for cross-border entities. ### Reverse charge and treaties Document which party remits VAT or sales tax for each entity. Store evidence with the invoice PDF for audit readiness. ## Receipts Card charges include a receipt link suitable for expense tools that accept emailed PDFs. Forward receipts immediately after charge—matching six months later is painful. ### Corporate cards If the cardholder rotates, update billing profiles so receipts reach the person who must attest to expenses. # Upgrade or downgrade your plan Source: https://docs.antigen.sh/docs/help/getting-started/billing/upgrade-downgrade Change plans, proration, and limit changes for subscriptions. Plan changes affect billing, feature gates, and sometimes data retention. Read the fine print on your order form—this article describes typical patterns for illustration only. ## Upgrade Upgrades take effect immediately in this template content. Proration is calculated against your billing cycle for illustration. ### Capacity planning After upgrading, revisit automation and storage settings—you may need to raise internal quotas now that platform limits moved. ### Communication Tell finance when upgrades happen mid-cycle so invoices match purchase orders. Link to the order confirmation in your ticket. ## Downgrade Downgrades apply at the next renewal unless your contract states otherwise. Features above the new cap become read-only until you adjust usage. ### Export first Download critical exports before downgrade if retention windows shrink. You cannot always rely on grace periods for compliance archives. ## Billing contacts Ensure finance and IT stakeholders are copied on invoices if your organization requires it. Rotate contacts when owners change roles—stale addresses delay tax validation and payment. # Create your account Source: https://docs.antigen.sh/docs/help/getting-started/create-account Sign up, verify your email, and choose the right organization type for your team. Creating an account should take minutes. The decisions that matter—company vs personal workspace, who pays, and which email domain owns the org—are easier to correct now than after you have invited dozens of people. ## Sign up Visit the signup page and enter your work email. We send a one-time link to verify ownership of the address. Links expire; request a fresh one if your inbox is slow. ### Domains and policy Some companies block consumer email providers. If signup fails silently, try your corporate domain or ask IT to allow the notification sender. ## Organization type * **Company** — Multiple teams under one billing profile. Choose this when finance expects a single invoice and you want shared administration. * **Personal** — Individual use with the option to upgrade later. Appropriate for evaluation before you commit a legal entity. ### Switching later Moving between types may require support or export/import if your product separates billing identities. When in doubt, start as **Company** if you know you will onboard a team within a month. ## Verification issues If the email does not arrive within a few minutes, check spam folders and ensure your IT allowlist includes notification domains. Corporate filters sometimes delay the first message more than subsequent ones. ### Shared inboxes Avoid signing up with distribution lists—you lose account recovery if nobody owns the mailbox. Prefer a named admin who can delegate later. # Getting started Source: https://docs.antigen.sh/docs/help/getting-started/index Create your account, secure access, and connect the product to the tools your team already uses. Welcome. This section walks you through account setup, your workspace, billing, and integrations so you can get productive quickly. Use the articles below to go deeper—each guide is written for busy teams who need clear steps without fluff. Get a small team from signup to a credible first project. Set up your account and organization. Understand sign-in methods, MFA, and SSO. Manage teammates, roles, and organization settings. Compare plans, manage changes, and find invoices. Connect Slack, CRMs, and developer tools. # Connect your CRM Source: https://docs.antigen.sh/docs/help/getting-started/integrations/connect-crm Link Salesforce or HubSpot through partner connectors or a custom sync strategy. CRM integrations keep customer context next to internal work. The hardest part is agreeing which system owns which field—decide that before you flip the sync on. ## Supported paths * Official partner connectors (see partner guides) * CSV or API-based sync via developer tools ### When to use each Partner connectors trade flexibility for speed. Custom sync suits unusual object models or heavy transformations mid-pipeline. ## Data expectations Define which objects sync and how conflicts resolve. Document owner fields so automation behaves predictably. ### Conflict rules “CRM wins” vs “product wins” should be explicit for every field. Ambiguity shows up first when sales reassigns accounts during a territory change. ## Privacy Limit synced fields to the minimum needed for your workflows and review access regularly. ### Retention Align deletion policies: when a CRM record disappears, decide whether related artifacts should archive, anonymize, or remain linked for audits. # Connect Slack Source: https://docs.antigen.sh/docs/help/getting-started/integrations/connect-slack Install the Slack app, pick channels, and manage notifications. Slack puts updates where people already work. A disciplined channel strategy keeps signal high—one noisy channel trains everyone to mute the integration entirely. ## Install From **Integrations → Slack**, authorize the workspace you use every day. You need admin approval if your Slack org restricts apps. ### Scopes Review requested OAuth scopes during install. If something looks broader than needed, ask your Slack admin whether a reduced app configuration exists. ## Channels Map events to public or private channels. Start with a low-noise channel for pilot testing. ### Naming Use a consistent prefix (`#help-`, `#docs-`) so people can browse related channels. Archive pilot channels after go-live to reduce clutter. ## Troubleshooting If messages stop, reauthorize the app and confirm the bot was not removed from the channel. ### Rate limits Bursty events can hit Slack posting limits—back off or batch summaries if you see `429` responses in integration logs. # API keys Source: https://docs.antigen.sh/docs/help/getting-started/integrations/developer/api-keys Create, rotate, and scope API keys for server-side automation. API keys authenticate machine-to-machine calls. They are simpler than OAuth but easier to leak—never embed them in browsers or mobile apps. ## Create keys Generate keys with descriptive labels and store them in a secrets manager—never in client-side code. ### Scoping If your platform supports scoped keys, split read vs write access so a compromised read-only key cannot mutate data. ## Rotation Rotate keys on a schedule or immediately after someone leaves the team with access. ### Dual-key rotation Issue a new key, deploy everywhere, verify traffic, then revoke the old key—avoids hard cutovers at midnight. ## Revocation Revoked keys stop working immediately. Update dependent services before revoking. ### Runbooks Document which cron jobs and CI pipelines use which key so rotation does not miss a dusty integration. # Developer integrations Source: https://docs.antigen.sh/docs/help/getting-started/integrations/developer/index OAuth apps, webhooks, and API keys for building on the platform. Developer integrations are for teams building custom workflows or connecting internal systems. Use OAuth for user-delegated access, webhooks for reactive automation, and API keys for secure server-to-server calls. Request delegated access for user-facing integrations. React to product events safely and reliably. Authenticate server-to-server integrations and rotate credentials. # OAuth apps Source: https://docs.antigen.sh/docs/help/getting-started/integrations/developer/oauth-apps Register an OAuth client, scopes, and redirect URLs for the API. OAuth connects user-authorized clients to your APIs without sharing primary passwords. Treat client secrets like production credentials—rotate them and restrict who can create apps. ## Register an app Create an application in **Developer settings** and note the client ID and secret. ### Environments Maintain separate apps for staging and production so tokens never cross environments accidentally. ## Scopes Request the smallest scope set that satisfies your feature. Review quarterly as APIs expand. ### User consent Write user-facing copy that explains why each scope is needed—reviewers and security questionnaires ask. ## Redirect URLs Use HTTPS endpoints and avoid wildcards in production. Register separate entries for staging and production. ### PKCE Prefer PKCE for public clients to reduce interception risk on mobile and SPA flows. # Webhooks Source: https://docs.antigen.sh/docs/help/getting-started/integrations/developer/webhooks Subscribe to events, verify signatures, and retry safely. Webhooks push events to your infrastructure so you can react without polling. Reliability hinges on verification, idempotency, and fast HTTP responses—treat the endpoint like a mini product. ## Subscriptions Create a webhook endpoint and select event types. The platform sends a signing secret for HMAC verification. ### Filtering Subscribe only to events you handle. Unused events still cost verification CPU and clutter logs. ## Verification Always validate signatures before processing payloads. Reject stale timestamps when present. ### Clock skew Allow a small clock skew window between signer and verifier, but bound it to limit replay windows. ## Retries Failed deliveries retry with exponential backoff. Ensure your endpoint is idempotent. ### Response codes Return **2xx** only after you have safely persisted or handed off work. Use **5xx** to signal transient failures worth retrying; **4xx** for permanent misconfiguration. # Integrations overview Source: https://docs.antigen.sh/docs/help/getting-started/integrations/index Connect Slack, CRMs, and custom tools using OAuth, webhooks, and partner connectors. Integrations let you meet your team where they already work. Start with managed connectors, then explore developer tools for custom workflows. Each subsection below focuses on a different depth: quick connections, developer primitives, and packaged partner integrations. Send product activity into the channels where your team works. Link Salesforce, HubSpot, or a custom CRM workflow. Build with OAuth apps, webhooks, and API keys. Start with maintained connectors and field mappings. # Custom connector template Source: https://docs.antigen.sh/docs/help/getting-started/integrations/partners/custom-connector-template Fork the connector template to build a private integration faster. The template encodes opinions: structured logging, retry policies, and test harnesses you would otherwise rebuild for every integration. Fork it, rename packages to match your org, and delete sample data before your first production credential touches it. ## What you get * Authentication scaffolding * Webhook handlers * Example tests ### Conventions Follow the included directory layout so future contributors know where to add mappers, clients, and fixtures. ## Customize Replace sample mappings with your schema and add monitoring for sync failures. ### Observability Emit metrics for lag, error categories, and record counts—dashboards beat grep when something breaks at 2 a.m. ## Support Partner engineering can review architecture for Enterprise customers in real deployments; this demo text is illustrative. ### Security review Schedule architecture review before handling regulated data—catch network paths and key storage issues early. # HubSpot connector Source: https://docs.antigen.sh/docs/help/getting-started/integrations/partners/hubspot Connect HubSpot CRM for deals and company records. HubSpot works well when marketing and sales already live there—your product becomes the execution layer while HubSpot remains the system of record for pipeline stages and company attributes. ## OAuth Authorize HubSpot with a user who can grant CRM scopes. Use a service account if your policy requires it. ### Scope review Confirm read vs write scopes against what your workflows actually need. Over-scoped tokens worry security reviewers. ## Pipelines Align HubSpot deal stages with project states for cleaner reporting. ### Definitions Maintain a shared glossary of stage names so dashboards match what revenue teams say on calls. ## Limits Watch API rate limits during large backfills; throttle initial syncs accordingly. ### Pagination Use cursor-based APIs where available—safer than offset paging on large datasets. # Partner connectors Source: https://docs.antigen.sh/docs/help/getting-started/integrations/partners/index Packaged integrations for Salesforce, HubSpot, and custom connector templates. Partner connectors ship maintained field mappings and sane defaults. Use them when you want speed over full custom control. Pick a vendor-specific guide below or start from the custom template when your stack is unique. Connect Salesforce with maintained defaults and mappings. Connect HubSpot and validate the data flow. Start from a safe structure when no packaged connector fits. # Salesforce connector Source: https://docs.antigen.sh/docs/help/getting-started/integrations/partners/salesforce Install, authenticate, and map Salesforce objects to the product. The Salesforce connector reduces copy-paste between CRM and your workspace. Plan object mapping before you sync thousands of rows—rework is cheaper in a spreadsheet than in production data. ## Prerequisites Admin access in Salesforce and an administrator to approve the connector. ### Sandboxes Pilot against a full or partial sandbox before production. Validate picklist values, required fields, and validation rules that might block writes. ## Field mapping Map accounts, contacts, and opportunities to entities. Resolve duplicates by external ID where possible. ### Ownership Decide who owns records when Salesforce and the product disagree. Document the rule in your runbook so support can answer “why did this flip?” ## Sync modes Choose one-way or two-way sync depending on which system owns each field. ### Monitoring Alert on sync lag and error rates. Backfills can look healthy while a handful of poison records retry forever. # Quickstart: get set up in under 15 minutes Source: https://docs.antigen.sh/docs/help/getting-started/quickstart A fast path from signup to first project: invites, roles, and your first integration. This checklist gets a small team from zero to a credible pilot: verified accounts, a safe place to collaborate, and one integration proving data can flow in and out. Adjust order if your security team requires SSO before invites. ## Before you begin * A verified email you can access * Admin access if you are enabling SSO later * Rough idea of who belongs in the pilot (five to fifteen people is typical) If you are migrating from another tool, keep a CSV of users and roles handy—you will move faster than recreating access from memory. ## Steps 1. **Create your organization** — Pick a name your team will recognize in notifications. Avoid internal codenames if customers might see the name on shared artifacts. 2. **Invite teammates** — Start with a small pilot group before rolling out widely. Ask them to accept within a week so you are not debugging expired invites during launch. 3. **Connect one integration** — Choose Slack or your CRM to see data flow end to end. Validate credentials in a sandbox or test channel first. 4. **Create a first project** — Use it as a sandbox for workflows and permissions. Seed a few realistic tasks so demos feel grounded. ### Time checks If any step waits on IT (DNS, SSO metadata, firewall rules), parallelize what you can—draft project structure while tickets move. ## Next steps Review [sign-in and security](/docs/help/getting-started/sign-in-security) and explore the [workspace](/docs/help/getting-started/workspace) guides when you are ready to tighten access. Consider a short retro after week one: what confused newcomers, which doc they opened first, and whether search surfaced the right page. # Sign-in and security basics Source: https://docs.antigen.sh/docs/help/getting-started/sign-in-security Passwords, SSO, session length, and how we protect your workspace. Good security balances friction for attackers without blocking legitimate work. Understand how people authenticate, how long sessions last, and what admins can require before high-risk actions. ## Authentication options * Email and password with optional MFA * SAML SSO on eligible plans * IdP-initiated login where supported ### MFA Require MFA for every member when your data classification demands it—not only admins. Attackers target contributors with broad file access too. ### SSO cutover Plan a maintenance window when enabling SAML: communicate downtime, validate attribute mapping with a pilot group, and keep a break-glass local admin. ## Sessions Sessions expire after a period of inactivity. Admins can require re-authentication for sensitive actions. Shorter sessions reduce risk on shared machines; longer sessions reduce nagging on trusted laptops. ### Device hygiene Encourage disk encryption and screen locks on machines that hold session cookies. Remote wipe policies complement session timeouts for lost hardware. ## Best practices Enforce MFA for all admins, use separate staging and production workspaces, and review connected OAuth apps quarterly. ### OAuth review Remove tokens for tools you no longer use—old integrations keep API access until revoked. Pair reviews with offboarding checklists when people change roles. # Workspace: teams, roles, and settings Source: https://docs.antigen.sh/docs/help/getting-started/workspace/index Configure how people collaborate: membership, roles, and org-wide preferences. Your workspace is where members, permissions, and org settings come together. The guides in this section explain how to invite people, align roles with how you operate, and keep administrative control as you grow. Bring a pilot group into your workspace without over-provisioning access. Match workspace access to how your organization operates. Configure workspace-wide preferences and controls. # Invite teammates to your workspace Source: https://docs.antigen.sh/docs/help/getting-started/workspace/invite-teammates Send invites, assign initial roles, and manage pending invitations. Invitations are the front door to your workspace. Clear roles and timely follow-up prevent “I never got access” threads during launches. Treat pending invites like inventory—review them weekly until cleared. ## Send invites From **Settings → Members**, enter email addresses and pick a default role. Invites expire after fourteen days unless resent. ### Bulk import If your product supports CSV import, validate columns against HR data first—typos in email addresses generate unnecessary support tickets. ### Messaging Tell people to expect an invite from a specific sender name so corporate filters do not hide it. Link to your internal wiki for “why we adopted this tool.” ## Roles at invite time You can assign **Member**, **Admin**, or custom roles if your plan supports them. You can change roles after someone joins. ### Principle of least privilege Default to Member unless someone truly needs billing or security settings. Elevate admins in pairs so coverage exists during PTO. ## Revoking invites Pending invites can be revoked individually. Revocation does not notify the recipient beyond the link no longer working. ### Audit trail Keep a note if you revoke because someone left the company—helps during access reviews and prevents accidental re-invite from stale spreadsheets. # Organization settings Source: https://docs.antigen.sh/docs/help/getting-started/workspace/organization-settings Name, branding touches, defaults, and workspace-level policies. Organization settings define how your workspace presents itself and which guardrails apply by default. Changes here often require admin rights and may notify all members—communicate before big switches. ## Profile Update display name and public-facing details shown in invites and notification footers. Align spelling with your legal entity where invoices and DPA references matter. ### Logos and assets Use brand-approved logos and color contrast checks for accessibility. Store source files in your brand portal so future admins are not hunting attachments in chat. ## Defaults Set default project visibility and automation limits for new projects created by members. ### Templates Pair defaults with project templates so teams inherit sane labels, sections, and automation caps without starting from zero every time. ## Policies Admins can require MFA, restrict invite domains, and define data residency expectations where features exist for your region. ### Exceptions Document how to request exceptions (contractors, acquisitions) so security can approve without inventing a new process each time. # Roles and permissions Source: https://docs.antigen.sh/docs/help/getting-started/workspace/roles-permissions Understand what admins, members, and custom roles can see and change. Permissions translate org structure into enforceable rules. When in doubt, mirror how your company already thinks about data classification—customer data vs internal-only vs public marketing. ## Default roles | Role | Typical use | | - | - | | Admin | Billing, security, workspace-wide settings | | Member | Day-to-day work inside assigned projects | ### Admin count Keep the admin group small and named. Too many admins increases accidental misconfiguration; too few blocks urgent fixes. ## Custom roles On supported plans, create roles that map to your internal job functions and restrict exports or automation actions. ### Design tips Name roles after outcomes (“Support – view only”) not job titles alone (“Engineer”), because titles drift faster than access needs. ### Testing Before rolling out a new role, impersonate or test with a sandbox user—verify denied actions fail closed with a clear error. ## Auditing Admins can review a lightweight access log of role changes and exports (retention varies by plan). ### Reviews Schedule quarterly access reviews for high-sensitivity projects. Export logs before reviews if you need to join them to HR systems. # Home Source: https://docs.antigen.sh/docs/help/index Find answers about your workspace, integrations, product guides, and policies.

How can we help?

Search the Help Center for setup guides, product how-tos, automation tips, and policies.

Popular searches

Browse by topic

All help articles

Getting started

Workspace and security

Billing and plans

Integrations

Product guides

Automation

Troubleshooting and support

Account, data, and legal

# Idempotency Source: https://docs.antigen.sh/docs/help/product/automation/advanced/idempotency Use idempotency keys to make automation safe under retries. Networks drop packets, clients retry, and queues redeliver. Without idempotency, the same user intent can create duplicate charges, tickets, or posts. Idempotency keys make “exactly-once behavior” practical on “at-least-once” infrastructure. ## Why it matters Retries can duplicate side effects without idempotent design. Payment and ticketing integrations are the usual victims—duplicate idempotency keys should return the original result, not create a second record. ### Scope Decide whether keys are global, per-tenant, or per-user. Collisions across tenants are rare but catastrophic if namespaces overlap. ## Keys Supply a stable idempotency key derived from natural identifiers—order ID, request UUID, or hash of canonical fields. Avoid keys that change when unrelated whitespace changes. ### Rotation If you must rotate key material, dual-write during transition and document the overlap window. ## Storage Record processed keys long enough to cover your retry window plus clock skew. Expire old keys to bound storage, but not before your longest plausible retry storm. ### Conflicts When a new payload arrives with an existing key but different body, reject loudly—something is inconsistent and needs human review. # Advanced patterns Source: https://docs.antigen.sh/docs/help/product/automation/advanced/index Rate limits, idempotency, and retry policies for high-volume automation. At scale, small mistakes amplify. This section covers defensive patterns so automation stays reliable under load. Read these articles before opening your integration to high-traffic events. Control throughput and keep shared systems responsive. Make repeated requests safe and predictable. Recover from transient failures without creating more load. # Rate limits Source: https://docs.antigen.sh/docs/help/product/automation/advanced/rate-limits Understand automation rate limits and how to design around them. Rate limits keep shared infrastructure healthy. Treat them as part of your design—not surprises—when you connect automation to external APIs or run fan-out jobs across many tenants. ## Defaults Limits protect shared infrastructure. Burst allowances exist for short spikes, but sustained traffic above quota will throttle or fail requests—often with `429` responses you must handle. ### Headers Many APIs return `Retry-After` or rate-limit headers. Log them during integration testing so your backoff code respects server hints instead of guessing. ## Strategies * Batch work where possible—one request with twenty IDs beats twenty serial requests. * Queue externally when needed so spikes flatten into steady throughput. * Shed load with sampling under stress: process every Nth event until pressure drops. ### Tenant fairness Multi-tenant systems sometimes enforce per-tenant caps. Coordinate with platform admins if one customer’s automation crowds others. ## Monitoring Graph throttle events to spot hot workflows early. Alert when throttle rates exceed a baseline for more than a few minutes—often the first sign of an infinite loop or misconfigured poll interval. ### Capacity planning Before launch week, rehearse peak traffic with load tests against staging. Compare observed QPS to your quotas and pad headroom for retries. # Retry policies Source: https://docs.antigen.sh/docs/help/product/automation/advanced/retry-policies Configure exponential backoff, max attempts, and dead-letter handling. Retries turn transient failures into success stories—when configured carefully. Backoff spreads load; max attempts bound damage; dead-letter queues preserve poison messages for inspection instead of infinite loops. ## Backoff Exponential backoff reduces thundering herds. Add jitter to desynchronize clients so retries do not align on the same second. ### Caps Put an upper bound on delay so a permanently broken endpoint does not stall workers for hours between attempts—pair backoff with a max attempts ceiling. ## Max attempts Stop after N tries and surface to operators with context. Include the last error code, truncated body, and correlation ID so the first responder does not reproduce the whole incident from scratch. ### Idempotency Retries assume idempotent handlers. If a step is not idempotent, disable blind retries or scope them to safe sub-operations. ## Dead letters Send poison messages to a dead-letter queue for manual inspection. Monitor DLQ depth: a flat line at zero might mean alerts are misconfigured; a rising line means systemic failure. ### Replay Document a safe replay procedure after fixing root cause—sometimes replay requires a new idempotency key or compensating cleanup first. # Automation Source: https://docs.antigen.sh/docs/help/product/automation/index Rules, workflows, schedules, and advanced reliability patterns. Automation reduces manual work by reacting to events and running trusted sequences. Start with simple rules, graduate to workflows, and apply advanced patterns when volume grows. This hub introduces each layer—use the child articles for specifics. React to events with focused, predictable rules. Chain steps, branch on conditions, and handle failures. Make high-volume automation reliable under load. Run recurring work on a deliberate schedule. # Rules and triggers Source: https://docs.antigen.sh/docs/help/product/automation/rules-triggers Define when automation runs using events, filters, and guardrails. Rules answer **when** something should run. Triggers are the signals—product events, webhooks, or schedules—that start evaluation. Filters and guardrails keep runs safe when traffic spikes or data is messy. ## Events Pick source events such as item created, status changed, or webhook received. Prefer the narrowest event that still captures your intent so you do not wake automation on unrelated edits. ### Ordering If multiple rules subscribe to the same event, understand whether execution is parallel or ordered. Side-effect-heavy rules may need explicit sequencing or a queue. ### Payload shape Automation often receives a structured payload with IDs and timestamps. Log sample payloads in a sandbox when writing conditions so you do not guess field names. ## Filters Narrow by project, label, or field values to avoid noisy runs. Combine predicates carefully: over-filtering misses legitimate cases; under-filtering spams logs and external systems. ### Testing filters Use historical replay or dry-run tools when available. “It worked once” is not the same as “it works for every region code.” ## Guardrails Set concurrency caps and failure alerts before automation touches production data. Caps protect downstream APIs; alerts help humans notice misconfigured filters before customers do. ### Kill switches Document how to disable a rule quickly—feature flag, toggle, or removal—during incidents. Practice the rollback path once per quarter. # Scheduled tasks Source: https://docs.antigen.sh/docs/help/product/automation/scheduled-tasks Cron-style schedules, timezone handling, and backoff. Scheduled tasks run without a human click: nightly syncs, weekly digests, or maintenance windows. Get timezones right once, then monitor failures—silent misses are harder to spot than user-triggered errors. ## Schedules Use cron expressions or friendly presets. All times respect the project timezone unless overridden explicitly for global teams. ### Cadence choices Prefer off-peak windows for heavy jobs. If you need “every hour,” confirm your platform’s minimum interval and whether missed runs catch up or skip. ### Holidays Some teams pause schedules on holidays via a calendar flag or a wrapper rule—otherwise your “Monday report” might fire on a quiet day with no fresh data. ## Daylight saving Ambiguous local times may skip or repeat—prefer UTC for critical jobs. If you must stay local, document the DST transition dates for your region and test around them. ### Jitter Add small random delay when many schedules align at midnight to avoid thundering herds against shared databases. ## Monitoring Failed runs surface in the automation console with logs for debugging. Wire alerts to the same channel as user-facing incidents when the job protects revenue or compliance. ### Runbooks Link a short runbook from each alert: what failed, what to check first, and who owns the downstream integration. # Build your first workflow Source: https://docs.antigen.sh/docs/help/product/automation/workflows/build-first-workflow Step-by-step creation of a simple approval workflow. This walkthrough builds confidence before you model complex branching. You will route new items to a human, time out if nobody responds, and notify a channel when the outcome is approved—patterns common to access requests, content launches, and finance approvals. ## Goal Route new items to a reviewer and notify Slack on approval. Keep scope intentionally small: one project, one template, one external integration. ### Success criteria Define what “done” means: reviewer assigned within five minutes, decision within one business day, and an audit log entry for compliance. ## Steps 1. Create a workflow from a template. Pick the closest match, then rename steps so stakeholders recognize language from your internal process doc. 2. Add a human approval step with timeout. Escalate or cancel when time expires—avoid infinite waits. 3. Connect Slack notification on success. Map channel names to environments (`#proj-approvals-staging` vs production). 4. Test in a sandbox project. Seed fake items that mirror real field shapes, including edge cases like missing optional fields. ### Data contracts Confirm the payload your steps receive matches what integrations expect. A missing `requesterId` in test data can hide a production-only failure. ## Validation Run dry-run executions with sample payloads before enabling for all projects. Capture logs for the first ten production runs and compare timings to your SLA. ### Rollout Enable for a pilot team, gather feedback on wording and timeouts, then expand. Feature-flag the workflow if your platform supports gradual exposure. # Conditions and branches Source: https://docs.antigen.sh/docs/help/product/automation/workflows/conditions-branches Model conditional paths and merge strategies in workflows. Branches let workflows mirror real decisions: approvals vs auto-reject, regional routing, or parallel reviews that must all pass. Invest time in condition clarity—ambiguous logic becomes expensive to debug under load. ## Conditions Express rules with comparisons on fields, regex, and presence checks. Prefer explicit comparisons over implicit truthiness so empty strings and nulls behave predictably. ### Short-circuit behavior Know whether conditions evaluate lazily. If expensive checks run even when a prior clause already failed, you may hit rate limits unnecessarily. ### Testing matrices Build a small table of inputs and expected branches before go-live. Include malformed payloads your API might emit during incidents. ## Branches Run mutually exclusive branches or parallel branches that join later. Parallel paths reduce latency but require clear merge semantics when both sides finish out of order. ### Dependencies If branch B needs artifacts from branch A, enforce ordering with explicit dependencies rather than hoping wall-clock timing works out. ## Merge Define how conflicting branch outputs combine—first wins, merge maps, or custom reducers. Document the merge rule in the workflow description so the next editor does not “simplify” it incorrectly. ### Conflicts When two branches set the same field, specify precedence. Last-write-wins is easy but surprising; structured merges are safer for financial totals. # Error handling Source: https://docs.antigen.sh/docs/help/product/automation/workflows/error-handling Retries, compensating steps, and alerting when workflows fail. Workflows fail in the real world: APIs time out, databases lock, humans go offline. Good error handling turns chaos into retries, compensations, and clear operator signals instead of silent data drift. ## Failures Classify transient versus permanent failures. Transient steps should retry with jitter; permanent failures should stop fast and surface a crisp error code. ### Observability Attach correlation IDs across steps so support can trace a single user action through every hop. Log HTTP status bodies at reduced verbosity to avoid leaking secrets. ### Poison messages If the same payload fails repeatedly, stop retrying and quarantine it—otherwise you starve healthy traffic. ## Compensation Undo partial effects when a downstream step fails—especially for payments or external posts. Compensation may mean voiding an invoice, deleting a draft record, or sending a corrective webhook. ### Ordering Design compensations in reverse dependency order: undo the last successful side effect first. ### Partial success When only one of two external systems succeeded, document the manual reconciliation path in the alert body. ## Alerts Route failures to on-call channels with runbook links. Include workflow name, step name, and last payload hash—not full PII—in the first line of the alert. ### Fatigue Throttle duplicate alerts for the same root cause. Pair alerts with dashboards so responders can see whether failures are trending or isolated. # Workflow builder Source: https://docs.antigen.sh/docs/help/product/automation/workflows/index Build multi-step workflows with branches and error handling. Workflows chain steps with explicit data handoff. Use branches for conditional logic and centralized error handling to avoid partial updates. The following articles walk through your first workflow and deeper branching strategies. Create, connect, and test a useful multi-step workflow. Model conditional paths and bring them back together safely. Make partial failures visible and recoverable. # Comments and mentions Source: https://docs.antigen.sh/docs/help/product/editor/comments-mentions Threaded comments, @mentions, and notification controls. Comments turn static pages into lightweight review spaces. Mentions pull the right people into the loop without forwarding threads in email. This article covers threading, @mentions, and how to stay sane when notification volume spikes. ## Threads Start a thread on a selection. Resolve threads when addressed so everyone can see what is still open versus done. ### Best practices Keep one topic per thread when you can—easier to resolve and easier for newcomers to scan. Quote or anchor to specific paragraphs so replies stay in context months later. ### Permissions Readers may or may not see comment sidebars depending on project policy. If someone says they cannot view a thread, check their project role and whether the page is in a restricted space. ## Mentions @mention teammates to pull them in. Mentions respect project membership: you cannot @mention someone who should not already access the underlying content. ### Typing and suggestions Most editors autocomplete @handles after a few characters. If a colleague recently joined, refresh the member list or wait for directory sync before assuming a name is missing. ### Bots and integrations Some integrations post as service accounts. Mentions to those accounts may open tickets or chat channels—confirm behavior in your automation settings. ## Notifications Mute noisy threads or adjust frequency in personal notification settings. Batch digests work well for deep work; real-time alerts suit on-call rotations or launch weeks. ### Email vs in-app If email feels loud, switch critical threads to in-app only and reserve email for @mentions directly to you. Mobile push can mirror desktop preferences or be disabled for weekends. # Drafts and publishing Source: https://docs.antigen.sh/docs/help/product/editor/drafts-publishing Draft states, review cues, and what happens when you publish. Drafts let you iterate without exposing work-in-progress to every reader. Publishing turns a snapshot into what visitors and integrations see. Use this guide to understand visibility rules, the publish action, and scheduled releases. ## Drafts Drafts are visible to editors you invite. Unpublished changes never appear to read-only roles, which keeps reviews and experiments contained until you are ready. ### Who can edit Editors with access to the project can create and update drafts. Viewers and external roles only see the last published version for pages that use publishing—there is no “preview link” leakage unless you explicitly enable one. ### Autosave and conflicts Edits typically save as you work. If two people edit the same section, you may see a merge prompt or last-write-wins behavior depending on your client—coordinate on busy pages or assign an owner during launches. ## Publish Publishing snapshots content for readers and triggers webhooks if configured. Think of publish as a labeled release: SEO, feeds, and automations usually key off the published revision, not every keystroke. ### Before you publish Skim the title, metadata, and any embedded media. Run a quick link check on high-traffic pages. If you use approvals, wait for the green light from reviewers named in your process. ### After you publish The prior published version remains in history, so you can roll forward again or restore if something looks off. Downstream systems that consume webhooks should treat duplicate delivery as idempotent where possible. ## Scheduling Schedule publish for a future time when your team coordinates launches—useful for announcements, pricing pages, and docs that must go live after a contract or feature flag flips. Pick a timezone that matches how your team communicates (“end of day PT”) and confirm daylight-saving edge cases for global audiences. You can usually reschedule or cancel a queued publish until it actually runs. # Editor and content Source: https://docs.antigen.sh/docs/help/product/editor/index Drafts, publishing, comments, and version history in the editor. The editor balances structured content with fast collaboration. Draft privately, publish when ready, and loop in teammates with comments. Version history helps you recover from mistakes and audit meaningful changes. Move content from private work to a published state. Keep feedback attached to the work it concerns. Review changes and recover an earlier version. # Version history Source: https://docs.antigen.sh/docs/help/product/editor/version-history Browse versions, compare changes, and restore content. Version history is your safety net: every meaningful save becomes a checkpoint you can compare, audit, or restore. Use it after bad merges, to see who changed a policy line, or to copy text from an older revision without undoing newer work elsewhere. ## Timeline Open history to see chronological snapshots with author attribution. Each entry usually includes a timestamp, editor, and optional note if your team labels releases. ### Retention How long versions are kept depends on your plan and admin policy. Legal or regulated teams should confirm retention meets internal records rules before relying on history alone for compliance. ### Naming and bookmarks If your product supports labels or tags on versions, use them for “before migration” or “approved by legal” so you can find needles in long timelines. ## Compare Diff view highlights additions and removals between versions. Use split view for prose and unified view for small edits. ### Large pages Very long pages may lazy-load diff segments. If something looks blank, scroll the full height or expand collapsed regions. ### Binary and embeds Embedded media may show as changed when URLs rotate even if text is identical—compare surrounding paragraphs to confirm intent. ## Restore Restore creates a new version based on the selected snapshot—nothing is silently overwritten. That means you keep a clear audit trail: the restore event itself is a new entry. ### Communicate restores Tell collaborators when you roll back shared pages so they do not re-introduce outdated facts on top of your fix. Link to the restored version in your team chat or ticket. # Product guides Source: https://docs.antigen.sh/docs/help/product/index Learn the interface, projects, editor, and automation features. This section is your field guide to everyday work: navigating the interface, structuring projects, writing content, and automating repeatable work. Jump to any guide below—the structure mirrors how teams typically roll out from first login to advanced workflows. Learn the sidebar, canvas, inspector, and settings model. Move through common actions without leaving the keyboard. Find content and move around the product quickly. Create, organize, archive, and restore collaborative work. Draft, publish, comment, and recover earlier versions. Build rules, workflows, schedules, and reliable automation. # Interface overview Source: https://docs.antigen.sh/docs/help/product/interface-overview Sidebar, command palette, and where to find settings. The product shell is designed to keep navigation predictable: primary work happens in the center, global navigation stays on the left, and contextual actions stay close to what you selected. Spend a few minutes learning the three regions below—you will move between them constantly. ## Layout * **Sidebar** — Projects, automation, and account entry points. Pin favorites if your client supports it so daily spaces stay one click away. * **Canvas** — The main surface for viewing and editing work. On smaller screens the sidebar may collapse; use the menu control to reopen it without losing context. * **Inspector** — Metadata and contextual actions for the current selection. Empty states usually mean “nothing selected yet” rather than missing permissions. ### Focus and panels Some workflows open transient panels (comments, history, AI). Closing a panel returns focus to the canvas; keyboard users can tab through interactive regions in DOM order. ## Command palette Open the palette to jump anywhere quickly. It respects your permissions—destinations you cannot access simply do not appear or show as disabled with a reason. ### Search vs navigate Use the palette for fuzzy jumps when you know a name fragment. Use the global search entry when you need full-text results across bodies and attachments. ## Settings Workspace settings live under your avatar; project settings are scoped per project. When in doubt, check the breadcrumb or page title so you do not change org-wide SSO while meaning to tweak a single project’s webhook. ### Auditing changes Admins should review who last changed workspace defaults after reorganizations. Project-level changes are easier to isolate in activity logs when each team owns its space. # Keyboard shortcuts Source: https://docs.antigen.sh/docs/help/product/keyboard-shortcuts Speed up navigation and editing with keyboard shortcuts. Shortcuts reduce context switching: keep hands on the keyboard for formatting, navigation, and comments. The tables below cover common defaults; your organization may publish a one-page cheat sheet for onboarding. ## General | Action | Shortcut | | - | - | | Command palette | ⌘K / Ctrl+K | | Search | ⌘P / Ctrl+P | On Windows and Linux, **Ctrl** replaces **⌘** where both are listed. If a shortcut conflicts with your browser or OS, disable the conflicting extension or remap inside the product when supported. ## Editor | Action | Shortcut | | - | - | | Bold | ⌘B / Ctrl+B | | Comment | ⌘⌥M / Ctrl+Alt+M | ### Selection and blocks Many editors support **⌘D** / **Ctrl+D** for multi-cursor or duplicate-line behaviors—check in-app hints because they can vary by block type (paragraph vs code). ### Accessibility If reduced-motion or sticky keys are enabled at the OS level, chord shortcuts may require slower presses. Screen reader users should verify focus lands in the expected region after palette commands. ## Customize Some shortcuts can be remapped in **Settings → Accessibility** on supported clients. Export your mapping before switching machines so you can import or recreate it on a new laptop. ### Conflicts with input methods IME users composing CJK text may need to disable certain chords temporarily or use the command palette instead of direct shortcuts that steal modifier keys. # Archive and restore projects Source: https://docs.antigen.sh/docs/help/product/projects/archive-restore Archive completed work and restore when needed. Archiving is the gentle off-ramp for completed initiatives: out of default lists, but recoverable when a customer reopens a contract or an audit asks for historical context. Plan exports before archive if compliance requires cold storage. ## Archive Archiving hides a project from default lists while preserving history. Automation pauses so you do not enqueue jobs against dormant data. ### Communication Tell stakeholders when you archive so they do not think content was deleted. Link to the new canonical project if work continued elsewhere. ### Partial archives If only one stream is done, consider labels or subfolders instead of whole-project archive when other tracks remain active. ## Restore Workspace admins can restore within the retention window. Older archives may require support if your policy moved data to long-term storage. ### Validation after restore Spot-check permissions and integrations after restore—tokens may have rotated while the project was idle. ## Compliance Export before archive if your policy requires long-term cold storage outside the product. Keep checksums or manifest files so legal can prove what was frozen at a point in time. # Create a project Source: https://docs.antigen.sh/docs/help/product/projects/create-project Name, visibility, and defaults when starting a new project. Projects are the boundary for permissions, notifications, and automation. Spending two minutes on naming and visibility up front prevents accidental exposure later—especially when customers or partners are invited. ## Create flow Click **New project**, choose a name, and pick visibility: workspace-only or invite-only. Invite-only is appropriate when content must not be discoverable by everyone in the org directory. ### Naming Use a name people will recognize in notifications and URLs. Avoid confidential codenames in titles if screenshots might leak; put codenames in an internal field instead. ### Ownership Assign an owner who can approve membership changes. Orphan projects without owners tend to accumulate stale access lists. ## Templates Start from blank or apply a template with prebuilt sections for your team’s process. Templates accelerate rollout but still need a quick review—remove sample text that could confuse readers. ### Forking templates When you customize a template heavily, save a new template version so other teams inherit your improvements instead of editing one-off copies. ## Defaults Set default labels and owners so new items do not land unassigned. Defaults reduce “triage debt” on Monday mornings when many items are created at once. ### Iteration Revisit defaults after major process changes (new severity model, new regions). Old defaults silently mis-route work if nobody updates them after a reorg. # Projects Source: https://docs.antigen.sh/docs/help/product/projects/index Create projects, organize work, and archive when you are done. Projects are the primary container for collaborative work. Permissions, automation, and notifications can all be scoped to a project. Use the articles here to create your first project and manage its lifecycle responsibly. Set up a useful project with the right initial structure. Remove inactive work from view and bring it back safely. # Search and navigation Source: https://docs.antigen.sh/docs/help/product/search-navigation Find projects, pages, and automation using search. Search is the fastest path from “where was that?” to the right page—especially as your workspace grows. Combine query syntax, filters, and recents to cut noise and land on canonical answers your team already wrote. ## Global search Search spans titles, bodies, and selected metadata. Filters narrow results by owner, date, and type so you can answer “what changed last week?” without scanning every project. ### Operators Use quoted phrases for exact matches and minus terms to exclude noise (for example, a term you know appears in boilerplate). Combine filters when you remember the author but not the title. ### Ranking Results usually favor recent edits and stronger title matches. If something ranks oddly, try a more specific phrase or open the containing project and browse by folder structure. ## Recent Recent items appear in the sidebar for fast return visits. Clear recents when demoing or handing off a laptop so you do not leak internal titles on a shared screen. ### Pinning If your client supports pins or favorites, use them for runbooks and onboarding hubs you open daily—faster than typing the same query repeatedly. ## Tips Use quoted phrases for exact matches and minus terms to exclude noise. When you find the canonical page, add a short internal link from related articles so the next person finds it in one click. ### When search is not enough If content is missing, file a docs ticket or add a stub page—search cannot surface what does not exist yet. For automation IDs, search by stable slug or external key when titles drift. # Delete your account Source: https://docs.antigen.sh/docs/help/support/account-data/delete-account Understand deletion impact and required confirmations. Deletion is destructive. Treat it like a production change: announce, export, and verify integrations will not recreate data you meant to purge. ## Workspace deletion Deleting a workspace is irreversible after the cooling-off period. Notify members first. ### Dependencies Disconnect billing identities, SSO apps, and webhooks before deletion—orphaned automation can still fire against deleted IDs in some systems. ## Personal account Personal deletion removes your profile from associated workspaces per policy. ### Identity recovery If you might return, understand whether email addresses can be reused later or remain locked to prevent impersonation. ## Backups Export before deletion if you need records for compliance. ### Certificates Download or transfer domain verification records if your brand moves to another provider. # Export your data Source: https://docs.antigen.sh/docs/help/support/account-data/export-data Request exports, formats, and retention notes for your data. Exports let you back up, migrate, or satisfy access requests. Plan format and scope before you click—large workspaces can queue for a while and may need multiple partial exports. ## Self-serve export Admins can export project bundles in standard formats from **Settings → Data**. ### Format choices Pick structured formats your downstream tools ingest—JSON for pipelines, PDF for human review. ## Timing Large exports queue asynchronously; you receive email when ready. ### Partial failures If an export completes with warnings, read the manifest for skipped objects—permissions or corrupt attachments are common causes. ## Scope Exports include content you have permission to read—respect confidentiality when sharing files. ### Legal holds Consult counsel before exporting if litigation holds apply—some systems block export or require approval. # Account and data Source: https://docs.antigen.sh/docs/help/support/account-data/index Export your data and understand account deletion. You should always know what you can take with you and what happens when an account ends. Use export for portability and follow deletion steps carefully when offboarding a workspace. Prepare and retrieve a portable copy of workspace data. Understand the impact and complete account deletion carefully. # Contact support Source: https://docs.antigen.sh/docs/help/support/contact-support Channels, severity levels, and what to include in a support request. Good support tickets get answers faster. Lead with impact, narrow the blast radius with IDs, and attach evidence your team already has—logs, HAR files, or screen recordings for UI issues. ## Channels * In-app chat on Team and Enterprise * Email for billing and security questions ### Routing Use the channel your contract lists for Sev1 incidents. Misrouted tickets lose time to handoffs. ## Severity Mark production outages as highest severity with clear customer impact. ### Be specific “Slow” is vague; “API p95 latency 8s since 14:05 UTC on `/v1/items`” is actionable. Include approximate user count affected. ## Good requests Include timestamps, URLs, request IDs, and steps to reproduce. ### Redaction Remove secrets from pasted logs—rotate anything that leaks accidentally. ### Follow-ups If you discover new data after filing, reply on the same thread so context stays unified. # Support and policies Source: https://docs.antigen.sh/docs/help/support/index Get help, check status, troubleshoot, and review legal information. This section covers how to reach us, what to do when something breaks, how to manage your data, and the legal agreements that govern use of the service in this demo. Nothing here is legal advice—replace with your counsel-approved text in production. Choose the right channel and send the context support needs. Check service health and follow an active incident. Work through common login and performance problems. Export workspace data or understand account deletion. Review terms, privacy materials, and regional information. # Legal and compliance Source: https://docs.antigen.sh/docs/help/support/legal/index Terms, privacy, regions, and compliance topics in this demo. Legal documents define how you may use the service. This hub links to terms, privacy materials, and regional notes used for the demo help center. Replace placeholder text with counsel-reviewed language before production use. Review the agreement that governs use of the service. Find the privacy policy, DPA, and subprocessors. Review high-level residency information for supported regions. # Data processing addendum Source: https://docs.antigen.sh/docs/help/support/legal/privacy/dpa Demo DPA overview for controllers and processors. A DPA formalizes GDPR-style obligations between controllers and processors: instructions, subprocessors, security measures, and breach notification. Use this outline as a starting point for legal review—not as executed terms. ## Roles You may act as a controller and the provider as a processor for certain processing activities. ### Sub-processing Specify whether prior approval is required for new subprocessors and how objections are handled. ## Instructions Processing follows your documented instructions and applicable law. ### Change control Define how processing instructions change over time—ticket references, email approvals, or signed addenda. ## Subprocessors Review the subprocessors page for infrastructure providers and their purposes. ### Audits Enterprise agreements often include audit rights, questionnaires, and evidence timelines—negotiate frequency and scope explicitly. # Privacy and GDPR Source: https://docs.antigen.sh/docs/help/support/legal/privacy/index Privacy policy, DPA, and subprocessors for this demo. Privacy practices describe what we collect, why, and how long we keep it. In this template, content is representative. Pair these articles with your actual privacy program and subprocessors list in production. Understand what data is collected and why. Review the terms that govern processing customer data. See the service providers involved in processing data. # Privacy policy Source: https://docs.antigen.sh/docs/help/support/legal/privacy/privacy-policy Demo privacy policy for this help center. Privacy policies describe what you collect, why, how long you keep it, and who you share it with. This template sketches sections only—your counsel should align it with your actual processing activities and jurisdictions. ## Data we process Account data, usage telemetry, and content you store in the product for demonstration purposes. ### Sensitive categories If you process health, financial, or children’s data, add explicit sections and lawful bases—generic text is insufficient. ## Purposes Operate the service, secure accounts, and improve reliability. ### Analytics Disclose whether you use analytics, session replay, or error tracking—and how users can opt out where required. ## Rights Depending on region, you may have rights to access, correct, or delete personal data—see regional articles. ### Requests Describe how individuals submit requests, expected response times, and appeal paths if you deny a request. # Subprocessors Source: https://docs.antigen.sh/docs/help/support/legal/privacy/subprocessors Illustrative list of subprocessors for this demo. Subprocessors extend your security perimeter—customers review them for data residency, certifications, and incident history. Keep this list current; stale entries erode trust during procurement. ## Infrastructure Hosting and networking vendors that operate regions you select. ### Certifications Link SOC 2, ISO, or FedRAMP reports where applicable so enterprise teams can self-serve. ## Communications Transactional email and in-product messaging providers. ### Data minimization Note which fields each vendor receives—full profile vs email-only. ## Updates We notify customers of substantive subprocessor changes as described in enterprise agreements. ### Objection windows Define how customers object or terminate if they cannot accept a new subprocessor—timeline and migration assistance matter. # APAC Source: https://docs.antigen.sh/docs/help/support/legal/regions/apac APAC considerations for this demo help center. APAC spans many jurisdictions—Australia, Japan, Singapore, India, and others—with different data localization, breach notification, and consent rules. Treat this page as a prompt for counsel, not a legal survey. ## Latency Pick APAC regions when most users are local to reduce round trips. ### Multi-region UX Surface the user’s active region in support tooling so you do not misdiagnose “slow” issues as application bugs when they are physics. ## Regulations Requirements vary widely—map your jurisdictions to product features with your counsel. ### Localization Some locales require local language privacy notices or consent capture—plan content and UX accordingly. ## Support hours Coverage windows may differ; Enterprise plans offer expanded follow-the-sun options. ### Holidays Regional holidays affect both your team and vendor staff—adjust SLAs for local observances. # EU data residency Source: https://docs.antigen.sh/docs/help/support/legal/regions/eu-residency EU data residency options in this demo help center. EU customers often ask where data lives and who can access it from abroad. Residency answers the first question; transfers and safeguards answer the second. ## Options Select EU regions when provisioning if your contract includes regional deployment. ### Multi-region If you operate globally, document which data classes stay in-region vs replicate for disaster recovery. ## Transfers Cross-border transfers rely on approved mechanisms described in your DPA. ### SCCs and IDTA Track which transfer tool you rely on for each flow and when standard contractual clauses update—legal teams run periodic refresh projects. ## Support EU customers may receive support from global teams with appropriate safeguards. ### Access logging Some customers require EU-only support staff for certain tickets—confirm whether your plan supports that routing. # Regional specifics Source: https://docs.antigen.sh/docs/help/support/legal/regions/index Data residency notes for EU, US, and APAC in this demo. Regional articles summarize how deployment choices affect storage and support. They are intentionally high level for the template. Validate residency requirements with your compliance team before go-live. Review high-level EU data residency considerations. Review high-level US data residency considerations. Review high-level APAC data residency considerations. # US data residency Source: https://docs.antigen.sh/docs/help/support/legal/regions/us-residency US data residency notes for this demo. US customers may choose US regions for latency, contractual requirements, or comfort with domestic legal process. Pair residency choice with encryption and key management policies. ## Regions Choose US data centers for latency and regulatory alignment where required. ### Multi-cloud If you span multiple providers, document failover behavior—some failover paths cross regions unless explicitly constrained. ## Government requests We publish high-level transparency about requests as permitted by law. ### Customer notice Your enterprise agreement may define when you receive notice of legal requests affecting your content—verify timelines and contact paths. ## Education FERPA and similar frameworks may impose additional obligations—consult specialists. ### Student data If you serve schools, map product features to FERPA roles and allowable disclosures before onboarding student populations. # Terms of service Source: https://docs.antigen.sh/docs/help/support/legal/terms-of-service Demo terms of service for this help center template. This page exists to show how legal content fits in navigation and layout. Replace every section with counsel-approved language before production use—placeholders are not enforceable contracts. ## Acceptance By using this demo, you agree to illustrative terms meant for layout and navigation only. ### Age and authority Real contracts specify eligible users, signing authority, and prohibited uses. Add those sections when you replace this text. ## Service changes Features described here may change without notice in a template environment. ### Notice periods Production agreements typically define how material changes are communicated—email, in-product banner, or versioned PDF. ## Liability This text is not legal advice and is not a binding agreement—consult your legal team. ### Caps and exclusions Negotiate liability caps, indirect damages, and carve-outs for gross negligence or IP infringement with your counterparty. # Status and incidents Source: https://docs.antigen.sh/docs/help/support/status-incidents Where to find live status and how incidents are communicated. Transparency during incidents builds trust. Subscribe before you need it—during an outage you will not want to hunt for the status page URL. ## Status page Bookmark the status page for component health and historical incidents. ### Components Understand which component maps to your integration path (API vs auth vs attachments) so partial outages make sense. ## Subscriptions Subscribe to email or RSS updates for maintenance windows. ### On-call Mirror status subscriptions into your incident channel so whoever is on-call sees updates without checking email. ## Postmortems Major incidents include summaries with remediation steps for transparency. ### Your runbooks After a vendor incident, update your internal runbook with workarounds you discovered—future you will thank past you. # Troubleshooting Source: https://docs.antigen.sh/docs/help/support/troubleshooting/index Fix common login and performance problems. When something feels off, start with the basics: connectivity, browser health, and account state. These guides address the most frequent issues we see in customer conversations—your mileage may vary in real deployments. Diagnose account, browser, MFA, and SSO sign-in problems. Narrow down slow pages, requests, and integrations. # Login issues Source: https://docs.antigen.sh/docs/help/support/troubleshooting/login-issues Resolve password resets, SSO failures, and session problems. Login problems cluster around expired passwords, SSO misconfiguration, and browser state. Work through the sections below before opening a ticket—most resolutions take minutes. ## Password reset Use the reset link once; repeated clicks invalidate older tokens. ### Inbox rules If resets never arrive, check quarantine and forwarding rules. Some enterprises strip links from unknown senders. ## SSO Confirm IdP certificates are valid and attribute mappings match service expectations. ### SAML traces Capture a SAML trace from your IdP when failures persist—support can compare assertion attributes to what the product expects. ### Clock skew Large skew between IdP and SP can break assertions—sync NTP on servers. ## Sessions Clear site data for stale cookies and retry from a private window to isolate extensions. ### Corporate proxies SSL inspection occasionally breaks OAuth flows—try off-network or a personal device to isolate the proxy as a variable. # Performance issues Source: https://docs.antigen.sh/docs/help/support/troubleshooting/performance-issues Diagnose slowness, large pages, and network constraints. Performance issues feel like “the app is slow” but usually break down into network, rendering, or data volume. Gather one slow trace with timestamps before escalating—patterns matter more than one-off complaints. ## Browser Disable heavy extensions and test with hardware acceleration toggled. ### Profiles Try a fresh browser profile with only default extensions. Ad blockers and password managers sometimes inject scripts that delay paint. ## Content Huge embedded media slows load—lazy load or host externally when possible. ### Tables and charts Large datasets should paginate or virtualize. If the editor feels fine but read mode lags, the DOM size is a likely culprit. ## Network Corporate proxies sometimes buffer WebSockets—ask IT for allowlist guidance. ### VPN Split tunnel vs full tunnel changes latency paths. Compare latency with VPN off (if policy allows) to isolate the network layer. # Antigen Documentation Source: https://docs.antigen.sh/docs/index Antigen runs cybersecurity agents that attack your infrastructure, investigate vulnerabilities, and prepare fixes. Your team reviews the results and proposed changes in the platform or through connected tools.

Get Started

Antigen Documentation

Antigen runs cybersecurity agents that attack your infrastructure, investigate vulnerabilities, and prepare fixes. Your team reviews the results and proposed changes in the platform or through connected tools.

## How Antigen works Connect your services, resources, and identities in one Asset Map. Agents use their relationships to understand your environment. Run Antigen’s pre-built offensive security agent against approved targets. It attempts to exploit weaknesses in your system and creates vulnerabilities with evidence when it succeeds. Agents investigate vulnerabilities and prepare fixes for review. Your team deploys the changes, then tCell tests whether they resolved the issue. ## Follow the work A vulnerability keeps its evidence and work history as agents investigate it, prepare a fix, and verify the deployed change. Hooks start the next step when its status or assignment changes. Follow how triage, remediation, and verification work together, and configure the hooks that launch your agents. When an agent needs access, a review, or a decision, it creates a human task. Receive these requests in your team’s messaging and issue tracking tools. ## Build with Antigen The Antigen team assembles its pre-built agents with the same SDK available to your team. Extend an agent or assemble your own, then use hooks to connect it to your workflows. You can also query your Asset Map and work with vulnerabilities, evidence, and human tasks from your own applications. Assemble agents and work with Antigen from TypeScript. Start runs and inspect results from your terminal or CI pipeline. Find endpoints, request parameters, and response schemas. For a guide to the terms used throughout these docs, see [Concepts](/docs/getting-started/concepts). # Anthropic Source: https://docs.antigen.sh/docs/integrations/anthropic Connect your Claude Console organization to add its members, workspaces, and API key metadata to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Organization members | Users and their organization roles. | | Workspaces | Workspaces within the organization. | | API keys | Key metadata, status, and relationships to workspaces and owners. | These relationships help agents understand how your team organizes access to the Claude API. ## Access required Use a Claude Console **Admin API key**, which starts with `sk-ant-admin`. An organization administrator must create it. Admin API keys have administrative permissions. Antigen uses the key to read resource and access metadata without changing your organization. See the [Anthropic Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) for supported organization resources. ## Connect Anthropic ### 1. Create an Admin API key Sign in to [Claude Console](https://platform.claude.com) as an organization administrator. Open **Settings → Admin keys**, create a key named `Antigen`, and copy its value. Use the Console organization that owns the workspaces you want to map. ### 2. Complete the connection Open **Settings → Integrations → Anthropic** in Antigen. Paste the Admin API key and select **Connect**. Antigen discovers the organization’s members, workspaces, and keys and adds them to your Asset Map. ## Troubleshooting ### The key is rejected Check that the key was created under **Admin keys** in Claude Console and has not expired or been revoked. A standard key for calling Claude does not provide the access required by this connection. ### Workspaces are missing Check which organization was selected when you created the key. Connect each Claude Console organization separately. # Astro Source: https://docs.antigen.sh/docs/integrations/astro Connect your Astronomer Astro organization to add its workspaces, Airflow deployments, and users to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Organization | Organization details and members. | | Workspaces | Workspaces and their deployments. | | Deployments | Airflow and Astro Runtime versions, executor type, cloud provider, region, and status. | | Users | Organization roles and account status. | These relationships help agents identify where your data pipelines run and who has access to the organization. ## Access required Use an **organization API token** with permission to view the organization, its workspaces, deployments, and users. Choose a role that covers these resources. A token restricted to one workspace will not provide organization-wide visibility. Antigen uses the token to read configuration. The token’s full permissions depend on the roles you assign in Astro. ## Connect Astro ### 1. Create an organization API token In Astro, open **Settings → Access Management → API Tokens** and select **New Organization API Token**. Name the token `Antigen`, select its organization role, and choose an expiration. Create the token and copy its value. See [Astro organization API tokens](https://www.astronomer.io/docs/astro/organization-api-tokens) for token roles and setup instructions. ### 2. Complete the connection Open **Settings → Integrations → Astro** in Antigen. Paste the token and select **Connect**. Antigen discovers the organization associated with the token and adds its resources to your Asset Map. ## Troubleshooting ### The token is rejected Check that you created an organization API token and that it has not expired or been revoked. ### Workspaces or deployments are missing Check the token’s organization and workspace roles. Its permissions must cover the resources you want to map, including deployments in each workspace. # AWS Source: https://docs.antigen.sh/docs/integrations/aws Connect an AWS account to add its resources, identities, and relationships to your [Asset Map](/docs/asset-map). ## What it maps | Service | Resources and configuration | | - | - | | EC2 | Instances, attached volumes, and network interfaces. | | VPC | VPCs, subnets, security groups, and traffic rules. | | IAM | Users, groups, roles, policies, and trust relationships. | | RDS | Database instances, clusters, and snapshots. | | S3 | Buckets and access policies. | Relationships show how these resources connect, including which security groups apply to an instance and which principals a role trusts. ## Access required The integration uses a **read-only IAM role** in your AWS account. Attach these AWS-managed policies: | Policy | Purpose | | - | - | | [SecurityAudit](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/SecurityAudit.html) | Read security configuration metadata. | | [ViewOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ViewOnlyAccess.html) | Discover resources and read their metadata. | Antigen assumes the role using temporary credentials. You do not need to create or share an IAM user’s access keys. See [AWS role-based access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) for how this works. You’ll need permission in AWS to create an IAM role and attach these policies. ## Connect your account ### 1. Get the trust policy Open **Settings → Integrations → AWS**. Copy the trust policy provided during setup. It identifies the Antigen role allowed to access your account and includes an external ID specific to this connection. ### 2. Create the IAM role In the AWS IAM console: 1. Open **Roles → Create role**. 2. Choose **Custom trust policy** and paste the policy from Antigen. 3. Attach **SecurityAudit** and **ViewOnlyAccess**. 4. Name the role `antigen-readonly` and create it. See [Create a role using a custom trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) for AWS’s instructions. ### 3. Complete the connection Copy the new role’s ARN and return to Antigen. Enter the role ARN and the regions you want to include, such as `us-east-1` and `us-west-2`, then select **Connect**. Antigen checks that it can assume the role and starts discovering resources. They appear in your Asset Map as the sync progresses. Repeat these steps for each AWS account you want to connect. ## Troubleshooting ### The role cannot be assumed Check that the role ARN is correct and its trust policy matches the policy provided during setup, including the external ID. ### Resources are missing Check that the connection includes the region containing those resources. Confirm that both required policies are attached to the role and that your organization’s AWS policies allow the required read operations. # Azure Boards Source: https://docs.antigen.sh/docs/integrations/azure-boards Connect Azure Boards to track [human tasks](/docs/team-workflows) as work items in Azure DevOps. Each work item is assigned to a person and includes the agent’s request and the relevant vulnerability. ## Access required Connect with a Microsoft work account that can access your Azure DevOps organization and project. The integration needs permission to read and update work items, assign project members, and receive work item updates. Authentication uses [Microsoft Entra OAuth](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/entra-oauth?view=azure-devops). Your Microsoft administrator may need to approve access, and a project administrator may need to complete the connection. ## Connect Azure Boards 1. Open **Settings → Integrations → Azure Boards**. 2. Select **Connect**, sign in with your Microsoft work account, and approve access. 3. Choose the Azure DevOps organization and project where tasks should appear. 4. Select a work item type and configure the fields required by your project. For example, your team can use the Task work item type and an area path dedicated to security work. The people assigned tasks need access to that project and area. ## Complete a request Use the work item’s discussion to provide updates or ask questions. Once you complete the requested action, move the work item to a completed state in your project’s process. An agent might ask you to deploy a proposed fix. After deployment, confirm the environment and change in the work item so the agent can continue with the right context. Work items can also update automatically when a connected integration detects the requested action. See [Issue tracking](/docs/team-workflows/issue-tracking) for how task completion works. ## Troubleshooting ### The project is unavailable Check that your Microsoft account belongs to the connected Azure DevOps organization and has access to the project. ### A work item cannot be created or assigned Check the required fields for its type, permissions on the selected area path, and the recipient’s project access. # Clerk Source: https://docs.antigen.sh/docs/integrations/clerk Connect a Clerk application instance to add its users and organizations to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration | | - | - | | Application instance | The instance and whether it is a development or production environment. | | Users | Names, email addresses, MFA status, and locked or banned status. | | Organizations | Names, slugs, and member counts. | Each user and organization is associated with the Clerk instance it belongs to. ## Access required Use the instance’s **Secret Key** to authenticate to Clerk’s Backend API. Production keys begin with `sk_live_`; development keys begin with `sk_test_`. See [Clerk Publishable and Secret Keys](https://clerk.com/docs/guides/development/clerk-environment-variables#clerk-publishable-and-secret-keys). Antigen reads instance, user, and organization information. A Clerk Secret Key can also authorize changes to that instance. ## Connect Clerk ### 1. Copy the instance’s Secret Key Open your application in the [Clerk Dashboard](https://dashboard.clerk.com/). Select the environment you want to map, then open **API keys** and copy the **Secret Key**. Use the production instance when mapping your production application. Development and production instances have separate users, organizations, and keys. ### 2. Complete the connection Open **Settings → Integrations → Clerk** in Antigen. Paste the Secret Key and select **Connect**. The instance’s users and organizations appear in your Asset Map. Repeat these steps for each application instance you want to connect. ## Troubleshooting ### The map shows development users Check that you selected the production instance in Clerk and supplied its `sk_live_` key. ### The key is rejected Confirm that you copied the Secret Key. Publishable keys beginning with `pk_` cannot authenticate the Backend API requests this integration uses. If you rotated the Secret Key, update the connection with its replacement. # Cursor Cloud Source: https://docs.antigen.sh/docs/integrations/cursor-cloud Use Cursor Cloud agents to investigate vulnerabilities and prepare pull requests. Your service receives an Antigen webhook, retrieves the vulnerability, and starts an agent through the Cursor API. The agent runs in Cursor’s environment. Your service controls when it starts and updates the vulnerability’s status and assignment as work progresses. ## Before you start You need: * Cursor Cloud agent access and an API key. * A repository connected to Cursor, with an environment configured for the agent’s work. * An [Antigen API key](/docs/sdk/authentication) for reading vulnerabilities and updating them. * A service that can receive [Antigen webhooks](/docs/vulnerability-lifecycle/hooks). Keep both API keys in your service’s secret storage. See [Cursor’s Cloud Agent API](https://cursor.com/docs/cloud-agent/api/overview) for API access and authentication. ## Set up the workflow ### 1. Choose when to start work Register a webhook pointing to your service. Choose the event that should start your workflow, such as a vulnerability entering **Open** or being assigned to your agent. Your handler checks the event before starting work. For assignment events, check that the new assignee is the agent your service handles. If you are replacing a default triage or remediation workflow, disable the corresponding default hook in the platform or via the API. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for the available triggers. ### 2. Launch a Cursor Cloud agent Use the Antigen API to retrieve the vulnerability and its evidence. Select the affected repository and include the relevant context in the agent’s instructions. For example, ask the agent to reproduce the reported behavior, inspect the affected code, and prepare a pull request with a fix and tests. Start the agent through the [Cursor API](https://cursor.com/docs/cloud-agent/api/endpoints). Save the returned agent identifier alongside the vulnerability ID so your service can follow its progress and associate the result with the right vulnerability. ### 3. Update the vulnerability Your service follows the agent’s progress through the Cursor API. Create a [human task](/docs/sdk/human-tasks) through the Antigen API to request your team’s review, including the pull request or proposed infrastructure change. When the fix has been deployed, move the vulnerability to **Remediated** to start verification if the default verification hook is enabled. ## Ask your team for help The agent or your service can create [human tasks](/docs/sdk/human-tasks) through the Antigen API to request access, a review, or an infrastructure change. Those requests use the same connected messaging and issue tracking tools as tasks from the pre-built agents. ## Troubleshooting ### The agent cannot access the repository Check the repository access granted to Cursor and its Cloud agent environment. The agent needs the dependencies and credentials required to inspect and test the code. ### A result appears on the wrong vulnerability Check the association your service stores between the Antigen vulnerability ID and the Cursor agent identifier. Use that association when processing later updates. # Devin Source: https://docs.antigen.sh/docs/integrations/devin Use Devin to investigate vulnerabilities and prepare fixes. Your service receives an Antigen webhook, retrieves the vulnerability and its evidence, and creates a Devin session with instructions for the work. Devin works in its own environment. Your service follows the session and updates the vulnerability’s status and assignment through the Antigen API. ## Before you start Connect the relevant repository to Devin and configure the environment it needs to work on your code. For automation, create a Devin service user with permission to create and read sessions. Generate its API key and copy your organization ID from **Settings → Service users**. See [Devin API authentication](https://docs.devin.ai/api-reference/authentication) for service user setup. You also need an [Antigen API key](/docs/sdk/authentication) and a service that can receive [webhooks](/docs/vulnerability-lifecycle/hooks). Store the API keys in your service’s secret storage. ## Set up the workflow ### 1. Register a webhook Point an Antigen webhook at your service and choose the status or assignment changes it should receive. Your handler decides which events should create a Devin session. For example, it can handle assignment events only when the new assignee is your agent. If you are replacing a default workflow, disable its hook in the platform or via the API. You can replace remediation while keeping the default triage and verification hooks. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents). ### 2. Create a Devin session Retrieve the vulnerability and its evidence through the Antigen API. Include the affected repository, the observed behavior, and the requested outcome in the session prompt. For remediation, the request might be to reproduce the issue, prepare a fix, run the relevant tests, and open a pull request. Use Devin’s [Create Session API](https://docs.devin.ai/api-reference/v3/sessions/post-organizations-sessions) and keep the session ID associated with the Antigen vulnerability ID. ### 3. Return the result Your service reads session progress and results through the Devin API. Create a [human task](/docs/sdk/human-tasks) through the Antigen API to request your team’s review, including the pull request or proposed infrastructure change. Your team reviews and deploys the change. Once it is deployed, move the vulnerability to **Remediated** to start verification if the default verification hook is enabled. ## Request a human task If Devin needs more access or a human decision, the agent or your service can create a [human task](/docs/sdk/human-tasks) through the Antigen API. The assigned person receives the request through your connected messaging or issue tracking tool. Your service can read the task’s updates and send the response back to the Devin session. ## Troubleshooting ### A session cannot be created Check the service user’s role, organization membership, and API key. Confirm that the request uses the intended Devin organization ID. ### Devin cannot work on the repository Check the repository connection and environment in Devin, including the dependencies needed to reproduce the issue and run tests. # GitHub Source: https://docs.antigen.sh/docs/integrations/github Connect GitHub to map repository access, let agents inspect your code and propose fixes, and assign [human tasks](/docs/team-workflows) as GitHub Issues. ## Choose what agents can access The GitHub App connects the repositories you select. The access you grant determines what agents can do: | Capability | How agents use it | | - | - | | Repository and organization metadata | Map repositories, teams, and access in your [Asset Map](/docs/asset-map). | | Read code | Inspect affected code while investigating a vulnerability or planning a fix. | | Propose changes | Create branches and pull requests for your team to review. | | Manage issues | Create and update human tasks, assign people, and read their responses. | Your team reviews proposed code changes through its normal pull request process. See [Connecting your codebase](/docs/vulnerability-lifecycle/connecting-your-code) for how repository access supports triage and remediation. ## Connect GitHub ### 1. Start the installation Open **Settings → Integrations → GitHub** and start the GitHub App installation. Sign in to GitHub and choose the organization you want to connect. An organization owner may need to approve the installation and its requested permissions. ### 2. Select repositories and permissions Choose **Only select repositories** to limit access, or **All repositories** to include every repository in the organization. Review the permissions requested for the capabilities you want to use, then approve the installation. GitHub controls repository access through this installation. See [Install a GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party) for organization approval requirements. ### 3. Choose where human tasks appear If you use GitHub Issues for human tasks, select a repository for those issues in the integration settings. Issues must be enabled in that repository, and the people receiving tasks must be eligible assignees. Each issue contains the agent’s request, the relevant vulnerability, and instructions for completing the work. ## Respond to a human task Complete the requested action, add any relevant details, and close the issue. You can also comment to ask questions or explain what is blocking you. If a task asks you to merge a pull request, the integration detects the merge and completes the task automatically. A request to deploy a fix remains open until deployment is confirmed. See [Issue tracking](/docs/team-workflows/issue-tracking) for how these updates let agents continue. ## Change repository access Open your organization’s installed GitHub Apps and configure the Antigen installation. Add or remove repositories as your needs change. If an agent needs code outside the selected repositories, it can create a human task asking your team to grant access. ## Troubleshooting ### An agent cannot read a repository or open a pull request Check that the repository is included in the installation and that the app has the permissions needed for the requested action. If GitHub is waiting for an owner to approve updated permissions, complete that approval first. ### An issue cannot be assigned Check that the selected person has access to the repository and can be assigned issues there. # GitLab Source: https://docs.antigen.sh/docs/integrations/gitlab Connect GitLab to track [human tasks](/docs/team-workflows) as issues. Each issue goes to the person responsible for the request and includes the vulnerability context and instructions. ## Access required Connect a GitLab account with access to the project where issues should appear. A project Maintainer should complete setup so the integration can create and update issues, assign members, and receive project updates. Authorization uses [GitLab OAuth](https://docs.gitlab.com/integration/oauth_provider/). Review the requested access when connecting. GitLab’s API scope can grant access beyond issues; the integration uses it to manage human tasks in your selected project. ## Connect GitLab 1. Open **Settings → Integrations → GitLab**. 2. Select **Connect**, sign in to GitLab, and authorize Antigen. 3. Choose the project where human tasks should appear. 4. Confirm that issues are enabled and the people receiving tasks have access to the project. ## Complete a request Use comments to discuss the request or provide information the agent needs. After completing the requested action, add any relevant details and close the issue. For example, if the task asks you to update a firewall rule, review the proposed change and apply it. Describe the change in the issue, then close it so the agent can continue. When another connected integration detects completion, the task and its issue update automatically. See [Issue tracking](/docs/team-workflows/issue-tracking) for how these updates relate to the vulnerability. ## Troubleshooting ### The project is unavailable Check that the connected account has access to the project and that the project’s Issues feature is enabled. ### An issue cannot be assigned Check that the intended recipient can be assigned issues in the selected project. If the connected account lost access, reconnect using an account with the required permissions. # Overview Source: https://docs.antigen.sh/docs/integrations/index Connect the tools your team uses to host applications, manage identities, maintain code, and track work. These integrations give agents context about your environment and let them work with your team through its existing tools. ## Asset Map Connect infrastructure providers to populate your [Asset Map](/docs/asset-map). Each integration adds assets and relationships that help your team and agents understand the environment. | Integration | What it maps | | - | - | | [AWS](/docs/integrations/aws) | Compute, storage, networking, and IAM configuration. | | [Vercel](/docs/integrations/vercel) | Projects, deployments, and domains. | | [Supabase](/docs/integrations/supabase) | Organizations, projects, and access. | | [Railway](/docs/integrations/railway) | Projects, services, and deployments. | | [Tailscale](/docs/integrations/tailscale) | Your tailnet. | | [Okta](/docs/integrations/okta) | Applications, identities, and assignments. | | [Clerk](/docs/integrations/clerk) | Users and organizations. | | [GitHub](/docs/integrations/github) | Repositories, teams, and access. | | [n8n](/docs/integrations/n8n) | Workflows, users, and access. | | [Astro](/docs/integrations/astro) | Workspaces, deployments, and access. | | [OpenAI](/docs/integrations/openai) | Organization members, projects, and keys. | | [Anthropic](/docs/integrations/anthropic) | Organization members, workspaces, and keys. | See [Connecting infrastructure](/docs/asset-map/connecting-infrastructure) for how these connections build and maintain the map. ## Code and remediation Connect [GitHub](/docs/integrations/github) so agents can inspect your code and open pull requests with proposed fixes. Your team selects which repositories agents can access and reviews changes through its existing workflow. See [Connecting your codebase](/docs/vulnerability-lifecycle/connecting-your-code) for how agents use repository access. ## Team workflows Connect messaging and issue tracking tools so people can receive and respond to [human tasks](/docs/team-workflows). Each task is assigned to a person in the connected tool. | Integration | How human tasks appear | | - | - | | [Slack](/docs/integrations/slack) | Direct messages | | [Microsoft Teams](/docs/integrations/microsoft-teams) | Direct messages | | [Linear](/docs/integrations/linear) | Issues | | [GitHub](/docs/integrations/github) | Issues | | [Jira](/docs/integrations/jira) | Issues | | [Azure Boards](/docs/integrations/azure-boards) | Work items | | [GitLab](/docs/integrations/gitlab) | Issues | | [ServiceNow](/docs/integrations/servicenow) | Tasks or change requests | You can connect both messaging and issue tracking to discuss and track the same task. ## External agents Use [Cursor Cloud](/docs/integrations/cursor-cloud) or [Devin](/docs/integrations/devin) in your vulnerability workflows. Your service receives a webhook and launches the agent, which can use the Antigen API to retrieve context and update the vulnerability. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for how this works. ## Connect an integration Open **Settings → Integrations**, select a provider, and follow its setup guide. Each guide explains the access required and how to choose which resources to connect. # Jira Source: https://docs.antigen.sh/docs/integrations/jira Connect Jira Cloud to track [human tasks](/docs/team-workflows) as issues in your team’s project. Each issue is assigned to a person and contains the agent’s request, relevant vulnerability, and instructions. ## Access required Authorize access to the Jira site and project where tasks should appear. The integration needs to read project members, create and update issues, assign people, and exchange comments. The authorizing account must have the corresponding project permissions. Jira’s [OAuth permissions](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/) do not override restrictions on the account or project. ## Connect Jira 1. Open **Settings → Integrations → Jira**. 2. Select **Connect** and sign in to Atlassian. 3. Select your Jira Cloud site and approve the requested access. 4. Choose the project and issue type for human tasks. 5. Configure any fields required by that project’s issue workflow. The people receiving tasks must be assignable in the selected project. ## Complete a request Carry out the requested action, add the relevant details in a comment, and move the issue to the completed state used by your project. The agent uses that update to continue. For example, a task may ask your team to change a cloud configuration. Review the recommendation, make the change, and describe it in the issue before marking the work done. If a connected integration can detect the requested action, the task and issue update automatically. See [Issue tracking](/docs/team-workflows/issue-tracking) for automatic completion and how tasks relate to vulnerability statuses. ## Troubleshooting ### An issue cannot be created Check the selected project, issue type, required fields, and the authorizing account’s permission to create issues. ### An issue cannot be assigned or completed Check that the recipient is an eligible assignee. For completion, confirm that the integration has permission to perform the required workflow transition and can supply any fields that transition requires. # Linear Source: https://docs.antigen.sh/docs/integrations/linear Connect Linear to create and track [human tasks](/docs/team-workflows) as issues. Each issue is assigned to the person responsible for the request and includes the vulnerability context and instructions. ## Access required Authorize Antigen in the Linear workspace where your team tracks work. The integration needs access to read teams and members, create and update issues, and read and write comments. Antigen connects as an application through [Linear OAuth](https://linear.app/developers/oauth-2-0-authentication). You do not need to create a personal API key. ## Connect Linear 1. Open **Settings → Integrations → Linear**. 2. Select **Connect** and choose your Linear workspace. 3. Review and approve the requested access. 4. Select the Linear team where human tasks should appear. People receiving tasks need access to that team. If the team is private, make sure the integration also has access to it. ## Work on a request The assigned issue describes what the agent needs and why. Use comments to provide details, ask questions, or explain what is blocking the work. After completing the requested action, move the issue to a completed status in your team’s workflow. For example, grant the requested repository access, comment with the change, and mark the issue done. The agent can then retry its work. If another integration detects that the requested action is complete, the task and its Linear issue update automatically. A GitHub pull request merge can complete a request to merge that pull request. See [Issue tracking](/docs/team-workflows/issue-tracking) for how task updates affect the vulnerability workflow. ## Troubleshooting ### A team or assignee is unavailable Check that you connected the correct workspace and that both the integration and intended assignee have access to the selected team. ### Issues stop updating Check whether the Antigen integration was removed or its access changed in Linear. Reconnect it in Antigen if authorization was revoked. # Microsoft Teams Source: https://docs.antigen.sh/docs/integrations/microsoft-teams Connect Microsoft Teams so agents can send [human tasks](/docs/team-workflows) to the assigned person in a private chat. Each message includes what the agent needs, the relevant vulnerability, and instructions for responding. ## Access required Your organization must allow the Antigen app in Teams. The app needs to be installed for people who receive tasks so it can start a conversation with them. Your Teams administrator can make the app available and deploy it to those users. This follows Microsoft’s [requirements for proactive messages](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages). ## Connect Microsoft Teams 1. Open **Settings → Integrations → Microsoft Teams**. 2. Select **Connect** and sign in with your Microsoft work account. 3. Choose the organization and approve the requested access. If administrator approval is required, have your administrator complete it. 4. Install the Antigen app in Teams for the people who will receive tasks. The connected Microsoft organization should contain the accounts your team uses in Teams. ## Respond to a task Open the task’s conversation with Antigen and reply to provide information or confirm that the requested work is done. You can also ask questions or explain why you cannot proceed. For example, after making a requested infrastructure change, describe what you changed in the conversation. The agent uses your response to continue its work. A task can also complete when a connected integration detects the requested action, such as a GitHub pull request being merged. See [Messaging](/docs/team-workflows/messaging) for how this works. ## Use Teams with an issue tracker If you also connect an [issue tracker](/docs/team-workflows/issue-tracking), the person receives a private message and an assigned issue for the same task. Updates through either tool stay associated with that task. ## Troubleshooting ### A person does not receive a task Check that the Antigen app is installed for that person and allowed by your organization’s Teams app policies. Confirm that their account belongs to the connected Microsoft organization. ### Installation requires approval Ask your Teams administrator to approve the app and its requested access, then complete the connection in Antigen. # n8n Source: https://docs.antigen.sh/docs/integrations/n8n Connect an n8n instance to add its workflows and users to your [Asset Map](/docs/asset-map). You can connect n8n Cloud or a self-hosted instance. ## What it maps | Resource | Configuration | | - | - | | Instance | The n8n instance URL. | | Workflows | Workflow names and whether they are active. | | Users | Names, email addresses, roles, and pending invitations. | The map groups workflows and users under their instance. ## Access required Use an n8n API key with access to list workflows and users. On plans that support API key scopes, select `workflow:list` and `user:list`. Antigen uses the key for read operations. On plans without scoped API keys, the key inherits broader access from its owner. Your n8n plan must include access to the public API and the resources you want to map. See [n8n API authentication](https://github.com/n8n-io/n8n-docs/blob/main/docs/connect/n8n-api/authentication.md). ## Connect n8n ### 1. Create an API key In n8n, open **Settings → n8n API** and select **Create an API key**. Name it `Antigen`, choose an expiration, and select the read scopes above if available. Copy the key. ### 2. Enter your instance URL Open **Settings → Integrations → n8n** in Antigen. Enter your instance’s base URL, such as `https://example.app.n8n.cloud`, and paste the API key. Use the base URL without `/api/v1`. For a self-hosted instance, the API must be reachable from Antigen. ### 3. Complete the connection Select **Connect**. Antigen reads the workflows and users available to the key and adds them to your Asset Map. ## Troubleshooting ### The instance cannot be reached Check the URL, HTTPS certificate, and any network restrictions in front of the instance. Confirm that the n8n public API is enabled. ### Workflows or users are missing Check the API key’s scopes and its owner’s permissions. Access to user information also depends on the capabilities available on your n8n plan. # Okta Source: https://docs.antigen.sh/docs/integrations/okta Connect Okta to add users, groups, applications, and their access relationships to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Users and groups | User accounts, group membership, and account status. | | Applications | Applications and their user and group assignments. | | Authentication factors | Factors enrolled by users. | | Administrative access | Admin role assignments available to the token. | | Trusted origins | Origins configured in Okta. | | AWS federation | AWS role mappings exposed by configured SAML applications. | These relationships help agents understand how an identity receives access to an application or AWS role. ## Access required Use an Okta API token created by an administrator with read access to the resources above. A dedicated service account keeps the connection independent of an individual employee’s account. Okta API tokens inherit their creator’s permissions. Antigen uses the token for read operations. See [Okta API token permissions](https://developer.okta.com/docs/guides/create-an-api-token/main/#privilege-level). ## Connect Okta ### 1. Create an API token Sign in to the Okta Admin Console with the account that will own the integration. Open **Security → API → Tokens** and create a token named `Antigen`. Copy the token value before closing the dialog. If you restrict the token to specific network zones, ensure those zones allow requests from Antigen. ### 2. Complete the connection Open **Settings → Integrations → Okta** in Antigen. Enter your Okta organization URL, such as `https://example.okta.com`, and paste the API token. Select **Connect**. Antigen discovers the resources available to the token and adds them to your Asset Map. ## Troubleshooting ### The connection stops syncing Check that the token’s owner is still active and has the required permissions. Okta also expires tokens after 30 days without use. See [Token expiration and deactivation](https://developer.okta.com/docs/guides/create-an-api-token/main/#token-expiration-and-deactivation). ### Applications or admin roles are missing Check whether the token’s owner can view those resources in Okta. The token’s access changes when the owner’s administrative permissions change. # OpenAI Source: https://docs.antigen.sh/docs/integrations/openai Connect your OpenAI API organization to add its projects, members, and API key metadata to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Organization members | Users and their organization roles. | | Projects | Projects within the organization. | | Service accounts | Service accounts associated with each project. | | API keys | Key metadata and relationships to projects and owners. | | Admin API keys | Organization-level key metadata and ownership. | The map helps your team understand which identities and credentials have access to your OpenAI organization. ## Access required Use an **Admin API key** created by an organization owner. A project API key does not provide the organization-level access needed for this integration. Admin API keys permit administrative operations. Antigen uses the key to read resource and access metadata without changing your organization. See [OpenAI Admin API keys](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/admin_api_keys). ## Connect OpenAI ### 1. Create an Admin API key Sign in to the OpenAI API platform as an organization owner and open [Admin keys](https://platform.openai.com/settings/organization/admin-keys). Create a key named `Antigen` and copy its value. ### 2. Copy your organization ID Open [Organization settings](https://platform.openai.com/settings/organization/general) and copy the organization ID. Use the organization where you created the key. ### 3. Complete the connection Open **Settings → Integrations → OpenAI** in Antigen. Enter the Admin API key and organization ID, then select **Connect**. Antigen reads the organization’s resources and adds them to your Asset Map. ## Troubleshooting ### The key is rejected Confirm that you entered an Admin API key and that it has not been revoked. Check that the organization ID matches the key’s organization. ### Projects are missing Check that you connected the intended OpenAI organization. Create a separate connection for each organization you want to map. # Railway Source: https://docs.antigen.sh/docs/integrations/railway Connect Railway to add your workspaces, projects, services, and deployments to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Workspaces and projects | Workspace ownership, project names, and project visibility. | | Services | Services and the projects they belong to. | | Environments | Environments within each project. | | Deployments | Deployment status, URLs, services, and environments. | | Volumes | Persistent volumes and their projects. | The map connects a deployment to its service and environment so agents can identify which part of your application it belongs to. ## Access required Use a Railway **workspace API token** to connect one workspace. An account token can cover multiple workspaces available to its owner. See [Railway API token types](https://docs.railway.com/integrations/api#choosing-a-token-type). Antigen uses the token to read resource metadata. Railway tokens may also permit changes within their scope. ## Connect Railway ### 1. Create a token Open the **Tokens** page in your Railway account settings. Create a token named `Antigen` and select the workspace you want to map. To connect all workspaces available to your account, select **No workspace** instead. Copy the token. Use a workspace or account token for this integration; a project token covers only one project environment. ### 2. Complete the connection Open **Settings → Integrations → Railway** in Antigen. Paste the token and select **Connect**. The workspace’s resources appear in your Asset Map as discovery progresses. For separate workspace tokens, create a connection for each workspace. ## Troubleshooting ### A workspace is missing Check the token’s scope. A workspace token can access only the workspace selected when you created it. An account token depends on its owner’s workspace membership. ### The token is rejected Confirm that you supplied an account or workspace API token and that it has not been revoked. # ServiceNow Source: https://docs.antigen.sh/docs/integrations/servicenow Connect ServiceNow to track [human tasks](/docs/team-workflows) as tasks or change requests. Each request is assigned to a person and includes the vulnerability, the agent’s recommendation, and the action your team needs to take. ## Access required Have a ServiceNow administrator configure an OAuth client for Antigen using the **client credentials** grant. The client needs access to create and update your chosen task or change request records, read assignees, and exchange comments. Limit access to the tables and operations required by that workflow. Your instance’s roles and access controls still apply. See [ServiceNow client credentials](https://www.servicenow.com/docs/r/platform-security/authentication/client-credentials.html) for the instance requirements. ## Connect ServiceNow ### 1. Configure the OAuth client Have your administrator create an inbound OAuth client for Antigen, enable the client credentials grant, and associate it with an integration user that has the required permissions. Copy the client ID and client secret. See [Configure an OAuth application user](https://www.servicenow.com/docs/r/platform-security/authentication/add-oauth-application-user.html) for assigning the user to the client. ### 2. Enter your instance details Open **Settings → Integrations → ServiceNow** in Antigen. Enter your instance URL, such as `https://example.service-now.com`, and the OAuth client ID and secret. ### 3. Choose how tasks appear Select the task or change request type your team uses, then configure its required fields and assignment group where applicable. Each human task is assigned to the responsible person’s ServiceNow account. Complete the connection after choosing the workflow. ## Review and complete a request Handle approvals through your existing ServiceNow process. If an agent proposes a production configuration change, your team reviews the recommendation, obtains any required approval, and makes the change. Add the outcome to the request and move it to the completed state in your workflow. Approval alone does not mean the requested change has been made. The agent uses the update to continue its work. See [Issue tracking](/docs/team-workflows/issue-tracking) for how completing a task affects the vulnerability workflow. ## Troubleshooting ### Authorization fails Have your administrator check that the client credentials grant is enabled, the client secret is current, and the OAuth application user is configured and active. ### A task cannot be created or updated Check the integration user’s access to the selected record type, required fields, and workflow transitions. The intended assignee must have an active account that can receive the request. # Slack Source: https://docs.antigen.sh/docs/integrations/slack Connect Slack so agents can send [human tasks](/docs/team-workflows) directly to the people responsible for them. Each task arrives as a direct message with the request, relevant vulnerability, and instructions. ## Access required Install the Antigen app in your Slack workspace. It needs access to identify workspace members, send direct messages, and receive replies to its conversations. If your workspace restricts app installations, a workspace administrator must approve the app. Slack shows the requested permissions during [installation](https://docs.slack.dev/authentication/installing-with-oauth/). ## Connect Slack 1. Open **Settings → Integrations → Slack**. 2. Select **Connect** and choose the Slack workspace your team uses. 3. Review the requested permissions and authorize the Antigen app. 4. Return to Antigen to complete the connection. People assigned human tasks need an account in the connected workspace so the app can message them. ## Respond to a task Reply in the task’s conversation to provide information, ask a question, or confirm that you completed the requested action. For example, an agent might ask you to grant access to a repository. Update the GitHub integration, then reply to the message. The agent retries its work with the new access and follows up if it still needs help. Some actions can be detected through another connected integration. A task asking you to merge a GitHub pull request completes when the merge is detected, without a separate reply. See [Messaging](/docs/team-workflows/messaging) for how conversations and task completion work. ## Use Slack with an issue tracker Connect an [issue tracker](/docs/team-workflows/issue-tracking) to give the assigned person both a direct message and an issue for the same task. They can discuss the request in Slack while tracking the work in the issue. ## Troubleshooting ### A person does not receive a message Check that they have an active account in the connected workspace and that the Antigen app is still installed and approved. Confirm that the human task is assigned to the intended person. ### Replies do not reach the agent Reply in the conversation containing the task. If the app’s permissions were revoked or changed, reconnect Slack and approve the requested access. # Supabase Source: https://docs.antigen.sh/docs/integrations/supabase Connect Supabase to add your organizations, projects, databases, and organization members to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Organizations | Organization names and their projects. | | Projects | Project names, regions, and status. | | Databases | Database hosts and versions associated with each project. | | Members | Organization membership, roles, and MFA status. | This gives agents context about where a project runs and who has access to manage it. ## Access required Use a Supabase **personal access token** for the Management API. The integration reads organization, project, and member metadata. If your account offers scoped tokens, grant **Read** access to **Organizations**, **Projects (account-wide)**, and **Organization Members**, covering the organizations you want to map. A token’s permissions are also limited by the account that creates it. See [Supabase personal access tokens](https://supabase.com/docs/guides/platform/personal-access-tokens). Classic personal access tokens inherit your account’s access. Antigen uses them for read operations, but the token may also permit changes in Supabase. ## Connect Supabase ### 1. Create a personal access token Open [Supabase access tokens](https://supabase.com/dashboard/account/tokens). Generate a token named `Antigen` and copy its value. Use a personal access token beginning with `sbp_`. Project publishable keys, secret keys, and legacy `anon` or `service_role` keys authenticate to a project’s APIs and cannot replace this management token. ### 2. Complete the connection Open **Settings → Integrations → Supabase** in Antigen. Paste the token and select **Connect**. Antigen discovers the organizations and projects available to the token and adds them to your Asset Map. ## Troubleshooting ### An organization or project is missing Check that the account that created the token has access to it. For a scoped token, also check the selected organizations, projects, and read permissions. ### The connection stops syncing Confirm that the token is still valid and that its owner still has the required access. If you revoke the token, reconnect with a replacement. # Tailscale Source: https://docs.antigen.sh/docs/integrations/tailscale Connect Tailscale to add your tailnet’s devices, users, groups, and access relationships to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Devices | Hostnames, addresses, operating systems, tags, and device posture. | | Users and groups | Tailnet users, group membership, and device ownership. | | Access policy | Groups, grants, and the access relationships they describe. | | Services | Services exposed through Tailscale Services. | Agents can use these relationships to understand which identities can reach a service and which devices belong to them. ## Access required Create a Tailscale OAuth credential with **read-only** access. The `all:read` scope covers the devices, users, policy, services, and posture information used by the integration. You’ll need a tailnet role that can create OAuth credentials with those scopes. See [Tailscale OAuth clients](https://tailscale.com/docs/features/oauth-clients). ## Connect your tailnet ### 1. Create an OAuth credential In the Tailscale admin console, open **Trust credentials**, select **Credential**, then **OAuth**. Select read access to all resources, corresponding to `all:read`, and generate the credential. Copy the client ID and client secret. Tailscale displays the secret only when it is created. ### 2. Complete the connection Open **Settings → Integrations → Tailscale** in Antigen and enter: | Field | Value | | - | - | | Tailnet organization | The tailnet name shown in Tailscale, such as `example.com`. | | OAuth client ID | The ID of the credential you created. | | OAuth client secret | Its secret. | Select **Connect**. Your tailnet’s resources and access relationships appear in the Asset Map as discovery progresses. ## Troubleshooting ### Access is denied Check that the credential belongs to the tailnet you entered and includes the required read scopes. The client ID and secret are case-sensitive. ### A device or group is missing Confirm that it belongs to the connected tailnet. Groups and access relationships come from the tailnet’s policy configuration. # Vercel Source: https://docs.antigen.sh/docs/integrations/vercel Connect a Vercel team to add its projects, deployments, domains, and configuration to your [Asset Map](/docs/asset-map). ## What it maps | Resource | Configuration and relationships | | - | - | | Projects and deployments | Projects, deployment URLs, and deployment status. | | Domains | Team domains, project domains, aliases, and DNS records. | | Team access | Members and access groups. | | Environment configuration | Environment variable names, deployment environments, and Edge Config resources. | | Network security | Firewall configuration, bypass rules, and Secure Compute networks. | | Connected services | Installed integrations, webhooks, and log drains. | The available resources depend on your Vercel plan and the token’s permissions. ## Access required Create a Vercel access token scoped to the team you want to connect. Select **All Projects** within that team so the integration can discover its projects and shared resources. See [Vercel access tokens](https://vercel.com/docs/accounts/access-tokens) for scope details. Antigen uses the token to read configuration and populate the map. Vercel’s team-scoped tokens can also permit writes, so the token itself is not restricted to read-only access. ## Connect your team ### 1. Create an access token Open [Vercel’s Account Tokens page](https://vercel.com/account/tokens). 1. Name the token `Antigen`. 2. Under **Scope**, select your team and **All Projects**. 3. Choose an expiration and create the token. 4. Copy the token. Vercel shows its value only once. ### 2. Copy your team ID In Vercel, open your team’s **Settings → General** and copy the **Team ID**. See [Find your team ID](https://vercel.com/docs/accounts#find-your-team-id) for Vercel’s instructions. ### 3. Complete the connection Open **Settings → Integrations → Vercel** in Antigen. Enter the access token and team ID, then select **Connect**. Antigen checks access and starts discovering resources. They appear in your Asset Map as the sync progresses. Create a separate connection for each Vercel team you want to map. ## Troubleshooting ### The token is rejected Check that the token has not expired or been revoked, and that its scope includes the team you’re connecting. ### Projects or configuration are missing Confirm that the team ID matches the token’s scope and that you selected **All Projects** when creating the token. Some resources, such as access groups, also depend on your Vercel plan. # Get an agent Source: https://docs.antigen.sh/docs/reference/endpoints/agents/get-an-agent /reference/openapi.yaml get /agents/{name} Returns the saved configuration. Pre-built names are tcell, triage-agent, and remediation-agent; the SDK exports constants for these names. A custom agent retains its underlying base reference and exposed settings. # List agents Source: https://docs.antigen.sh/docs/reference/endpoints/agents/list-agents /reference/openapi.yaml get /agents Returns pre-built agents and agents registered in your organization. Each item includes its exposed configuration. Private instructions are not returned. # Register an agent Source: https://docs.antigen.sh/docs/reference/endpoints/agents/register-an-agent /reference/openapi.yaml post /agents Saves a configuration under a unique name. Registered agents can be retrieved and assigned vulnerabilities. A name that already exists returns 409. Registration does not start a run. Fields supplied alongside base replace its exposed values. To append skills or tools, retrieve the agent and send the combined array. See [Agents](/sdk/agents). # Update an agent Source: https://docs.antigen.sh/docs/reference/endpoints/agents/update-an-agent /reference/openapi.yaml patch /agents/{name} Updates only the supplied fields. Arrays and strings replace their saved values; an empty array clears that field. Pre-built agents cannot be edited. Retrieve and register a customized configuration instead. Existing runs keep the configuration they started with. Updating an agent affects future runs that use the updated configuration. # Create an API key Source: https://docs.antigen.sh/docs/reference/endpoints/api-keys/create-an-api-key /reference/openapi.yaml post /api-keys Creates a key for your organization. Requires permission to manage API keys. The new key cannot grant more access than the credential creating it. Store the returned key now; subsequent requests return only metadata. Create your first key in the platform. # List API keys Source: https://docs.antigen.sh/docs/reference/endpoints/api-keys/list-api-keys /reference/openapi.yaml get /api-keys Returns key metadata for your organization. Full credentials are only returned at creation. Requires permission to manage API keys. # Revoke an API key Source: https://docs.antigen.sh/docs/reference/endpoints/api-keys/revoke-an-api-key /reference/openapi.yaml delete /api-keys/{id} Revokes the key so it can no longer authenticate requests. Requires permission to manage API keys. # Get a graph Source: https://docs.antigen.sh/docs/reference/endpoints/asset-map/get-a-graph /reference/openapi.yaml get /asset-map Returns the selected nodes and their neighbors within your organization. Connections are followed in both directions up to depth, while each edge keeps its original direction. Nodes and edges are deduplicated; every returned edge references nodes in the result. Use repeated nodeIds parameters for multiple starting nodes. depth=0 returns the selected nodes and edges between them. Missing or inaccessible starting nodes return 404. See [Asset Map](/sdk/asset-map) for graph fields and querying. # Query the graph Source: https://docs.antigen.sh/docs/reference/endpoints/asset-map/query-the-graph /reference/openapi.yaml post /asset-map/query Executes read-only Cypher within your organization’s Asset Map and returns an array of rows. Each row uses the aliases selected by RETURN. No matches returns []. Graph nodes, edges, and paths use the same representation as GET /asset-map. The HTTP request carries query text and parameters. The SDK accepts a @neo4j/cypher-builder query object and serializes the built query into this body. Parameter values cannot change the query’s organization scope. Writes, administrative operations, and operations that access external resources are rejected. # Download evidence Source: https://docs.antigen.sh/docs/reference/endpoints/evidence/download-evidence /reference/openapi.yaml get /evidence/{id}/content Returns the original file bytes. Content-Type identifies the file’s media type; Content-Disposition supplies its filename. The SDK’s evidence.download() method returns these bytes as a Uint8Array. # Get evidence Source: https://docs.antigen.sh/docs/reference/endpoints/evidence/get-evidence /reference/openapi.yaml get /evidence/{id} Returns file metadata and the vulnerability it supports. # List evidence Source: https://docs.antigen.sh/docs/reference/endpoints/evidence/list-evidence /reference/openapi.yaml get /evidence Returns evidence metadata. Use vulnerabilityId for supporting files across runs or runId for files produced by one run. Filters apply together; omit them to list evidence across your organization. The SDK’s run.evidence.list() method supplies runId. A referenced run or vulnerability outside your organization returns 404. # Get a hook Source: https://docs.antigen.sh/docs/reference/endpoints/hooks/get-a-hook /reference/openapi.yaml get /hooks/{id} Returns configuration without its signing secret. Built-in hooks have builtIn set to true and url set to null. # List hooks Source: https://docs.antigen.sh/docs/reference/endpoints/hooks/list-hooks /reference/openapi.yaml get /hooks Returns built-in hooks and your custom webhooks. Use enabled to determine which are active. Built-in hooks handle triage, remediation, and verification; their IDs are triage, remediation, and verification. Their internal destinations are not exposed. # Register a webhook Source: https://docs.antigen.sh/docs/reference/endpoints/hooks/register-a-webhook /reference/openapi.yaml post /hooks Registers a public HTTPS endpoint for one event type. Your service receives previous and current values and decides how to respond. Creating a webhook does not disable a default hook. The response includes a signing secret once. Store it in your service and verify deliveries as described in [Webhook events](/reference/webhooks). Destinations on private, loopback, link-local, or metadata-service addresses are rejected, including after DNS resolution. Redirects are not followed. # Remove a webhook Source: https://docs.antigen.sh/docs/reference/endpoints/hooks/remove-a-webhook /reference/openapi.yaml delete /hooks/{id} Removes a custom webhook and stops future delivery attempts. Built-in hooks cannot be removed; disable them instead. Already delivered events may still be processing in your service. # Update a hook Source: https://docs.antigen.sh/docs/reference/endpoints/hooks/update-a-hook /reference/openapi.yaml patch /hooks/{id} Changes a custom webhook’s destination or enabled state. Built-in hooks support only enabled. Disable the corresponding built-in hook when replacing triage, remediation, or verification with your own workflow. To replace a signing secret, register a new webhook and remove the old one. # Create a human task Source: https://docs.antigen.sh/docs/reference/endpoints/human-tasks/create-a-human-task /reference/openapi.yaml post /human-tasks Creates an open request assigned to a person. Connected messaging tools deliver a direct message; connected issue trackers create an assigned issue. Both refer to the same task when both are configured. An optional completion condition lets the GitHub integration confirm a pull request merge. Otherwise the assigned person confirms the work through a connected tool. See [Human tasks](/sdk/human-tasks). # Get a human task Source: https://docs.antigen.sh/docs/reference/endpoints/human-tasks/get-a-human-task /reference/openapi.yaml get /human-tasks/{id} Returns the request, assignee, status, completion condition, and response. Completion confirms the requested action; it does not by itself mark the vulnerability verified. # List human tasks Source: https://docs.antigen.sh/docs/reference/endpoints/human-tasks/list-human-tasks /reference/openapi.yaml get /human-tasks Returns requests assigned to people in your organization. Filters apply together. Read status and response to decide when your service should continue its work. A referenced run or vulnerability outside your organization returns 404. # Update a human task Source: https://docs.antigen.sh/docs/reference/endpoints/human-tasks/update-a-human-task /reference/openapi.yaml patch /human-tasks/{id} Updates supplied fields and reflects the change in connected tools. Reassign a task by email, revise its instructions, or update status. Supply response when confirming work through your service. Set cancelled when the request is no longer needed. External agents use the task’s status and response to decide when to continue. A completed access request tells the agent to retry the operation that required access. # Disconnect an integration Source: https://docs.antigen.sh/docs/reference/endpoints/integrations/disconnect-an-integration /reference/openapi.yaml delete /integrations/{id} Disconnects the provider and stops new syncs or task delivery through this connection. It does not delete vulnerabilities, reports, human tasks, or issues already created in the external tool. # Get an integration Source: https://docs.antigen.sh/docs/reference/endpoints/integrations/get-an-integration /reference/openapi.yaml get /integrations/{id} Returns the connected account or workspace, sync status, and any connection error. Cursor Cloud and Devin workflows are managed by your own service through webhooks; they are not provider connections in this collection. # List integrations Source: https://docs.antigen.sh/docs/reference/endpoints/integrations/list-integrations /reference/openapi.yaml get /integrations Returns connected providers in your organization and their current status. Credentials are never included. Connect and configure providers through Settings → Integrations; each [integration guide](/integrations) explains the required access. # List models Source: https://docs.antigen.sh/docs/reference/endpoints/models/list-models /reference/openapi.yaml get /models Returns the models available to your organization. Use an ID in an agent configuration. Cyber-capable models are accessed by agents running in sandboxes against approved targets or vulnerabilities. See [Models](/sdk/models). # Download a report Source: https://docs.antigen.sh/docs/reference/endpoints/reports/download-a-report /reference/openapi.yaml get /reports/{id}/content Returns the report as a PDF. # Get a report Source: https://docs.antigen.sh/docs/reference/endpoints/reports/get-a-report /reference/openapi.yaml get /reports/{id} Returns the report’s summary, scope, methodology, and captured vulnerability and evidence metadata. Reports can cover more than one run. See [Reports](/runs/reports) for creating and reviewing reports in the platform. # List reports Source: https://docs.antigen.sh/docs/reference/endpoints/reports/list-reports /reference/openapi.yaml get /reports Returns reports written for your organization. A report captures an engagement at the time it was written. Its vulnerability and evidence metadata remain unchanged as the live vulnerabilities progress. A referenced run or vulnerability outside your organization returns 404. # Get a run Source: https://docs.antigen.sh/docs/reference/endpoints/runs/get-a-run /reference/openapi.yaml get /runs/{id} Returns current status, the captured agent configuration, task, and failure details when present. Use this endpoint to check whether background work has completed. # List runs Source: https://docs.antigen.sh/docs/reference/endpoints/runs/list-runs /reference/openapi.yaml get /runs Returns runs in your organization. Filters apply together. Each result contains the agent configuration captured at launch and the task being performed. # Resume a run Source: https://docs.antigen.sh/docs/reference/endpoints/runs/resume-a-run /reference/openapi.yaml post /runs/{id}/resume Restores a stopped run into a new sandbox and continues with the same ID, agent configuration, files, and conversation context. Target authorization is checked again before testing continues. Returns once the run is running. This endpoint accepts no configuration overrides. To supply new context, steer the resumed run. To use a different agent configuration, start a new run. A run that is not stopped returns 409. # Start a run Source: https://docs.antigen.sh/docs/reference/endpoints/runs/start-a-run /reference/openapi.yaml post /runs Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection. Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution. The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later. # Steer a run Source: https://docs.antigen.sh/docs/reference/endpoints/runs/steer-a-run /reference/openapi.yaml post /runs/{id}/steer Adds a message to the run’s conversation. Use it to provide context, pursue a lead, or ask a question about the results. Steering a completed run continues the same run with its saved context. Resume a stopped run before steering it. Failed runs return 409. The message is accepted before the agent responds. Read the response through the event stream. Steering preserves the saved agent configuration and approved scope. # Stop a run Source: https://docs.antigen.sh/docs/reference/endpoints/runs/stop-a-run /reference/openapi.yaml post /runs/{id}/stop Snapshots the sandbox and shuts it down. Returns when the snapshot is saved and the run is stopped. Saved vulnerabilities and evidence remain available. Stopping an already stopped run returns that run; completed or failed runs return 409. # Stream run events Source: https://docs.antigen.sh/docs/reference/endpoints/runs/stream-run-events /reference/openapi.yaml get /runs/{id}/events Returns server-sent events. Each data field contains a RunEvent object; event matches its type, and id identifies the event. Progress and tool events include a summary. Vulnerability events identify the vulnerability; status events identify the run’s state. The connection replays retained events and then streams new ones. It closes after the run reaches stopped, completed, or failed. To reconnect, send the last received event ID in Last-Event-ID. Only later events are replayed. Reopen the stream after resuming or steering a completed run. An unknown event ID returns 400. Every JSON payload has id, runId, type, summary, and createdAt. Additional fields depend on type: | Type | Additional fields | | --- | --- | | progress | None | | tool | None | | vulnerability | vulnerabilityId | | status | status: creating, running, stopped, completed, or failed | | error | code | The SDK exposes this stream through the Run object’s async iterator. # Get a target Source: https://docs.antigen.sh/docs/reference/endpoints/targets/get-a-target /reference/openapi.yaml get /targets/{id} Returns the target’s value, current approval status, and review note. # List targets Source: https://docs.antigen.sh/docs/reference/endpoints/targets/list-targets /reference/openapi.yaml get /targets Returns your organization’s targets. Filter by status to select targets awaiting review or approved for testing. An empty result is []. # Submit a target Source: https://docs.antigen.sh/docs/reference/endpoints/targets/submit-a-target /reference/openapi.yaml post /targets Submits one domain, wildcard domain, or IP address for review. attested must be true to confirm your organization is authorized to test it. The Antigen team reviews every new target; a new submission has pending status. Duplicate values return 409. # Update a target Source: https://docs.antigen.sh/docs/reference/endpoints/targets/update-a-target /reference/openapi.yaml patch /targets/{id} Replaces the target value and confirms authorization for the new value. Changing a value resets status to pending and clears the previous review note. The new value must be approved before testing. Approval status cannot be set by this endpoint. # Get a vulnerability Source: https://docs.antigen.sh/docs/reference/endpoints/vulnerabilities/get-a-vulnerability /reference/openapi.yaml get /vulnerabilities/{id} Returns the vulnerability’s current description, severity, remediation steps, status, and assignment. Retrieve supporting file metadata with GET /evidence?vulnerabilityId={id}. # List vulnerabilities Source: https://docs.antigen.sh/docs/reference/endpoints/vulnerabilities/list-vulnerabilities /reference/openapi.yaml get /vulnerabilities Returns current vulnerabilities. Filters apply together. runId selects vulnerabilities discovered or worked on during that run, including subsequent verification; their current status and assignment are returned. The SDK’s run.vulnerabilities.list() method supplies this filter. A referenced run or vulnerability outside your organization returns 404. # Update a vulnerability Source: https://docs.antigen.sh/docs/reference/endpoints/vulnerabilities/update-a-vulnerability /reference/openapi.yaml patch /vulnerabilities/{id} Updates status, assignee, and riskAcceptance atomically. Technical findings and remediation content are maintained through authorized agent tools. Omitted fields retain their values. Assign a team member by email or an agent by its registered name; use null to unassign. Moving to in_progress requires an assignee, which can be included in the same request. Set remediated after the fix is deployed. With the default verification hook enabled, this starts verification. The verified status is set through verification and cannot be assigned directly here. Accepting risk requires riskAcceptance with a note and future expiresAt. Moving away from accepted_risk clears riskAcceptance. Changes to status or assignee emit their respective events after the update is saved. Sending an unchanged value emits no event. Work started by hooks runs separately. The SDK’s updateStatus() and updateAssignee() methods call this endpoint. # Overview Source: https://docs.antigen.sh/docs/reference/index Use the Antigen API from your own service, an external agent, or any language that can make HTTP requests. It works with the same resources as the platform and the [Antigen SDK](/docs/sdk). The base URL is `https://api.antigen.sh/v1`. ## Make a request Create an API key in the platform and send it in the `x-api-key` header: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl 'https://api.antigen.sh/v1/targets?status=approved' \ -H "x-api-key: $ANTIGEN_API_KEY" ``` The key determines your organization and permissions. Keep it in your backend or secret store. See [Authentication](/docs/sdk/authentication) for creating and replacing keys. ## Start a run Send an agent configuration and a task to `POST /runs`. This example uses tCell’s configuration and an approved target: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://api.antigen.sh/v1/runs \ -H "x-api-key: $ANTIGEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent": { "base": "tcell" }, "task": { "instructions": "Test the production API for authorization vulnerabilities.", "targets": ["api.example.com"] } }' ``` Replace the hostname with a target approved for your organization. The response contains the run’s ID and status. Work continues in the background; retrieve `GET /runs/{id}` to check progress or connect to `GET /runs/{id}/events` to stream activity. You can supply configuration fields alongside `base` to customize the agent, or supply a model and configuration without a pre-built base. To work on existing vulnerabilities, include `vulnerabilityIds` in the task. ## Resources | Resource | What you can do | | - | - | | Agents | Retrieve configurations, register your own, and update saved fields. | | Models | List models available to your organization. | | Targets | Submit testing scope and check its approval. | | Runs | Launch agents, stream events, steer, stop, and resume. | | Vulnerabilities | Read vulnerabilities and manage status, assignment, and risk acceptance. | | Evidence | List evidence, read its metadata, and download files. | | Reports | Read captured engagement results and download PDFs. | | Human tasks | Assign requests to people and follow their responses. | | Hooks | Register webhooks and enable or disable lifecycle automation. | | Asset Map | Retrieve nodes and edges or execute read-only Cypher queries. | | Integrations | Inspect connected providers and disconnect them. | | API keys | Create and revoke credentials. | Skills, guardrails, and tools are fields on an agent configuration. Steering, stopping, and resuming operate on a run. Status and assignment are fields on a vulnerability. Authorized agent runs create vulnerabilities and evidence through their tools. The public API lets your applications read those results and coordinate the work that follows. ## Requests and responses JSON fields use `camelCase`, including `vulnerabilityId` and `createdAt`. IDs are opaque strings. Timestamps use ISO 8601 in UTC. List endpoints return an array containing all matching resources. An empty result is `[]`. Filters apply together. There are no pagination parameters or result envelopes. `PATCH` changes only the fields you supply. Arrays replace their previous values. To append to an array, retrieve the resource, combine the values in your code, and send the resulting array. Fields accept `null` only where the reference allows it. Creation returns `201`. Reads and completed updates return `200`. Steering returns `202` when the message is accepted. Deletion returns `204` with no response body. Starting a run returns before the agent finishes its work. Status and assignment changes trigger the same hooks as changes made in the platform. See [Webhook events](/docs/reference/webhooks) for payloads and delivery verification. ## Errors Errors use the same JSON shape across endpoints: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "code": "not_found", "message": "The resource does not exist in this organization." } } ``` | Status | Meaning | | - | - | | `400` | A request field or parameter is invalid. | | `401` | The API key is missing, invalid, or revoked. | | `403` | The key lacks permission, or the requested work is outside approved scope. | | `404` | The resource does not exist in your organization. | | `409` | The request conflicts with an existing name or the resource’s current state. | | `429` | Too many requests. Wait for the number of seconds in `Retry-After`. | Each endpoint documents its request, response, and applicable errors. # Webhook events Source: https://docs.antigen.sh/docs/reference/webhooks Receive vulnerability status and assignment changes in your service. Register a hook with `POST /hooks` to receive events at your service’s HTTPS endpoint. Each hook subscribes to one event type. Your handler checks the change and decides what to do next. ## Event types | Type | When it is sent | Values | | - | - | - | | `vulnerability.status_changed` | A vulnerability is created or its status changes. | `previous` and `current` contain lifecycle statuses. `previous` is `null` on creation. | | `vulnerability.assignee_changed` | The assignee changes. | `previous` and `current` contain a team member’s email or an agent name. Either can be `null` for an unassigned vulnerability. | A request that changes both fields emits one event of each type. Setting a field to its existing value does not emit an event. ## Payload ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "event_123", "type": "vulnerability.assignee_changed", "vulnerabilityId": "vuln_123", "previous": null, "current": "our-remediation-agent", "createdAt": "2026-09-13T10:00:00Z" } ``` | Field | Meaning | | - | - | | `id` | Stable event ID. Retries keep the same ID. | | `type` | Event type. | | `vulnerabilityId` | Vulnerability whose status or assignment changed. | | `previous` | Value before the change. | | `current` | Value after the change. | | `createdAt` | Time the change was recorded, in UTC. | Use `GET /vulnerabilities/{id}` when your handler needs the current vulnerability, and `GET /evidence?vulnerabilityId={id}` for its supporting files. ## Verify a delivery Creating a webhook returns a signing `secret` once. Store it in your receiving service. Each delivery includes these headers: ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} Antigen-Timestamp: 1789293600 Antigen-Signature: sha256= Content-Type: application/json ``` The signature is an HMAC-SHA256 of the timestamp, a period, and the raw request body. Use the signing secret exactly as returned, encoded as UTF-8: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} HMAC-SHA256(secret, timestamp + "." + rawBody) ``` Verify the signature before parsing or acting on the event. Compare it using a constant-time comparison, and reject timestamps more than five minutes from your service’s current time. Each retry gets a fresh delivery timestamp and signature while retaining the original event ID and payload. Do not reserialize the JSON before verification. Whitespace or field-order changes alter the signed bytes. ## Acknowledge and process Return a `2xx` response within 10 seconds after durably accepting the event. Queue work that takes longer, such as launching an agent, and process it separately. Timeouts and non-`2xx` responses are retried for up to 24 hours. Delivery can occur more than once, so record the event ID and avoid repeating work for an event you have already accepted. Events may arrive out of order; retrieve the vulnerability’s current state before acting when your workflow depends on it. For example, a remediation handler can check that the current assignee still matches its agent before launching a run. ## Default hooks `GET /hooks` includes the built-in triage, remediation, and verification hooks. They have `builtIn: true` and no public webhook destination. | Hook ID | Trigger | | - | - | | `triage` | A vulnerability enters `open`. | | `remediation` | A vulnerability is assigned to `remediation-agent`. | | `verification` | A vulnerability enters `remediated`. | Use `PATCH /hooks/remediation` with `{"enabled": false}` to disable the default remediation hook when replacing that workflow. Custom webhooks work alongside defaults unless you disable them. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for choosing which workflow to replace. # Evidence Source: https://docs.antigen.sh/docs/runs/evidence Evidence shows what an agent tested and what happened. It supports a vulnerability with material your team can inspect to understand and reproduce the issue. An evidence item belongs to a vulnerability and can identify the run that produced it. A vulnerability may have several items that demonstrate different parts of the issue. ## What evidence can include * **Requests and responses** showing how a service handled an action. * **Screenshots** capturing application behavior or exposed information. * **Code and scripts** used to reproduce a weakness. * **Logs and other files** containing observations from testing. For example, evidence for an access-control vulnerability might include a request made as one user and a response containing another user’s data. Together, they show the action the agent took and the result that demonstrates the weakness. ## Review evidence Open a vulnerability in the platform to inspect its supporting evidence. Use it to understand the conditions that made the issue exploitable and the steps needed to reproduce it. The vulnerability’s description explains the issue; the evidence shows the observations behind that explanation. # Runs Source: https://docs.antigen.sh/docs/runs/index ## Start with an agent and targets To launch an offensive run against your system, you need an agent and approved targets. **Choose an agent.** You can use [tCell](/docs/runs/tcell), Antigen’s pre-built security agent, or assemble your own with the [Antigen SDK](/docs/sdk). Each run executes the agent you choose against the targets you provide. **Define the targets.** [Targets](/docs/runs/targets) are the domains or IP addresses the agent is allowed to test. Because you can start runs directly through the API, the Antigen team manually reviews and approves every new target to ensure responsible use of our cyber-capable models. You can view your targets and their approval status under **Settings → Targets** or query them through the API. **Start the run.** Your Antigen expert can plan the engagement and run tCell for your team. You can also start runs yourself through the SDK or API. In either case, the targets must be approved before testing begins. Your [Asset Map](/docs/asset-map) provides context about the infrastructure behind those targets. It helps the agent understand connected services, resources, and identities. The map may describe more infrastructure than the agent is authorized to test; the approved targets still define the testing scope. ## What happens during a run The agent investigates the targets, tests potential weaknesses, and follows what it learns to decide what to investigate next. It can use the Asset Map to explore how a weakness in one service might affect another resource. When the agent confirms an exploitable weakness, Antigen records a [vulnerability](/docs/runs/vulnerabilities) with its severity, description, and supporting [evidence](/docs/runs/evidence). Evidence can include the requests, responses, screenshots, or other artifacts that demonstrate the issue. Your team can review confirmed vulnerabilities in the platform while the run continues. ## What happens to the results A vulnerability is a record your team can track independently of the run that discovered it. Finishing the run does not close the vulnerability. Its status, assignment, and evidence can change as agents and your team work on it. A [report](/docs/runs/reports) summarizes an engagement and captures the relevant vulnerabilities and evidence at the time it is written. The report preserves those results while the vulnerabilities continue through their lifecycle. ## How other agents continue the work Discovering a vulnerability can trigger further work. Antigen uses hooks that respond to changes in a vulnerability’s status or assignment to start other agents. The [vulnerability lifecycle](/docs/vulnerability-lifecycle) explains these hooks, the built-in agents they trigger, and how you can connect your own agents. # Reports Source: https://docs.antigen.sh/docs/runs/reports A report summarizes an engagement and captures the relevant vulnerabilities and evidence at the time it is written. The report preserves those results while the vulnerabilities continue through their lifecycle. Use reports to share the results of testing with your team, customers, or auditors. ## What a report contains * **Executive summary:** an overview of the engagement and its results. * **Scope and methodology:** what was tested and how the testing was performed. * **Vulnerabilities:** the security weaknesses identified, including their severity and descriptions. * **Evidence:** the material supporting those vulnerabilities. Reports can also map vulnerabilities to compliance frameworks such as HIPAA, PCI DSS, SOC 2, and NIST 800-53. ## View and export a report Open **Reports** in the platform and select a report to read it. You can review the engagement summary, inspect individual vulnerabilities, and examine their supporting evidence. Select **Export** to download a PDF for sharing outside the platform. ## Reports and ongoing work A report describes the engagement at a particular point in time. Work on its vulnerabilities can continue after the report is written. For example, a vulnerability may be open when it appears in a report and verified after your team deploys a fix. The report preserves the original results; the **Vulnerabilities** page shows the current status and subsequent work. # Targets Source: https://docs.antigen.sh/docs/runs/targets Targets define what an agent is allowed to test. A target can be a domain, subdomain, wildcard domain, or IP address. The Antigen team manually reviews and approves every new target to ensure responsible use of our cyber-capable models. This applies whether your expert runs tCell for you or you launch an agent through the SDK or API. ## Add targets Open **Settings → Targets** and add the domains or IP addresses you want tested. For example: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} example.com api.example.com *.example.com 203.0.113.10 ``` You can also submit targets through the API. See [SDK → Targets](/docs/sdk/targets) for working with targets programmatically. Adding a target submits it for review. It does not start a run. ## Check approval You can view each target’s approval status under **Settings → Targets** or query your targets through the API. If you need help defining the scope, contact your Antigen expert. Once a target is approved, you can include it in a [run](/docs/runs). When you need to test an additional domain or IP address, submit it for approval before including it in a run. # tCell Source: https://docs.antigen.sh/docs/runs/tcell tCell is Antigen’s pre-built offensive security agent. The Antigen team continuously experiments, tests, and improves how tCell investigates systems, identifies weaknesses, and verifies vulnerabilities. Antigen builds tCell with the same [Antigen SDK](/docs/sdk) available to your team. Using tCell gives you those improvements without having to assemble and maintain an agent yourself. ## Access applications during testing tCell uses Antigen’s identity infrastructure to interact with applications that require an account. It can sign up for services, sign in with Google accounts, and complete CAPTCHA challenges. These capabilities let tCell investigate application behavior beyond publicly accessible pages, including signup, login, and features available to signed-in users. ## What comes with tCell tCell combines cyber-capable models with skills and guardrails configured by the Antigen team: * **Skills** provide instructions that guide how the agent investigates. * **Guardrails** constrain what the agent is allowed to do during a run. These are already configured, so you can use tCell without assembling an agent yourself. During a run, tCell can query your [Asset Map](/docs/asset-map/how-agents-use-asset-map) to understand the infrastructure behind a target and investigate relationships between services, resources, and identities. ## Run tCell Your Antigen expert can plan an engagement and run tCell for your team. To discuss testing scope or plan an engagement, book office hours from the platform sidebar or [schedule directly](https://cal.com/team/antigen/antigen-office-hours). You can also launch tCell through the SDK or API against [approved targets](/docs/runs/targets). Confirmed vulnerabilities and their supporting evidence appear in the platform as tCell works. See [Runs](/docs/runs) for how testing works and what happens to the results. ## Assemble your own agent If you need a different combination of models, skills, or guardrails, you can assemble a custom agent with the Antigen SDK. Custom agents run in the same sandboxed environment as tCell and can access your organization’s Asset Map. See [SDK → Agents](/docs/sdk/agents) for details. # Vulnerabilities Source: https://docs.antigen.sh/docs/runs/vulnerabilities When an agent confirms an exploitable security weakness during a run, it creates a vulnerability with a description, severity, and supporting evidence. A vulnerability stays available after the run ends. Your team and agents can update its status, assignment, and evidence as they investigate the issue, prepare a fix, and verify the result. ## Review a vulnerability Open **Vulnerabilities** in the platform to view your vulnerabilities as a board or a list. Select a vulnerability to review: * **Description:** what the issue is and which systems it affects. * **Severity:** how serious the issue is. * **Evidence:** the requests, responses, screenshots, or other artifacts that demonstrate the weakness. * **Status and assignment:** where the work stands and who or which agent is responsible. A vulnerability can have multiple [evidence items](/docs/runs/evidence). Together, they help your team understand and reproduce the issue. ## Track the work The vulnerability’s status, assignment, and supporting evidence can change as work progresses. For example, a remediation agent can prepare a fix, and a later run can add evidence showing whether that fix resolved the issue. These updates stay attached to the vulnerability, so your team can follow the work from the original discovery through verification. Hooks can trigger this work automatically. Your team reviews proposed changes and handles work that needs human input. See the [vulnerability lifecycle](/docs/vulnerability-lifecycle) for how statuses, assignments, and hooks coordinate this work. ## Vulnerabilities in reports A [report](/docs/runs/reports) captures the vulnerabilities and evidence relevant to an engagement at the time it is written. The report preserves those results while the vulnerabilities continue through their lifecycle. # Agents Source: https://docs.antigen.sh/docs/sdk/agents An agent combines a model, skills, guardrails, and tools into a configuration you can run. Retrieve an existing agent or construct one locally, then use it to start runs against approved targets or work on vulnerabilities. You can customize an agent before running it and register its configuration for your team to reuse. ## Use a pre-built agent The SDK exports constants for tCell, **triage-agent**, and **remediation-agent**. Retrieve one with `antigen.agents.get()`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell, triageAgent, remediationAgent, } from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const agent = await antigen.agents.get(tCell); ``` | Agent | Purpose | | - | - | | `tCell` | Test approved targets and verify fixes | | `triageAgent` | Investigate vulnerabilities and determine how remediation should proceed | | `remediationAgent` | Prepare pull requests or recommend changes for your team to make | The Antigen team develops these agents with the same SDK available to your team. ## Customize an existing agent Use object composition to keep an agent’s configuration while changing selected fields. Supplying a field replaces its value; combining its existing value with yours adds to it. Skills are instruction strings. This example reads a skill from a Markdown file, changes tCell’s model, and adds the instructions to its configuration: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { readFile } from "node:fs/promises"; const original = await antigen.agents.get(tCell); const authentication = await readFile("./skills/our-jwt-scheme.md", "utf8"); const agent = antigen.agent({ ...original, model: "claude-opus-5-cyber", skills: [ ...original.skills, authentication, ], }); ``` The configuration includes a `base` reference that identifies the underlying agent. Keeping that reference preserves tCell’s built-in behavior while you customize its exposed fields. Those fields do not include tCell’s private instructions. The same composition works with other pre-built agents and agents your team has registered. See [Models](/docs/sdk/models), [Skills](/docs/sdk/skills), and [Guardrails](/docs/sdk/guardrails) for the available configuration. ## Construct an agent locally Call `antigen.agent()` with your configuration to assemble an agent without starting from a pre-built agent: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const agent = antigen.agent({ model: "claude-opus-5-cyber", skills: ["Check whether a token for one account can access another account's data."], guardrails: "Do not test /internal endpoints.", }); ``` This creates a local Agent object without making an API request. You can use it to start a run without registering it first. See [Runs](/docs/sdk/runs) for launching agents and working with their results. ## Register an agent Register an agent to save its configuration in Antigen under a name: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.agents.register("our-security-agent", agent); ``` Your team can then retrieve it without defining the configuration again: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const agent = await antigen.agents.get("our-security-agent"); ``` Registered agents also appear in the platform’s assignment dropdown. When your team assigns a vulnerability to one, your webhook handler can retrieve the agent and launch it to investigate or prepare a fix. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for setting up that workflow. Registering a name that already exists returns an error. Use `update()` to change an existing agent. ## Update a registered agent Pass the fields you want to change: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.agents.update("our-security-agent", { model: "claude-opus-5-cyber", }); ``` Fields you omit keep their saved values. To append skills, retrieve the agent and include its existing skills in the update: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const agent = await antigen.agents.get("our-security-agent"); await antigen.agents.update("our-security-agent", { skills: [...agent.skills, "Our GraphQL API uses cursor-based pagination. Check authorization when following cursors across accounts."], }); ``` Updating a name that does not exist returns an error. ## Using the Asset Map Agents can query your organization’s [Asset Map](/docs/asset-map) through a tool available during a run. They can look up assets and explore their relationships to gather infrastructure context as they work. For example, an agent investigating an application can look up its connected resources and use those relationships to decide what to investigate next. You can also [query the Asset Map directly](/docs/sdk/asset-map) from your application using the SDK. # Asset Map Source: https://docs.antigen.sh/docs/sdk/asset-map Use the SDK to explore your organization’s [Asset Map](/docs/asset-map), find assets, and follow their connections. You can retrieve part of the graph as JavaScript objects or compose a Cypher query to select specific information. Both read the same map shown in the platform, using your API key’s organization. | Method | Use it to | | - | - | | `antigen.assetMap.get()` | Retrieve assets and their connections as nodes and edges. | | `antigen.assetMap.query()` | Filter assets, follow specific relationships, or aggregate results with Cypher. | ## How the graph is organized Assets are represented as **nodes**. Each node has an ID, labels describing what it is, and properties containing its details. A Supabase database, for example, has both `SupabaseDatabase` and `Database` labels. Its properties include its hostname and database version. These labels let you query a specific integration’s resources or work across integrations using a shared category. **Edges** describe directed relationships between nodes. A `HAS_DATABASE` edge connects a Supabase project to its database. A `RESOURCE` edge connects an account or organization to the resources it contains. The available labels, properties, and relationships depend on the integrations connected to your map. ## Retrieve assets and their connections Call `antigen.assetMap.get()` with one or more asset IDs. Set `depth` to control how far to explore their connections. ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const graph = await antigen.assetMap.get({ nodeIds: ["project_123"], depth: 1, }); ``` This returns the selected project and its immediate neighbors. Increasing `depth` to `2` also includes assets connected to those neighbors. Connections are followed in both directions. Each returned edge retains its original direction, so you can distinguish a project’s database from the organization that contains the project. ### Parameters | Parameter | Type | Description | | - | - | - | | `nodeIds` | `string[]` | IDs of the assets to start from. | | `depth` | `number` | Number of connections to follow from each starting asset. Defaults to `1`. | ### Return value The result contains `nodes` and `edges` arrays. Nodes appear once in the result, even when several paths lead to them. Each edge references nodes in the returned array through `fromId` and `toId`. ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} for (const node of graph.nodes) { console.log(node.id, node.labels, node.properties); } for (const edge of graph.edges) { console.log(edge.fromId, edge.label, edge.toId); } ``` You can use these arrays to display a graph or inspect relationships in your own code. For example, this finds the databases connected to the selected project: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const nodesById = new Map( graph.nodes.map((node) => [node.id, node]), ); for (const edge of graph.edges) { if ( edge.fromId === "project_123" && edge.label === "HAS_DATABASE" ) { const database = nodesById.get(edge.toId); console.log(database?.properties.host); } } ``` ## Query the map Use `antigen.assetMap.query()` when you want to select assets by their properties, follow particular relationships, or compute values such as resource counts. Build the query with [Neo4j’s Cypher Builder](https://neo4j.com/docs/cypher-builder/current/): ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @neo4j/cypher-builder ``` This example finds Supabase projects in a region and returns their IDs and names: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Cypher from "@neo4j/cypher-builder"; const project = new Cypher.Node(); const query = new Cypher.Match( new Cypher.Pattern(project, { labels: ["SupabaseProject"], }), ) .where(project, { region: new Cypher.Param("us-east-1"), }) .return( [project.property("id"), "id"], [project.property("name"), "name"], ); const projects = await antigen.assetMap.query(query); ``` `Cypher.Param` supplies the region as a query parameter. The aliases in `.return()` name the fields in each result: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} // Example result [ { id: "project_123", name: "production" }, { id: "project_456", name: "staging" }, ] ``` You can use those IDs to explore the matching projects: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const graph = await antigen.assetMap.get({ nodeIds: projects.map((project) => String(project.id)), depth: 1, }); ``` ### Parameters | Parameter | Description | | - | - | | `query` | A query object constructed with `@neo4j/cypher-builder`. The SDK builds and executes the query with its parameters. | ### Return value Returns an array of rows. Each row contains the fields selected by the query. A query with no matches returns an empty array. Queries can select properties, nodes, relationships, paths, and aggregate values. Returned nodes and edges use the same representation as `get()`. Paths contain `nodes` and `edges` arrays. The builder provides TypeScript types for constructing queries. Label names, property names, and result fields depend on the graph schema. ## Node and edge fields ### Node | Field | Type | Description | | - | - | - | | `id` | `string` | Identifier used to retrieve the asset and resolve edge endpoints. | | `labels` | `string[]` | Labels describing the asset. A node can have multiple labels. | | `properties` | Object | Asset details supplied by its integration. | ### Edge | Field | Type | Description | | - | - | - | | `id` | `string` | Identifier for the relationship. | | `fromId` | `string` | Source node’s ID. | | `toId` | `string` | Destination node’s ID. | | `label` | `string` | Relationship type, such as `RESOURCE` or `HAS_DATABASE`. | | `properties` | Object | Additional details about the relationship. | ## Access Both methods provide read-only access to your organization’s map. Queries that create, update, or delete graph data are rejected. You can call these methods from scripts, applications, or external agent environments using [API key authentication](/docs/sdk/authentication). Connecting infrastructure is covered in [Connecting infrastructure](/docs/asset-map/connecting-infrastructure). # Authentication Source: https://docs.antigen.sh/docs/sdk/authentication Use an API key to authenticate the Antigen SDK from scripts, CI pipelines, and applications. ## Create an API key Create an API key in the Antigen platform, then store it as `ANTIGEN_API_KEY` in your environment. For CI pipelines and hosted applications, use your environment’s secret store. Use a separate key for each application so you can replace or revoke one without affecting the others. ## Initialize the SDK Pass the key when creating the client. The SDK includes it with subsequent API requests. ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); ``` Keep your key out of source control and browser code. If you’re building a frontend, make authenticated requests to Antigen from your application’s backend. ## Replace or revoke a key To replace a key, create a new one, update the applications that use it, and revoke the old key in the platform. If a key is exposed, revoke it and update the affected applications with a new key. # Evidence Source: https://docs.antigen.sh/docs/sdk/evidence Use the SDK to retrieve the [evidence](/docs/runs/evidence) supporting a vulnerability and download its files. Evidence shows what an agent tested and what happened. It can include requests and responses, screenshots, reproduction scripts, and logs. Each item belongs to a vulnerability and can identify the run that produced it. ## List evidence for a vulnerability Pass the vulnerability’s ID to `antigen.evidence.list()`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const evidence = await antigen.evidence.list({ vulnerabilityId: "vuln_abc123", }); for (const item of evidence) { console.log(item.id, item.filename, item.sizeBytes); } ``` This returns information about each evidence item, including its filename and size. Use the item’s ID to download its contents. A vulnerability can have several evidence items. For example, an access-control issue might include a reproduction script, the service’s response, and a screenshot showing the exposed information. ### Parameters | Parameter | Type | Description | | - | - | - | | `vulnerabilityId` | `string` | ID of the vulnerability whose evidence you want to retrieve. | Returns an array of evidence items. If the vulnerability has no evidence, the array is empty. ## List evidence from a run Use `run.evidence.list()` to retrieve evidence produced by a particular run: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const run = await antigen.runs.get("run_123"); const evidence = await run.evidence.list(); ``` The results can include evidence for several vulnerabilities discovered during that run. Each item includes its `vulnerabilityId`, so you can associate it with the relevant issue. Evidence attached to a vulnerability may come from several runs. Listing by vulnerability gives you its supporting material across those runs; listing by run selects material produced during that execution. ## Download a file Pass an evidence ID to `antigen.evidence.download()`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { writeFile } from "node:fs/promises"; const contents = await antigen.evidence.download("ev_123"); await writeFile("./reproduction.py", contents); ``` The method returns the file’s contents as a `Uint8Array`. You can save those bytes to disk or process them in your application. ### Parameters | Parameter | Type | Description | | - | - | - | | `evidenceId` | `string` | ID of the evidence item to download. | ### Read a text file For text evidence, decode the downloaded bytes: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const contents = await antigen.evidence.download("ev_123"); const text = new TextDecoder().decode(contents); console.log(text); ``` Use this for scripts, logs, and other text files. Images and packet captures can be saved and opened with tools that support their formats. ## Evidence fields List methods return metadata describing each item: | Field | Type | Description | | - | - | - | | `id` | `string` | Identifier used to download the evidence. | | `vulnerabilityId` | `string` | Vulnerability supported by this item. | | `runId` | `string \| null` | Run that produced the evidence, when available. | | `filename` | `string` | Name of the file. | | `sizeBytes` | `number` | Size of the file in bytes. | | `createdAt` | `string` | Creation time as an ISO 8601 timestamp. | ## Access Evidence is available within your API key’s organization. Requests for a vulnerability, run, or evidence item that does not exist in your organization return a not-found error. See [Vulnerabilities](/docs/sdk/vulnerabilities) for reading the issue’s description, checking its status, and assigning work. # Pentest after a deployment Source: https://docs.antigen.sh/docs/sdk/example This example adds a pentest to your production deployment workflow. You’ll start with a script that runs tCell against your application, then connect it to GitHub Actions and limit testing to once every 24 hours. The check runs after deployment. Critical vulnerabilities fail the check so your team can investigate. The sections below explain each part. The [complete files](#complete-files) at the end combine them into a script and workflow you can copy into your repository. ## 1. Start a pentest First, choose the production hostname you want to test and [submit it for approval](/docs/sdk/targets). This example checks for an exact hostname, such as `api.example.com`. Submit that hostname separately if you already have a wildcard target. Install the SDK and `tsx`, which runs the TypeScript script: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @antigen/sdk npm install --save-dev tsx ``` The script reads your [API key](/docs/sdk/authentication) and target from environment variables. Before launching an agent, it checks that both are present and the target is approved: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; const apiKey = process.env.ANTIGEN_API_KEY; const target = process.env.PENTEST_TARGET; if (!apiKey || !target) { throw new Error("Set ANTIGEN_API_KEY and PENTEST_TARGET before running."); } const antigen = new Antigen(apiKey); const approved = await antigen.getApprovedTargets(); if (!approved.includes(target)) { throw new Error(`${target} is not approved for testing.`); } ``` Retrieve tCell and give it a task containing the approved target: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const agent = await antigen.agents.get(tCell); const run = await agent.run({ instructions: "Test the production application for vulnerabilities.", targets: [target], }); console.log(`Started run ${run.id}`); ``` At this point, testing has started in a [sandbox](/docs/getting-started/concepts#agents-and-runs). The Run object lets your script follow the work and retrieve its results. ## 2. Give the agent more context You can customize tCell before starting the run. For this example, ask it to investigate access between accounts and give it constraints for testing production. Replace the agent lookup above with this configuration: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const original = await antigen.agents.get(tCell); const agent = antigen.agent({ ...original, skills: [ ...original.skills, ` Investigate authorization across accounts. Check whether one account can read or modify resources belonging to another account. `, ], guardrails: [ original.guardrails, "Do not attempt denial of service or delete customer data.", ].join("\n"), }); ``` The spreads preserve tCell’s configuration and existing skills. The additional skill describes what to investigate, while the guardrail constrains how the agent should work. Use these fields for your application’s own procedures and constraints. See [Skills](/docs/sdk/skills) and [Guardrails](/docs/sdk/guardrails) for more examples. The call to `agent.run()` stays the same. ## 3. Follow the run and collect results A pentest can take time. Iterate over the run to print activity as it happens, so someone viewing the CI logs can follow its progress: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} for await (const event of run) { console.log(`${event.type}: ${event.summary}`); } await run.wait(); ``` `run.wait()` resolves when testing completes and throws if the run fails or stops. Once it resolves, retrieve the vulnerabilities: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const vulnerabilities = await run.vulnerabilities.list(); ``` You now have the vulnerabilities from the completed run. The next step is deciding how they affect the CI check. ## 4. Make the results a CI check This example fails the check when it finds a critical vulnerability. It saves all vulnerabilities to a JSON file so your team can review the results, including issues below that threshold. Add the filesystem import at the top of the script, then save the results after retrieving them: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { mkdir, writeFile } from "node:fs/promises"; await mkdir("pentest-results", { recursive: true }); await writeFile( "pentest-results/vulnerabilities.json", JSON.stringify(vulnerabilities, null, 2), ); ``` Set a nonzero exit code when a critical vulnerability is present: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const critical = vulnerabilities.filter( (vulnerability) => vulnerability.severity === "critical", ); if (critical.length > 0) { console.error(`Found ${critical.length} critical vulnerabilities.`); process.exitCode = 1; } ``` The complete script wraps this work in `main()` and handles errors separately: | Exit code | Meaning | | - | - | | `0` | Testing completed without critical vulnerabilities. | | `1` | Testing completed and found critical vulnerabilities. | | `2` | The script could not complete testing or retrieve the results. | It also saves `run.json` as soon as the run starts. That file contains the run ID, target, and triggering deployment’s commit, which you can use to find the run later. ## 5. Run after a production deployment With the script in place, connect it to GitHub Actions. Add these values under your repository’s **Settings → Secrets and variables → Actions**: | Name | Kind | Value | | - | - | - | | `ANTIGEN_API_KEY` | Secret | Your Antigen API key. | | `PENTEST_TARGET` | Variable | The approved production hostname. | The workflow listens for deployment status updates and starts its job when the deployment succeeds in `production`: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} on: deployment_status: jobs: pentest: if: >- github.event.deployment_status.state == 'success' && github.event.deployment.environment == 'production' runs-on: ubuntu-latest ``` Your deployment provider must report status through GitHub’s [deployment status API](https://docs.github.com/en/rest/deployments/statuses). Change `production` if it uses a different environment name. After checking out your default branch and installing dependencies, the workflow passes the configured values to the script: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} - name: Run pentest env: ANTIGEN_API_KEY: ${{ secrets.ANTIGEN_API_KEY }} PENTEST_TARGET: ${{ vars.PENTEST_TARGET }} DEPLOYMENT_SHA: ${{ github.event.deployment.sha }} run: npx --no-install tsx scripts/pentest.ts ``` The final step uploads `pentest-results/` as an artifact, including when critical vulnerabilities fail the check. Your team can download it from the workflow execution or review the vulnerabilities and evidence in Antigen. If deployment itself runs in GitHub Actions, you can instead add the pentest job after your deployment job with `needs: deploy`. Adapt the condition to that workflow and pass the deployed commit as `DEPLOYMENT_SHA`. Events created using a workflow’s `GITHUB_TOKEN` generally do not trigger another workflow. See [Triggering a workflow](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow). ## 6. Limit testing to once every 24 hours Your team may deploy several times a day. Before installing dependencies or starting a pentest, the workflow checks whether its **Run pentest** step has already started in the last 24 hours. GitHub keeps that history, so the check can read earlier executions and their job steps. It includes previous attempts of rerun workflows. Once it finds a recent pentest attempt, it returns early: ```js theme={"theme":{"light":"github-light","dark":"github-dark"}} if (recentAttempt) { core.info("Skipping: a pentest was attempted in the last 24 hours."); return false; } ``` The check runs in a step named `cooldown`. Later steps use its result to decide whether to proceed: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} if: steps.cooldown.outputs.result == 'true' ``` A skipped step does not extend the window. For example, if testing starts at 10:00 on Monday, deployments later that day skip testing. The first deployment more than 24 hours after that attempt can start another pentest. Failed attempts count too, so repeated deployments do not repeatedly launch testing after an error. A concurrency group makes subsequent jobs wait for the current job to finish. The next job checks the history before deciding whether to test: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} concurrency: group: antigen-production-pentest cancel-in-progress: false ``` This example shares one cooldown across the workflow’s production target. Keep the workflow, job, and pentest step names stable, and retain their history. If the history request fails, the job fails before testing starts. ## Complete files Save these files in your repository and commit them with `package.json` and `package-lock.json` to your default branch. ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; import { mkdir, writeFile } from "node:fs/promises"; async function main() { const apiKey = process.env.ANTIGEN_API_KEY; const target = process.env.PENTEST_TARGET; if (!apiKey || !target) { throw new Error( "Set ANTIGEN_API_KEY and PENTEST_TARGET before running.", ); } const antigen = new Antigen(apiKey); const approved = await antigen.getApprovedTargets(); if (!approved.includes(target)) { throw new Error(`${target} is not approved for testing.`); } const original = await antigen.agents.get(tCell); const agent = antigen.agent({ ...original, skills: [ ...original.skills, ` Investigate authorization across accounts. Check whether one account can read or modify resources belonging to another account. `, ], guardrails: [ original.guardrails, "Do not attempt denial of service or delete customer data.", ].join("\n"), }); await mkdir("pentest-results", { recursive: true }); const run = await agent.run({ instructions: "Test the production application for vulnerabilities.", targets: [target], }); console.log(`Started run ${run.id}`); await writeFile( "pentest-results/run.json", JSON.stringify( { runId: run.id, target, deploymentSha: process.env.DEPLOYMENT_SHA, }, null, 2, ), ); for await (const event of run) { console.log(`${event.type}: ${event.summary}`); } await run.wait(); const vulnerabilities = await run.vulnerabilities.list(); await writeFile( "pentest-results/vulnerabilities.json", JSON.stringify(vulnerabilities, null, 2), ); const critical = vulnerabilities.filter( (vulnerability) => vulnerability.severity === "critical", ); if (critical.length > 0) { console.error(`Found ${critical.length} critical vulnerabilities.`); process.exitCode = 1; return; } console.log("Pentest completed without critical vulnerabilities."); } main().catch((error) => { console.error(error instanceof Error ? error.message : error); process.exitCode = 2; }); ``` ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} name: Production pentest on: deployment_status: permissions: contents: read actions: read jobs: pentest: name: Pentest production if: >- github.event.deployment_status.state == 'success' && github.event.deployment.environment == 'production' runs-on: ubuntu-latest timeout-minutes: 350 concurrency: group: antigen-production-pentest cancel-in-progress: false steps: - name: Check the last pentest attempt id: cooldown uses: actions/github-script@v9 with: script: | const cutoff = Date.now() - 24 * 60 * 60 * 1000; const { data: current } = await github.rest.actions.getWorkflowRun({ ...context.repo, run_id: context.runId, }); const runs = await github.paginate( github.rest.actions.listWorkflowRuns, { ...context.repo, workflow_id: current.workflow_id, per_page: 100, }, ); for (const run of runs) { if ( run.status === "completed" && Date.parse(run.updated_at) < cutoff ) { continue; } const jobs = await github.paginate( github.rest.actions.listJobsForWorkflowRun, { ...context.repo, run_id: run.id, filter: "all", per_page: 100, }, ); const recentAttempt = jobs.some((job) => job.name === "Pentest production" && job.steps?.some((step) => step.name === "Run pentest" && step.status !== "queued" && step.conclusion !== "skipped" && step.started_at && Date.parse(step.started_at) >= cutoff ) ); if (recentAttempt) { core.info( "Skipping: a pentest was attempted in the last 24 hours." ); return false; } } return true; - uses: actions/checkout@v7 if: steps.cooldown.outputs.result == 'true' with: ref: ${{ github.event.repository.default_branch }} - uses: actions/setup-node@v7 if: steps.cooldown.outputs.result == 'true' with: node-version: 24 cache: npm - name: Install dependencies if: steps.cooldown.outputs.result == 'true' run: npm ci - name: Run pentest if: steps.cooldown.outputs.result == 'true' env: ANTIGEN_API_KEY: ${{ secrets.ANTIGEN_API_KEY }} PENTEST_TARGET: ${{ vars.PENTEST_TARGET }} DEPLOYMENT_SHA: ${{ github.event.deployment.sha }} run: npx --no-install tsx scripts/pentest.ts - name: Save results if: always() && steps.cooldown.outputs.result == 'true' uses: actions/upload-artifact@v7 with: name: pentest-results-${{ github.run_id }}-${{ github.run_attempt }} path: pentest-results/ if-no-files-found: ignore ``` Testing runs against the live application, which may change during the pentest. The deployment SHA in `run.json` identifies what triggered testing. If CI is cancelled or times out, the agent can continue working. Use the run ID in the logs or artifact to [retrieve or stop it](/docs/sdk/stopping-and-resuming). # Guardrails Source: https://docs.antigen.sh/docs/sdk/guardrails Guardrails specify constraints on an agent’s behavior. Use them to identify actions it should avoid, conditions that should stop its work, or situations that require help from your team. Pass guardrails as a string in the agent’s configuration. The agent interprets these instructions while it works. ## Set guardrails This example keeps tCell’s configuration and adds constraints for testing your application: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const original = await antigen.agents.get(tCell); const agent = antigen.agent({ ...original, guardrails: [ original.guardrails, "Do not test endpoints under /internal/.", "Do not attempt denial of service.", "If you find exposed credentials, report them without using them.", ].join("\n"), }); ``` Combining the existing guardrails with your instructions preserves the constraints exposed in the original configuration. Passing a new string without the existing value replaces those configurable guardrails. ## Write specific constraints Describe the action or condition and what the agent should do in response. | Constraint | Example | | - | - | | Avoid an action | “Do not submit transactions through the production payment flow.” | | Stop testing | “Stop the run when you confirm a critical vulnerability.” | | Request human input | “If remediation requires a cloud configuration change, create a human task describing the change for the infrastructure owner.” | | Limit proposed changes | “Do not modify database migration files when preparing a fix.” | Guardrails can apply to offensive testing, triage, or remediation. Choose instructions that match the work your agent performs. Use [skills](/docs/sdk/skills) to explain procedures and provide context. Use guardrails to constrain how the agent carries out that work. ## Update saved guardrails Use `antigen.agents.update()` to change a registered agent’s guardrails. The string you provide becomes its saved value. ### Add constraints Retrieve the agent and combine its existing guardrails with the new instructions: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const saved = await antigen.agents.get("our-security-agent"); await antigen.agents.update("our-security-agent", { guardrails: [ saved.guardrails, "Do not test endpoints under /internal/.", ].join("\n"), }); ``` ### Replace the guardrails Pass a new string containing the configurable guardrails you want the agent to use: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.agents.update("our-security-agent", { guardrails: ` Do not test endpoints under /internal/. Do not attempt denial of service. If you find exposed credentials, report them without using them. `.trim(), }); ``` Replacing this field changes the configurable instructions. It does not remove a pre-built agent’s internal restrictions or the platform’s enforced controls. ## Guardrails and enforced restrictions Guardrails guide the agent through natural-language instructions. They are not a substitute for access controls or isolation. [Target approval](/docs/sdk/targets) and [sandbox restrictions](/docs/getting-started/concepts#agents-and-runs) are enforced separately. A guardrail cannot authorize testing an unapproved target or grant access the agent does not have. # Human tasks Source: https://docs.antigen.sh/docs/sdk/human-tasks Use [human tasks](/docs/team-workflows) when an agent needs a person to review a change, grant access, or make a decision. Each task is assigned to a person and explains what they need to do. Antigen delivers the request through your connected messaging and issue tracking tools, then tracks the response. | Where your agent runs | How it uses human tasks | | - | - | | An agent assembled with the Antigen SDK | Uses the **human\_tasks** tool during its run. | | Your own service or an external agent environment | Creates and manages tasks through the SDK or Antigen API. | Both use the same assignments and integrations configured in the platform. ## Use human tasks from an agent Agents assembled with the SDK have a **human\_tasks** tool they can use to request help and follow the response. Describe when the agent should involve your team in its [skills](/docs/sdk/skills) or task instructions. For example: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const run = await agent.run({ instructions: ` Prepare a fix for this vulnerability. If you need access to a repository, create a human task for alex@example.com explaining which repository you need and what access is required. `, vulnerabilities: [vulnerability], }); ``` The agent creates the request with the relevant vulnerability context. When the person responds, the agent uses that response to continue its work. For an access request, it retries the operation after confirmation and follows up if access is still missing. ## Create a task from your code Call `antigen.humanTasks.create()` with the vulnerability, assignee, and request: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const task = await antigen.humanTasks.create({ vulnerabilityId: "vuln_abc123", assignee: "alex@example.com", title: "Connect the payments repository", description: ` Add acme/payments to the GitHub integration so the remediation agent can inspect the affected code. Once access is granted, confirm that the repository is connected. `, }); console.log(task.id); ``` The assigned person receives a direct message through connected messaging tools and an assigned issue through connected issue trackers. If both are configured, they refer to the same human task. See [Messaging](/docs/team-workflows/messaging) and [Issue tracking](/docs/team-workflows/issue-tracking) for delivery and assignment behavior. ### Parameters | Parameter | Type | Description | | - | - | - | | `vulnerabilityId` | `string` | Vulnerability the request relates to. | | `assignee` | `string` | Email address of the person responsible. | | `title` | `string` | Short description of the requested action. | | `description` | `string` | What the person needs to do, why it is needed, and how to confirm completion. | | `completion` | Object | Optional condition that a connected integration can confirm automatically. | Returns the created task with an `open` status. ## Complete a task automatically Some actions can be confirmed through a connected integration. For a pull request review, specify the pull request whose merge completes the task: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const task = await antigen.humanTasks.create({ vulnerabilityId: "vuln_abc123", assignee: "alex@example.com", title: "Review and merge the authorization fix", description: ` Review the ownership check added to the payments API and merge the pull request once the change is approved. `, completion: { type: "pull_request_merged", url: "https://github.com/acme/payments/pull/42", }, }); ``` The task completes when the GitHub integration detects that pull request’s merge. Its associated issue updates automatically. Without an automatic completion condition, the assigned person completes the action and confirms through the connected tool. Write each request around the action you need. If the agent needs a fix deployed, the request should ask for deployment confirmation. ## Check a task Retrieve a task by its ID: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const task = await antigen.humanTasks.get("task_123"); console.log(task.status); console.log(task.response); ``` | Status | Meaning | | - | - | | `open` | The requested action is still outstanding. | | `completed` | The action was confirmed by a person or a connected integration. | | `cancelled` | The request is no longer needed. | `response` contains the person’s completion response when one was provided. Tasks completed through an integration may have no written response. For an external agent, your service uses the task’s status and response to decide when to continue. A completed access request, for example, tells your service to retry the operation that needed access. ## List tasks Retrieve tasks associated with a vulnerability: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const tasks = await antigen.humanTasks.list({ vulnerabilityId: "vuln_abc123", status: "open", }); ``` Both filters are optional. Omit them to list tasks across your organization. Returns an array of tasks. If none match, the array is empty. ## Update a task Use `antigen.humanTasks.update()` to revise the request or change its assignee: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.humanTasks.update("task_123", { assignee: "sam@example.com", description: ` Connect acme/payments with access to the source code. Confirm once the repository is available. `, }); ``` Only the supplied fields change. Updates are reflected in the connected tools. If the request is no longer needed, cancel it: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.humanTasks.update("task_123", { status: "cancelled", }); ``` ## Continue work on the vulnerability Completing a human task confirms the requested action. The next step depends on what the agent was waiting for: repository access may allow investigation to continue, while deployment confirmation may allow verification to begin. See [Vulnerabilities](/docs/sdk/vulnerabilities) for updating status and assignment, and [Runs](/docs/sdk/runs) for launching an agent with the vulnerability. # Antigen SDK Source: https://docs.antigen.sh/docs/sdk/index The Antigen SDK gives you access to the Antigen API from TypeScript. Use it to: * Query your organization’s [Asset Map](/docs/sdk/asset-map). * Create and manage [team workflows](/docs/sdk/human-tasks). * Assemble agents and control their runs. * Work with targets, vulnerabilities, and evidence. Your code works with the same resources your team sees in the platform. ## Install the SDK ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install @antigen/sdk ``` Set `ANTIGEN_API_KEY` in your environment. See [Authentication](/docs/sdk/authentication) for creating and using API keys. Python support is planned. Python applications can use the [Antigen API](/docs/reference) directly. ## Run an agent To start a run, retrieve an agent or construct one locally. This example uses tCell to test your approved targets and collect the vulnerabilities it discovers. ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const targets = await antigen.getApprovedTargets(); const agent = await antigen.agents.get(tCell); const run = await agent.run({ instructions: "Test these applications for vulnerabilities.", targets, }); await run.wait(); const vulnerabilities = await run.vulnerabilities.list(); console.log(vulnerabilities); ``` `antigen.agents.get(tCell)` retrieves tCell’s configuration. Calling `agent.run()` with a task starts testing in a [sandbox](/docs/getting-started/concepts#agents-and-runs) and returns a Run object. `run.wait()` waits for completion, and `run.vulnerabilities.list()` retrieves the vulnerabilities discovered during the run. You can run the same agent again against different approved targets. Each invocation creates a separate run with its own progress and results. See [Targets](/docs/sdk/targets) for submitting targets, updating them, and checking their approval status. ## Customize an agent tCell, **triage-agent**, and **remediation-agent** are pre-built agents developed with the same SDK. You can retrieve them using the exported `tCell`, `triageAgent`, and `remediationAgent` constants. An agent’s configuration determines its model, skills, guardrails, and tools. You can customize an existing agent by replacing configuration fields or adding to them. This example keeps tCell’s configuration and appends a skill describing your application’s authentication: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { readFile } from "node:fs/promises"; const authentication = await readFile("./skills/our-jwt-scheme.md", "utf8"); const custom = antigen.agent({ ...agent, skills: [...agent.skills, authentication], }); ``` Constructing an agent locally creates a configuration you can use to start runs. Registering it saves that configuration in Antigen under a name, so your team can retrieve and reuse it without defining it again. Registered agents also appear in the platform’s assignment dropdown. Your team can assign a vulnerability to an agent, and your webhook handler can launch it to investigate or prepare a fix. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for setting up this workflow. See [Agents](/docs/sdk/agents) for composition and registration, [Models](/docs/sdk/models) for model selection, and [Skills](/docs/sdk/skills) and [Guardrails](/docs/sdk/guardrails) for configuring instructions and constraints. ## Control a run A run continues in its sandbox if your script exits or disconnects. While it runs, you can stream progress events or send messages to adjust the agent’s focus. You can also stop a run and resume it later. Runs can test targets, investigate vulnerabilities, or prepare fixes, depending on the agent you launch. See [Runs](/docs/sdk/runs), [Steering](/docs/sdk/steering), and [Stopping and resuming](/docs/sdk/stopping-and-resuming). ## Work with results Use the SDK to read [vulnerabilities](/docs/sdk/vulnerabilities), update their status and assignment, and retrieve their supporting [evidence](/docs/sdk/evidence). These updates appear in the platform, where your team can review and act on them. Status and assignment changes can trigger [hooks](/docs/vulnerability-lifecycle/hooks). For example, when a vulnerability is assigned to your registered agent, your handler can retrieve the agent and start a run with that vulnerability. See [Pentest after a deployment](/docs/sdk/example) for a complete example that runs tCell from CI after a production deployment. # Models Source: https://docs.antigen.sh/docs/sdk/models Agents use models through Antigen’s model gateway. Set the `model` field when assembling an agent, or keep the model configured on a pre-built agent. The gateway provides cyber-capable Claude models alongside GLM and Kimi models. Your Antigen API key provides access through the SDK; you do not need separate provider keys. ## Available models Anthropic’s cyber-capable Claude models are available through Antigen’s model gateway for use against approved targets and vulnerabilities. | Model | Model ID | | - | - | | Claude Opus 5 | `claude-opus-5-cyber` | | Claude Opus 4.8 | `claude-opus-4-8-cyber` | | Claude Opus 4.7 | `claude-opus-4-7-cyber` | | Claude Opus 4.6 | `claude-opus-4-6-cyber` | | Claude Opus 4.5 | `claude-opus-4-5-20251101-cyber` | | Claude Sonnet 5 | `claude-sonnet-5-cyber` | | Claude Sonnet 4.6 | `claude-sonnet-4-6-cyber` | | Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929-cyber` | | Claude Haiku 4.5 | `claude-haiku-4-5-20251001-cyber` | GLM and Kimi use their standard model IDs without the suffix. | Model | Model ID | | - | - | | GLM 5.2 | `zai-org/GLM-5.2` | | GLM 5.3 | `zai-org/GLM-5.3` | | Kimi K3 | `moonshotai/Kimi-K3` | ## List models Use `antigen.models.list()` to retrieve the models available to your organization: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const models = await antigen.models.list(); for (const model of models) { console.log(model.id); } ``` Use the returned IDs when configuring agents. ## Select a model Set `model` when constructing an agent. This example keeps tCell’s configuration and selects Claude Opus 5 Cyber: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const original = await antigen.agents.get(tCell); const agent = antigen.agent({ ...original, model: "claude-opus-5-cyber", }); ``` Changing the model preserves the other configuration fields, including the agent’s skills, guardrails, and tools. To change the model saved on a registered agent, use `antigen.agents.update()`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.agents.update("our-security-agent", { model: "claude-opus-5-cyber", }); ``` See [Agents](/docs/sdk/agents) for constructing and updating agent configurations. ## Model access during runs Cyber-capable models are available to agents running in [sandboxes](/docs/getting-started/concepts#agents-and-runs), where target restrictions control which systems they can test. For offensive testing, submit your targets for approval before starting a run. See [Targets](/docs/sdk/targets) for submitting targets and checking their status. # Runs Source: https://docs.antigen.sh/docs/sdk/runs A run executes an agent on a task. The agent provides the model, skills, guardrails, and tools; the task describes what to do and which resources to work on. The agent runs in a [sandbox](/docs/getting-started/concepts#agents-and-runs). Your code receives a Run object for following progress, sending messages, and retrieving results. ## Start a run Retrieve or assemble an agent, then pass a task to `agent.run()`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const agent = await antigen.agents.get(tCell); const targets = await antigen.getApprovedTargets(); const run = await agent.run({ instructions: "Test these applications for vulnerabilities.", targets, }); ``` The call returns once the run has started. The agent continues working independently, including if your script exits or disconnects. Each call starts a separate run. Use `run.id` to identify it: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} console.log(run.id); ``` ## Define the task A task contains instructions and the resources the agent should work on. | Field | Purpose | | - | - | | `instructions` | Describe what the agent should do. | | `targets` | Approved targets the agent should test. | | `vulnerabilities` | Existing vulnerabilities the agent should investigate, remediate, or verify. | The same task can include targets and vulnerabilities. For example, verification instructions can ask an agent to retest a vulnerability against a specific approved target. Task instructions apply to that run. Use [skills](/docs/sdk/skills) for procedures and knowledge you want to reuse across runs, and [guardrails](/docs/sdk/guardrails) for constraints on the agent’s behavior. ## Work on a vulnerability Retrieve the vulnerability and include it in the task. This example asks the pre-built **remediation-agent** to prepare a fix: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { remediationAgent } from "@antigen/sdk"; const agent = await antigen.agents.get(remediationAgent); const vulnerability = await antigen.vulnerabilities.get("vuln_abc123"); const run = await agent.run({ instructions: "Prepare a fix for this vulnerability for our team to review.", vulnerabilities: [vulnerability], }); ``` You can use the same pattern in a webhook handler. When a vulnerability is assigned to your registered agent, retrieve both and start a run with the requested work. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for connecting this to assignment events. ## Follow progress The Run object is an async iterable. Iterate over it to receive events as the agent works: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} for await (const event of run) { console.log(event.type, event.summary); } ``` Events describe activity during the run, such as progress, tool use, and discovered vulnerabilities. If you only need the final results, wait for completion: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.wait(); ``` `run.wait()` resolves when the run completes. If the run fails, it throws an error with the failure details. If the run is stopped, it throws an error indicating that the run was stopped. Vulnerabilities and evidence already saved remain available even if the run fails or stops. ## Read vulnerabilities and evidence Use the run’s resource methods to retrieve vulnerabilities and evidence associated with it: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.wait(); const vulnerabilities = await run.vulnerabilities.list(); const evidence = await run.evidence.list(); ``` What a run produces depends on its task. An offensive run may discover vulnerabilities, while a remediation run may prepare a pull request or recommend an infrastructure change. See [Vulnerabilities](/docs/sdk/vulnerabilities) and [Evidence](/docs/sdk/evidence) for querying and working with these resources. ## Adjust or pause the work Send a message to an active run when you need to provide context or change its focus: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.steer("Focus on the GraphQL endpoint we deployed today."); ``` You can also stop a run and resume it later. See [Steering](/docs/sdk/steering) and [Stopping and resuming](/docs/sdk/stopping-and-resuming) for these controls. # Skills Source: https://docs.antigen.sh/docs/sdk/skills Skills give an agent instructions for a procedure or knowledge about your systems. A skill can explain how your application authenticates requests, how to investigate a particular weakness, or which conventions to follow when preparing a fix. Pass skills as strings in the agent’s `skills` array. You can write the instructions directly in your code or load them from another source, such as a Markdown file. ## Add skills to an agent To add a skill to an existing agent, preserve its configured skills with object composition: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen, { tCell } from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const original = await antigen.agents.get(tCell); const authentication = ` Our application uses JWTs signed with RS256. The public keys are available at /.well-known/jwks.json. Access tokens expire after one hour. Clients refresh them through POST /auth/refresh. When testing authentication: - Check whether expired tokens are rejected. - Check whether modified claims invalidate the signature. - Check whether the refresh endpoint validates the original token. - Check whether a token for one account can access another account's data. `; const agent = antigen.agent({ ...original, skills: [...original.skills, authentication], }); ``` Focus each skill on a specific topic. “Check authentication for vulnerabilities” adds little context; the token format, endpoints, and expected behavior give the agent something concrete to investigate. ## Load instructions from a file You can keep skills in Markdown files alongside your code. Read each file and pass its contents to the SDK: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { readFile } from "node:fs/promises"; const authentication = await readFile( "./skills/our-jwt-scheme.md", "utf8", ); const agent = antigen.agent({ ...original, skills: [...original.skills, authentication], }); ``` The SDK treats each string as instructions. It does not interpret file paths or read files for you. In this example, the Markdown file must be available where your code calls `readFile()`. ## Replace configured skills Supply a new array to replace the skills exposed in the agent’s configuration: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const agent = antigen.agent({ ...original, skills: [authentication], }); ``` This replaces the configurable skills while retaining the underlying pre-built agent’s behavior. See [Agents](/docs/sdk/agents) for how configuration inherits from a base agent. ## Use skills for different kinds of work Skills can guide offensive testing, triage, or remediation. For example: | Work | Useful skill content | | - | - | | Testing | Authentication flows, API conventions, and expected access boundaries | | Triage | Service ownership, deployment structure, and how to locate affected code | | Remediation | Repository conventions, test commands, and requirements for proposed changes | Use skills to explain how work should be done. Use [guardrails](/docs/sdk/guardrails) to specify constraints, such as avoiding particular endpoints or stopping when a critical vulnerability is found. ## Save and update skills Registering an agent saves its skill strings with the rest of its configuration: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.agents.register("our-security-agent", agent); ``` When your team retrieves the agent, its `skills` array contains those instructions. It does not depend on files from the environment that registered it. To change the saved skills, pass the updated strings to `antigen.agents.update()`. The `skills` array you send becomes the agent’s saved array. ### Append a skill Retrieve the agent and spread its existing skills into the new array before adding your instructions. This keeps the saved skills and adds `authentication`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const saved = await antigen.agents.get("our-security-agent"); await antigen.agents.update("our-security-agent", { skills: [...saved.skills, authentication], }); ``` ### Replace the skills Pass only the instructions you want to keep. This replaces all previously saved configurable skills with `authentication`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.agents.update("our-security-agent", { skills: [authentication], }); ``` `update()` does not merge arrays. Include the existing entries to append to them, or leave them out to replace them. If you keep instructions in a file, read the file again and submit its updated contents. Editing a local file alone does not change a registered agent. # Steering Source: https://docs.antigen.sh/docs/sdk/steering Use steering to guide an investigation, explore a promising result, or ask questions about the work an agent has done. Messages stay in the run’s conversation, so the agent can respond using its investigation history and evidence. Call `run.steer()` to send a message during a run or continue the conversation after the agent finishes its task. ## Guide an investigation As you follow a run, you may notice an area that deserves more attention. Give the agent a specific direction to explore: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.steer( "The account API returned different responses for those two users. Investigate whether that difference exposes another account's data.", ); ``` You can also share context that changes its priorities: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.steer( "We deployed a new GraphQL schema today. Spend more time checking authorization in its mutations.", ); ``` The agent uses your message alongside the task, skills, and guardrails to decide how to proceed. ## Explore further When the agent identifies a weakness or leaves a question unresolved, you can ask it to investigate further. ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.steer( "You confirmed the issue on the export endpoint. Check whether the same authorization behavior affects downloads.", ); ``` Describe the observation and what you want to learn next. This helps the agent pursue a concrete lead and build on the evidence it already collected. Further testing stays within the run’s approved scope. ## Ask questions after testing You can continue the conversation after the agent finishes testing. Ask it to explain a vulnerability, discuss the evidence, or clarify what it tested: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.wait(); await run.steer( "Did you test whether a read-only user could access the export endpoint? Explain what you tried and what the responses showed.", ); for await (const event of run) { console.log(event.type, event.summary); } ``` The agent answers using the context from that run. You can ask follow-up questions or give it additional work in the same conversation. ## Use steering for triage and remediation Steering also works with agents investigating vulnerabilities or preparing fixes. You can explain a repository convention, question a proposed change, or ask the agent to consider another approach: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.steer( "Older clients depend on this response format. Can you address the authorization issue while preserving it?", ); ``` Steering messages apply to the current run. To reuse instructions across future runs, add them to the agent’s [skills](/docs/sdk/skills) or [guardrails](/docs/sdk/guardrails). # Stopping and resuming Source: https://docs.antigen.sh/docs/sdk/stopping-and-resuming Stop a run when you want to pause its work and continue later. Stopping snapshots its [sandbox](/docs/getting-started/concepts#agents-and-runs) and shuts it down. Resuming creates a new sandbox from that snapshot, so the agent can continue with its saved conversation, files, and tools. ## Stop a run Call `run.stop()` and wait for it to finish: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.stop(); ``` The run saves a snapshot of its sandbox before shutting it down. Vulnerabilities and evidence already saved remain available in the platform and through the SDK. ## Resume a run Call `run.resume()` to create a sandbox from the saved snapshot and continue: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.resume(); for await (const event of run) { console.log(event.type, event.summary); } ``` The run keeps its ID and continues with its saved agent configuration and context. Progress and results remain associated with the same run. ## Retrieve a run later Save the run ID if you want to continue from another script or application session: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} console.log(run.id); ``` Retrieve it through the SDK, then resume: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const run = await antigen.runs.get("run_abc123"); await run.resume(); ``` ## Provide additional context After resuming, use [steering](/docs/sdk/steering) to share new information or adjust the agent’s focus: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await run.resume(); await run.steer( "The application now uses a separate identity provider for admin accounts.", ); ``` To change skills or guardrails for future runs, [update the registered agent](/docs/sdk/agents#update-a-registered-agent). Existing runs retain the configuration they started with, including when resumed. # Targets Source: https://docs.antigen.sh/docs/sdk/targets Antigen agents can use cyber-capable models through our partnership with Anthropic. To ensure responsible use, offensive runs can only test targets approved by the Antigen team. Targets define which systems an agent can test, such as a domain or IP address. Use the SDK to submit targets for review, check their approval status, and include approved targets in a [run](/docs/sdk/runs). The Antigen team manually reviews every new target. Targets submitted through the SDK also appear under **Settings → Targets** in the platform. ## Submit a target Call `antigen.targets.create()` with the domain or IP address you want to test: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const target = await antigen.targets.create({ value: "api.example.com", attested: true, }); console.log(target.id); console.log(target.status); // "pending" ``` `attested: true` confirms that your organization is authorized to test the target. The target becomes available for testing once the Antigen team approves it. Submit each domain, wildcard domain, or IP address as a separate target so you can track its approval independently. ### Parameters | Parameter | Type | Description | | - | - | - | | `value` | `string` | Domain, subdomain, wildcard domain, or IP address to submit. | | `attested` | `true` | Confirmation that your organization is authorized to test the target. Required. | Returns the submitted target with a `pending` status. ## Check approval Retrieve a target by its ID to check its current status and any review notes: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const target = await antigen.targets.get("target_123"); console.log(target.status); console.log(target.reviewNote); ``` | Status | Meaning | | - | - | | `pending` | Waiting for review. | | `approved` | Available for testing. | | `rejected` | Not approved for testing. Read `reviewNote` for the reason. | If a target is rejected, use the review note to understand what needs to change. Your Antigen expert can help clarify the scope. ## List targets Call `antigen.targets.list()` to retrieve your organization’s targets: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const targets = await antigen.targets.list(); ``` Filter by status when you only need targets at a particular stage of review: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const pending = await antigen.targets.list({ status: "pending", }); const approved = await antigen.targets.list({ status: "approved", }); ``` Each result includes the target’s ID, value, approval status, and review note. ### Parameters | Parameter | Type | Description | | - | - | - | | `status` | `"pending" \| "approved" \| "rejected"` | Filter by approval status. Omit to include all statuses. | Returns an array of targets. If none match, the array is empty. ## Use approved targets in a run `antigen.getApprovedTargets()` returns your approved target values as a string array, ready to pass into a task: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const targets = await antigen.getApprovedTargets(); // Example result: // ["example.com", "*.example.com", "api.example.com"] ``` Retrieve an agent and include those targets when starting a run: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { tCell } from "@antigen/sdk"; const agent = await antigen.agents.get(tCell); const targets = await antigen.getApprovedTargets(); if (targets.length === 0) { throw new Error("No approved targets are available."); } const run = await agent.run({ instructions: "Test these applications for vulnerabilities.", targets, }); ``` You can also select a subset of approved targets: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const approved = await antigen.targets.list({ status: "approved", }); const targets = approved .filter((target) => target.value === "api.example.com") .map((target) => target.value); if (targets.length === 0) { throw new Error("api.example.com is not approved for testing."); } const run = await agent.run({ instructions: "Investigate the API's authentication flow.", targets, }); ``` Target approval is checked when the run starts. The values in your task must fall within your organization’s approved scope. ## Update a target Use `antigen.targets.update()` to correct a target’s value: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const target = await antigen.targets.update("target_123", { value: "api.staging.example.com", attested: true, }); console.log(target.status); // "pending" ``` Changing the value submits the target for another review. Wait until it is approved before using the updated value in a run. To add another system while keeping an existing target, submit it with `antigen.targets.create()`. ### Parameters | Parameter | Type | Description | | - | - | - | | `targetId` | `string` | ID of the target to update. | | `value` | `string` | Replacement target value. | | `attested` | `true` | Confirmation that your organization is authorized to test the replacement value. | Returns the updated target. ## Target fields | Field | Type | Description | | - | - | - | | `id` | `string` | Identifier used to retrieve or update the target. | | `value` | `string` | Domain, wildcard domain, or IP address submitted for testing. | | `status` | `"pending" \| "approved" \| "rejected"` | Current approval status. | | `reviewNote` | `string \| null` | Note from the Antigen team explaining its review decision. | ## Permissions Submitting or updating targets requires permission to manage your organization’s targets. Approval decisions are made by the Antigen team. The SDK rejects invalid target values and duplicate submissions. Requests to retrieve or update a target that does not exist in your organization return a not-found error. # Vulnerabilities Source: https://docs.antigen.sh/docs/sdk/vulnerabilities Use the SDK to retrieve [vulnerabilities](/docs/runs/vulnerabilities), review their details, and update their status and assignment. Vulnerabilities remain available after a run finishes. Your code works with the same vulnerabilities your team sees in the platform, including updates made by people and agents as remediation progresses. ## List vulnerabilities Call `antigen.vulnerabilities.list()` to retrieve vulnerabilities across your organization’s runs: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import Antigen from "@antigen/sdk"; const antigen = new Antigen(process.env.ANTIGEN_API_KEY); const vulnerabilities = await antigen.vulnerabilities.list({ severity: "critical", status: "open", }); ``` Filters apply together. This example returns vulnerabilities that are both critical and open. | Parameter | Description | | - | - | | `severity` | Filter by severity. | | `status` | Filter by lifecycle status. | Omit the filters to include all severities and statuses. ### Vulnerabilities from a run Use the run’s collection to retrieve vulnerabilities associated with that run: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const run = await antigen.runs.get("run_123"); const vulnerabilities = await run.vulnerabilities.list(); for (const vulnerability of vulnerabilities) { console.log(vulnerability.severity, vulnerability.title); } ``` The returned vulnerabilities reflect their current status and assignment. A [report](/docs/runs/reports) preserves the results captured at the time it was written. ## Read a vulnerability Retrieve a vulnerability by its ID to inspect its description and supporting information: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const vulnerability = await antigen.vulnerabilities.get( "vuln_abc123", ); console.log(vulnerability.title); console.log(vulnerability.description); console.log(vulnerability.severity); console.log(vulnerability.status); console.log(vulnerability.assignee); ``` The description explains the weakness and the affected system. Supporting evidence shows what the agent observed and helps your team reproduce the issue. See [Evidence](/docs/sdk/evidence) for retrieving requests, responses, screenshots, and other artifacts associated with a vulnerability. ## Assign work A vulnerability can be assigned to a team member or a registered agent. To assign it to a team member, pass their email address: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.vulnerabilities.updateAssignee( "vuln_abc123", "alex@example.com", ); ``` To use the pre-built **remediation-agent**, pass its SDK constant: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { remediationAgent } from "@antigen/sdk"; await antigen.vulnerabilities.updateAssignee( "vuln_abc123", remediationAgent, ); ``` With the default remediation hook enabled, this assignment starts a run to prepare remediation steps. ### Assign a custom agent Pass the name of an agent your team has registered: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.vulnerabilities.updateAssignee( "vuln_abc123", "our-remediation-agent", ); ``` The assignment triggers an event for your configured webhooks. Your handler can retrieve the vulnerability and launch the agent when it is ready to start work. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for registration and webhook setup. ### Remove an assignment Pass `null` to leave the vulnerability unassigned: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.vulnerabilities.updateAssignee( "vuln_abc123", null, ); ``` ## Update status Use `antigen.vulnerabilities.updateStatus()` as work progresses: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.vulnerabilities.updateStatus( "vuln_abc123", "in_progress", ); ``` Assign a person or agent before moving a vulnerability to `in_progress`. | Status | Meaning | | - | - | | `open` | The vulnerability needs investigation or remediation. | | `in_progress` | A person or agent is working on it. | | `remediated` | A fix has been deployed and is ready for verification. | | `verified` | Verification confirmed that the original exploit no longer succeeds. | | `accepted_risk` | Your team has decided to accept the risk. | Accepting risk requires a note explaining the decision and an expiration time. ### Request verification Once the fix is deployed, move the vulnerability to `remediated`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await antigen.vulnerabilities.updateStatus( "vuln_abc123", "remediated", ); ``` With the default verification hook enabled, this starts a tCell run to test the original exploit again. A successful verification moves the vulnerability to `verified`. If the exploit still succeeds, the vulnerability returns to `open` with new evidence. Merging a pull request may be one step toward remediation. Move the vulnerability to `remediated` when the fix is deployed to the affected system. The `verified` status is set through verification. It cannot be assigned directly with `updateStatus()`. ## Work on a vulnerability in a run You can also retrieve a vulnerability and pass it directly to an agent: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const agent = await antigen.agents.get( "our-remediation-agent", ); const vulnerability = await antigen.vulnerabilities.get( "vuln_abc123", ); const run = await agent.run({ instructions: "Investigate this vulnerability and prepare a fix.", vulnerabilities: [vulnerability], }); ``` This is the same pattern your webhook handler can use after an assignment event. See [Runs](/docs/sdk/runs) for following progress and retrieving results. ## Status and assignment hooks Changes made through the SDK trigger the same [hooks](/docs/vulnerability-lifecycle/hooks) as changes made in the platform. Status-change events include the previous and new statuses. Assignment-change events include the previous and new assignees. Your service can use these values to decide what to do next. The update completes when the change has been saved. Work started by a hook, such as a remediation or verification run, continues separately. # Team workflows Source: https://docs.antigen.sh/docs/team-workflows/index Agents sometimes need your team to review a change, grant access, or make a decision. They request that help through **human tasks**. Each human task is assigned to a person. It explains what the agent needs, why it needs it, and what that person should do next. ## When an agent needs help Antigen’s pre-built **triage-agent** and **remediation-agent** create human tasks when they need someone to act. For example: * **triage-agent** requests access to a repository. * **triage-agent** asks for a decision about how to proceed with a vulnerability. * **remediation-agent** requests a review and merge of a proposed pull request. * **remediation-agent** asks someone to make a cloud configuration change. Each request includes the relevant vulnerability and instructions for completing the task. ## Receive requests in your tools Connect your tools under **Settings → Integrations**. With [messaging](/docs/team-workflows/messaging) connected, the assigned person receives a direct message in Slack or Microsoft Teams. With [issue tracking](/docs/team-workflows/issue-tracking) connected, the request appears as an issue assigned to that person. You can connect both to discuss and track the same task. Tasks also remain available in the platform. ## How agents continue When a connected integration can confirm the requested action, the task updates automatically. For example, if an agent asks you to merge a pull request, it detects the merge through GitHub. You do not need to confirm it separately. For other requests, complete the action and confirm through the connected tool. If an agent asks for repository access, grant access and respond to the request. The agent retries its work and follows up if it still needs help. Completing a human task lets the agent continue. It does not necessarily mean the vulnerability is resolved. See the [vulnerability lifecycle](/docs/vulnerability-lifecycle) for how fixes are verified. ## Use human tasks with your own agents Custom agents assembled with the [Antigen SDK](/docs/sdk) have a **human\_tasks** tool they can use directly to request help from your team. External agents, such as Cursor Cloud or Devin, can create and interact with human tasks through the Antigen API. In both cases, requests use the same assignments and connected integrations as requests from the pre-built agents. # Issue tracking Source: https://docs.antigen.sh/docs/team-workflows/issue-tracking Assign and track human tasks in your team's issue tracker or management tool. Track [human tasks](/docs/team-workflows) in your team’s issue tracker or management tool. | Tool | How human tasks appear | | - | - | | Linear | Issues | | GitHub | Issues | | Jira | Issues | | Azure Boards | Work items | | GitLab | Issues | | ServiceNow | Tasks or change requests | Each task is assigned to the responsible person in the connected tool. It includes the relevant vulnerability, what the agent needs, and instructions for completing the request. ## Connect your issue tracker Open **Settings → Integrations** and connect your tool. Configure the team, project, repository, or queue where tasks should appear. Human tasks are assigned to the responsible person’s account in the connected tool. ## Complete a request Complete the requested action, add any relevant details, and mark the issue complete. The agent uses your update to continue its work. For example, an agent may ask you to change a cloud firewall rule. Review the recommendation, make the change, and confirm what you changed in the ticket. If the agent still needs something, it follows up through the same task. You can also use comments to ask questions or explain what is blocking the work. ## Tasks that complete automatically When a connected integration can confirm the requested action, the task and its associated issue update automatically. For example, if a task asks you to merge a pull request, the GitHub integration detects the merge and marks the task complete. You do not need to close the associated issue separately. ## Follow your team’s approval process Handle any required approvals through your existing workflow. In ServiceNow, for example, your team can review and approve a change request before making the proposed change. The agent provides the recommendation and supporting context. Your team reviews and carries out the production change. ## Track progress on the vulnerability Completing a task means the requested action is done. Granting access may let an agent begin investigating; deploying a fix may let verification begin. Closing a ticket does not mark the vulnerability as verified. See the [vulnerability lifecycle](/docs/vulnerability-lifecycle) for how agents verify fixes and update vulnerability statuses. You can also receive tasks through [Slack or Microsoft Teams](/docs/team-workflows/messaging) to discuss requests while tracking the work in your issue tracker. # Messaging Source: https://docs.antigen.sh/docs/team-workflows/messaging Receive and respond to human tasks in Slack and Microsoft Teams. Receive [human tasks](/docs/team-workflows) through direct messages in Slack or Microsoft Teams. Each request goes to the person assigned to the task and includes the relevant vulnerability and instructions. ## Connect your messaging tool Open **Settings → Integrations** and connect Slack or Microsoft Teams. When an agent assigns you a human task, you receive a direct message in the connected tool. You can respond there without repeating the update in the platform. ## Respond to a request Reply to the task’s message to provide information, ask a question, or confirm that you completed the requested action. For example, an agent may ask for access to a repository. Grant access through the GitHub integration, then reply to let the agent know. It retries its work and follows up in the same conversation if it still needs help. If you cannot complete the request, explain what is blocking you so the agent can account for it. ## Tasks that complete automatically Some requests concern actions that a connected integration can detect. If an agent asks you to merge a pull request, the task completes when the GitHub integration detects the merge. You do not need to send a separate confirmation. Completion depends on what the task asks for. If it asks you to deploy a fix, merging the pull request alone does not complete the request. ## Use messaging with issue tracking You can also connect an [issue tracker](/docs/team-workflows/issue-tracking). The assigned person receives a direct message and an assigned issue for the same human task. Use the conversation to discuss the request and the issue to track the work. The agent receives updates through either tool. # Assigning to your own agents Source: https://docs.antigen.sh/docs/vulnerability-lifecycle/assigning-to-your-own-agents You can use your own agents to investigate vulnerabilities, prepare fixes, and verify deployed changes. These can be agents assembled with the [Antigen SDK](/docs/sdk) or agents running in another environment, such as Cursor Cloud or Devin. Antigen provides the pre-built **triage-agent** and **remediation-agent** by default, and uses tCell for verification. You can keep the defaults for some work and use your own agents for other tasks. ## Choose where your agent runs Your service receives a [webhook](/docs/vulnerability-lifecycle/hooks) and decides when to launch the agent. The agent can run in an external environment or in a [sandbox](/docs/getting-started/concepts#agents-and-runs). ### Use an external agent Your service can launch an agent through a tool such as Cursor Cloud or Devin. The agent runs in that environment and can use the Antigen API to retrieve vulnerabilities, read evidence, and update the work. For example, your webhook handler can check an assignment event, retrieve the vulnerability and its evidence, and start a Cursor Cloud agent against the relevant repository. ### Use a custom Antigen agent Custom Antigen agents can use [cyber-capable models](/docs/sdk/models) from OpenAI and Anthropic through Antigen’s model gateway. The agents run in sandboxes and can only work on your approved targets or vulnerabilities. 1. **Assemble your agent** with the Antigen SDK. Choose its models, skills, guardrails, and tools. 2. **Register your agent** to save its configuration. You can then select it from the assignment dropdown in the platform or assign vulnerabilities to it through the API. 3. **Set up a webhook handler** in your own service to receive assignment changes. Check whether the vulnerability was assigned to your custom agent. 4. **Launch your agent from the handler.** Retrieve the registered agent through the SDK and start a run with the vulnerability and its evidence. You receive the webhook in your hosted environment, but the custom agent runs in a sandbox with its configured tools and access to your organization’s [Asset Map](/docs/asset-map). See [SDK → Agents](/docs/sdk/agents) for assembling and registering agents, and [SDK → Runs](/docs/sdk/runs) for launching them. ## Update the vulnerability Your agent or the service running it can use the API to update the vulnerability as work progresses. It can change the status or assign work to someone else. These updates appear on the same vulnerability your team reviews in the platform. Status and assignment changes can trigger additional hooks, just as they do for the pre-built agents. ## Replace a default workflow If you’re replacing triage, remediation, or verification with your own workflow, disable the corresponding default hook in the platform or via the API. This applies to both external agents and custom Antigen agents. * **Your own triage:** receive status changes to **Open** and launch your agent to investigate the vulnerability and determine how remediation should proceed. * **Your own remediation:** receive assignment changes, check whether the vulnerability was assigned to your agent, and launch it to prepare remediation steps. * **Your own verification:** receive status changes to **Remediated** and launch your agent with the vulnerability and its original evidence to test whether the fix worked. You can keep any default hooks you are not replacing. For example, use your own remediation agent and keep the default verification hook to have tCell verify deployed fixes. ## Request help from your team Your agent can create a human task to request a review, additional access, or an infrastructure change. See [Team workflows](/docs/team-workflows) for how these requests reach your team and how agents continue after a response. # Connecting your codebase Source: https://docs.antigen.sh/docs/vulnerability-lifecycle/connecting-your-code Connect your GitHub repositories so agents can inspect the code behind a vulnerability and prepare pull requests with proposed fixes. Antigen’s pre-built **triage-agent** uses repository access to investigate the issue and determine how remediation should proceed. **remediation-agent** uses it to prepare code changes for your team to review. ## Connect GitHub Open **Settings → Integrations** and connect GitHub. An organization admin completes the installation of the Antigen GitHub App and selects which repositories it can access. Select the repositories containing the applications and services you want agents to investigate. Agents can only access repositories included in the installation. ## Review proposed changes When **remediation-agent** prepares a code fix, it opens a pull request in the connected repository. Your team reviews, merges, and deploys the change through its existing GitHub workflow. A fix may also require changes outside the repository, such as updating cloud configuration or rotating credentials. See [How remediation works](/docs/vulnerability-lifecycle/how-remediation-works) for how these steps are proposed and tracked. ## Update repository access If **triage-agent** or **remediation-agent** needs a repository that is not included in the installation, it asks your team to update the GitHub integration. Grant access to the required repository through the GitHub App installation so the agent can continue. You can update repository access as your codebase changes. # Hooks Source: https://docs.antigen.sh/docs/vulnerability-lifecycle/hooks Hooks send an HTTP request to a configured URL when a vulnerability’s status or assignment changes. These requests are webhooks. Your service receives the event and decides what to do with it. You can use hooks to send notifications, launch agents, or connect vulnerabilities to your existing workflows. ## Status changes A status-change event includes the vulnerability’s previous status and its new status. When an agent creates a vulnerability, it starts in **Open** with no previous status. Later, verification might return an unresolved vulnerability from **Remediated** to **Open**. Your service can check these values to decide how to respond. For example, it could notify your security team whenever a vulnerability returns to **Open**. ## Assignment changes An assignment-change event includes the previous assignee and the new assignee. Either can be empty when a vulnerability is first assigned or becomes unassigned. Your service can use this event to notify the assignee, create a task in another system, or start work automatically. ## Default hooks Antigen comes with hooks configured for triage, remediation, and verification: * Entering **Open** starts Antigen’s pre-built **triage-agent**. * Assignment to Antigen’s pre-built **remediation-agent** starts remediation. * Entering **Remediated** starts a verification run. You can turn these hooks on or off in the platform or via the API. See the [lifecycle overview](/docs/vulnerability-lifecycle) for how the default setup works. ## Add your own webhooks You can also register webhooks through the SDK or API to receive status and assignment changes at your own URL. Your service decides how to respond, whether that means sending a notification, launching an agent, or starting another workflow. Keep the default hooks enabled to run your automation alongside them, or disable them to handle the work yourself. # How remediation works Source: https://docs.antigen.sh/docs/vulnerability-lifecycle/how-remediation-works Antigen’s pre-built **remediation-agent** prepares changes to address a vulnerability. It uses the investigation completed during triage, the original evidence, and your infrastructure context to determine what needs to change. ## When remediation starts With the default remediation hook enabled, assigning a vulnerability to **remediation-agent** starts a run. In the default setup, the triage agent makes this assignment when it determines that remediation can proceed. The agent receives the vulnerability, the triage investigation, and evidence from the run that discovered the issue. It can also use your [Asset Map](/docs/asset-map) and connected integrations to understand the affected systems and their dependencies. ## What the agent produces **remediation-agent** produces **remediation steps**. Each step describes a concrete change needed to address the vulnerability. Steps can include: * **Code changes:** a GitHub pull request containing a proposed fix. * **Infrastructure changes:** instructions for updating cloud resources, permissions, or service configuration. * **Work for your team:** actions that require someone with the necessary access or context. A single vulnerability may require several steps. For example, resolving exposed database credentials could require both a code change and a credential rotation. ## Review and complete the work The agent sends proposed work to your connected tools. It can open GitHub pull requests, create issues in Linear, Jira, or GitHub, and send requests through Slack. Your team reviews the proposed changes, merges pull requests, and completes infrastructure updates through its usual workflow. If the agent needs additional access or information, it explains what is missing and asks your team for help. Once the required changes are deployed, the vulnerability moves to **Remediated**. ## Verify the fix With the default verification hook enabled, entering **Remediated** starts a tCell run to test the original exploit against the approved target. If the exploit no longer succeeds, the vulnerability moves to **Verified**. If it still succeeds, the vulnerability returns to **Open** with new evidence. With the default triage hook enabled, this starts another investigation. ## Use your own workflow You can turn the default remediation hook on or off in the platform or via the API. To handle remediation through another system, add a webhook that responds to assignment changes. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for details. # How triage works Source: https://docs.antigen.sh/docs/vulnerability-lifecycle/how-triage-works Antigen’s pre-built **triage-agent** investigates a vulnerability and determines how remediation should proceed. It checks the available evidence, identifies the affected systems, and decides whether it has enough information and access to hand the work to Antigen’s pre-built **remediation-agent**. ## When triage starts With the default triage hook enabled, entering **Open** starts **triage-agent**. This happens when an agent creates a vulnerability or when verification finds that a previous fix did not resolve it. ## What the agent investigates **triage-agent** uses the vulnerability’s evidence, your [Asset Map](/docs/asset-map), and connected integrations to understand the issue. It investigates: * Which services, resources, and repositories are involved. * What changes could address the vulnerability. * Whether the required information and access are available. * Whether **remediation-agent** can handle the work or a person should investigate further. For example, a vulnerability in an application may require access to its repository. A cloud configuration issue may require context from the provider integration. ## What happens next **If remediation can proceed**, **triage-agent** moves the vulnerability to **In progress** and assigns it to **remediation-agent**. Its investigation is passed along so **remediation-agent** can use it when preparing changes. **If information or access is missing**, **triage-agent** explains what it needs and asks your team for help through your connected tools. For example, it may ask you to update your GitHub integration to grant access to the repository containing the affected code. **If the issue needs human investigation**, the vulnerability stays **Open**. Your team can assign it to a person or another agent. See [How remediation works](/docs/vulnerability-lifecycle/how-remediation-works) for how the investigation becomes proposed changes. ## Customize triage You can turn the default triage hook on or off in the platform or via the API. To handle triage through your own system, register a [webhook](/docs/vulnerability-lifecycle/hooks) that responds when a vulnerability enters **Open**. # Vulnerability lifecycle Source: https://docs.antigen.sh/docs/vulnerability-lifecycle/index Each vulnerability has a status and can be assigned to a person or an agent. When the status or assignment changes, it triggers a hook. A hook is a function that runs in response to that change. It can launch an agent, notify your team, or start another workflow. **When set up correctly, hooks and agents let you use Antigen as a security factory** - agents investigate vulnerabilities, prepare fixes, and verify deployed changes, while your team reviews proposed changes and steps in where needed. You can manage this work from **Vulnerabilities** in the platform. The board groups vulnerabilities by status; the list shows the same vulnerabilities in a table. ## Track status and assignment Status tells you where the work stands. Assignment tells you who or which agent is responsible. | Status | Meaning | | - | - | | **Open** | The vulnerability needs investigation or remediation. | | **In progress** | A person or agent is working on it. | | **Remediated** | A fix has been deployed and is ready for verification. | | **Verified** | An agent has tested the original exploit and confirmed that it no longer succeeds. | | **Accepted risk** | Your team has decided not to remediate the vulnerability. | A vulnerability does not have to pass through every status. For example, your team may accept the risk, or verification may return an unresolved vulnerability to **Open**. ## Use hooks to start work A [hook](/docs/vulnerability-lifecycle/hooks) responds when a vulnerability’s status or assignment changes. It can launch an agent, notify your team, or start another workflow. Antigen comes with hooks configured for triage, remediation, and verification. These connect the work automatically while your team reviews proposed changes and handles tasks that need human input. ## How the default setup works 1. **A new vulnerability starts triage.** When a vulnerability enters **Open**, a hook launches Antigen’s pre-built **triage-agent**. It investigates the issue and determines whether it has enough information and access for remediation to proceed. 2. **Assignment starts remediation.** If triage can proceed, it moves the vulnerability to **In progress** and assigns it to Antigen’s pre-built **remediation-agent**. That assignment triggers a run to prepare remediation steps, such as a GitHub pull request or a proposed cloud configuration change. If triage needs help, it asks your team. 3. **Your team reviews and deploys the changes.** Your team completes the proposed work through its usual tools. Once the fix is deployed, the vulnerability moves to **Remediated**. 4. **Verification tests the fix.** Moving to **Remediated** triggers tCell to test the original exploit again. If it no longer succeeds, the vulnerability moves to **Verified**. If it still succeeds, the vulnerability returns to **Open** with new evidence, starting triage again. See [How triage works](/docs/vulnerability-lifecycle/how-triage-works) and [How remediation works](/docs/vulnerability-lifecycle/how-remediation-works) for details. ## Connect your own agents and workflows The default setup uses the same hooks available to your team. You can add a notification, replace an agent, or send work to an agent environment you already use. For example, you could send critical vulnerabilities to Slack or assign remediation to Cursor Cloud, Devin, or an agent assembled with the Antigen SDK. See [Assigning to your own agents](/docs/vulnerability-lifecycle/assigning-to-your-own-agents) for how to customize this behavior.