Skip to content
Reference

Introduction and Overview

This page is normative

This page is considered a core part of the Vultron Protocol. This is a normative section of the documentation.

The whole specification on one page

The specification is also published as a single page that holds every section and annex in order, for printing or for searching the whole text at once.

This page holds sections 1 to 3 of the Vultron Protocol Specification: why the protocol exists, the terms it defines, and an overview of how it works.

1. Introduction [I]

1.1 Background and Motivation

A vulnerability divides the world into two sets: those who know about it, and those who do not. From the moment of discovery, every party in the knowing set repeatedly answers two questions. What should it do next, and who else needs to know what, and when? Coordinated Vulnerability Disclosure (CVD) continues until the answers are "nothing" and "nobody".

Multi-Party CVD (MPCVD) is CVD involving three or more independent organizations with different interests and roles. The shapes vary. A reporter may go to one vendor, which discovers that other vendors ship the same component. A reporter may go to a coordinator, which finds and notifies the affected vendors. A reporter may go to a vendor and a coordinator at once. What the cases have in common is that the set of participants grows after coordination has begun, each vendor works to its own timeline, and the parties must agree when disclosure happens.

Each of those organizations usually already runs its own vulnerability tracking system. The coordination problem is therefore not only one of people talking to each other; it is one of separate systems needing to stay consistent about a shared case. That is the problem Vultron addresses.

Email carries the content of a CVD case but records none of its state. No participant can see which vendors have read the report, which have agreed to an embargo, or in what order events occurred. Adding a party mid-case means re-sending the history by hand, and nothing detects the gap if that fails. Vultron gives each of these an explicit, machine-checkable representation: report status per participant (§6 Report Management (RM) State Machine), embargo agreement per participant (§9 Participant Embargo Consent (PEC) State Machine), and an ordered case ledger that every participant replicates (§5.4 Addressing and Channels).

Embargo timing is worth noting early. In practice the first two parties to a case establish the initial embargo, and it carries forward as further participants join and agree to it. Establishing terms early is generally easier than negotiating them once many parties are already involved.

The protocol tracks coordination state across four dimensions: the report lifecycle, Report Management (RM); the embargo, Embargo Management (EM); what is known about the vulnerability, Case State (CS); and each participant's agreement to the embargo, Participant Embargo Consent (PEC). Because CS is a compound of two independent axes, an implementation runs five state machines (§3.3 Tracking Dimensions). Messages are ActivityStreams 2.0 Activities delivered over Hypertext Transfer Protocol (HTTP). Delivery is asynchronous: no exchange requires both parties to be available at the same moment.

Who this specification is for

This specification is written for implementers building software that takes part in Vultron cases, and for reviewers assessing whether an implementation conforms.

It assumes familiarity with coordinated vulnerability disclosure as a practice — reporters, vendors, coordinators, embargoes, Common Vulnerabilities and Exposures (CVE) IDs. It does not assume prior knowledge of Vultron. Where it relies on an external specification, it says so and cites it (§1.3 Relationship to Existing Standards).

See also

1.2 Design Goals

Actor-local state. Each participant keeps its own replica of the case, assembled from the messages it has received. A participant is the authority on its own report and fix status. What the case as a whole asserts — its embargo state and what is publicly known — has a single writer, the participant holding the Case Manager role, so that concurrent claims resolve to one answer (§5.4.1 Single-Writer Authority).

Coordination is scoped to a case, not to a system. The Case Manager role is held per case, and different cases may be managed by different actors. The protocol does not require every case to pass through one shared service. It does require, within a case, that shared state have one writer.

Informative: how centralized is this?

Two readings should both be avoided.

Vultron does not require a single central authority holding all cases. Any actor able to satisfy the Case Manager role can manage a case, and the role is transferable (§11.3 Case Ownership Transfer).

Equally, Vultron as it stands is not a fully decentralized design. Within a case there is one writer, and its availability bounds how fast the case can progress. The current reference implementation goes further and runs a dedicated service actor per case.

The protocol leaves more distributed realizations open — a shared ledger among peers, for instance — and this version does not specify one (§5.4.2 Routing Topology).

Asynchronous, message-driven coordination. Participants announce their own transitions rather than being polled, and no exchange requires two parties to be online at once. A participant that is temporarily unreachable does not block the others from making progress.

Extensible role model. Roles are not exclusive: a participant may hold Reporter, Vendor and Coordinator at the same time (§3.5 Participants and Roles). Roles that confer protocol authority are kept separate from roles that describe what an actor does in the world, so the two can vary independently.

Interoperable wire format. ActivityStreams 2.0 is the normative wire vocabulary. Reusing an established open standard means the message format is already specified and already understood, and it leaves ActivityPub-based delivery available as a path to potentially compatible tooling. Vultron has not yet been integrated with the wider ActivityPub ecosystem.

1.3 Relationship to Existing Standards

ActivityStreams 2.0 and ActivityPub. Vultron uses the ActivityStreams 2.0 vocabulary as its wire format, and ActivityPub HTTP delivery is the anticipated transport.

This version requires the vocabulary but not full ActivityPub server behavior: inbox and outbox HTTP delivery, WebFinger discovery and HTTP Signatures are not conformance requirements here. A future version is expected to raise the floor to full ActivityPub for all participants, at which point the vocabulary-only profile may become a compatibility profile. An implementation built against this version should expect to be re-evaluated against that one. This paragraph is the specification's single statement of that roadmap; other sections cite it.

ISO/IEC 29147 and 30111. International Organization for Standardization (ISO) 29147 specifies vulnerability disclosure practices; ISO 30111 specifies vulnerability handling processes. Vultron implements the multi-party coordination layer those standards describe at a high level. The CERT Guide to Coordinated Vulnerability Disclosure provides the practitioner-level complement.

See also

1.4 Document Conventions

This specification uses the key words defined in RFC 2119: MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL.

Sections marked [N] are normative. Sections marked [I] are informative. Sections marked [N/I] contain a mix; normative requirements are explicitly flagged.

State names. This specification writes state names in full, in prose form: Received, Active, Agreed, Fix Ready. Where the name of a specific enumerated value matters, for example when citing an implementation's enumeration, the value is written in code font with its machine as a prefix, as in RM.RECEIVED or EM.ACTIVE. The two forms name the same state. Consent row states and embargo register statuses are written in code font without a prefix (AGREED, PROPOSED); where a word names both an EM state and a register status, the text says which. Some positions the specification names are reads of state rather than states: a participant is a signatory when its consent to the embargo in force is Agreed (§9.3 Signatory and Lapsed).

Case-state notation. The Case State axes use one letter per condition. A lowercase letter means the condition is not met; an uppercase letter means it is. Vfd therefore means the vendor is aware, the fix is not ready, and the fix is not deployed. An arrow names the transition that flips one letter, so f→F is the change from "fix not ready" to "fix ready". An asterisk is a wildcard: pX* matches any state in which p is lowercase and X is uppercase.

2. Terminology [N/I]

Vultron gives several ordinary Coordinated Vulnerability Disclosure (CVD) words a narrower meaning than they carry in general use. The tables in this section state the protocol meaning of each term. Where the protocol meaning differs from common usage, the protocol meaning applies throughout this specification.

This section is the authoritative source for the terms it defines, including the role enumeration in §2.2 Roles. An implementation derives its vocabulary from this specification.

Where a term already has a settled definition in the wider coordinated vulnerability disclosure literature, this specification adopts that definition rather than coining its own, and says where it came from. Vulnerability is such a term.

2.1 Actors, Participants and Cases

These four terms are ordered deliberately: each builds on the one before it.

Term Definition
Vulnerability A set of conditions or behaviors that allows the violation of an explicit or implicit security policy. Vulnerabilities are the subject of every Vultron case.
Report A document describing a specific vulnerability, submitted to initiate coordination.
Case The coordination context around a specific vulnerability: the participants, the shared state, the messages exchanged, and any embargo agreement. The case is the unit of Vultron protocol activity.
Actor An identity in the protocol, named by a Uniform Resource Identifier (URI). An actor may be an organization, a person, or a service. Actors exist independently of any case.
Participant An actor with a CaseParticipant record in a specific case, whether or not it has yet joined. The record associates that actor with the roles it holds and the state it owns. An active participant is one that has joined and agreed to the case's current embargo. An actor is a participant in a case; the same actor may participate in many.

Source of the vulnerability definition

The definition of vulnerability above is taken unchanged from the CERT Guide to Coordinated Vulnerability Disclosure. It is also consistent with ISO/IEC 29147:2018 §5.4, which defines the term in the same policy-violation terms (ISO crosswalks).

Note what the definition does not require: it says nothing about whether the vulnerability is known, reported, fixed or public. Those are properties a Vultron case tracks about a vulnerability (§8 Case State (CS) Dimensions), not part of what makes something one.

2.2 Roles

A role is a position held within a case. It determines what a participant is obliged to do and which transitions it is authorized to cause. Roles are granted through the case's authority chain (§11.1 Role Assignment), not claimed. A participant may hold several at once.

Roles fall into two categories, which §12.3 Role Taxonomy develops further.

Process roles describe what an actor does in a case:

Role Definition
Reporter A participant that submitted the report. The protocol is concerned with who reported the vulnerability, not who discovered it; a discoverer who reports holds the Reporter role.
Vendor A participant that produces a product containing the vulnerability and is responsible for developing a fix.
Coordinator A participant that facilitates multi-party coordination without being responsible for developing a fix itself.
Deployer A participant that deploys a vendor's fix to systems it operates. Distinct from Vendor: producing a fix and applying it are separate acts.
CVE Numbering Authority (CNA) A participant authorized to assign CVE IDs directly, rather than delegating assignment to an external service. Orthogonal to the other process roles and commonly held alongside Coordinator or Vendor.
Observer A participant with no obligation to drive vendor/fix/deploy transitions. An Observer still tracks case state, is subject to embargo consent, and may report observations about the world.

Protocol authority roles describe what an actor controls in the protocol itself:

Role Definition
Case Owner The party whose disclosure decision the case exists to serve. It decides who is admitted, which roles they hold, and whether embargo terms are accepted or torn down. Case ownership is never delegated, though it may be transferred (§11.3 Case Ownership Transfer).
Case Manager The participant that writes the canonical case ledger and relays case-scoped messages, acting on the Case Owner's behalf. It is the case's single-writer authority (§5.4.1 Single-Writer Authority). The Case Owner may delegate this role.

The Observer role and the Case Observer capability set

Observer is a process role (defined above). The minimum conformance capability set that every participant must provide is the Case Observer capability set (§12.2 Capability Sets) — named to echo the least-privileged role, with a Case prefix that keeps the two distinct. They are not the same kind of thing: a role is a position in a case; a capability set is a property of software (§12.3.3 Roles and Capability Sets Are Independent). The same prefix distinguishes the Case Decision and Case Hosting capability sets from the roles they serve.

Informative: the CASE_MANAGER role and the actor that holds it

Authority over a case follows the Case Manager role. It does not follow any actor's name, URI, or hosting location. Normative text in this specification therefore names the authority the CASE_MANAGER, meaning whichever participant currently holds the role.

The reference implementation happens to satisfy the role with an automated software actor it labels a case actor, provisioned by a case actor service. Those are implementation labels with no protocol meaning. An implementation MUST NOT infer authority from them.

Informative: Finder is not a protocol role

Earlier CVD models distinguish the finder of a vulnerability from its reporter. Vultron does not: nothing in the protocol depends on who discovered the vulnerability, so an actor that discovers and reports holds the Reporter role. The discoverer's identity may be recorded in the report content or in a case note.

2.3 Protocol Objects and Messages

These terms name the things a case is made of and the messages that move between participants.

Term Definition
Activity The wire form of a Vultron message: an ActivityStreams 2.0 Activity. Every message this specification describes is carried as an Activity (§5 Syntactic Layer — Wire Format).
Message A protocol operation sent from one actor to another. A message states that something has happened; it is not an instruction to the recipient.
Message type One of the operations the protocol defines, each named by a protocol shorthand. RS (Report Submission) and EP (Embargo Proposal) are message types (§4 Semantic Layer — Message Meanings).
Protocol shorthand The two-letter code naming a message type by its meaning rather than its wire form — RS, EP, CV, and so on. Introduced in §4 Semantic Layer — Message Meanings and mapped to wire forms in §5.7 Shorthand to Wire Form Mapping. A reader meeting a shorthand before §4 Semantic Layer — Message Meanings may treat it as an opaque label.
Case stub A minimal description of a case, carrying enough for an invited actor to decide whether to join and no vulnerability detail. Sent with an invitation, before the invitee has been admitted (§11.2 Invitation and Acceptance).
Case ledger The case's authoritative, append-only history. The CASE_MANAGER is its only writer, and every participant holds a replica built from what the CASE_MANAGER sends.
CaseLedgerEntry One entry in the case ledger. Each entry records one admitted change, carries a timestamp assigned by the CASE_MANAGER, and is hash-chained to its predecessor so a participant can tell whether it holds the entries in order and without gaps.
ParticipantStatus A participant's report about its own state, or its observation about the world. A ParticipantStatus is a claim: any participant may write one, and writing one does not change the case's state (§10.3 Status Adoption: The Two-Seam Model).
CaseStatus The case's shared state — its embargo state and what is publicly known. A CaseStatus is canonical: only the CASE_MANAGER writes it, and it changes only when a claim is adopted (§10.3 Status Adoption: The Two-Seam Model).
Channel The path a message travels. In Vultron the delivery path is inbox to inbox, and case-scoped messages route through the CASE_MANAGER (§5.4.2 Routing Topology).

2.4 State, Embargo and Disclosure

These terms concern what a case knows and what its participants have agreed to. The last two are the pair most often conflated.

Term Definition
State The current value of one state machine. Always qualified in this specification — RM state, embargo state, case state — because the unqualified word is ambiguous.
Transition A change from one state to another.
Track To maintain a local value for a state machine and update it as incoming messages report transitions. Every participant tracks all five machines (§12.2 Capability Sets).
Drive To cause a transition that the participant's roles authorize, and announce it so the other participants learn of it. Which transitions a participant may drive depends on its roles (§12.4 Role-Specific Normative Requirements).
Embargo A time-bounded agreement among the participants of a case not to disclose the vulnerability publicly before an agreed point. Tracked for the case by the embargo state machine (§7 Embargo Management (EM) State Machine) and per participant by embargo consent (§9 Participant Embargo Consent (PEC) State Machine).
Teardown Ending an active embargo. The CASE_MANAGER performs the teardown and records it; a participant may report that it intends to exit, or propose an earlier end, but does not end the case's embargo itself (§10.2 Embargo Revision and Termination Cascades).
Publication A deliberate act by a participant that makes vulnerability information publicly available. Publication is something a participant does, and the embargo constrains when a participant may do it.
Public awareness The condition of the vulnerability being known outside the case, however that came about. Public awareness may arise with no participant publishing anything: an attacker may discover the vulnerability independently, a commit may reveal it, or a non-participant may write about it.

Publication and public awareness are not the same thing

Vultron governs publication — what a participant may deliberately disclose, and when. It cannot govern public awareness, which is a fact about the world that no participant controls.

The distinction is load-bearing because most of the protocol's disclosure logic keys off whether information is public, not off how it became public. An embargo that is overtaken by an independent leak is over as surely as one ended by agreement, and the case state records Public Aware either way (§8.2 PXA — Public Aware, Exploit Public, Attacks Observed).

See also

3. Protocol Overview [I]

This section describes the shape of the protocol before the normative sections specify it. It covers how the protocol is modeled, what state it tracks, how that state is divided between individual participants and the case as a whole, and what roles participants hold. Nothing here is normative; each subsection points to the section that carries the requirements.

3.1 Coordination Model

Vultron models a case as a set of communicating state machines — one set per participant — that coordinate only by exchanging messages. No participant reads another's state directly. Each learns about the others from the messages it receives.

A participant's own view is therefore always a replica: its local copy of what it believes the case state to be, assembled from the messages that have reached it. Two participants can hold different views at the same moment, because a message is still in transit or because a participant has not yet reported something.

State divides into two kinds, and the distinction runs through the whole specification. Participant-specific state belongs to one participant, which is the authority on its own value. Shared case state has one value for the entire case, and only the participant holding the CASE_MANAGER role writes it (§5.4.1 Single-Writer Authority); it replicates each admitted change to every participant as Announce(CaseLedgerEntry).

Machine Ownership Written by
Report Management (RM) Participant-specific The participant itself
Vendor aware, Fix ready, fix Deployed (VFD) Participant-specific The participant itself
Embargo Management (EM) Shared case state The CASE_MANAGER only
Public aware, eXploit public, Attacks observed (PXA) Shared case state The CASE_MANAGER only
Participant Embargo Consent (PEC) Per-participant The CASE_MANAGER only

A participant reports its own state and reports observations about the world. It does not write shared case state, and reporting an observation is not the same as that observation becoming canonical (§10.3 Status Adoption: The Two-Seam Model).

3.2 What a Deployment Looks Like

The protocol is abstract, but a deployment is concrete, and the shape is worth stating plainly before the state machines begin.

Each participating organization runs one Vultron service, which exposes an inbox at a URI. For each case, one participant additionally holds the CASE_MANAGER role for that case, and every case-scoped message passes through it: a participant addresses the message to the CASE_MANAGER, which records it in the case ledger and then sends the resulting entry to every participant, including the sender.

---
title: Message flow within one case
---
flowchart LR
    R["Reporter<br/>(own inbox)"]
    V1["Vendor A<br/>(own inbox)"]
    V2["Vendor B<br/>(own inbox)"]
    CM["Participant holding<br/>CASE_MANAGER for this case<br/>(own inbox + case ledger)"]

    R -- "case-scoped message" --> CM
    V1 -- "case-scoped message" --> CM
    V2 -- "case-scoped message" --> CM
    CM -- "Announce(CaseLedgerEntry)" --> R
    CM -- "Announce(CaseLedgerEntry)" --> V1
    CM -- "Announce(CaseLedgerEntry)" --> V2

Two things this is not:

  • It is not a central clearinghouse. The role is held per case. A different case may route through a different organization entirely, and there is no service that sees every case.
  • It is not a registry. Nothing looks up authority in a directory; authority follows the role recorded on the case (§5.4.1 Single-Writer Authority).

Participants also talk to each other outside the protocol — by mail, by phone, in a shared channel. That is normal and out of scope. What routes through the CASE_MANAGER is the case's protocol traffic, because that is what changes case state (§5.4.2 Routing Topology).

Messages describe what has happened

A Vultron message states that something has already occurred. It is not an instruction to the recipient. An RV message means "I received this report and determined it was valid" — it does not ask the recipient to treat the report as valid. This holds throughout §4 Semantic Layer — Message Meanings through §10 Model Interactions and Cascade Rules and governs how every message description in those sections should be read.

One construct is deliberately request-shaped: a proposal such as an embargo invitation asks for a decision. Even there, the reply reports a decision that has been made; it does not command a transition.

See also

3.3 Tracking Dimensions

The protocol tracks coordination state across four dimensions. Each is a state machine, or a pair of them, with its own states and transitions. The lists below name the states so the rest of this overview can refer to them; the defining sections carry the full definitions.

  • Report Management (RM) — the lifecycle of a report inside one participant, from receipt to closure. Participant-specific. Seven states: Start, Received, Invalid, Valid, Deferred, Accepted, Closed (§6 Report Management (RM) State Machine).
  • Embargo Management (EM) — the negotiated disclosure timing agreed for the case. Shared case state, computed from the case's embargo register of every embargo proposed on it. Five states: None, Proposed, Active, Revised, Exited (§7 Embargo Management (EM) State Machine).
  • Case State (CS) — what is known about the vulnerability. CS is the pair (VFD, PXA) (§8 Case State (CS) Dimensions).
  • Participant Embargo Consent (PEC) — each participant's answer to each embargo in the register, one row per embargo. Per-participant, written by the CASE_MANAGER. Five states: Uninvited, Invited, Agreed, Declined, Timed out. Whether a participant is bound, a signatory, is read from its row for the embargo in force (§9 Participant Embargo Consent (PEC) State Machine).

Four dimensions, five state machines

Case State (CS) is a compound of two independent axes, so four tracked dimensions are realized as five state machines:

This specification says "four dimensions" when describing what is tracked and "five state machines" when describing what an implementation must provide. Both counts are correct; they count different things.

RM, EM and CS were present in the original protocol design. PEC emerged during implementation and is fully normative; its provenance is recorded at §9 Participant Embargo Consent (PEC) State Machine.

3.4 How the Dimensions Interact

The four dimensions are coupled. A transition in one creates obligations in others. This subsection summarizes the couplings; §10 Model Interactions and Cascade Rules specifies them.

RM governs what a participant receives. A participant's RM state determines what it is obliged to do and what the CASE_MANAGER may send it. Full case content is withheld until the participant has been admitted — recorded in the case's participant roster with RM state Received — and its embargo consent has been resolved (§9.7 Gating Full Case Delivery).

EM gates disclosure. While an embargo is in force, participants defer publication. An embargo ends by teardown: the CASE_MANAGER terminates it and records the termination. A participant may report that it intends to exit, or propose a shorter embargo or an earlier end date, but a participant does not end the case's embargo by itself — EM is shared case state (§7.2 Transitions and Guards, §10.2 Embargo Revision and Termination Cascades).

CS records observation, not decision. A VFD transition is a fact about what one participant has done. A PXA transition is a fact about the world. Any participant may report a PXA observation; whether that report becomes canonical case state is decided separately (§10.3 Status Adoption: The Two-Seam Model).

EM and PEC answer different questions. EM says whether the case has an embargo. PEC says whether a given participant is bound by it. The two can disagree: a case at EM Active may hold a participant whose row for the embargo in force is not Agreed, if that participant has been invited but has not yet joined, or declined the terms. Cascade rules keep them consistent (§10.2 Embargo Revision and Termination Cascades).

3.5 Participants and Roles

An actor is an identity in the protocol — an organization, a person, or a service, named by a URI. An actor that joins a case becomes a participant in that case, and the case's record of that participant associates it with a set of roles. Roles determine what a participant is obliged to do and which transitions it is authorized to cause.

Roles are not exclusive. A participant may hold Reporter, Vendor and Coordinator at once. A vendor that discovers a vulnerability in its own product is both Reporter and Vendor.

Participant count is not role count. Every participant runs all five state machines regardless of which roles it holds. Roles govern which transitions it may cause, not which machines it maintains.

Two categories of role apply. §12.3 Role Taxonomy gives the full taxonomy.

  • Process roles — what an actor does in a case: Reporter, Vendor, Coordinator, Deployer, CVE Numbering Authority (CNA), Observer.
  • Protocol authority roles — what an actor controls in the protocol itself: Case Owner and Case Manager. These confer specific rights within a case, independent of what other actors do.

The distinction between the two authority roles matters throughout:

  • The Case Owner is the party whose disclosure decision the case exists to serve. It decides who is admitted, which roles they hold, and whether embargo terms are accepted or torn down. Case ownership is never delegated, though it may be transferred (§11.3 Case Ownership Transfer).
  • The Case Manager is the participant holding the CASE_MANAGER role. It writes the canonical case ledger, relays case-scoped messages, and acts on the Case Owner's behalf. The role cannot be granted by a role offer (§11.1 Role Assignment); how it is handed to another actor is not yet specified.

Roles are assigned through the case's authority chain, not claimed. An actor does not acquire a case role by asserting that it holds one (§11.1 Role Assignment).

See also