Skip to content
Tutorial

Tutorial: Run the Receive-Report Demo

In this tutorial, we will run the Vultron receive-report demo end-to-end using Docker Compose. By the end of this tutorial, we will have:

  • started a local Vultron API server,
  • run three vulnerability-report workflows, and
  • observed how a vendor accepts, invalidates, and closes reports in the Vultron protocol.

What we will learn

This tutorial focuses on the receive-report workflow: a reporter submits a vulnerability report to a vendor, and the vendor decides what to do with it. We will run all three outcomes — accept (validate), hold (invalidate), and reject-and-close — and read the structured log output to understand what happened at each step. The vendor's decision is a move in the Report Management (RM) state machine, and each move has a formal message name and an ActivityStreams wire form. The demo log prints the wire form; this page names both.


Prerequisites

We need the following tools installed before we begin:

  • Docker (version 20.10 or later)
  • Docker Compose (version 2.x; included with Docker Desktop)
  • Git (to clone the repository)

We do not need Python installed locally; the containers include everything required.


Step 1 — Clone the repository

First, let's get a local copy of the Vultron project:

git clone https://github.com/CERTCC/Vultron.git
cd Vultron

Tip

If you already have a local clone, cd into the repository root and run git pull to make sure you are up to date.


Step 2 — Start the demo container

The demo container depends on the api-dev container. Docker Compose starts both automatically and waits until the API server is healthy before launching the demo shell.

docker compose -f docker/docker-compose.yml run --rm demo

After the images are built (this takes a few minutes the first time), we should see a shell prompt inside the container:

root@<container-id>:/app#

Notice that both the api-dev and demo containers are now running. The api-dev container exposes the Vultron API at http://localhost:7999/api/v2.

The api-dev container also hosts the Case Actor Service, the endpoint that opens a case for each report the vendor receives. The server finds that service through the VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL variable, and the Compose file sets it to http://localhost:7999/api/v2 for us.

Running the server without Docker

To run the API server directly instead, we set the same variable when we start it:

VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL=http://localhost:7999/api/v2 \
  uv run uvicorn vultron.adapters.driving.fastapi.main:app --host localhost --port 7999

If the variable is not set, the server cannot ask for a case for a report. No case is opened, and every demo fails. The vultron-demo command needs the same variable, and it stops with an error that names the variable when it is unset. The Compose file sets it in the demo container too.

The Node Configuration Reference lists every other setting the server reads, and the config.yaml file that can carry them instead of environment variables.


Step 3 — Run the receive-report demo

Inside the container shell, run:

vultron-demo receive-report

The demo runs three separate workflows in sequence. Each step begins with a 🚥 marker and ends with either 🟢 (success) or 🔴 (failure). Verification checks are marked with 📋 (start) and ✅ (pass) or ❌ (fail).

Each workflow ends with its own completion line, for example:

✅ DEMO 1 COMPLETE: Report validated, case created, and introduced to the reporter.

If any step or check failed, the demo prints a failure summary after the last workflow, reports FAIL, and exits with a non-zero status.


Step 4 — Read the output

Let's look at what happened in each workflow.

Demo 1: Validate Report

DEMO 1: Validate Report and Create Case
  1. Step 1 — The reporter actor submits a VulnerabilityReport through its own submit-report trigger, which sends a Report Submission (RS), Offer(VulnerabilityReport), to the vendor. The trigger also records which actor the reporter sent the report to, so the reporter can later check who introduces the case. Notice the log lines showing that the offer and the report are both stored in the vendor's DataLayer. When the vendor receives the report, it asks its CaseActor to open a case for it.

  2. Step 2 — The vendor calls its own validate-report trigger, which sends a Report Valid (RV), Accept(Offer(VulnerabilityReport)), to the CaseActor that manages the case. The CaseActor records the vendor at RM.VALID, and the case ledger carries that record to the reporter's copy of the case. Notice the ✅ confirming that the reporter's copy records the vendor at VALID.

  3. Step 3 — The vendor finds the case that was opened for the report, and introduces it to the reporter with its own Create Case, Create(VulnerabilityCase). The reporter accepts the introduction because it comes from the actor the reporter sent the report to. Notice the final ✅ confirming that the reporter's record of the report now names the vendor and points at the case.

---
title: Demo 1 — validate the report
---
sequenceDiagram
    participant R as Reporter
    participant V as Vendor
    participant CA as CaseActor

    R->>V: Report Submission (RS)<br/>Offer(VulnerabilityReport)
    Note over V,CA: Stores offer and report<br/>case opened
    V->>R: Create Case<br/>Create(VulnerabilityCase)
    V->>CA: Report Valid (RV)<br/>Accept(Offer(VulnerabilityReport))
    Note over CA: Records the vendor at RM.VALID
    CA-->>R: Case ledger entry

Demo 2: Invalidate Report

DEMO 2: Invalidate Report (Hold for Reconsideration)

The reporter submits a second, separate report. The vendor calls its invalidate-report trigger, which sends a Report Invalid (RI), TentativeReject(Offer(VulnerabilityReport)), to the CaseActor. A Report Invalid means the report is held open for further investigation rather than closed outright. The CaseActor records the vendor at RM.INVALID, and the reporter learns the decision from its copy of the case. The vendor still opened a case when the report arrived, so the demo ends by checking that the reporter accepted the vendor's introduction of it.

---
title: Demo 2 — hold the report as invalid
---
sequenceDiagram
    participant R as Reporter
    participant V as Vendor
    participant CA as CaseActor

    R->>V: Report Submission (RS)<br/>Offer(VulnerabilityReport)
    Note over V,CA: case opened on receipt
    V->>CA: Report Invalid (RI)<br/>TentativeReject(Offer(VulnerabilityReport))
    Note over CA: Records the vendor at RM.INVALID
    CA-->>R: Case ledger entry

Demo 3: Invalidate and Close Report

A third report is submitted. The vendor first invalidates it with a Report Invalid (RI), and then closes the case it opened for the report. Once a case holds a report, its Case Owner closes the case with Leave(VulnerabilityCase), never with a Report Closed (RC), Reject(Offer(VulnerabilityReport)), which the CASE_MANAGER refuses from every sender. The case has an active embargo, and the Case Owner cannot leave while it is active, so the vendor ends the embargo first with its terminate-embargo trigger. The reporter then leaves the case, and the vendor leaves last, each through its own leave-case trigger. Notice the ✅ lines confirming that the CaseActor records every participant at RM.CLOSED, and that the reporter again accepted the vendor's introduction of the case.

---
title: Demo 3 — invalidate the report and close its case
---
sequenceDiagram
    participant R as Reporter
    participant V as Vendor
    participant CA as CaseActor

    R->>V: Report Submission (RS)<br/>Offer(VulnerabilityReport)
    V->>CA: Report Invalid (RI)<br/>TentativeReject(Offer(VulnerabilityReport))
    V->>CA: Embargo ended
    R->>CA: Leave(VulnerabilityCase)
    V->>CA: Close Case<br/>Leave(VulnerabilityCase)
    Note over CA: Every participant at RM.CLOSED

Step 5 — Exit the container

When we are finished, type exit to leave the container shell:

exit

The --rm flag we passed in Step 2 ensures the container is removed automatically on exit. The api-dev container will continue running; stop it with:

docker compose -f docker/docker-compose.yml down

What we accomplished

We have:

  • started the Vultron API server and demo container with a single docker compose run command,
  • run three vulnerability-report workflows covering the three main outcomes defined in the Report Management (RM) state machine, and
  • read structured log output showing each step and verification check.

Next steps

  • Run more demos — see Tutorial: Running the Other Demos to explore case initialization, embargo management, actor invitation, and more.
  • Understand the protocol — read How to Report a Vulnerability for a detailed walkthrough of the activities we observed.
  • Explore the demo scripts — the source for this demo is in vultron/demo/exchange/receive_report_demo.py; the shared utilities are in vultron/demo/utils/.
  • See the formal names — Report Management (RM) Messages maps each RM message to its ActivityStreams wire form.
  • Run all demos at once — inside the demo container, run vultron-demo all to execute every demo in sequence.

Reading path: You want to work on the Vultron reference implementation

This page is part of Run it.

Path overview

Reading path: You handle vulnerability reports and coordinate cases with other organizations

This page is part of Watch a case run.

Path overview