Capability Model
The specification governs
This page explains the design of the Vultron Protocol. It is informative: the normative text is the Vultron Protocol Specification. Where this page and the specification differ, the specification governs.
Vultron does not decide whether a report is credible, how urgent a case is, or when an advisory is ready to publish. Each of those decisions is a call-out point: a place where the protocol stops and asks a system you run. This page answers the objection "Vultron doesn't do X" by naming, for each X, the call-out point where your system does it. It then describes the four shapes a call-out point can take, the Sentinel call-in pattern, and a catalog of every named capability, generated from the code.
Vultron doesn't do X: your system does
Every objection below is true, and each is true by design. The protocol coordinates the case; the judgment, the data, and the side effects come from your systems.
| "Vultron doesn't…" | Where your system plugs in | Shape |
|---|---|---|
| judge whether a report is credible or valid | EvaluateReportCredibility, EvaluateReportValidity | Evaluator |
| prioritize cases | EvaluateCasePriority, the natural home for a Stakeholder-Specific Vulnerability Categorization (SSVC) decision | Evaluator |
| decide which cases to host for others | EvaluateCaseProposal | Evaluator |
| set or accept embargo terms | SelectEmbargoOfferTerms, EvaluateEmbargoProposal | Evaluator |
| assign Common Vulnerabilities and Exposures (CVE) IDs | IdAssigned, InScope, AssignId | Retriever, Evaluator, Composer |
| develop or deploy fixes | CreateFix, DeployFix | Composer, Evaluator |
| know whether an exploit exists | HaveExploit, FindExploit | Retriever |
| write or publish advisories | DraftAdvisoryArtifact, ReviewAdvisoryDraft, SubmitAdvisoryArtifact | Composer, Evaluator, Actuator |
| know who else belongs in the case | a participant suggester, asked by SuggestParticipants inside a behavior tree or by a Sentinel that calls suggest-actor-to-case, or IdentifyVendors, IdentifyCoordinators, InjectParticipant in the simulator |
Retriever, Actuator |
| look up a peer named only by its URI | ResolveActorDetails | Retriever |
| watch threat feeds | MonitorAttacks, MonitorExploits, MonitorPublicReports, or a Sentinel that reports what it sees | Retriever |
| update your ticketing system | OnAccept, OnDefer and PreCloseAction | Actuator |
The plug-in seam is the same in every row. During development and simulation, each call-out point is filled by a fuzzer node: a stub that returns a random success or failure. You replace the stub with a capability implementation that answers the question for real. Wiring a Capability into the Reference Implementation walks through that replacement for one call-out point.
Why the protocol asks instead of deciding
Much of the Coordinated Vulnerability Disclosure (CVD) process is mechanical: send a message, record a state, wait for a reply. Vultron automates that part with behavior trees (BTs), which run as protocol activities arrive.
The remaining steps need judgment that depends on your organization's policy, data, and tools. A protocol that made those decisions would impose one organization's policy on every participant. So the BT reaches a call-out point, asks, and continues with the answer.
The line falls between two kinds of decision. A mechanical decision reads recorded state and applies a rule: is this participant already in the Valid state, does this case exist in this actor's store, does the state machine permit this transition. Two conformant implementations reach the same answer, because the rule and the inputs are both fixed. A delegated decision has no answer in the record: whether a report is credible, whether embargo terms are acceptable, whether a vulnerability merits a CVE identifier. The protocol marks where the decision is made and defines what an answer looks like, but it does not supply the answer. Two conformant implementations may legitimately differ here; every call-out point is a delegated decision.
A question for another actor is never a call-out point
A call-out point asks a service you run, so it is answered while the BT is still running (BT-18-011). A question that needs a decision from another actor in the case is never a call-out point (BT-18-014). It is a protocol ask: the actor sends a request, finishes, and acts on the reply when it arrives (ADR-0080). An example is whether the Case Owner permits a change to the case's agreed state. No service can answer that on the owner's behalf, and the answer may take days. A call-out point in its place could only ever answer no, because no answer exists when the BT asks. See Protocol Event Flow.
The two integration surfaces
An external service interacts with Vultron in one of two directions.
Call-out: Vultron calls you. The BT reaches a call-out point, packages the question as a structured payload, and waits for a structured answer. Your service decides and responds.
Call-in: you call Vultron. Your service monitors something outside the case, such as a timer, a threat feed, or a deployment system. When a condition is met, it calls a Vultron trigger, and Vultron acts on it.
Every capability uses the call-out surface. The call-in surface belongs to the Sentinel call-in pattern and to any other external system that acts on a case.
Three-level taxonomy
Every call-out point fits a three-level hierarchy:
Shape → Capability → Capability implementation
| Level | What it is | Example |
|---|---|---|
| Shape | The abstract type of interaction: what the service receives, what it returns, and how the BT uses the result | Evaluator |
| Capability | A specific named call-out point with its own input and output contract | EvaluateCveEligibility |
| Capability implementation | The concrete service you build that fulfills a capability at runtime | A microservice that applies the CVE Numbering Authority (CNA) Operational Rules and returns pass or fail |
Think of the shape as a job description, the capability as the open role, and your implementation as the service hired into that role.
Some capabilities are sub-steps of a larger workflow.
For example, EvaluateCveEligibility is a step within the broader ID assignment workflow.
Most capabilities are not nested.
Design decisions
The taxonomy is defined in ADR-0024, and ADR-0097 reduces it to four shapes. The factory-injection pattern is defined in ADR-0025.
Every answer is yes, no or error
Whatever its shape, a capability gives one answer each time the BT asks: a verdict of yes, no or error, and the data its capability declares for that verdict (ADR-0183).
- Yes carries the capability's declared outputs. The BT writes them to its shared state and goes on.
- No is a decision against the request. It carries a refusal payload: a human-readable reason at minimum, and any structured refusal fields the capability declares. The BT writes the payload to the declared refusal keys and takes its "declined" path.
- Error means the capability could not decide or act. It carries diagnostics for the logs only. The BT does not judge the message: the message stays in holding, and the next delivery asks again.
One place in the reference implementation, the call-out seam, turns the answer into BT behavior. No BT reads the answer itself, so a BT still branches only on success and failure.
When to answer error instead of no. Answer no only for a decision you made about this request, because the BT treats it as permanent. An unreachable service, a rejected credential, a timeout, or a side effect you cannot confirm is error. A capability that answers no for an outage turns the outage into a permanent refusal, such as a case proposal declined for good because the policy service was down.
The Wiring a Capability guide shows the answer in code.
The four shapes
There are exactly four capability shapes (BT-18-013). The normative contracts are in Annex G Capability Shapes in the protocol specification; this section explains how each one behaves.
Evaluator
You receive: a situation, such as case context, report details, or embargo terms. You return: a structured recommendation, typically a decision plus optional reasoning. The BT uses it to: gate what happens next.
If you answer yes with "needs revision," the BT routes to the revision branch. If you answer no, with your reason, the pipeline stops. No is the only way to stop it: an Evaluator that answers yes with a "rejected" value in its output does not block the next step (BT-18-007). The BT does not care whether the judgment came from a human reviewer, a rules engine, or a large language model (LLM); it needs a structured answer it can act on.
Evaluators carry human-level judgment. Examples are assessing whether a report is credible, deciding whether an embargo proposal is acceptable, and checking whether a vulnerability meets CVE assignment criteria.
Retriever
You receive: a query. You return: structured facts the BT needs to proceed. The BT uses it to: supply inputs for downstream steps.
Retrievers are data lookups. Examples are whether a CVE ID already exists for this vulnerability, whether a public exploit database lists an exploit, and what the current SSVC decision is for this case. A yes-or-no question the protocol asks is also a Retriever, never a Sentinel. When the case or the actor's own records already hold the fact, the tree reads it there and does not ask the Retriever (BT-18-039). A Retriever is asked only for what the case and the actor's records do not already hold, so any cache of what it fetches is the Retriever's own (BT-18-029).
Most Retrievers can be wired directly to an API or database without human involvement.
Composer
You receive: context, such as case details, draft content, and constraints. You return: a content artifact, such as a document, report body, advisory text, or fix description. The BT uses it to: pass the artifact to the next stage, such as review or publication.
The Composer writes its output into the BT's shared state, the blackboard, so later steps can read it. Examples are drafting a security advisory, writing a vulnerability report body, and preparing a fix description.
Composer vs. Actuator
If your service generates a document, it is a Composer. If it submits that document to a publication platform, it is an Actuator.
Actuator
You receive: a trigger, a signal that something should happen, with the one target it acts on and an idempotency id. You return: yes when the side effect is confirmed, no when you decided not to act, and error when you could not confirm it; never a content artifact. The BT uses it to: confirm that a side effect was executed.
Actuators fire side effects in external systems. Examples are posting an embargo acceptance to a collaboration platform, submitting an advisory to a publication pipeline, and updating a ticket when a report is closed. Each call acts on one target, and a re-run of the same act gives the call the same idempotency id, so an Actuator that keys its side effect on that id never repeats it (Wiring a Capability).
The Sentinel call-in pattern
A Sentinel is not a capability shape (BT-18-013, ADR-0097). It watches a condition over time and, when the condition is met, acts on its own initiative. The protocol never asks it anything, so it has no call-out point, no blackboard contract, and no backend factory.
The discriminator is who initiates, not where the information comes from. A capability is asked and answers within the tick that asks. A Sentinel decides for itself that the moment has come.
A Sentinel takes one of two forms:
- a case Participant, typically holding the
CVDRole.OBSERVERrole, that learns case state through ordinary ledger replication (Add(CaseLedgerEntry)) and acts by sending ordinary protocol messages, visible to every participant; - operator-side machinery with no case identity, which drives one actor through its call-in triggers and is invisible to the case.
Examples are an embargo timer that calls terminate-embargo when the agreed end date passes, a threat-feed monitor that reports active attacks, and a deployment monitor that reports a fix as deployed.
A Sentinel is a long-running monitor, so building one needs different infrastructure from building a call-out responder: a way to observe, a decision rule, and something to call.
Capability hierarchy
The catalog below lists every named capability, by domain. Use it to identify which capability you are building toward.
Every entry is a call-out point: Vultron asks, and your capability answers. A Sentinel never appears here, because it is a call-in pattern that watches a condition and calls a trigger on its own initiative (see The Sentinel call-in pattern).
The tables are generated from the capability declarations in vultron/core/behaviors/call_out/capabilities/ each time the site is built.
Each row gives these facts about one capability:
- Capability: the name a BT gives to the backend factory.
- Shape: the shape base class that the declaration subclasses.
- Asks: the first paragraph of the declaration's docstring.
- Reads: the input ports that the capability reads.
- Writes on yes: the output ports that the capability writes when it answers yes (BT-18-012).
"Verdict only" means the capability writes nothing, and its yes or no is the whole answer (BT-18-010).
A capability's simulation stand-in, its fuzzer node, sits at the same module path under vultron/demo/fuzzer/.
Report Validation
See also: Validation behavior
Declared in vultron/core/behaviors/call_out/capabilities/report_management/validate.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
EvaluateReportCredibility |
Evaluator | Assess whether the report's source and content are credible. | — | report_credibility_verdict (str) |
EvaluateReportValidity |
Evaluator | Assess whether the report is valid for this organization's scope. | — | report_validity_verdict (str) |
GatherValidationInfo |
Retriever | Request or collect additional information needed to validate. | — | validation_info_gathered (str) |
NoNewValidationInfo |
Retriever | Check whether any new information has arrived that should trigger re-evaluation of the report's validity. | — | verdict only |
Report Prioritization
See also: Prioritization behavior
EvaluateCasePriority is the natural home for a Stakeholder-Specific Vulnerability Categorization (SSVC) decision.
OnAccept and OnDefer are the hooks that update your ticketing system when a report is accepted or deferred.
Declared in vultron/core/behaviors/call_out/capabilities/report_management/prioritize.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
EnoughPrioritizationInfo |
Evaluator | Determine whether sufficient context exists to make an accept/defer decision. | — | enough_prioritization_info_verdict (str) |
EvaluateCasePriority |
Evaluator | Evaluate whether to engage or defer a case using prioritization policy. | — | evaluate_case_priority_verdict (str) |
GatherPrioritizationInfo |
Retriever | Collect additional context needed to support a prioritization decision. | — | prioritization_info_gathered (str) |
NoNewPrioritizationInfo |
Retriever | Check whether new information has arrived that should trigger re-prioritization of the report. | — | verdict only |
OnAccept |
Actuator | Execute site-specific tasks when a report is accepted. | — | side effect only |
OnDefer |
Actuator | Execute site-specific tasks when a report is deferred. | — | side effect only |
Case Admission
See also: Propose case behavior, Case Initialization
EvaluateCaseProposal is the admission decision a case actor service makes on an inbound Create(CaseProposal), and the only place admission policy lives.
Answering no sends Reject(CaseProposal); the default admits.
An unreachable policy service answers error, which leaves the proposal in holding rather than declining it.
Build this one if you run a case actor service for others. The Propose case page carries the full reasoning: what the policy decides, why the decision sits ahead of every write, and the two ways a refusal gate can be defeated.
Declared in vultron/core/behaviors/call_out/capabilities/case_management.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
EvaluateCaseProposal |
Evaluator | Decide whether to admit an inbound Create(CaseProposal). |
— | evaluate_case_proposal_verdict (str) |
Embargo Management
See also: Embargo behaviors, Evaluate proposed embargo, Propose embargo, Terminate embargo
A participant's answer to an embargo invitation is its own consent, so EvaluateEmbargoProposal decides it from that participant's own policy, and no capability asks the Case Owner to approve it (EMB-15-013).
A decision that only the Case Owner can make is a protocol ask, not a call-out point (BT-18-014).
A gate where the Case Owner lets the CASE_MANAGER activate an embargo for it would sit on the CASE_MANAGER's activation path.
That idea is open in #6045.
Whether the active embargo stays acceptable as conditions change (CurrentEmbargoAcceptable) is open in #1943.
The embargo's end time is in the case, so a BT reads it there instead of asking EmbargoTimerExpired (BT-18-039; see Still open).
Declared in vultron/core/behaviors/call_out/capabilities/embargo/proposal.py, vultron/core/behaviors/call_out/capabilities/embargo/evaluation.py, vultron/core/behaviors/call_out/capabilities/embargo/termination.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
ReasonToProposeEmbargoWhenDeployed |
Evaluator | Decide whether to start a new embargo after the fix is already deployed. | — | reason_to_propose_when_deployed_verdict (str) |
SelectEmbargoOfferTerms |
Evaluator | Select the specific terms to include in an embargo proposal. | — | selected_embargo_terms_verdict (str) |
StopProposingEmbargo |
Evaluator | Decide whether to abandon an ongoing embargo negotiation. | — | stop_proposing_embargo_verdict (str) |
WantToProposeEmbargo |
Evaluator | Decide whether to initiate an embargo negotiation. | — | want_to_propose_embargo_verdict (str) |
WillingToCounterEmbargoProposal |
Evaluator | Decide whether to counter an incoming embargo proposal. | — | willing_to_counter_verdict (str) |
CurrentEmbargoAcceptable |
Evaluator | Decide whether the current active embargo terms remain acceptable. | — | current_embargo_acceptable_verdict (str) |
EvaluateEmbargoProposal |
Evaluator | Assess an incoming embargo proposal and decide whether to accept it. | — | evaluate_embargo_proposal_verdict (str) |
OnEmbargoAccept |
Actuator | Execute site-specific tasks when an embargo proposal is accepted. | — | side effect only |
OnEmbargoReject |
Actuator | Execute site-specific tasks when an embargo proposal is rejected. | — | side effect only |
EmbargoExitOverride |
Evaluator | Actor explicitly overrides a policy veto to terminate the embargo. | — | embargo_exit_override_verdict (str) |
EmbargoExitPolicyGuard |
Evaluator | Check whether site policy permits voluntary embargo termination. | — | embargo_exit_policy_guard_verdict (str) |
EmbargoTimerExpired |
Retriever | Check whether the embargo's agreed-upon deadline has passed. | — | verdict only |
ExitEmbargoForOtherReason |
Evaluator | Decide whether to exit an embargo for an uncommon or exceptional reason. | — | exit_embargo_other_reason_verdict (str) |
ExitEmbargoWhenDeployed |
Evaluator | Decide whether to exit an active embargo when the fix is deployed. | — | exit_embargo_when_deployed_verdict (str) |
ExitEmbargoWhenFixReady |
Evaluator | Decide whether to exit an active embargo when the fix is ready. | — | exit_embargo_when_fix_ready_verdict (str) |
OnEmbargoExit |
Actuator | Execute site-specific tasks when leaving an active embargo. | — | side effect only |
CVE / Vulnerability ID Assignment
See also: ID Assignment behavior
These capabilities are the sub-steps of one ID assignment workflow.
EvaluateCveEligibility is a single judgment call that applies the CNA Operational Rules eligibility criteria as one unit.
The publication condition stays a separate protocol check just before it.
RequestId asks an outside CNA for an ID when this actor is not the appropriate authority.
Declared in vultron/core/behaviors/call_out/capabilities/report_management/assign_vul_id/eligibility.py, vultron/core/behaviors/call_out/capabilities/report_management/assign_vul_id/assignment.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
EvaluateCveEligibility |
Evaluator | Evaluate whether the vulnerability is eligible for a CVE ID. | — | cve_eligibility_verdict (bool)cve_eligibility_rationale (str) |
InScope |
Evaluator | Check whether the vulnerability is within scope for an ID assignment. | — | in_scope_verdict (str) |
IsMostAppropriateCNA |
Evaluator | Evaluate whether this CNA has first-refusal authority for the product. | — | is_most_appropriate_cna (bool)is_most_appropriate_cna_rationale (str) |
ProductInCNAScope |
Evaluator | Evaluate whether the affected product is within this CNA's scope. | — | product_in_cna_scope (bool)product_in_cna_scope_rationale (str) |
AssignId |
Composer | Assign a Vulnerability ID directly to the vulnerability. | — | assigned_vul_id (str) |
IdAssignable |
Evaluator | Check whether the vulnerability qualifies for an ID assignment. | — | id_assignable_verdict (str) |
IdAssigned |
Retriever | Check whether the vulnerability has already been assigned an identity. | — | verdict only |
RequestId |
Retriever | Request a Vulnerability ID assignment from an external authority. | — | assigned_id (str) |
Fix Development
See also: Fix Development behavior
Declared in vultron/core/behaviors/call_out/capabilities/report_management/develop_fix.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
CreateFix |
Composer | Initiate the process of creating a fix for the vulnerability. | — | fix_artifact (str) |
Fix and Mitigation Deployment
See also: Deployment behavior
Declared in vultron/core/behaviors/call_out/capabilities/report_management/deploy_fix.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
DeployFix |
Evaluator | Deploy the vendor fix to the affected environment. | — | deploy_fix_verdict (str) |
DeployMitigation |
Evaluator | Deploy the available mitigation for the vulnerability. | — | deploy_mitigation_verdict (str) |
MitigationAvailable |
Retriever | Check whether a mitigation option is available to deploy. | — | verdict only |
MitigationDeployed |
Retriever | Check whether a mitigation has already been deployed. | — | verdict only |
MonitorDeployment |
Actuator | Monitor the ongoing deployment of the fix or mitigation. | — | side effect only |
MonitoringRequirement |
Evaluator | Determine whether deployment monitoring is required by policy. | — | monitoring_requirement_verdict (str) |
NoNewDeploymentInfo |
Retriever | Check whether any new deployment information has arrived. | — | verdict only |
PrioritizeDeployment |
Evaluator | Assign priority to deploying the available fix or mitigation. | — | deployment_priority_verdict (str) |
Exploit Management
See also: Exploit Acquisition behavior
Declared in vultron/core/behaviors/call_out/capabilities/report_management/acquire_exploit.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
DevelopExploit |
Composer | Develop an exploit for the vulnerability internally. | — | developed_exploit_artifact (str) |
EvaluateExploitPriority |
Evaluator | Evaluate the priority of acquiring an exploit for this vulnerability. | — | exploit_priority_verdict (str) |
EvaluateExploitStrategy |
Evaluator | Evaluate the overall exploit-acquisition strategy for this vulnerability. | — | exploit_strategy_decision (ExploitStrategyDecision) |
FindExploit |
Retriever | Search external sources for an existing exploit. | — | verdict only |
HaveExploit |
Retriever | Check whether the organization already possesses an exploit. | — | verdict only |
PurchaseExploit |
Evaluator | Pursue purchase of an exploit from an external vendor or broker. | — | purchase_exploit_verdict (str) |
Publication
See also: Publication behavior, Reporting behavior
ReviewAdvisoryDraft answers yes with needs_revision to route the draft to revision, or no to block submission entirely.
Declared in vultron/core/behaviors/call_out/capabilities/report_management/publication/intents.py, vultron/core/behaviors/call_out/capabilities/report_management/publication/advisory.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
PrepareExploit |
Composer | Create, document, and stage the exploit artifact for publication. | — | prepared_exploit_artifact (str) |
PrepareFix |
Composer | Create, document, and stage the fix artifact for publication. | — | prepared_fix_artifact (str) |
PrepareReport |
Composer | Create, review, and stage the vulnerability advisory for publication. | — | prepared_report_artifact (str) |
PrioritizePublicationIntents |
Evaluator | Establish and record publication intentions for the case. | — | publication_intent_decision (PublicationIntentDecision) |
Publish |
Actuator | Execute the publication of a prepared artifact to the intended audience. | — | side effect only |
ReprioritizeExploit |
Evaluator | Update the priority of the exploit artifact in the publication queue. | — | reprioritize_exploit_verdict (str) |
ReprioritizeFix |
Evaluator | Update the priority of the fix artifact in the publication queue. | — | reprioritize_fix_verdict (str) |
ReprioritizeReport |
Evaluator | Update the priority of the report artifact in the publication queue. | — | reprioritize_report_verdict (str) |
DraftAdvisoryArtifact |
Composer | Draft the advisory artifact from case data. | — | draft_advisory_artifact (str) |
ReviewAdvisoryDraft |
Evaluator | Review and approve the advisory draft. | draft_advisory_artifact (str) |
advisory_review_decision (AdvisoryReviewDecision) |
ReviseAdvisoryDraft |
Composer | Revise the advisory draft based on review feedback. | advisory_review_decision (AdvisoryReviewDecision) |
draft_advisory_artifact (str) |
SubmitAdvisoryArtifact |
Actuator | Submit the finalized advisory artifact to the external advisory platform. | — | side effect only |
Leaving a Case
See also: Closure behavior
An actor closes its part in a case by calling the leave-case trigger, which sends Leave(VulnerabilityCase) to the CASE_MANAGER.
leave-case runs PreCloseAction before it sends the Leave, for every caller, so it is where you close your own ticket.
A failure stops the trigger with nothing sent.
OtherCloseCriteriaMet is superseded, because the decision to close is the act of calling leave-case (ADR-0145).
Declared in vultron/core/behaviors/call_out/capabilities/report_management/close_report.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
OtherCloseCriteriaMet |
Evaluator | Check whether site-specific closure criteria have been satisfied. | — | other_close_criteria_met_verdict (str) |
PreCloseAction |
Actuator | Perform required actions immediately before closing the report. | — | side effect only |
Reporting to Others
See also: Reporting behavior
These capabilities find and notify the other parties a report should reach.
They come from the simulator's report-to-others BT.
To find who else belongs in a case, use a Sentinel that calls suggest-actor-to-case or invite-actor-to-case (ADR-0047).
The Sentinel asks a participant suggester who is missing.
Declared in vultron/core/behaviors/call_out/capabilities/report_management/report_to_others/recipients.py, vultron/core/behaviors/call_out/capabilities/report_management/report_to_others/injection.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
AllPartiesKnown |
Evaluator | Check whether all relevant parties for notification have been identified. | — | all_parties_known_verdict (str) |
ChooseRecipient |
Retriever | Select the next recipient from the identified-parties list. | — | chosen_recipient (str) |
IdentifyCoordinators |
Retriever | Identify coordinator organizations that should be involved. | — | identified_coordinators (list) |
IdentifyVendors |
Retriever | Identify the software vendors responsible for the affected product(s). | — | identified_vendors (list) |
PolicyCompatible |
Evaluator | Check whether the recipient's disclosure policy is compatible with the case. | — | policy_compatible_verdict (str) |
RecipientEffortExceeded |
Evaluator | Check whether notification effort for a recipient has exceeded a limit. | — | recipient_effort_exceeded_verdict (str) |
RemoveRecipient |
Actuator | Remove a recipient from the pending notification queue. | — | side effect only |
SetRcptQrmR |
Actuator | Record notification by transitioning recipient's RM state to RECEIVED. | — | side effect only |
TotalEffortLimitMet |
Evaluator | Check whether the total notification effort ceiling has been reached. | — | total_effort_limit_met_verdict (str) |
InjectParticipant |
Actuator | Add a new participant to the case (generic form). | — | side effect only |
Participant and Actor Discovery
See also: ADR-0186, #1142, Actor Knowledge Model
Participant suggestion
Participant suggestion answers one question: given this case, who else should take part, and why?
Your system answers it by implementing one port, ParticipantSuggestionPort in vultron/core/ports/participant_suggestion.py, with one method, suggest_participants.
The same adapter serves a BT and a Sentinel, because both ask through one core service, suggest_case_participants (BT-24-001, BT-24-008).
The port never sees the case. It receives a suggestion context, which the core service builds from the case (BT-24-002, BT-24-009). The context carries each report's title, summary and body as the evidence, and each participant's actor id and roles as who is already in the case. A report can name a vendor or a product that is not yet in the case, and finding that party is the point of the port. The participants that hold the VENDOR role are the case's current vendors.
Each answer names an actor id, a suggested CVD role and a reason, and an empty answer is valid (BT-24-004). A suggestion carries no timing: the actor that receives it decides when to invite, from the invitee's embargo policy (BT-24-006). Prefer suggesting a party that turns out not to be needed over leaving out one that is (BT-24-005).
An adapter that calls a third-party service hands that service the whole suggestion context, report content included, and the case may be under embargo. Choosing such an adapter is your trust decision, not one the port can make.
Inside a BT, the SuggestParticipants Retriever below wraps the core service, and it answers within the call-out time budget like any other capability (BT-18-015).
An adapter too slow for that budget is reachable only from a Sentinel.
With no adapter wired, the default answers with no suggestions, so nobody is suggested.
Declared in vultron/core/behaviors/call_out/capabilities/participant_suggestion.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
SuggestParticipants |
Retriever | Suggest the parties a case is missing, each with a role and a reason. | case_id (str) |
participant_suggestions (ParticipantSuggestions) |
Actor resolution
ResolveActorDetails looks up a peer that a request names by URI and that the actor holds no record of.
It answers through one port: give it the peer's id, and it returns the peer's profile as a CoreActor.
A static adapter returns a profile declared up front, for demos and tests.
A live adapter fetches the profile with a GET of the actor URL and validates it.
The actor records the profile only when its id is the peer's.
On no, on error, or with no source wired, it records the peer's URI alone, which is enough to address it (AKM-05-001).
Resolution never blocks the request that named the peer.
Declared in vultron/core/behaviors/call_out/capabilities/actor_resolution.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
ResolveActorDetails |
Retriever | Return the actor record of a peer this actor knows only by its URI. | peer_actor_id (str)actor_id (str) |
resolved_actor (CoreActor) |
Threat Monitoring
See also: Monitoring Threats behavior, #1845, #1856
Each capability here answers a question the BT asks once. A feed watcher that reports what it sees as it happens is a Sentinel instead.
Declared in vultron/core/behaviors/call_out/capabilities/report_management/monitor_threats.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
MonitorAttacks |
Retriever | Monitor threat-intelligence feeds for active attacks on the vulnerability. | — | verdict only |
MonitorExploits |
Retriever | Monitor threat-intelligence feeds for public exploits of the vulnerability. | — | verdict only |
MonitorPublicReports |
Retriever | Monitor public sources for disclosure of the vulnerability. | — | verdict only |
Messaging
See also: Other message behaviors
Declared in vultron/core/behaviors/call_out/capabilities/messaging.py.
| Capability | Shape | Asks | Reads | Writes on yes |
|---|---|---|---|---|
FollowUpOnErrorMessage |
Composer | Attempt to send a follow-up inquiry when an error message is received. | — | followup_message_artifact (str) |
Call-in triggers
These are the actions an external system can invoke on a Vultron actor, each at POST /actors/{actor_id}/trigger/{behavior}.
An operator-side Sentinel uses them to act when a monitored condition fires, and any other external system may call them directly.
The Trigger API Reference gives each endpoint's request and response.
Report lifecycle
submit-report— create and offer a vulnerability report to a recipientack-report— acknowledge a received report to its sendervalidate-report— mark a received report as validinvalidate-report— mark a received report as invalidreject-report— hard-close a report before validation completes; it also sendsReject(Offer(VulnerabilityReport)), so it fails once a case holds the report, which by default happens on receipt; from then on you leave the case withleave-case
Case management
create-case— create a local vulnerability caseengage-case— accept a case (transitions to ACCEPTED state)defer-case— defer a case (transitions to DEFERRED state)add-report-to-case— link a report to an existing caseadd-object-to-case— ask the CASE_MANAGER to add an existing report or note to a case; other object types are refusedleave-case— leave a case: runs yourPreCloseAction, then sendsLeave(VulnerabilityCase)to the CASE_MANAGER; the Case Owner's Leave closes the case, so it fails while the case has an active embargo, and you terminate the embargo first
Embargo
propose-embargo— propose a new embargoaccept-embargo— accept a pending embargo proposal, or the embargo in force by naming the Invite you received for itreject-embargo— reject a pending embargo proposal, or the embargo in force by naming the Invite you received for itpropose-embargo-revision— propose a revision to an active embargoterminate-embargo— end the active embargo immediately
Participants and actors
suggest-actor-to-case— recommend another actor to the Case Ownerinvite-actor-to-case— directly invite an actor to a caseaccept-case-invite/reject-case-invite— respond to a case invitationaccept-actor-recommendation/reject-actor-recommendation— approve or decline a suggested actor (Case Owner only)offer-case-participant-role— offer a CVD role to another actoroffer-case-ownership-transfer/accept-case-ownership-transfer/reject-case-ownership-transfer/withdraw-case-ownership-transfer— transfer case ownership, decline the transfer, or withdraw an open offeradd-on-behalf-status— as CASE_MANAGER or Case Owner, record a vendor's awareness (the V event) on behalf of a vendor participant, typically an invitee that has not yet replied, or a deployer's deployment (the D event) on behalf of a deployer participant that has accepted, deferred or closed the case, when the evidence is in hand; the target must already be a participant, because a status update never adds an actor to the case (invite the actor first); fix readiness is never recorded on another actor's behalf
Typical Sentinel patterns
| Sentinel condition | How it acts |
|---|---|
| Embargo end date passes | Calls terminate-embargo with the reason END_TIME_REACHED |
| Active attack observed in a threat feed | As a case Participant, sends Add(ParticipantStatus) recording the attack (the A event); no trigger endpoint covers this yet (#1845) |
| Fix confirmed deployed | As a case Participant, sends Add(ParticipantStatus) recording deployment (the D event) |
| New party named by a participant suggester | Calls suggest-actor-to-case or invite-actor-to-case |
Settled and open design questions
You can build the core logic of a capability implementation now. The questions below determine the wiring details.
Settled
What a capability must define (#2452).
A named capability declares its blackboard contract as typed input and output ports, on a declaration owned by the core layer (BT-18-012, ADR-0097).
Every capability has its declaration in vultron/core/behaviors/call_out/capabilities/, and its simulation stand-in binds to it (BT-18-021).
How a capability implementation is invoked (#2453). A backend answers synchronously, within the tick that asks, with yes, no or error, and never returns RUNNING (BT-18-011, ADR-0080, ADR-0183). It also answers within a time budget that each actor configures (BT-18-015, BT-18-026). An answer that takes longer is discarded and reported as an internal error that names the node (BT-18-027). A decision that takes days is not a call-out point: it is a request to another actor, or a Sentinel.
What a deployment that supplies nothing gets. Every call-out point is built through a backend factory, and the default backend is a deterministic one, so a deployment that plugs in nothing still runs (BT-18-004, BT-23-001, ADR-0025). The default is usually the permissive answer, on the reasoning that a stub should not silently hold up progress. One class of gate inverts that. Where a permissive default would let a party other than the Case Owner force the adoption of a case state or the teardown of an embargo, the default is the conservative answer instead (BT-23-012, ADR-0076). So when a page says a call-out point "defaults to accept", that describes the stub, not a protocol requirement to accept.
What the shape classes are called in code (#2454).
The shape base classes are EvaluatorCapability, RetrieverCapability, ComposerCapability, and ActuatorCapability, in vultron/core/behaviors/call_out/capability.py (ADR-0097).
Each named capability is declared once in core, as a subclass of one of them that declares its blackboard contract as typed ports, and its fuzzer node subclasses that declaration (BT-18-012, BT-18-021).
The older names, such as EvaluatorCallOutPoint, still import from vultron/demo/fuzzer/call_out_point.py and name the same classes.
Still open
Should a Sentinel end embargoes on time? (#1893)
This is no longer a choice of shape for EmbargoTimerExpired.
If a BT asks "has the end date passed?" and gets only yes or no, it asks a Retriever.
A synchronous query from the BT is always a Retriever, never a Sentinel (BT-18-006).
The end time is in the case's embargo register, so a BT reads it there instead of asking (BT-18-039).
The CASE_MANAGER ends the embargo the next time it handles the case after the end time (EMB-13-003).
What stays open is whether something should end an embargo at its end time when nothing else happens in the case.
That is a Sentinel (BT-18-013).
No BT asks it: it watches the clock, and calls terminate-embargo with the reason END_TIME_REACHED on its own initiative.
Who runs it, and how it authenticates to the trigger, are among the Sentinel design questions in #2450.
Choosing what to build
- Find the objection you are answering. Start from the table above, or browse the capability hierarchy for a domain that matches your organization's tooling.
- Identify the direction. If Vultron asks and you answer, you are building one of the four shapes. If you watch something and act when it happens, you are building a Sentinel.
- Check the GitHub issues.
Several capabilities already have open idea issues under epic #1147.
If one fits, comment on it.
If yours is not listed, file a new issue with the
idealabel. - Design the contract. Decide what context your capability needs from Vultron and what structured answer it returns.
- Wire it in and test it. Replace the fuzzer node with your backend, following Wiring a Capability into the Reference Implementation, and run it against the existing BT structure.
Reading path: You maintain a vulnerability tracker and want it to talk to your partners
This page is part of Understand the shape of the integration.
Previous
Reading path: You handle vulnerability reports and coordinate cases with other organizations
This page is part of Map it onto what you already do.
Next — pick one
Reading path: You want to understand how a vulnerability case runs under Vultron
This page is part of Follow a case from report to publication.
Previous
Next — pick one