Evidence

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

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:

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

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:

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 for reading the issue’s description, checking its status, and assigning work.

Getting started

Asset Map

Runs

Vulnerability Lifecycle

Team Workflows

SDK

CLI

Integrations

List evidence for a vulnerability

Parameters

List evidence from a run

Download a file

Parameters

Read a text file

Evidence fields

Access

​List evidence for a vulnerability

​Parameters

​List evidence from a run

​Download a file

​Parameters

​Read a text file

​Evidence fields

​Access

List evidence for a vulnerability

Parameters

List evidence from a run

Download a file

Parameters

Read a text file

Evidence fields

Access