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 |
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:
- Setup: submit a vulnerability report (precondition for case creation)
- Create Case: vendor explicitly creates a as_VulnerabilityCase
- Add Vendor as Participant: vendor adds themselves as case creator/owner
- Add Report to Case: vendor links the submitted report to the case
- Invite the Reporter: vendor sends the reporter the stub Invite
- Reporter Joins: the reporter accepts, and the vendor, as CASE_MANAGER, seats it
(ADR-0114;
Add(CaseParticipant)only reinstates, CM-31-011) - 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:
- 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.
- Invite the Coordinator: the vendor, as Case Owner, asks the CaseActor to invite the coordinator, and the CaseActor sends the stub Invite
- 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:
- Accept path: case owner invites coordinator → coordinator accepts → coordinator becomes a case participant
- 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:
- Accept path: participant proposes embargo → case owner accepts → embargo is activated on the case (EM state = ACTIVE)
- 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:
- 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. - Reporter proposes longer (60 vs 30 days): the Receiver's default is the
active embargo at creation and the Reporter's terms — the same
EmbargoEventthe 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 atEM.REVISEuntil the owner acts. In run 1 the relay goes to the Reporter instead, whose acceptance only records consent, so that case also stays atEM.REVISE. - 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:
- Acknowledge Only: submit → vendor sends ack (RmReadReportActivity) to reporter
- Acknowledge then Validate: submit → ack to reporter → validate → reporter's replica records it
- 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
- Reporter submits report to vendor
- 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
- Reporter submits report to vendor
- Vendor sends RmReadReportActivity (as:Read) to the reporter
- Vendor invalidates through its invalidate-report trigger, which sends the Report Invalid (as:TentativeReject) to the case's CASE_MANAGER
- 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
- Reporter submits report to vendor
- Vendor sends RmReadReportActivity (as:Read) to the reporter
- Vendor validates through its validate-report trigger, which sends the Report Valid (as:Accept) to the case's CASE_MANAGER
- 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:
- Notes workflow: vendor adds a note, carried inline, to a case
- 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):
- Accept path, each act through its actor's trigger (#5438):
- Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase] (
suggest-actor-to-case) - CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
- Case Owner → CASE_MANAGER: Accept(Offer(CaseParticipant))
(
accept-actor-recommendation) -
CASE_MANAGER → Coordinator: Invite(VulnerabilityCase preview)[target=Actor], the stub carrying the embargo and the Invite the intended roles
-
Reject path, each act through its actor's trigger (#5459):
- Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase] (
suggest-actor-to-case) - CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
- Case Owner → CASE_MANAGER: Reject(Offer(CaseParticipant))
(
reject-actor-recommendation) - 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:
- Setup: initialize case
- Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase]
- CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
- Case Owner → CASE_MANAGER: Accept(Offer(CaseParticipant))
- 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:
- Setup: initialize case
- Reporter → CASE_MANAGER: Offer(Actor)[target=VulnerabilityCase]
- CASE_MANAGER → Case Owner: Offer(CaseParticipant)[target=VulnerabilityCase]
- Case Owner → CASE_MANAGER: Reject(Offer(CaseParticipant))
- CASE_MANAGER ledgers the Reject (CM-16-007)
- 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:
- 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
- Reject path: current owner (vendor) offers case to coordinator → coordinator rejects → case.attributed_to remains with vendor
- 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:
- Engage Path: submit → validate → create_case → engage → close
- Defer and Re-engage Path: submit → validate → create_case → defer → re-engage → close
- 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:
- Activate-and-terminate path: coordinator proposes embargo → vendor accepts → embargo is activated → vendor terminates (removes) the embargo
- 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:
- 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) - 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:
-
Validate and Engage: Reporter submits a report through its own
submit-reporttrigger; vendor then proactively validates the report and engages the resulting case usingPOST /actors/{actor_id}/trigger/validate-reportandPOST /actors/{actor_id}/trigger/engage-case. -
Invalidate and Close: Reporter submits a second report the same way; vendor proactively invalidates it via
POST .../trigger/invalidate-reportand then closes the case it opened for the report viaPOST .../trigger/leave-case, which sendsLeave(VulnerabilityCase): once a case holds the report, its owner closes the case byLeave, never byReject(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.