analyze-cve

name	analyze-cve
description	Analyze CVE vulnerability applicability and generate VEX assessment

CVE Analysis Skill

This skill provides instructions for analyzing whether a CVE (Common Vulnerabilities and Exposures) vulnerability applies to a codebase, and generating appropriate VEX (Vulnerability Exploitability eXchange) documentation.

When to Use This Skill

Use this skill when you need to:

• Determine if a reported CVE actually affects the codebase
• Generate a VEX assessment for a vulnerability
• Create security documentation for CVE triage

Analysis Process

When analyzing a CVE, follow these steps:

1. Understand the Vulnerability

Read and understand the CVE details:

• CVE ID: The unique identifier (e.g., CVE-2024-1234)
• Affected Package: The dependency with the vulnerability
• Affected Versions: Version range that contains the vulnerability
• Vulnerability Type: What kind of issue (RCE, XSS, SQL injection, etc.)
• Attack Vector: How the vulnerability can be exploited
• CVSS Score: Severity rating (Critical, High, Medium, Low)

2. Examine Dependency Usage

Search the codebase to understand how the affected dependency is used:

• Find all import/require statements for the package
• Identify which modules and functions from the package are used
• Map the call sites and data flow
• Check if the vulnerable code path is reachable

3. Assess Applicability

Determine if the vulnerability applies based on:

Not Affected - Use when:

• code_not_reachable: The vulnerable function/code path is never called
• code_not_present: The vulnerable code was removed or never included
• requires_configuration: Vulnerability requires specific config not present
• requires_dependency: Vulnerability requires another dependency not present
• requires_environment: Vulnerability requires specific environment not present
• protected_by_compiler: Compiler/runtime protections prevent exploitation
• protected_by_mitigating_control: Other security controls prevent exploitation

Affected - Use when:

• The vulnerable code path IS reachable
• The application could be exploited via this vulnerability
• Immediate action is needed

Under Investigation - Use when:

• More analysis is needed to determine applicability
• Complex code paths require deeper review

Fixed - Use when:

• The vulnerability has been patched
• The dependency has been updated to a non-vulnerable version

4. Document Your Analysis

For each CVE, record:

• How the dependency is used in the codebase
• Which functions/methods are called
• Whether the vulnerable code path is reachable
• Any mitigating factors or controls
• Confidence level in the assessment

Output Requirements

VEX Document (CycloneDX JSON)

Generate a CycloneDX 1.6 VEX document with this structure:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "version": 1,
  "metadata": {
    "timestamp": "<ISO 8601 timestamp>",
    "tools": [
      {
        "vendor": "patch-inator",
        "name": "analyze-cve",
        "version": "1.0.0"
      }
    ]
  },
  "vulnerabilities": [
    {
      "id": "<CVE-ID>",
      "source": {
        "name": "NVD",
        "url": "https://nvd.nist.gov/vuln/detail/<CVE-ID>"
      },
      "ratings": [
        {
          "source": { "name": "NVD" },
          "score": <CVSS score>,
          "severity": "<critical|high|medium|low>",
          "method": "CVSSv3"
        }
      ],
      "description": "<Brief description of the vulnerability>",
      "analysis": {
        "state": "<not_affected|affected|fixed|under_investigation>",
        "justification": "<code_not_reachable|code_not_present|requires_configuration|requires_dependency|requires_environment|protected_by_compiler|protected_by_mitigating_control>",
        "detail": "<Detailed explanation of why this assessment was made>",
        "response": ["<will_not_fix|update|workaround_available|none>"]
      },
      "affects": [
        {
          "ref": "<PURL of affected component>"
        }
      ],
      "recommendation": "<Recommended action if any>"
    }
  ]
}

PURL Format: Package URLs should follow the PURL specification:

• npm: pkg:npm/package-name@version
• PyPI: pkg:pypi/package-name@version
• Maven: pkg:maven/group-id/artifact-id@version
• Go: pkg:golang/module-path@version

Markdown Report

Generate a human-readable markdown report for docs/security/:

# Security Analysis: <CVE-ID>

**Date**: <YYYY-MM-DD>
**Analyst**: patch-inator
**Status**: <Not Affected | Affected | Under Investigation | Fixed>

## Vulnerability Summary

| Field | Value |
|-------|-------|
| CVE ID | <CVE-ID> |
| Severity | <Critical/High/Medium/Low> |
| CVSS Score | <score> |
| Affected Package | <package-name> |
| Affected Versions | <version range> |
| Installed Version | <current version> |

## Description

<Brief description of what the vulnerability is and how it could be exploited>

## Analysis

### Dependency Usage

<Explain how the affected package is used in this codebase>

### Vulnerable Code Path

<Analysis of whether the vulnerable code path is reachable>

### Assessment

**Status**: <status>
**Justification**: <justification reason>

<Detailed explanation of the assessment>

## Evidence

<List of files examined, code snippets analyzed, etc.>

## Recommendation

<What action (if any) should be taken>

## References

- [NVD Entry](https://nvd.nist.gov/vuln/detail/<CVE-ID>)
- [GitHub Advisory](https://github.com/advisories/<GHSA-ID>) (if applicable)
- <Other relevant links>

File Naming Convention

• VEX document: .patch-inator/vex/<CVE-ID>.vex.cdx.json
• Markdown report: docs/security/<YYYY-MM-DD>-<CVE-ID>.md

Example Analysis

Input: CVE Context File

{
  "cve_id": "CVE-2024-1234",
  "package": "lodash",
  "version": "4.17.20",
  "severity": "high",
  "cvss": 7.5,
  "description": "Prototype pollution in lodash.set() function",
  "affected_versions": "< 4.17.21",
  "advisory_url": "https://nvd.nist.gov/vuln/detail/CVE-2024-1234"
}

Analysis Steps

1. Search for lodash usage:

   grep -r "require.*lodash\|import.*lodash" --include="*.js" --include="*.ts"
   

2. Find lodash.set() calls:

   grep -r "\.set\s*(" --include="*.js" --include="*.ts"
   

3. Analyze if prototype pollution is exploitable based on:

   • Source of input to set() function
   • Whether user input reaches this code path
   • Presence of input validation

Assessment Decision Tree

Is the vulnerable function (set) called?
├─ No → NOT AFFECTED (code_not_reachable)
└─ Yes → Is user input passed to it?
    ├─ No → NOT AFFECTED (requires_configuration)
    └─ Yes → Is input validated?
        ├─ Yes, sufficiently → NOT AFFECTED (protected_by_mitigating_control)
        └─ No → AFFECTED (needs remediation)

Best Practices

1. Be Thorough: Check all code paths, not just obvious ones
2. Be Conservative: When uncertain, mark as "under_investigation"
3. Document Everything: Record all evidence for future reference
4. Consider Context: A vulnerability's real risk depends on deployment context
5. Update State: Record analysis progress in .patch-inator/state.json

State Integration

Update the patch-inator state after analysis:

# Source state utilities
source scripts/utils/state.sh

# Update analysis status
state_set "analyses.${CVE_ID}.status" "completed"
state_set "analyses.${CVE_ID}.result" "not_affected"
state_set_timestamp "analyses.${CVE_ID}.completed_at"

Related Scripts

• scripts/vex/generate.sh - Generate VEX documents
• scripts/vex/generate-report.sh - Generate markdown reports
• scripts/sbom/merge-vex.sh - Merge VEX back into SBOM
• scripts/pr/create.sh - Create PR with VEX and report