Skip to content

Demo Scripts

Individual protocol-fragment exchange demo scripts in vultron.demo.exchange. Each script can be run standalone via python -m vultron.demo.exchange.<script> or through the unified CLI (vultron-demo <sub-command>).

receive-report

vultron.demo.exchange.receive_report_demo

Demonstrates the workflow for receiving and processing vulnerability reports via the Vultron API.

This demo script showcases three different outcomes when processing vulnerability reports: 1. Validate Report: as_Accept - creates a case 2. Invalidate Report: as_TentativeReject - holds for reconsideration 3. Invalidate and Close: as_TentativeReject + as_Leave - invalidates the report and closes the case opened for it

The reporter submits each report through its own submit-report trigger, so the reporter holds the anchor it checks the vendor's case introduction against (CBT-01-005). The vendor answers through its own validate-report, invalidate-report, terminate-embargo and leave-case triggers, whose outbox sends each answer to the CASE_MANAGER of the case opened on receipt; the demo posts nothing into an inbox by hand (#5438).

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run three separate demo workflows, each with a unique report: - demo_validate_report: Submit → Validate → Case introduced to the reporter - demo_invalidate_report: Submit → Invalidate → Reporter's replica records it - demo_invalidate_and_close_report: Submit → Invalidate → End the embargo → Reporter leaves, then the vendor (Case Owner) closes the case 5. Verify side effects in the data layer and the reporter's replica of the case

Note on Behavior Tree Execution: The validate_report handler uses py_trees behavior tree execution to orchestrate the validation workflow. BT execution logging is available server-side: - INFO level: BT execution start, completion status, and feedback - DEBUG level: Detailed tree structure visualization and execution state

To see BT execution details, run the API server with DEBUG logging enabled: VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL=http://localhost:7999/api/v2 LOG_LEVEL=DEBUG uv run uvicorn vultron.adapters.driving.fastapi.main:app --host localhost --port 7999

The server needs VULTRON_ACTOR__CASE_ACTOR_SERVICE_URL: the vendor proposes the case for each report to that CaseActor service, and with it unset the proposal fails and no case is opened (CP-08-001, CP-08-005).

The BT logs will show tree structure before execution and final state after completion.

demo_invalidate_and_close_report(client, reporter, vendor, coordinator=None)

Demonstrates the workflow where a vendor invalidates a report and closes it.

Uses VultronActivity (TentativeReject) followed by a Leave(VulnerabilityCase): the vendor opened a case for the report on receipt, and once a case holds the report its owner closes the case by Leave, never by Reject(Offer(VulnerabilityReport)) (CM-23-019). The Case Owner first ends the case's embargo, which blocks its Leave (TRIG-13-003), and leaves after the reporter (CM-23-015). Each act goes through the actor's own trigger to the case's CASE_MANAGER.

This follows the "Receiver Invalidates and Closes Offered Report" sequence diagram from docs/howto/activitypub/activities/report_vulnerability.md.

demo_invalidate_report(client, reporter, vendor, coordinator=None)

Demonstrates the workflow where a vendor invalidates a report.

The vendor's invalidate-report trigger sends the TentativeReject to the CASE_MANAGER of the case opened on receipt, and the reporter learns of it from its replica of that case.

This follows the "Receiver Invalidates and Holds Offered Report" sequence diagram from docs/howto/activitypub/activities/report_vulnerability.md.

demo_validate_report(client, reporter, vendor, coordinator=None)

Demonstrates the workflow where a vendor validates a report and creates a case.

Uses VultronActivity (Accept) activity. The vendor's own Create(VulnerabilityCase) then introduces the case to the reporter (CBT-01-001), and the demo checks the reporter took it on the trusted route.

This follows the "Receiver Accepts Offered Report" sequence diagram from docs/howto/activitypub/activities/report_vulnerability.md.

find_case_by_report(client, report_id)

Find the as_VulnerabilityCase that references report_id.

Public name kept for backward compatibility — imported by test/demo/test_find_case_by_report.py.

Parameters:

Name Type Description Default
client DataLayerClient

DataLayerClient instance

required
report_id str

Full URI of the vulnerability report

required

Returns:

Type Description
as_VulnerabilityCase | None

The matching case, or None if not found.

main(skip_health_check=False, demos=None)

Main entry point for the receive_report demo script.

initialize-case

vultron.demo.exchange.initialize_case_demo

Demonstrates the workflow for initializing a vulnerability case via the Vultron API.

This demo script showcases the case initialization process:

  1. Setup: submit a vulnerability report (precondition for case creation)
  2. Create Case: vendor explicitly creates a as_VulnerabilityCase
  3. Add Vendor as Participant: vendor adds themselves as case creator/owner
  4. Add Report to Case: vendor links the submitted report to the case
  5. Invite the Reporter: vendor sends the reporter the stub Invite
  6. Reporter Joins: the reporter accepts, and the vendor, as CASE_MANAGER, seats it (ADR-0114; Add(CaseParticipant) only reinstates, CM-31-011)
  7. Show final case state

This corresponds to the workflow documented in

docs/howto/activitypub/activities/initialize_case.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run the initialize_case demo workflow 5. Verify side effects in the data layer

Note on direct inbox communication: This demo uses direct inbox-to-inbox communication between actors, per the Vultron prototype design. Actors post activities directly to each other's inboxes.

demo_initialize_case(client, reporter, vendor, coordinator=None)

Demonstrates the full case initialization workflow.

Steps: 1. Reporter submits a vulnerability report to vendor inbox 2. Vendor validates the report through its validate-report trigger 3. Vendor creates the case through the create-case trigger 4. The trigger registers the vendor as CASE_OWNER and CASE_MANAGER 5. Vendor adds the report to the case (AddReportToCaseActivity) 6. Vendor asks the CASE_MANAGER (itself) to invite the reporter, which sends the stub Invite 7. Reporter accepts (RmAcceptInviteToCaseActivity), which seats it as a REPORTER participant (ADR-0114, ADR-0078) 8. Final case state is logged

This follows the workflow in docs/howto/activitypub/activities/initialize_case.md. The case creator (vendor) must be added as a participant before any other participants, as they need to be a case participant to act on the case. The vendor is also the case owner, indicated by attributed_to on the case.

main(skip_health_check=False, demos=None)

Main entry point for the initialize case demo demo script.

initialize-participant

vultron.demo.exchange.initialize_participant_demo

Demonstrates the workflow for initializing a CaseParticipant via the Vultron API.

This demo script showcases the participant initialization process:

  1. Setup: Submit and validate a vulnerability report; the report-validation BT triggers ProposeReportCaseToActorNode, which causes the CaseActor to create the canonical VulnerabilityCase with vendor (CASE_OWNER), reporter, and CaseActor (CASE_MANAGER) as initial participants.
  2. Invite the Coordinator: the vendor, as Case Owner, asks the CaseActor to invite the coordinator, and the CaseActor sends the stub Invite
  3. Coordinator Joins: the coordinator accepts, the CaseActor creates its CoordinatorParticipant, and the vendor's replica stores the record from the ledger entries the CaseActor commits for it

A participant is only ever initialized this way (ADR-0114): Add(CaseParticipant) is the Case Owner's request to reinstate a removed participant, not a way to seat a new one (CM-31-011, ADR-0116). Compare with invite_actor_demo.py, which drives the same join through the triggers.

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run the initialize_participant demo workflow 5. Verify side effects in the data layer

demo_initialize_participant(client, reporter, vendor, coordinator)

Demonstrate the standalone CaseParticipant initialization workflow.

Precondition: A canonical VulnerabilityCase exists with vendor (CASE_OWNER), reporter, and the CaseActor (CASE_MANAGER) as initial participants. This is set up automatically by the report validation → ProposeReportCaseToActorNode → CaseActor flow (ADR-0041).

Steps: 1. Show initial case participant list 2. The vendor asks the CaseActor to invite the coordinator, and the coordinator accepts; the CaseActor creates its participant record 3. Verify the vendor's replica holds the coordinator from the ledger entries alone (CM-31-012) 4. Verify final participant count

This follows the workflow in

docs/howto/activitypub/activities/initialize_participant.md

main(skip_health_check=False, demos=None)

Main entry point for the initialize participant demo demo script.

setup_case_precondition(client, reporter, vendor)

Set up the precondition for the demo.

Thin wrapper over :func:~vultron.demo.helpers.workflow.setup_canonical_case, which drives the report → validate → Create(CaseProposal) → CaseActor path so the resulting case has vendor (CASE_OWNER), reporter, and the CaseActor (CASE_MANAGER) as initial participants (ADR-0041, CP-01-004).

Returns:

Type Description
as_VulnerabilityCase

The canonical VulnerabilityCase created by the CaseActor.

invite-actor

vultron.demo.exchange.invite_actor_demo

Demonstrates the workflow for inviting an actor to a case via the Vultron API.

This demo script showcases two invitation paths:

  1. Accept path: case owner invites coordinator → coordinator accepts → coordinator becomes a case participant
  2. Reject path: case owner invites coordinator → coordinator rejects → coordinator is not added to the case

Each demo starts from an initialized case (report submitted and validated, case created, reporter participant added) so that the invitation workflow can be demonstrated in isolation.

This corresponds to the workflow documented in

docs/howto/activitypub/activities/invite_actor.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run both demo workflows (accept and reject) 5. Verify side effects in the data layer

Note on puppeteering: The vendor asks the CASE_MANAGER to invite the coordinator by trigger, and the coordinator answers the Invite the CASE_MANAGER sent and recorded by trigger. A reply to an Invite the CASE_MANAGER has no record of is refused (CM-11-017), so the demo does not build the Invite or the reply itself.

demo_invite_actor_accept(client, reporter, vendor, coordinator)

Demonstrates the accept path of the invite-actor-to-case workflow.

Steps: 1. Setup: initialize case (report submitted + validated, case created, reporter participant added) 2. Vendor fires the invite-actor-to-case trigger; the CASE_MANAGER invites the coordinator 3. Coordinator fires the accept-case-invite trigger 4. The CASE_MANAGER follows the join with the full-case Invite, and the coordinator replies to it (RM VALID) 5. Verify coordinator appears in case participant list

This follows the accept branch in docs/howto/activitypub/activities/invite_actor.md.

demo_invite_actor_reject(client, reporter, vendor, coordinator)

Reject path of the invite-actor-to-case workflow.

ADR-0114 / CM-11-006: the invite-actor-to-case trigger is called first so that CreateInertInviteeParticipantNode records an inert CaseParticipant for coordinator at invite-send time. Coordinator then rejects the Invite the CASE_MANAGER recorded. After the Reject, ApplyInviteRejectToParticipantNode closes the inert record at RM CLOSED (CM-11-007) — coordinator is present in actor_participant_index but never active (DEMOMA-27-008).

Steps: 1. Setup: initialize case (report submitted + validated, case created, reporter participant added) 2. Vendor fires invite-actor-to-case trigger (creates inert participant, CM-11-006) and delivers the invite 3. Coordinator fires the reject-case-invite trigger 4. Verify coordinator is in actor_participant_index at RM.CLOSED (never active)

This follows the reject branch in docs/howto/activitypub/activities/invite_actor.md.

main(skip_health_check=False, demos=None)

Main entry point for the invite_actor demo script.

establish-embargo

vultron.demo.exchange.establish_embargo_demo

Demonstrates the workflow for establishing an embargo via the Vultron API.

This demo script showcases two embargo paths:

  1. Accept path: participant proposes embargo → case owner accepts → embargo is activated on the case (EM state = ACTIVE)
  2. Reject path: participant proposes embargo → case owner rejects → embargo is not activated (EM state unchanged)

Each demo starts from an initialized case with two participants so the embargo negotiation workflow can be demonstrated in isolation.

This corresponds to the workflow documented in

docs/howto/activitypub/activities/establish_embargo.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run both demo workflows (propose-accept and propose-reject) 5. Verify side effects in the data layer

Note on direct inbox communication: This demo uses direct inbox-to-inbox communication between actors, per the Vultron prototype design. Actors post activities directly to each other's inboxes.

demo_propose_embargo_accept(client, reporter, vendor, coordinator)

Demonstrates the accept path of the propose-embargo workflow.

Steps: 1. Setup: initialize case with two participants (vendor + coordinator) 2. Coordinator proposes embargo (EmProposeEmbargoActivity → vendor inbox) 3. Vendor, the case owner and CASE_MANAGER, activates the embargo: Add(EmbargoEvent)[target=VulnerabilityCase] → vendor inbox (ADR-0180) 4. Vendor announces embargo to all participants 5. Verify case has ACTIVE embargo

This follows the accept branch in docs/howto/activitypub/activities/establish_embargo.md.

demo_propose_embargo_reject(client, reporter, vendor, coordinator)

Demonstrates the reject path of the propose-embargo workflow.

Steps: 1. Setup: initialize case with two participants (vendor + coordinator) 2. Coordinator proposes embargo (EmProposeEmbargoActivity → vendor inbox) 3. Vendor, the case owner and CASE_MANAGER, rejects the proposal: Reject(EmbargoEvent)[target=VulnerabilityCase] → vendor inbox (ADR-0122) 4. Verify case has no active embargo and no open proposal

This follows the reject branch in docs/howto/activitypub/activities/establish_embargo.md.

main(skip_health_check=False, demos=None)

Main entry point for the establish_embargo demo script.

report-with-embargo

vultron.demo.exchange.report_with_embargo_demo

Demonstrates the negotiated embargo path: the Reporter proposes embargo terms with the Report submission (EP-04-004, ADR-0096).

Every other demo reaches EM.ACTIVE by the default path: the Reporter submits without stating terms, which is tacit acceptance of the Receiver's published default (EP-04-001), so no embargo negotiation is visible at all. This demo is the one that exercises the other path — the Reporter carries a proposed EmbargoEvent on the Offer(VulnerabilityReport) — and readers should not mistake it for the default one. There is still no pre-case negotiation exchange to watch: ADR-0096 declined a pre-case protocol phase, so the Reporter states terms once, on the Offer, and the CASE_MANAGER settles the comparison when it creates the case (EP-04-003, shortest-wins). What is visible is the result — which terms became active and which were left pending as EM.REVISE. The CASE_MANAGER relays every creation-time revision to the party whose terms won (EP-04-027); no run shows an automatic answer, because the protocol requires none (EP-09-006).

Three runs:

  1. Reporter proposes shorter than the Receiver's actor default (10 vs 30 days): the Reporter's own terms become the active embargo, identity kept, and the Receiver's longer default is registered as a pending revision, so the case is created at EM.REVISE.
  2. Reporter proposes longer (60 vs 30 days): the Receiver's default is the active embargo at creation and the Reporter's terms — the same EmbargoEvent the Reporter sent, now about the case rather than the report (EP-04-009) — are the pending revision, relayed to the Receiver. The Receiver is the CASE_OWNER and the protocol requires no automatic answer to the relayed Invite (EP-09-006), so the Receiver's default stays active and the case stays at EM.REVISE until the owner acts. In run 1 the relay goes to the Reporter instead, whose acceptance only records consent, so that case also stays at EM.REVISE.
  3. Receiver has no actor default: the Reporter's terms are the only candidate and win outright at their stated length. The 10-day proposal is longer than the protocol default's 5-day ceiling (EP-04-018), so an active 10-day embargo shows the proposal was honored (EP-04-007) and the protocol default did not compete (EP-04-006).

Whose default is "the Receiver's". The actor default is the policy on the CASE_OWNER's own actor profile — the Receiver, the actor that received the report (EP-04-003, CP-09-001). Step 1 publishes it on the Receiver, which writes it into the Receiver's profile (EP-01-001); the Receiver then sends that profile inline as the actor of its Create(CaseProposal), and the CASE_MANAGER reads the default from there and nowhere else (CP-01-010).

Puppeteering. The Reporter is driven through its submit-report trigger (proposed_embargo_end_time), the Receiver through the embargo-policy endpoint; no protocol activity is forged. The Offer is then delivered to the Receiver's inbox in the way every exchange demo delivers (exchange/README).

This corresponds to the workflow documented in docs/howto/activitypub/activities/report_vulnerability.md § "Submit a report" and the semantics in notes/embargo-default-semantics.md.

demo_receiver_has_no_default(client, reporter, vendor, coordinator=None)

No actor default: the Reporter's terms win outright, at their length.

demo_reporter_proposes_longer(client, reporter, vendor, coordinator=None)

Receiver's default wins; the Reporter's longer terms stay pending.

demo_reporter_proposes_shorter(client, reporter, vendor, coordinator=None)

Reporter's shorter terms win; the Receiver's default is the revision.

main(skip_health_check=False, demos=None)

Main entry point for the report-with-embargo demo script.

acknowledge

vultron.demo.exchange.acknowledge_demo

Demonstrates the acknowledgement workflow for vulnerability reports via the Vultron API.

This demo script showcases the RmReadReportActivity (as:Read) acknowledgement mechanism:

  1. Acknowledge Only: submit → vendor sends ack (RmReadReportActivity) to reporter
  2. Acknowledge then Validate: submit → ack to reporter → validate → reporter's replica records it
  3. Acknowledge then Invalidate: submit → ack to reporter → invalidate → reporter's replica records it

The reporter submits through its submit-report trigger, so it holds the Offer and admits the ack only from the Offer's addressee, the vendor (RMB-08-004). The vendor sends the ack through its ack-report trigger, which addresses the reporter alone, never the CASE_MANAGER, case or no case (RMB-08-003, RMB-08-005). The vendor validates or invalidates through its own validate-report or invalidate-report trigger, which sends the answer to the CASE_MANAGER of the case opened on receipt (#5438).

The acknowledge workflow corresponds to

docs/howto/activitypub/activities/acknowledge.md

As described in that document, RmReadReportActivity acknowledges receipt without committing to an outcome. The receiver can subsequently validate or invalidate the report. Sending RmValidateReportActivity or RmInvalidateReportActivity already implies that the report was read, so a separate RmReadReportActivity is optional but demonstrates good protocol hygiene.

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run three separate demo workflows, each with a unique report: - demo_acknowledge_only: Submit → RmReadReportActivity to reporter - demo_acknowledge_then_validate: Submit → RmReadReportActivity → Validate - demo_acknowledge_then_invalidate: Submit → RmReadReportActivity → Invalidate 5. Verify the ack reached the reporter's inbox, and the reporter's replica of the case records each validate or invalidate

demo_acknowledge_only(client, reporter, vendor, coordinator=None)

Demonstrates a bare acknowledgement: the vendor reads the report without committing to validate or invalidate it.

Workflow

  1. Reporter submits report to vendor
  2. Vendor, the Offer's addressee, sends RmReadReportActivity (as:Read) to the reporter, and the demo verifies it reached the reporter's inbox

demo_acknowledge_then_invalidate(client, reporter, vendor, coordinator=None)

Demonstrates acknowledge followed by invalidation.

Workflow

  1. Reporter submits report to vendor
  2. Vendor sends RmReadReportActivity (as:Read) to the reporter
  3. Vendor invalidates through its invalidate-report trigger, which sends the Report Invalid (as:TentativeReject) to the case's CASE_MANAGER
  4. Verify the reporter's replica of the case records the invalidation

demo_acknowledge_then_validate(client, reporter, vendor, coordinator=None)

Demonstrates acknowledge followed by validation.

Workflow

  1. Reporter submits report to vendor
  2. Vendor sends RmReadReportActivity (as:Read) to the reporter
  3. Vendor validates through its validate-report trigger, which sends the Report Valid (as:Accept) to the case's CASE_MANAGER
  4. Verify the reporter's replica of the case records the validation

main(skip_health_check=False, demos=None)

Main entry point for the acknowledge demo script.

status-updates

vultron.demo.exchange.status_updates_demo

Demonstrates status updates and notes workflows via the Vultron API.

This demo script showcases the following workflows:

  1. Notes workflow: vendor adds a note, carried inline, to a case
  2. Status workflow: vendor reports public awareness in a new ParticipantStatus, carried inline, on its own participant record

A participant reports P, X or A only in the CaseStatus its own Add(ParticipantStatus) embeds; Add(CaseStatus) is the CASE_MANAGER's record of the status it adopted, and a receiver refuses it from anyone else (RSH-04-001, RSH-04-005).

Each demo starts from an initialized case with a single REPORTER participant, seated through its stub Invite, so the status update workflows can be demonstrated in isolation.

This corresponds to the workflow documented in

docs/howto/activitypub/activities/status_updates.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run both demo workflows 5. Verify side effects in the data layer

demo_notes_workflow(client, reporter, vendor, coordinator)

Demonstrate the notes workflow: 1. Add a note, carried inline, to a case 2. Verify the note is stored and the case has the note

It shows no removal: removing ledgered content is not supported, so every receiver refuses a Remove(Note) (CM-30-003, #6430).

The note travels inline on the single Add(Note) that attaches it; this implementation does not send a separate Create(Note) ahead of the Add (VAM-01-015, #4706).

demo_status_workflow(client, reporter, vendor, coordinator)

Demonstrate the status updates workflow: 1. The vendor reports public awareness in a new ParticipantStatus, carried inline, on its own participant record 2. Verify the status is on the vendor's record and the case status adopted the public awareness

A participant sends only Add(ParticipantStatus), embedding its view of the case status; it never sends Add(CaseStatus), which only the CASE_MANAGER sends (RSH-04-001, RSH-04-005). The status travels inline on the Add that attaches it. This implementation does not support a separate Create(ParticipantStatus) ahead of the Add (#4598).

main(skip_health_check=False, demos=None)

Main entry point for the status updates demo demo script.

suggest-actor

vultron.demo.exchange.suggest_actor_demo

Demonstrates the workflow for suggesting an actor for a case via the Vultron API.

This demo script showcases two suggestion paths per ADR-0026 (CaseActor-routed):

  1. Accept path, each act through its actor's trigger (#5438):
  2. Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase] (suggest-actor-to-case)
  3. CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
  4. Case Owner → CASE_MANAGER: Accept(Offer(CaseParticipant)) (accept-actor-recommendation)
  5. CASE_MANAGER → Coordinator: Invite(VulnerabilityCase preview)[target=Actor], the stub carrying the embargo and the Invite the intended roles

  6. Reject path, each act through its actor's trigger (#5459):

  7. Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase] (suggest-actor-to-case)
  8. CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
  9. Case Owner → CASE_MANAGER: Reject(Offer(CaseParticipant)) (reject-actor-recommendation)
  10. CASE_MANAGER → Reporter: RejectActorRecommendation

The vendor mints the case through create-case, so it holds both CASE_OWNER and CASE_MANAGER and the recommendation routes through its inbox in both roles.

Each demo starts from an initialized case (report submitted and validated, case created, reporter participant added) so that the suggestion workflow can be demonstrated in isolation.

demo_suggest_actor_accept(client, reporter, vendor, coordinator)

Demonstrates the accept path of the suggest-actor-to-case workflow.

ADR-0026 CaseActor-routed protocol, each act through its actor's trigger:

  1. Setup: initialize case
  2. Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase]
  3. CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
  4. Case Owner → CASE_MANAGER: Accept(Offer(CaseParticipant))
  5. CASE_MANAGER → coordinator: Invite to the case

The vendor minted the case, so it holds both CASE_OWNER and CASE_MANAGER.

demo_suggest_actor_reject(client, reporter, vendor, coordinator)

Demonstrates the reject path of the suggest-actor-to-case workflow.

ADR-0026 CaseActor-routed protocol, each act through its actor's trigger:

  1. Setup: initialize case
  2. Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase]
  3. CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
  4. Case Owner → CASE_MANAGER: Reject(Offer(CaseParticipant))
  5. CASE_MANAGER ledgers the Reject (CM-16-007)
  6. Verify no new participant was added

The vendor minted the case, so it holds both CASE_OWNER and CASE_MANAGER.

main(skip_health_check=False, demos=None)

Main entry point for the suggest_actor demo script.

transfer-ownership

vultron.demo.exchange.transfer_ownership_demo

Demonstrates the workflow for transferring case ownership via the Vultron API.

This demo script showcases two ownership transfer paths:

  1. Accept path: current owner (vendor) offers case to coordinator, with a deadline to answer (TRIG-11-007) → the CaseActor's Offer carries it → coordinator accepts in time → case.attributed_to is updated to coordinator
  2. Reject path: current owner (vendor) offers case to coordinator → coordinator rejects → case.attributed_to remains with vendor
  3. Withdraw path: current owner (vendor) offers case to coordinator → vendor withdraws the offer before it is answered → case.attributed_to remains with vendor

Each demo starts from a canonical, CaseActor-owned case (report submitted and validated, Create(CaseProposal) delivered, CaseActor creates the case) so that the transfer workflow can be demonstrated in isolation.

This corresponds to the workflow documented in

docs/topics/case_lifecycle/ownership_transfer.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run the demo workflows (accept, reject and withdraw) 5. Verify side effects in the data layer

Routing model (ADR-0053, ADR-0148): The vendor's proposal, Offer(Offer(VulnerabilityCase)), the response to the Offer and the proposal's withdrawal are addressed to the CaseActor's inbox, never to the transferee or the offerer directly (CM-21-005, CM-21-006, CM-21-010, CM-21-015). The CaseActor records the proposal, makes the one Offer(VulnerabilityCase) of the transfer under its own id, sends it to the transferee and ledgers it, broadcasting each Add(CaseLedgerEntry) to every participant — which is how actors outside the negotiation, such as the reporter, learn a transfer is pending. The demo therefore discovers the CaseActor's Offer by its properties rather than by the proposal's id (EDF-06-004).

demo_transfer_ownership_accept(client, reporter, vendor, coordinator)

Demonstrates the accept path of the transfer-ownership workflow.

Steps: 1. Setup: canonical CaseActor-owned case, coordinator added as participant 2. Vendor offers case ownership to coordinator, with a deadline to answer (OfferCaseOwnershipTransferActivity → CaseActor inbox, CM-21-005, TRIG-11-007) 3. CaseActor makes the Offer from the proposal and sends it to the coordinator, carrying the deadline; the demo discovers it 4. Coordinator accepts through its accept-case-ownership-transfer trigger (AcceptCaseOwnershipTransferActivity → CaseActor inbox, CM-21-006, TRIG-11-002) 5. Verify case.attributed_to is updated to coordinator

This follows the accept branch in docs/topics/case_lifecycle/ownership_transfer.md.

demo_transfer_ownership_reject(client, reporter, vendor, coordinator)

Demonstrates the reject path of the transfer-ownership workflow.

Steps: 1. Setup: canonical CaseActor-owned case, coordinator added as participant 2. Vendor offers case ownership to coordinator (OfferCaseOwnershipTransferActivity → CaseActor inbox, CM-21-005) 3. CaseActor makes the Offer and sends it to the coordinator; the demo discovers it 4. Coordinator rejects through its reject-case-ownership-transfer trigger (RejectCaseOwnershipTransferActivity → CaseActor inbox, CM-21-010, TRIG-11-005) 5. Once the CaseActor has ledgered the Reject (CM-21-012), verify case.attributed_to remains with vendor

This follows the reject branch in docs/topics/case_lifecycle/ownership_transfer.md.

demo_transfer_ownership_withdraw(client, reporter, vendor, coordinator)

Demonstrates the withdrawal path of the transfer-ownership workflow.

Steps: 1. Setup: canonical CaseActor-owned case, coordinator added as participant 2. Vendor offers case ownership to coordinator (OfferCaseOwnershipTransferActivity → CaseActor inbox, CM-21-005) 3. CaseActor makes the Offer and sends it to the coordinator; the demo discovers it 4. Before the coordinator answers, the vendor withdraws the Offer through its withdraw-case-ownership-transfer trigger (UndoCaseOwnershipTransferActivity → CaseActor inbox, CM-21-036, TRIG-11-006) 5. Once the CaseActor has ledgered the withdrawal, verify case.attributed_to remains with vendor

This follows the withdrawal branch in docs/topics/case_lifecycle/ownership_transfer.md.

main(skip_health_check=False, demos=None)

Main entry point for the transfer_ownership demo script.

manage-case

vultron.demo.exchange.manage_case_demo

Demonstrates the case management workflow via the Vultron API.

This demo script showcases the Report Management (RM) process:

  1. Engage Path: submit → validate → create_case → engage → close
  2. Defer and Re-engage Path: submit → validate → create_case → defer → re-engage → close
  3. Invalidate Path: submit → invalidate → close the case (Leave)

The manage_case workflow corresponds to

docs/howto/activitypub/activities/manage_case.md

Key activities demonstrated: - Report Submission (as:Offer) — reporter submits a report to vendor through its own submit-report trigger - RmValidateReportActivity (as:Accept) — vendor validates the report - RmInvalidateReportActivity (as:TentativeReject) — vendor invalidates the report - create-case trigger — vendor mints a as_VulnerabilityCase - RmEngageCaseActivity (as:Join) — actor actively engages the case (RM → ACCEPTED) - RmDeferCaseActivity (as:Ignore) — actor defers the case (RM → DEFERRED) - RmCloseCaseActivity (as:Leave) — actor closes the case (RM → CLOSED)

Note on re-engagement: Per implementation notes, re-engaging a deferred case is done by sending another RmEngageCaseActivity (as:Join) activity. There is no separate RmReEngageCase activity; the RM state machine allows a direct DEFERRED → ACCEPTED transition.

When run as a script, this module will: 1. Check if the API server is available 2. Run three demo workflows, each resetting to a clean state: - demo_engage_path: submit → validate → create_case → engage → close - demo_defer_reengage_path: submit → validate → create_case → defer → re-engage → close - demo_invalidate_path: submit → invalidate → end the embargo → close the case (Leave), each act through its actor's trigger 3. Verify side effects in the data layer for each workflow

demo_defer_reengage_path(client, reporter, vendor, coordinator=None)

Demonstrates the defer-and-re-engage path: submit → validate → create_case → defer → re-engage → close.

Per implementation notes, re-engaging a deferred case uses another RmEngageCaseActivity (as:Join) — there is no separate RmReEngageCase activity. The RM state machine allows a direct DEFERRED → ACCEPTED transition.

Workflow steps: 1. Reporter submits report; vendor validates it 2. Vendor creates case with vendor participant and linked report 3. Vendor defers the case (RmDeferCaseActivity — RM → DEFERRED) 4. Vendor re-engages via RmEngageCaseActivity (RM → ACCEPTED) 5. Vendor closes the case (RmCloseCaseActivity — RM → CLOSED)

demo_engage_path(client, reporter, vendor, coordinator=None)

Demonstrates the full happy-path case management workflow: submit → validate → create_case → engage → close.

Workflow steps: 1. Reporter submits report; vendor validates it 2. Vendor creates as_VulnerabilityCase; adds vendor participant and report 3. Vendor engages the case (RmEngageCaseActivity — RM → ACCEPTED) 4. Vendor closes the case (RmCloseCaseActivity — RM → CLOSED)

demo_invalidate_path(client, reporter, vendor, coordinator=None)

Demonstrates the invalidation path: submit → invalidate → close.

The vendor opened a case for the report on receipt, so once the report is invalid the vendor, as Case Owner, closes that case with Leave(VulnerabilityCase): no actor sends Reject(Offer(VulnerabilityReport)) for a report a case holds (CM-23-019). The case is never engaged.

Workflow steps: 1. Reporter submits a report to the vendor 2. Vendor invalidates the report through its invalidate-report trigger (RM → INVALID) 3. Vendor ends the embargo; the reporter leaves, then the vendor (as:Leave), through their leave-case triggers

main(skip_health_check=False, demos=None)

Main entry point for the manage case demo demo script.

setup_report_and_case(client, reporter, vendor, report_name, report_content, case_name, case_content)

Shared setup: submit and validate a report, create a case, and add the vendor as a participant with the report linked.

Returns the created report and case objects.

manage-embargo

vultron.demo.exchange.manage_embargo_demo

Demonstrates the workflow for managing an embargo via the Vultron API.

This demo script showcases two embargo management paths:

  1. Activate-and-terminate path: coordinator proposes embargo → vendor accepts → embargo is activated → vendor terminates (removes) the embargo
  2. Reject-and-repropose path: coordinator proposes embargo → vendor rejects → coordinator proposes a revised embargo → vendor accepts → activated

Each demo starts from a case with two participants (vendor + coordinator) as a precondition, then exercises the post-establishment management cycle.

This corresponds to the workflow documented in

docs/howto/activitypub/activities/manage_embargo.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run both demo workflows 5. Verify side effects in the data layer

Note on direct inbox communication: This demo uses direct inbox-to-inbox communication between actors, per the Vultron prototype design. Actors post activities directly to each other's inboxes.

demo_activate_then_terminate(client, reporter, vendor, coordinator)

Demonstrates the full activate-then-terminate embargo management cycle.

Steps: 1. Setup: initialize case with two participants (vendor + coordinator) 2. Coordinator proposes embargo (EmProposeEmbargoActivity → vendor inbox) 3. Vendor, the case owner and CASE_MANAGER, activates the embargo: Add(EmbargoEvent)[target=VulnerabilityCase] → vendor inbox (ADR-0180) 4. Vendor announces embargo to participants 5. Verify case has active embargo 6. Vendor terminates (removes) the embargo (RemoveEmbargoFromCaseActivity) 7. Verify case has no active embargo

This follows the activate → terminate branch in docs/howto/activitypub/activities/manage_embargo.md.

demo_reject_then_repropose(client, reporter, vendor, coordinator)

Demonstrates the reject-then-repropose embargo management cycle.

Steps: 1. Setup: initialize case with two participants (vendor + coordinator) 2. Coordinator proposes first embargo (45-day) 3. Vendor, the case owner, rejects the proposal: Reject(EmbargoEvent)[target=VulnerabilityCase] → vendor inbox (ADR-0122) 4. Verify case has no active embargo after rejection 5. Coordinator proposes a revised embargo (90-day) 6. Vendor, the case owner, activates the revised proposal: Add(EmbargoEvent)[target=VulnerabilityCase] → vendor inbox 7. Verify case has active embargo

This follows the reject → re-propose → accept branch in docs/howto/activitypub/activities/manage_embargo.md.

main(skip_health_check=False, demos=None)

Main entry point for the manage_embargo demo script.

manage-participants

vultron.demo.exchange.manage_participants_demo

Demonstrates the full manage-participants workflow via the Vultron API.

This demo script showcases two participant management paths:

  1. Accept path: vendor invites coordinator → coordinator accepts, which seats it (ADR-0114) → coordinator creates participant status → coordinator adds status to participant → vendor, as Case Owner, removes the participant from active participation (the record stays on the case) → vendor, as Case Owner, reinstates it with Add(CaseParticipant) (ADR-0116)
  2. Reject path: vendor invites coordinator → coordinator rejects → coordinator is not added to the case

Add(CaseParticipant) never seats a member: it is the Case Owner's request to reinstate a removed one (CM-31-011). Each demo starts from an initialized case (report submitted and validated, case created through the create-case trigger, which seats the vendor as Case Owner and CASE_MANAGER) so that the invitation and participant management workflows can be demonstrated in isolation.

This corresponds to the workflow documented in

docs/howto/activitypub/activities/manage_participants.md

When run as a script, this module will: 1. Check if the API server is available 2. Reset the data layer to a clean state 3. Discover actors (reporter, vendor, coordinator) via the API 4. Run both demo workflows (accept+manage and reject) 5. Verify side effects in the data layer

demo_manage_participants_accept(client, reporter, vendor, coordinator)

Demonstrates the full accept path of the manage-participants workflow.

Steps: 1. Setup: initialize case (report submitted + validated, case created through the trigger, vendor seated as Case Owner and CASE_MANAGER) 2. Vendor invites coordinator to case (RmInviteToCaseActivity) 3. Coordinator accepts invitation (RmAcceptInviteToCaseActivity), which seats it (ADR-0114) 4. Coordinator adds a new status, carried inline, to their participant (AddStatusToParticipantActivity) 5. Vendor, as Case Owner, removes the coordinator participant (RemoveParticipantFromCaseActivity) 6. Verify the coordinator's record stays on the case and carries the removal fact (CM-31-001) 7. Vendor, as Case Owner, reinstates the coordinator (AddParticipantToCaseActivity, CM-31-011) 8. Verify the removal fact is cleared and the coordinator was sent the CASE_MANAGER's notice

This follows the accept branch in docs/howto/activitypub/activities/manage_participants.md.

demo_manage_participants_reject(client, reporter, vendor, coordinator)

Demonstrates the reject path of the manage-participants workflow.

Steps: 1. Setup: initialize case (report submitted + validated, case created, vendor participant added) 2. Vendor asks the CASE_MANAGER (itself) to invite the coordinator, which sends the stub Invite 3. Coordinator rejects that Invite through its reject-case-invite trigger 4. Verify the coordinator's inert record is closed: it never joined (CM-11-006, CM-11-007)

This follows the reject branch in docs/howto/activitypub/activities/manage_participants.md.

main(skip_health_check=False, demos=None)

Main entry point for the manage participants demo demo script.

trigger

vultron.demo.exchange.trigger_demo

Demonstrates the trigger endpoint workflow for the Vultron API.

Trigger endpoints let an actor proactively initiate a CVD protocol behavior based on its own internal state, as opposed to reacting to an inbound ActivityStreams message. They are the outgoing counterpart to the inbound handler pipeline and are essential for demonstrating the full Vultron Protocol (see specs/triggerable-behaviors.yaml and notes/triggerable-behaviors.md).

Two demo workflows are shown:

  1. Validate and Engage: Reporter submits a report through its own submit-report trigger; vendor then proactively validates the report and engages the resulting case using POST /actors/{actor_id}/trigger/validate-report and POST /actors/{actor_id}/trigger/engage-case.

  2. Invalidate and Close: Reporter submits a second report the same way; vendor proactively invalidates it via POST .../trigger/invalidate-report and then closes the case it opened for the report via POST .../trigger/leave-case, which sends Leave(VulnerabilityCase): once a case holds the report, its owner closes the case by Leave, never by Reject(Offer(VulnerabilityReport)) (CM-23-019, TRIG-13-001).

Each demo verifies that the resulting ActivityStreams activity is returned in the response body and that the vendor's outbox is updated accordingly.

demo_invalidate_and_close(client, reporter, vendor, coordinator=None)

Demonstrate proactive invalidation and report closure via trigger endpoints.

Workflow: 1. Reporter submits a report that the vendor deems invalid. 2. Vendor calls POST .../trigger/invalidate-report to mark it invalid. 3. Vendor ends the case's embargo, which would refuse its close (CM-23-011), then calls POST .../trigger/leave-case to close the case it opened for the report on receipt: a Leave(VulnerabilityCase), since the case's owner never sends Reject(Offer(VulnerabilityReport)) for it (CM-23-019).

demo_validate_and_engage(client, reporter, vendor, coordinator=None)

Demonstrate proactive validation and case engagement via trigger endpoints.

Workflow: 1. Reporter submits a vulnerability report to the vendor (submit-report). 2. Vendor calls POST .../trigger/validate-report to validate the report. 3. Vendor calls POST .../trigger/engage-case to engage the created case.

main(skip_health_check=False, demos=None)

Main entry point for the trigger demo demo script.

vultrabot (CVD BT Demo)

The CVD behaviour-tree self-simulation demo now lives in the legacy simulator tree alongside its siblings (pacman, robot); see Vultrabot Demo for its documentation and source.