Metadata-Version: 2.4
Name: ai-assisted-vulnerability-triage
Version: 0.4.2
Summary: AI-assisted vulnerability triage, reachability analysis, false-positive detection, risk scoring, and remediation intelligence.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.23
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Provides-Extra: ai
Requires-Dist: openai; extra == "ai"
Requires-Dist: pydantic>=2.0; extra == "ai"

# 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:

```bash
python -m build
```

Install the wheel:

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

Or install the source distribution:

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

Verify the installation:

```bash
vuln-triage --version
```

## Basic Usage

Run the canonical findings dataset:

```bash
vuln-triage dataset/findings.json
```

Generate JSON output:

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

Write output to a file:

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

## Semgrep

Process Semgrep findings:

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

## Optional AI Explanations

Enable the optional AI explanation provider:

```bash
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:

```bash
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:

```bash
vuln-triage \
  --history \
  PREVIOUS_SNAPSHOT \
  CURRENT_SNAPSHOT
```

Lifecycle classification includes:

* NEW
* UNCHANGED
* CHANGED
* RESOLVED
* REAPPEARED

## History Directory

Generate a multi-scan lifecycle report:

```bash
vuln-triage \
  --history-dir .history
```

Generate JSON:

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

## Lifecycle Trends

Analyze finding behavior across the complete scan history:

```bash
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:

```text
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:

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

Aggregate metrics include:

```text
Findings With Changes
Findings Ever Resolved
Findings Ever Reappeared
Findings With Multiple Changes
```

Example lifecycle:

```text
NEW -> CHANGED -> RESOLVED -> REAPPEARED
```

## CLI Help

```bash
vuln-triage --help
```

```bash
vuln-triage --version
```

## Development

Create a virtual environment:

```bash
python -m venv venv
source venv/bin/activate
```

Install development dependencies:

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

Install optional AI dependencies:

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

## Testing

Run the complete test suite:

```bash
python -m pytest -q
```

Validate Python syntax:

```bash
python -m py_compile auditor/*.py
```

Check whitespace:

```bash
git diff --check
```

Check dependencies:

```bash
python -m pip check
```

## Building Distributions

Build the wheel and source distribution:

```bash
python -m build
```

Validate the distributions:

```bash
python -m twine check dist/*
```

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

## Project Structure

```text
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:

```text
0.4.2
```

## License

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