Vulnerabilities

Use the SDK to retrieve 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:

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:

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

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

await antigen.vulnerabilities.updateAssignee(
  "vuln_abc123",
  "alex@example.com",
);

To use the pre-built remediation-agent, pass its SDK constant:

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:

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 for registration and webhook setup.

Remove an assignment

Pass null to leave the vulnerability unassigned:

await antigen.vulnerabilities.updateAssignee(
  "vuln_abc123",
  null,
);

Update status

Use antigen.vulnerabilities.updateStatus() as work progresses:

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:

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:

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 for following progress and retrieving results.

Status and assignment hooks

Changes made through the SDK trigger the same 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.

Getting started

Asset Map

Runs

Vulnerability Lifecycle

Team Workflows

SDK

CLI

Integrations

List vulnerabilities

Vulnerabilities from a run

Read a vulnerability

Assign work

Assign a custom agent

Remove an assignment

Update status

Request verification

Work on a vulnerability in a run

Status and assignment hooks

​List vulnerabilities

​Vulnerabilities from a run

​Read a vulnerability

​Assign work

​Assign a custom agent

​Remove an assignment

​Update status

​Request verification

​Work on a vulnerability in a run

​Status and assignment hooks

List vulnerabilities

Vulnerabilities from a run

Read a vulnerability

Assign work

Assign a custom agent

Remove an assignment

Update status

Request verification

Work on a vulnerability in a run

Status and assignment hooks