Skip to content
Tutorial

Tutorial: Submit a report to a Vultron actor

The reference implementation is the test bench

This tutorial teaches how the protocol behaves. It runs CERT/CC's reference implementation only as a convenient set of actors to exchange messages with. What it shows holds for any implementation that conforms to the Vultron Protocol Specification.

In this tutorial, we will submit a vulnerability report to a running Vultron actor and confirm that the actor received it. We will start the reference implementation, create one actor to play the part of a vendor and one to play the part of a finder, have the finder send the vendor a signed Create(VulnerabilityReport) message, and read the report back out of the vendor's store. This tutorial is for a developer who wants to see, first-hand, what it takes to speak to a Vultron actor over the wire.

What we will learn

Vultron actors exchange ActivityStreams messages over HTTP. We will construct one such message, have the sending actor's Outbox sign it and deliver it to the receiving actor's Inbox, and watch the report land in the receiving actor's store. We will not cover the full report-management lifecycle here; the How to Report a Vulnerability how-to guide takes the story further.

The commands and the message on this page are rendered from vultron.wire.as2.vocab.examples.submit_report_tutorial, the same module a test drives end-to-end, so what you copy here is what the code actually does.


Prerequisites

You need the following before we begin:

  • uv (the project's Python runner; it manages its own virtual environment)
  • curl (to send HTTP requests from a second terminal)
  • Git (to clone the repository)

You do not need to install Python or any dependencies by hand; uv run resolves them on first use.


Step 1 — Clone the repository

First, 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 so you are up to date.


Step 2 — Start the Vultron API server

From the repository root, start the reference API server:

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

The first run downloads dependencies, so it may take a moment. When the server is ready, you should see:

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:7999 (Press CTRL+C to quit)

Leave this terminal running. The server now serves the Vultron API at http://localhost:7999/api/v2.

Open a second terminal and confirm the server is live:

curl http://localhost:7999/api/v2/health/live

The server responds with:

{"status":"ok"}

Prefer containers?

You can also start the same API server with Docker Compose by running docker compose -f docker/docker-compose.yml up api-dev, which exposes the API at the same http://localhost:7999/api/v2 address. The remaining steps are identical. See Run the Receive-Report Demo for the container-based tour.


Step 3 — Create the vendor and the finder

A report has to be sent to someone, so we first create an actor to play the part of a vendor. Run this in the second terminal:

curl -i -X POST http://localhost:7999/api/v2/actors/ \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "VendorCo",
  "actor_type": "Organization",
  "id": "vendorco"
}'

The server responds with 201 Created and the new actor record:

{"@context":["https://www.w3.org/ns/activitystreams","https://certcc.github.io/Vultron/ns/context.jsonld"],"id":"http://localhost:7999/api/v2/actors/vendorco","type":"Organization","name":"VendorCo","published":"2026-01-01T00:00:00.000000+00:00","updated":"2026-01-01T00:00:00.000000+00:00","inbox":"http://localhost:7999/api/v2/actors/vendorco/inbox","outbox":"http://localhost:7999/api/v2/actors/vendorco/outbox"}

Your published and updated timestamps will differ; everything else matches. Notice that the actor's id is the URL that reaches it. Its Inbox, the endpoint where it receives messages, is that same URL with /inbox/ appended.

A report also has to come from someone. Every message a Vultron actor receives must carry a proof: a signature made with its sender's key. The receiver reads the sender's public key from the sender's actor profile, so the sender has to be an actor that a server hosts. Create a second actor to play the part of the finder who reports the vulnerability:

curl -i -X POST http://localhost:7999/api/v2/actors/ \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Finn",
  "actor_type": "Person",
  "id": "finn"
}'

The server again responds with 201 Created and the actor record, this time for a Person named Finn. Finn's actor profile, with the public key that verifies Finn's messages, is at http://localhost:7999/api/v2/actors/finn/profile.


Step 4 — Submit the report

Now Finn sends the vendor a Create(VulnerabilityReport) message. This is an ActivityStreams Vocabulary 2.0 (AS2) activity: a Create activity whose object is the VulnerabilityReport we are reporting. The actor field names Finn as the sender, and the to field addresses the message to our vendor by its id, the URL from Step 3:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://certcc.github.io/Vultron/ns/context.jsonld"
  ],
  "type": "Create",
  "id": "urn:uuid:11111111-1111-1111-1111-111111111111",
  "name": "http://localhost:7999/api/v2/actors/finn Create FDR-0001",
  "to": [
    "http://localhost:7999/api/v2/actors/vendorco"
  ],
  "actor": "http://localhost:7999/api/v2/actors/finn",
  "object": {
    "id": "urn:uuid:22222222-2222-2222-2222-222222222222",
    "type": "VulnerabilityReport",
    "name": "FDR-0001",
    "published": "2026-01-01T00:00:00.000000+00:00",
    "updated": "2026-01-01T00:00:00.000000+00:00",
    "content": "I found a vulnerability!",
    "attributedTo": "http://localhost:7999/api/v2/actors/finn"
  },
  "published": "2026-01-01T00:00:00.000000+00:00"
}

The message carries no proof yet. We do not sign it ourselves, and we do not post it to the vendor's Inbox directly: the vendor would refuse an unsigned message with 422 Unprocessable Content. Instead, we hand the message to Finn's Outbox, the endpoint where an actor sends messages:

curl -i -X POST http://localhost:7999/api/v2/actors/finn/outbox/ \
  -H 'Content-Type: application/json' \
  -d '{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://certcc.github.io/Vultron/ns/context.jsonld"
  ],
  "type": "Create",
  "id": "urn:uuid:11111111-1111-1111-1111-111111111111",
  "name": "http://localhost:7999/api/v2/actors/finn Create FDR-0001",
  "to": [
    "http://localhost:7999/api/v2/actors/vendorco"
  ],
  "actor": "http://localhost:7999/api/v2/actors/finn",
  "object": {
    "id": "urn:uuid:22222222-2222-2222-2222-222222222222",
    "type": "VulnerabilityReport",
    "name": "FDR-0001",
    "published": "2026-01-01T00:00:00.000000+00:00",
    "updated": "2026-01-01T00:00:00.000000+00:00",
    "content": "I found a vulnerability!",
    "attributedTo": "http://localhost:7999/api/v2/actors/finn"
  },
  "published": "2026-01-01T00:00:00.000000+00:00"
}'

The server responds with 200 OK:

HTTP/1.1 200 OK

Finn's Outbox checks that the message's actor is Finn, signs the message with Finn's key, and delivers it to the vendor's Inbox in the background. The vendor's Inbox fetches Finn's actor profile, reads Finn's public key from it, and verifies the proof before it accepts the message. The Inbox answers the delivery with 202 Accepted, and the vendor processes the report.

Switch to the terminal running the server. You should see the delivery, the key lookup and the vendor processing the report:

INFO:     Processing outbox item for actor 'http://localhost:7999/api/v2/actors/finn': urn:uuid:11111111-1111-1111-1111-111111111111
INFO:     Fetched 'http://localhost:7999/api/v2/actors/finn' from http://localhost:7999/api/v2/actors/finn/profile for actor_id=http://localhost:7999/api/v2/actors/vendorco (attempt 1)
INFO:     Resolved key http://localhost:7999/api/v2/actors/finn#main-key from the fetched profile of http://localhost:7999/api/v2/actors/finn for actor_id=http://localhost:7999/api/v2/actors/vendorco
INFO:     Delivered activity urn:uuid:11111111-1111-1111-1111-111111111111 to http://localhost:7999/api/v2/actors/vendorco/inbox/ (HTTP 202)
INFO:     Dispatching activity of type 'VulnerabilityReport' with semantics 'create_report'
INFO:     Dispatch: dispatched create_report activity_id=urn:uuid:11111111-1111-1111-1111-111111111111 disposition=applied

The following diagram shows the exchange we just completed: we hand the report to Finn's Outbox, Finn's Outbox signs it and delivers it to the vendor's Inbox, and the vendor verifies it by Finn's published key.

---
title: Submitting a signed report to a Vultron actor
---
sequenceDiagram
    autonumber
    actor reader as Reader (curl)
    participant outbox as Finn's Outbox
    participant inbox as Vendor Inbox
    participant profile as Finn's Profile
    reader->>outbox: POST /actors/finn/outbox/<br/>Create(VulnerabilityReport)
    outbox-->>reader: 200 OK
    Note over outbox: signs as Finn
    outbox->>inbox: POST /actors/vendorco/inbox/<br/>signed Create(VulnerabilityReport)
    inbox->>profile: GET /actors/finn/profile
    profile-->>inbox: Finn's public key
    Note over inbox: proof verified
    inbox-->>outbox: 202 Accepted
    Note over inbox: create_report runs<br/>report stored

Step 5 — Confirm the actor received the report

The vendor's 202 Accepted went to Finn's Outbox, not to us. Let's confirm the vendor verified and stored the report by reading its store back:

curl http://localhost:7999/api/v2/actors/vendorco/datalayer/Reports/

The vendor returns the report we submitted, keyed by its id:

{
  "urn:uuid:22222222-2222-2222-2222-222222222222": {
    "id": "urn:uuid:22222222-2222-2222-2222-222222222222",
    "type": "VulnerabilityReport",
    "name": "FDR-0001",
    "published": "2026-01-01T00:00:00.000000+00:00",
    "updated": "2026-01-01T00:00:00.000000+00:00",
    "content": "I found a vulnerability!",
    "attributedTo": "http://localhost:7999/api/v2/actors/finn",
    "@context": [
      "https://www.w3.org/ns/activitystreams",
      "https://certcc.github.io/Vultron/ns/context.jsonld"
    ]
  }
}

The report, with our content of "I found a vulnerability!", is now in the vendor's store. The vendor received our report.


Step 6 — Stop the server

When you are finished, return to the first terminal and press Ctrl+C to stop the server.


What we accomplished

We have:

  • started the Vultron reference implementation with a single uv run command,
  • created an actor to receive a report and an actor to send it,
  • constructed a Create(VulnerabilityReport) AS2 message and handed it to the sender's Outbox, which signed it and delivered it to the receiver's Inbox, and
  • confirmed, by reading the receiver's store, that the report was verified and received.

Next steps

  • Go deeper on report submission — read How to Report a Vulnerability to see how a report is validated, accepted, and turned into a Case, and how the Offer(VulnerabilityReport) activity fits alongside Create(VulnerabilityReport).
  • Decide whether to submit at all — read How to Decide Who Owns a Case to choose between submitting a report, creating the case yourself, and transferring ownership of a case you already run.
  • See the full workflow run for you — follow Run the Receive-Report Demo to watch a finder and a vendor exchange reports end-to-end with the demo CLI.
  • Read the source of these examples — the commands and the message above come from vultron/wire/as2/vocab/examples/submit_report_tutorial.py, and the flow is verified end-to-end in test/demo/test_submit_report_tutorial.py.

Reading path: You maintain a vulnerability tracker and want it to talk to your partners

This page is part of Send your first message.

Path overview