Concepts
Pipeline
What happens to a sample from upload to report: routing, the triage pack, the analysis stages, the debate, the verdict and the report.
A run is one team working on one sample. The team is a list of stages, and the pipeline runs them in order. Code does the deterministic work; agents make every decision.
1. Upload and routing
The API stores the sample in the object store and its metadata in Postgres. Submitting a job queues it for the worker.
The worker reads the sample's magic bytes into a file type and a platform. Everything after that routes on this answer: the sandbox package, the rules that apply, the tools an analyst gets and the ATT&CK domain. No sample is refused for its format. A format nothing recognises takes a neutral path, and the report says so.
When a sandbox is configured, the sample is submitted to it at the start, and its report feeds the stages below.
2. The triage pack
Before any agent starts, the pipeline runs a fixed list of tools itself. A human analyst runs the same commands on every sample before opening a disassembler; the pack makes sure those facts are always there.
Each result is an ordinary ledger entry under the agent pipeline. In the
benchmark run, the pack wrote the first 28 entries:
| Entries | Tools |
|---|---|
ev_0001–ev_0006 | identify_file, hashes, signing_info, pe_info, strings, iocs_from_file |
ev_0007–ev_0011 | yara_scan, capa, sigma_match_sandbox, api_capability, lolbin_lookup |
ev_0012–ev_0017 | sandbox_processes, sandbox_network, sandbox_signatures, sandbox_dropped_files, sandbox_channels, pcap_summary |
ev_0018 | get_file_report, through VirusTotal's own MCP server |
ev_0019–ev_0028 | floss, resolve_api_hashes, decode_string_blobs, api_capability, find_crypto_constants, anti_analysis_scan, function_index, sandbox_sections, find_directed_text, behaviour_code_links |
The pack is a list of steps declared as data. You can add your own steps, and a step can call any tool server's tool. See The pack's steps.
3. The analysis stages
Each analysis stage runs the agents it names. An agent gets its prompt, the
pack's facts, the findings of the stages it depends on, and its tools. It then
works in a loop: call a tool, read the answer, decide the next call. It stops
when it has an answer, and files it as claims. Each claim carries a
confidence and the ev_ ids it rests on.
A stage can carry a condition. The default team runs its dynamic analyst in
its one analysis stage, with no condition. The mobile team gates its dynamic
stage on a sandbox report (when: has_sandbox_report), and its Android stage
on an APK or DEX file (when: file_type in ("apk", "dex")). A stage that does not run says which
condition failed.
On a hosted API the analysts of a stage run in parallel. On a single-slot local
server they run one after another, so they do not fight over the slot. The
default, auto, picks per job.
See Agents and teams for how stages are written.
4. The debate
The mediator reads every analyst's claims and lists each contradiction still standing. The analysts it names revise, with the disputed ledger entries in front of them. The loop ends when nothing blocking is left, when a round changes nothing, or at the round limit. See Debate and judge.
5. The verdict
The judge reads the debate and the evidence and states the verdict, its confidence, the severity, the category and the family. Each ATT&CK technique it publishes is checked against the catalogue and the claims behind it; a technique without support is dropped, and the report says why. The judge's answer becomes the STIX 2.1 bundle.
6. The report
The reporter writes the report section by section from the claims in force, the verdict and the ledger. Every section names the entries it rests on. Code checks the sections against each other and against the ledger before the report is stored. See Report.
When the run is stored, the ledger is sealed with a hash chain, so a later change to an entry or to the report shows.
Where to read more
The Architecture reference describes each step in full: the job lifecycle, the worker processes, every validation loop and every event the pipeline publishes.