TypeScript implementation of SSVC (Stakeholder-Specific Vulnerability Categorization)



A prioritization framework to triage CVE vulnerabilities as an alternative or compliment to CVSS.

🤖 NEW: AI/LLM Methodology Available

We've added a new AI/LLM Triage methodology specifically designed for assessing AI and LLM vulnerabilities. This methodology addresses the unique security considerations of AI systems including model security, data poisoning, prompt injection, and AI-specific attack vectors.

Features:
- AI-specific decision points: Model access, data poisoning potential, and AI system impact assessment
- Comprehensive coverage: Addresses both traditional software vulnerabilities in AI systems and AI-specific threats
- Aligned with AI security frameworks: Follows emerging best practices for AI security assessment

See the AI/LLM Triage Documentation for detailed usage and examples.

🏗️ Schema-Driven Architecture

This library implements a standardized YAML schema for SSVC methodologies, staying true to SSVC's core design principle of being "Stakeholder-Specific" while enabling interoperability and portability:

- 🔧 Flexibility: Create custom methodologies tailored to your organization's needs
- 🔗 Interoperability: Schema-compliant YAML works across different SSVC tools
- 📦 Portability: Take your configurations with you - no vendor lock-in
- ✅ Validation: Built-in schema validation ensures consistency and correctness

``bash


Validate your YAML methodologies against the schema

just validate-methodologies

or

npx ts-node scripts/validate-methodologies.ts
`

See the Schema Documentation for complete details on creating schema-compliant YAML methodologies.

This library features a plugin-based architecture that allows for easy integration of different SSVC methodologies. It includes built-in support for 7 methodologies:

| Methodology | Description | Documentation | Official Source |
|-------------|-------------|---------------|-----------------|
| AI LLM Triage | AI-specific vulnerability triage for LLMs | docs/ai_llm_triage.md | NIST AI Risk Management |
| CISA | CISA Stakeholder-Specific Vulnerability Categorization | docs/cisa.md | CISA SSVC Guide |
| Coordinator Triage | CERT/CC Coordinator Triage Decision Model | docs/coordinator_triage.md | CERT/CC Coordinator Triage |
| Coordinator Publication | CERT/CC Coordinator Publication Decision Model | docs/coordinator_publication.md | CERT/CC Publication Decision |
| Engineer Triage | Developer-focused vulnerability triage methodology | docs/engineer_triage.md | Comprehensive Guide |
| Supplier | CERT/CC Supplier Decision Model for patch prioritization | docs/supplier.md | CERT/CC Supplier Tree |
| Deployer | CERT/CC Deployer Decision Model for patch deployment | docs/deployer.md | CERT/CC Deployer Tree |

All methodologies support both quantitative (structured decision trees) and qualitative (expert judgment) approaches, with the library providing the quantitative framework while allowing for qualitative override based on domain expertise.

#### Other Languages

Check out the  Python implementation of SSVC

> Golang is currently in development

Installation

`sh
npm install ssvc
`

Quick Start

$3

`javascript
import { createDecision, listMethodologies } from 'ssvc';

// See available methodologies
console.log(listMethodologies());
// ['CISA', 'AI/LLM Triage', 'Coordinator Triage', 'Coordinator Publication', 'Supplier', 'Deployer']

// Critical vulnerability requiring immediate action
const criticalDecision = createDecision('CISA', {
exploitation: 'active', // Active exploitation detected
automatable: 'yes', // Can be automated
technical_impact: 'total', // Complete system compromise possible
mission_wellbeing: 'high' // High impact on mission/business
});

const result = criticalDecision.evaluate();
console.log(result); // { action: 'act', priority: 'immediate' }

// Lower priority vulnerability for comparison
const lowPriorityDecision = createDecision('CISA', {
exploitation: 'none', // No known exploitation
automatable: 'no', // Manual exploitation required
technical_impact: 'partial', // Limited impact
mission_wellbeing: 'low' // Minimal business impact
});

const lowResult = lowPriorityDecision.evaluate();
console.log(lowResult); // { action: 'track', priority: 'low' }
`

$3

`javascript
// AI-specific vulnerability assessment
const aiVulnDecision = createDecision('AI/LLM Triage', {
model_access: 'direct', // Direct model access possible
data_poisoning: 'confirmed', // Training data compromised
ai_system_impact: 'full_compromise', // Complete AI system compromise
traditional_exploit: 'yes' // Also exploitable via traditional methods
});

const aiResult = aiVulnDecision.evaluate();
console.log(aiResult); // { action: 'act', priority: 'immediate' }
`

📋 Schema Validation System

The schema validation system ensures all SSVC methodologies follow a consistent hierarchical tree structure while preserving the flexibility that makes SSVC "Stakeholder-Specific":

$3

SSVC's Design Philosophy: The name "Stakeholder-Specific Vulnerability Categorization" explicitly recognizes that different organizations have different priorities, risk tolerances, and operational contexts. However, this flexibility should not come at the cost of interoperability.

Benefits of Schema Compliance:

1. 🎯 True to SSVC's Intent: Enables stakeholder-specific customization within a consistent framework
2. 🔄 Tool Interoperability: Your YAML configurations work across different SSVC implementations
3. 📊 Data Portability: Move between tools without vendor lock-in or configuration migration
4. ✅ Quality Assurance: Validation catches structural errors before deployment
5. 📚 Documentation: Standardized structure enables automatic documentation generation
6. 🔧 Extensibility: Add new methodologies following established patterns

$3

`bash


Validate all methodologies

just validate-methodologies

Output example:

🔍 Validating SSVC Methodology Files...

Validating cisa.yaml...
✅ cisa.yaml is valid

Validating custom-methodology.yaml...
❌ custom-methodology.yaml has errors:
• Inconsistent tree depth: found depths 3, 4. All paths should have the same depth.
• Action 'REVIEW' has no priority mapping
`

$3

All YAML methodologies must follow these structural requirements:

- Hierarchical Decision Trees: Nested tree structure (not flat arrays)
- Consistent Depth: All decision paths must have identical depth
- Complete Mappings: All actions must have priority mappings
- Enum Validation: All declared enums must be used, all used enums must be declared

See Schema Documentation for detailed requirements and examples.

Plugin-Based Architecture

The library supports a flexible plugin system where each methodology is a separate plugin. This allows for:

- Easy extensibility - Add new methodologies by creating schema-compliant YAML configurations
- Clean separation - Each methodology is self-contained
- Type safety - Full TypeScript support with generated types
- Documentation generation - Automatic mermaid diagrams and markdown docs

Built-in Methodologies

$3

The CISA Stakeholder-Specific Vulnerability Categorization framework:

`javascript
import { createDecision } from 'ssvc';

const cisaDecision = createDecision('CISA', {
exploitation: 'active', // 'none' | 'poc' | 'active'
automatable: 'yes', // 'yes' | 'no'
technical_impact: 'total', // 'partial' | 'total'
mission_wellbeing: 'high' // 'low' | 'medium' | 'high'
});

const outcome = cisaDecision.evaluate();
// Returns: { action: 'act', priority: 'immediate' }
`

Possible Actions:
- track → Low priority
- track* → Medium priority
- attend → Medium priority
- act → Immediate priority

$3

The AI/LLM Triage methodology addresses the unique security considerations of AI systems, including model vulnerabilities, data poisoning, prompt injection, and AI-specific attack vectors:

`javascript
import { createDecision } from 'ssvc';

const aiDecision = createDecision('AI/LLM Triage', {
model_access: 'api', // 'none' | 'local' | 'api' | 'direct'
data_poisoning: 'confirmed', // 'none' | 'suspected' | 'confirmed'
ai_system_impact: 'full_compromise', // 'minimal' | 'degraded' | 'full_compromise'
traditional_exploit: 'yes' // 'yes' | 'no'
});

const outcome = aiDecision.evaluate();
// Returns: { action: 'act', priority: 'immediate' }
`

Possible Actions:
- track → Low priority
- monitor → Medium priority
- investigate → High priority
- act → Immediate priority

AI-Specific Considerations:
- Model Security: Direct access to model weights, training data, or inference logic
- Data Poisoning: Malicious training data affecting model behavior
- AI System Impact: Range from performance degradation to complete system compromise
- Traditional Exploits: Whether the vulnerability can be exploited through conventional software attack vectors

$3

The CERT/CC Coordinator Triage Decision Model for vulnerability coordinators:

`javascript
import { createDecision } from 'ssvc';

const coordinatorDecision = createDecision('Coordinator Triage', {
report_public: 'yes', // 'yes' | 'no'
supplier_contacted: 'yes', // 'yes' | 'no'
report_credibility: 'credible', // 'credible' | 'not_credible'
supplier_cardinality: 'multiple', // 'one' | 'multiple'
utility: 'super_effective', // 'laborious' | 'efficient' | 'super_effective'
public_safety_impact: 'significant' // 'minimal' | 'significant'
});

const outcome = coordinatorDecision.evaluate();
// Returns: { action: 'coordinate', priority: 'high' }
`

Possible Actions:
- decline → Low priority
- track → Medium priority
- coordinate → High priority

$3

The CERT/CC Coordinator Publication Decision Model for publication decisions:

`javascript
const publicationDecision = createDecision('Coordinator Publication', {
supplier_involvement: 'fix_ready', // 'fix_ready' | 'cooperative' | 'uncooperative_unresponsive'
exploitation: 'active', // 'none' | 'public_poc' | 'active'
public_value_added: 'precedence' // 'limited' | 'amplificative' | 'precedence'
});

const outcome = publicationDecision.evaluate();
// Returns: { action: 'publish', priority: 'high' }
`

Possible Actions:
- don't_publish → Low priority
- publish → High priority

$3

The CERT/CC Supplier Decision Model for patch development prioritization:

`javascript
const supplierDecision = createDecision('Supplier', {
exploitation: 'active', // 'none' | 'public_poc' | 'active'
utility: 'super_effective', // 'laborious' | 'efficient' | 'super_effective'
technical_impact: 'total', // 'partial' | 'total'
public_safety_impact: 'significant' // 'minimal' | 'significant'
});

const outcome = supplierDecision.evaluate();
// Returns: { action: 'immediate', priority: 'immediate' }
`

Possible Actions:
- defer → Low priority
- scheduled → Medium priority
- out_of_cycle → High priority
- immediate → Immediate priority

$3

The CERT/CC Deployer Decision Model for patch deployment prioritization:

`javascript
const deployerDecision = createDecision('Deployer', {
exploitation: 'active', // 'none' | 'public_poc' | 'active'
system_exposure: 'open', // 'small' | 'controlled' | 'open'
utility: 'super_effective', // 'laborious' | 'efficient' | 'super_effective'
human_impact: 'very_high' // 'low' | 'medium' | 'high' | 'very_high'
});

const outcome = deployerDecision.evaluate();
// Returns: { action: 'immediate', priority: 'immediate' }
`

Possible Actions:
- defer → Low priority
- scheduled → Medium priority
- out_of_cycle → High priority
- immediate → Immediate priority

$3

The Engineer Triage methodology is specifically designed for software engineers to prioritize vulnerability response within development workflows. It focuses on actionable outcomes that integrate directly with development practices:

`javascript
import { createDecision } from 'ssvc';

const engineerDecision = createDecision('Engineer Triage', {
reachability: 'verified_reachable', // 'verified_reachable' | 'verified_unreachable' | 'unknown'
remediation_option: 'patchable_deployment', // patch availability and deployment method
mitigation_option: 'automation', // available defensive measures
reported_priority: 'critical' // 'critical' | 'high' | 'medium' | 'low'
});

const outcome = engineerDecision.evaluate();
// Returns: { action: 'spike_effort', priority: 'high' }
`

Decision Points:
- Reachability: Can vulnerable code paths be executed? (determined via SAST, code coverage, call graph analysis)
- Remediation Option: What patching options are available? (from package managers, lock files, vendor advisories)
- Mitigation Option: What defensive measures can be implemented? (WAF rules, code changes, alternative libraries)
- Reported Priority: What is the severity rating? (from CVSS scores, vulnerability databases, internal assessments)

Possible Actions:
- nightly_auto_patch → Low priority (routine automated patching)
- spike_effort → High priority (time-boxed investigation needed)
- drop_tools → Immediate priority (stop current work, address now)
- backlog → Medium priority (schedule for future sprint)

For detailed implementation guidance, including data source mapping and practical examples, see the Engineer Triage Comprehensive Guide.

Quantitative vs Qualitative Decision Making

SSVC supports both approaches to vulnerability prioritization:

$3

The library provides structured decision trees with specific criteria and outcomes. This ensures:
- Consistency across different analysts
- Reproducibility of decisions
- Transparency in decision rationale
- Scalability for automated processing

$3

Domain experts can override quantitative results using expert judgment when:
- Context requires specialized knowledge
- Edge cases not covered by decision trees
- Organizational priorities differ from standard frameworks
- Time-sensitive decisions need immediate action

$3

1. Start with quantitative assessment using the library
2. Apply qualitative judgment to validate or override
3. Document rationale for any overrides
4. Learn and adapt decision trees based on expert feedback

Advanced Usage

$3

`javascript
import { DecisionCisa, CISAExploitationStatus, CISAAutomatableStatus } from 'ssvc';

const decision = new DecisionCisa({
exploitation: CISAExploitationStatus.ACTIVE,
automatable: CISAAutomatableStatus.YES,
technicalImpact: 'total',
missionWellbeingImpact: 'high'
});

const outcome = decision.evaluate();
`

$3

`javascript
import { PluginRegistry, SSVCPlugin } from 'ssvc';

// Register a custom plugin
const registry = PluginRegistry.getInstance();
registry.register(new MyCustomPlugin());

// List all registered methodologies
const methodologies = registry.list();
`

Creating Custom Methodologies

You can add new methodologies by creating schema-compliant YAML configuration files and generating TypeScript plugins:

1. Create a YAML file in the methodologies/ directory:

`yaml
name: "My Custom Methodology"
description: "Custom vulnerability categorization"
version: "1.0"

enums:
SeverityLevel:
- LOW
- MEDIUM
- HIGH

priorityMap:
IGNORE: low
MONITOR: medium
PATCH: high

decisionTree:
type: SeverityLevel
children:
HIGH: PATCH
MEDIUM: MONITOR
LOW: IGNORE

defaultAction: IGNORE
`

2. Validate your methodology:

`bash
just validate-methodologies
`

3. Generate the plugin:

`bash
yarn generate-plugins
`

4. Use your custom methodology:

`javascript
const decision = createDecision('My Custom Methodology', {
severity: 'high'
});
`

$3

Your YAML methodology must follow these requirements:

- Hierarchical Structure: Use nested type and children objects (not flat arrays)
- Consistent Depth: All paths from root to leaf must have identical depth
- Complete Mappings: Every action must have a priority mapping
- Valid Enums: All enum types used in the decision tree must be declared

See the Schema Documentation for detailed validation rules and migration guides.

Documentation

Each methodology includes auto-generated documentation with:

- Decision trees as mermaid diagrams
- Enum definitions and possible values
- Priority mappings between actions and priority levels
- Usage examples in TypeScript

See the docs/ directory for detailed methodology documentation, including:
- Schema Validation Guide
- Individual methodology documentation

Migration from Legacy API

The library maintains backward compatibility with the previous hardcoded API:

`javascript
// Legacy API (still works)
import { Decision, Exploitation, Automatable } from 'ssvc';

const decision = new Decision({
methodology: 'CISA',
exploitation: Exploitation.ACTIVE,
automatable: Automatable.YES,
technical_impact: 'total',
mission_wellbeing: 'high'
});

// New Plugin API (recommended)
import { createDecision } from 'ssvc';

const decision = createDecision('CISA', {
exploitation: 'active',
automatable: 'yes',
technical_impact: 'total',
mission_wellbeing: 'high'
});
`

Decision Trees

$3

`mermaid
flowchart LR
0{ExploitationStatus}
1{AutomatableStatus}
2{TechnicalImpactLevel}
3{MissionWellbeingImpactLevel}
4[ATTEND]
5{MissionWellbeingImpactLevel}
6[ATTEND]
7{TechnicalImpactLevel}
8{MissionWellbeingImpactLevel}
9[TRACK_STAR]
10{MissionWellbeingImpactLevel}
11[TRACK_STAR]
12{AutomatableStatus}
13{TechnicalImpactLevel}
14{MissionWellbeingImpactLevel}
15[TRACK_STAR]
16[ATTEND]
17{MissionWellbeingImpactLevel}
18[ATTEND]
19{TechnicalImpactLevel}
20{MissionWellbeingImpactLevel}
21[TRACK_STAR]
22{MissionWellbeingImpactLevel}
23[TRACK_STAR]
24[ATTEND]
25{AutomatableStatus}
26{TechnicalImpactLevel}
27{MissionWellbeingImpactLevel}
28[ATTEND]
29[ATTEND]
30[ACT]
31{MissionWellbeingImpactLevel}
32[ATTEND]
33[ACT]
34[ACT]
35{TechnicalImpactLevel}
36{MissionWellbeingImpactLevel}
37[ATTEND]
38{MissionWellbeingImpactLevel}
39[ATTEND]
40[ACT]
0 -->|NONE| 1
1 -->|YES| 2
2 -->|PARTIAL| 3
3 -->|HIGH| 4
2 -->|TOTAL| 5
5 -->|HIGH| 6
1 -->|NO| 7
7 -->|PARTIAL| 8
8 -->|HIGH| 9
7 -->|TOTAL| 10
10 -->|HIGH| 11
0 -->|POC| 12
12 -->|YES| 13
13 -->|TOTAL| 14
14 -->|MEDIUM| 15
14 -->|HIGH| 16
13 -->|PARTIAL| 17
17 -->|HIGH| 18
12 -->|NO| 19
19 -->|PARTIAL| 20
20 -->|HIGH| 21
19 -->|TOTAL| 22
22 -->|MEDIUM| 23
22 -->|HIGH| 24
0 -->|ACTIVE| 25
25 -->|YES| 26
26 -->|PARTIAL| 27
27 -->|LOW| 28
27 -->|MEDIUM| 29
27 -->|HIGH| 30
26 -->|TOTAL| 31
31 -->|LOW| 32
31 -->|MEDIUM| 33
31 -->|HIGH| 34
25 -->|NO| 35
35 -->|PARTIAL| 36
36 -->|HIGH| 37
35 -->|TOTAL| 38
38 -->|MEDIUM| 39
38 -->|HIGH| 40
`

Development

$3

`bash
yarn build
`

$3

`bash
yarn test
`

$3

`bash
just validate-methodologies
`

This validates all YAML files in methodologies/ against the schema and checks for:
- Structural consistency
- Tree depth uniformity
- Complete priority mappings
- Enum usage validation

$3

`bash
yarn generate-plugins
`

This will:
1. Validate all YAML files first
2. Process compliant YAML files in methodologies/
3. Generate TypeScript plugin files in src/plugins/
4. Create documentation with mermaid diagrams in docs/

Contributing

1. Create your methodology as a schema-compliant YAML file in methodologies/
2. Validate using just validate-methodologies
3. Generate the plugin with yarn generate-plugins`
4. Add tests for your methodology
5. Submit a pull request

See the Schema Documentation for detailed requirements and validation rules.

License

MIT