ai-assisted-vulnerability-triage

AI-Assisted Vulnerability Triage

AI-assisted vulnerability triage for scanner findings, combining vulnerability analysis, reachability assessment, false-positive detection, risk scoring, remediation guidance, and historical lifecycle analytics.

Features

• Vulnerability triage and prioritization
• Reachability analysis
• False-positive detection
• Risk and impact analysis
• MITRE ATT&CK mapping
• Remediation guidance
• Canonical JSON and Semgrep input
• Human-readable and JSON output
• Optional AI-generated explanations
• Immutable scan snapshots
• Two-scan lifecycle comparison
• Multi-scan lifecycle history
• Lifecycle trend analytics
• Lifecycle transition analytics
• Lifecycle insight metrics

Requirements

• Python 3.12 or newer

Installation

Build the package:

python -m build

Install the wheel:

python -m pip install dist/ai_assisted_vulnerability_triage-0.4.2-py3-none-any.whl

Or install the source distribution:

python -m pip install dist/ai_assisted_vulnerability_triage-0.4.2.tar.gz

Verify the installation:

vuln-triage --version

Basic Usage

Run the canonical findings dataset:

vuln-triage dataset/findings.json

Generate JSON output:

vuln-triage dataset/findings.json --format json

Write output to a file:

vuln-triage dataset/findings.json \
  --format json \
  --output report.json

Semgrep

Process Semgrep findings:

vuln-triage \
  tests/fixtures/semgrep-results.json \
  --scanner semgrep

Optional AI Explanations

Enable the optional AI explanation provider:

vuln-triage \
  dataset/findings.json \
  --ai-explain

The required AI provider configuration must be available in the runtime environment.

Scan Snapshots

Persist an immutable scan snapshot:

vuln-triage \
  dataset/findings.json \
  --snapshot-dir .history

Snapshots are stored as scan-specific JSON files in the selected history directory.

Compare Two Scans

Compare two persisted snapshots:

vuln-triage \
  --history \
  PREVIOUS_SNAPSHOT \
  CURRENT_SNAPSHOT

Lifecycle classification includes:

• NEW
• UNCHANGED
• CHANGED
• RESOLVED
• REAPPEARED

History Directory

Generate a multi-scan lifecycle report:

vuln-triage \
  --history-dir .history

Generate JSON:

vuln-triage \
  --history-dir .history \
  --format json

Lifecycle Trends

Analyze finding behavior across the complete scan history:

vuln-triage \
  --history-dir .history \
  --trends

Trend analytics include:

• Unique findings
• Active findings
• Resolved findings
• Changed findings
• Reappeared findings
• Persistent findings
• Per-finding timelines
• Transition counts
• Lifecycle insights

Transition Analytics

Lifecycle transitions include:

NEW->UNCHANGED
NEW->CHANGED
UNCHANGED->RESOLVED
CHANGED->RESOLVED
RESOLVED->REAPPEARED

Trend reports include total transition counts, transition frequencies, and per-finding transition histories.

Lifecycle Insights

Per-finding insights include:

Change Count
Resolution Count
Reappearance Count
Ever Changed
Ever Resolved
Ever Reappeared

Aggregate metrics include:

Findings With Changes
Findings Ever Resolved
Findings Ever Reappeared
Findings With Multiple Changes

Example lifecycle:

NEW -> CHANGED -> RESOLVED -> REAPPEARED

CLI Help

vuln-triage --help

vuln-triage --version

Development

Create a virtual environment:

python -m venv venv
source venv/bin/activate

Install development dependencies:

python -m pip install -e ".[dev]"

Install optional AI dependencies:

python -m pip install -e ".[ai]"

Testing

Run the complete test suite:

python -m pytest -q

Validate Python syntax:

python -m py_compile auditor/*.py

Check whitespace:

git diff --check

Check dependencies:

python -m pip check

Building Distributions

Build the wheel and source distribution:

python -m build

Validate the distributions:

python -m twine check dist/*

The repository includes GitHub Actions workflows for testing and publishing Python package distributions.

Project Structure

auditor/
    Core triage and analysis modules
    lifecycle.py
    lifecycle_report.py
    scan_history.py
    schema_validation.py
    schemas/
        batch-result-v1.json

dataset/
    findings.json

docs/
    schemas/
        batch-result-v1.json

tests/
    Unit and integration tests

.github/workflows/
    tests.yml
    publish.yml

pyproject.toml
README.md

Version

Current package version:

0.4.2

License

Add the project's license information before public release if a license has not already been selected.