Skip to content

Add SSVC doc explaining "human-scale bottleneck" idea#1087

Open
ahouseholder wants to merge 13 commits intomainfrom
fix-1033
Open

Add SSVC doc explaining "human-scale bottleneck" idea#1087
ahouseholder wants to merge 13 commits intomainfrom
fix-1033

Conversation

@ahouseholder
Copy link
Copy Markdown
Contributor

@ahouseholder ahouseholder commented Mar 12, 2026

resolves #1033

This pull request adds a new documentation file explaining the role of SSVC (Stakeholder-Specific Vulnerability Categorization) as a human-scale bottleneck in automated vulnerability response processes. The document clarifies how SSVC condenses complex, automated data into manageable decision points, and emphasizes the importance of human oversight in policy definition and governance.

Key additions to documentation:

  • Introduced a comprehensive explanation of SSVC as a human-scale bottleneck, ensuring transparency and accountability in automated vulnerability response workflows.
  • Detailed the characteristics of SSVC decision points, including their ordinal, orthogonal, and "chunky" nature, which keeps the decision table compact and understandable.
  • Explained how the SSVC decision table codifies policy as code, mapping technical inputs to business-aligned outcomes, and outlined criteria for effective table design.
  • Provided guidance on governance and policy refinement, describing how SSVC enables straightforward modification and clear accountability for risk owners.
  • Clarified that SSVC is not a process bottleneck—automation can occur throughout, with humans responsible for designing and governing the decision framework rather than reviewing every decision.

Copilot AI review requested due to automatic review settings March 12, 2026 20:07
@ahouseholder ahouseholder self-assigned this Mar 12, 2026
@ahouseholder ahouseholder requested a review from sei-renae March 12, 2026 20:07
@ahouseholder ahouseholder added the content/semantic Changes to the semantic content of the SSVC documentation label Mar 12, 2026
@ahouseholder ahouseholder added this to the 2026-03 milestone Mar 12, 2026
Copilot AI reviewed Mar 12, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new How-To documentation page explaining SSVC’s role as a “human-scale bottleneck” between large-scale automated vulnerability data collection/analysis and large-scale operational response, emphasizing policy governance and accountability.

Changes:

  • Added a new documentation page describing SSVC decision points as a compact, human-governable interface in automated workflows.
  • Documented design characteristics (ordinal/orthogonal/chunky) and how decision tables encode organizational policy and governance refinement.

You can also share your feedback on Copilot code review. Take the survey.

sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
@sei-renae
Copy link
Copy Markdown
Contributor

sei-renae commented Mar 18, 2026 •
edited
Loading

Some high level notes:

  1. This does not read like a "how to guide" per the diataxis framework. It seems more akin to an "explanation."
  2. I don't know who the audience is
  3. H2 "The Decision Table: Policy as Code" lost my interest as a reader, if I'm expecting to learn about a human bottleneck

sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae reviewed Mar 18, 2026
View reviewed changes
sei-renae
sei-renae requested changes Mar 18, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comments in-line and in the Conversation.

ahouseholder and others added 4 commits March 30, 2026 15:03
@ahouseholder
revise ssvc-human-scale-bottleneck.md
427f4e0
@ahouseholder
Address unresolved reviewer comments on PR #1087
49b1af3 
- Move file from docs/howto/ to docs/topics/ (parallels decision_points_as_bricks.md,
  addresses Diataxis how-to vs. explanation concern)
- Update mkdocs.yml nav: remove from howto, add to topics alongside
  decision_points_as_bricks.md
- Fix intro: add 'designed by humans, for humans' thesis and 'not a process
  bottleneck' clarification at top of document (threads at lines 68, 107)
- Add diagram scope clarification: make explicit that Decision Model = SSVC scope,
  Data Mapping and Use & Respond are adjacent but outside scope (thread at line 36)
- Fix 'layer' jargon: replace 'any layer of the model' with explicit enumeration
  of outcomes, decision points, decision table, and data mapping (thread at line 97)
- Fix Use & Respond contradiction: remove direct feedback link that conflicted
  with use.md documentation; restate as 'observing real-world results' (line 105)
- Add prepare.md hyperlink to Input Automation section (thread at line 113)
- Fix all relative links: bootstrap/ -> ../howto/bootstrap/ after file move

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ahouseholder
Add human-on-the-loop terminology to intro and conclusion
0e7b699 
Introduces the standard AI/autonomy term 'human-on-the-loop' in two places
to connect it explicitly to the 'human-scale bottleneck' concept:

- Introduction: adds one sentence defining the term after establishing that
  the decision table can be fully automated
- Conclusion: replaces the closing sentence with an explicit 'human-on-the-loop'
  framing that ties accountability to policy governance, not per-decision review

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ahouseholder
Refine terminology and formatting in ssvc-human-scale-bottleneck.md
89dcca8
@ahouseholder ahouseholder requested a review from sei-renae March 30, 2026 20:06
sei-renae
sei-renae reviewed Mar 31, 2026
View reviewed changes
docs/topics/ssvc-human-scale-bottleneck.md
csaf.
io/), [CVE JSON](https://cveproject.github.io/cve-schema/schema/docs/)), and
diverse analytical tools, increasingly including AI features like Large
Language Models (LLMs). SSVC's
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Large Language Models are not a proper noun and should be all lowercase

docs/topics/ssvc-human-scale-bottleneck.md
The initial stages of vulnerability
response—[data collection and mapping](../howto/bootstrap/collect.md)—often involve large
amounts of information, various data sharing formats (e.g., [CSAF](https://www.
csaf.
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hope markdownlint catches this...

docs/topics/ssvc-human-scale-bottleneck.md
- **Densely Defined and Ordinal:** Each decision point uses values that are
ordered (ordinal variables), moving from least likely to most likely to imply
action (e.g., Low, Medium, High). This ordering provides a clear, qualitative
progression without the mathematical properties of intervals.
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the audience of this doc (do we expect the audience to know about math intervals)?

docs/topics/ssvc-human-scale-bottleneck.md

The concept of SSVC as a human-scale bottleneck means that the complexity of the
automated threat landscape is filtered through a framework designed by humans,
for humans, and understood by humans.
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was said almost verbatim in the first paragraph

docs/topics/ssvc-human-scale-bottleneck.md
# SSVC: The Human-Scale Bottleneck in Automated Vulnerability Response

The Stakeholder-Specific Vulnerability Categorization (SSVC) framework is
designed to provide a human-scale decision bottleneck in the vulnerability
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this does not make sense to me, or sounds like bad advertising (if it does make sense)

docs/topics/ssvc-human-scale-bottleneck.md
does *not* mean that a human must manually review every vulnerability
decision—the decision table, once defined, can be entirely automated.
In AI and autonomous systems terminology, this makes SSVC a
*human-on-the-loop* pattern: humans are not required to approve every
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HOTL is too similar to HITL, so we should really emphasize the O in HOTL

docs/topics/ssvc-human-scale-bottleneck.md
established during [Prepare](../howto/bootstrap/prepare.md) defines how to
connect data sources to decision point values.
- **Output Automation:** The prioritized outcome from the SSVC table (e.g., "
Immediate") can feed directly into automated patching, ticketing, or software
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

odd spacing - markdownlint might not catch

docs/topics/ssvc-human-scale-bottleneck.md
- Have there been cases where the table led to a decision that was later
regretted?
- Are there new constraints or requirements not yet captured?
- Is the [data mapping](../howto/bootstrap/prepare.md) still appropriate—are the
Copy link
Copy Markdown
Contributor

@sei-renae sei-renae Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this link to collect.md?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@sei-renae sei-renae sei-renae requested changes

@cgyarbrough cgyarbrough Awaiting requested review from cgyarbrough cgyarbrough is a code owner

@sei-vsarvepalli sei-vsarvepalli Awaiting requested review from sei-vsarvepalli sei-vsarvepalli is a code owner

@j--- j--- Awaiting requested review from j--- j--- is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

@ahouseholder ahouseholder

Labels

content/semantic Changes to the semantic content of the SSVC documentation

Projects

None yet

Milestone

2026-03

Development

Successfully merging this pull request may close these issues.

Write up the "SSVC as human-scale bottleneck" concept

3 participants

@ahouseholder @sei-renae