Metadata-Version: 2.4
Name: sbom-sentinel
Version: 1.1.1
Summary: End-to-end SBOM generation and vulnerability intelligence pipeline
Project-URL: Repository, https://github.com/Dashtid/sbom-sentinel
Project-URL: Issues, https://github.com/Dashtid/sbom-sentinel/issues
Author: David Dashti
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.32
Requires-Dist: rich>=13.0
Provides-Extra: pdf
Requires-Dist: markdown-it-py>=3.0; extra == 'pdf'
Requires-Dist: weasyprint>=63; extra == 'pdf'
Description-Content-Type: text/markdown

# sbom-sentinel

[![CI](https://github.com/Dashtid/sbom-sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/Dashtid/sbom-sentinel/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Dashtid/sbom-sentinel/branch/main/graph/badge.svg)](https://codecov.io/gh/Dashtid/sbom-sentinel)
[![PyPI](https://img.shields.io/pypi/v/sbom-sentinel)](https://pypi.org/project/sbom-sentinel/)

End-to-end SBOM generation and vulnerability intelligence pipeline.

Wraps [Syft](https://github.com/anchore/syft) and [Grype](https://github.com/anchore/grype) behind a six-command CLI. Enriches results with the CISA Known Exploited Vulnerabilities (KEV) catalog, supports OpenVEX / CSAF suppression, and produces Markdown, HTML, or audit-ready PDF reports.

## Installation

Requires [Syft](https://github.com/anchore/syft#installation) and [Grype](https://github.com/anchore/grype#installation) on `PATH`.

```bash
pip install sbom-sentinel
```

For PDF output, install the optional extra (needs a [GTK runtime](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation) on Windows):

```bash
pip install 'sbom-sentinel[pdf]'
```

## Quick start

Run the full pipeline against a directory, container image, or Git URL:

```bash
sbom-sentinel run --target ./myapp           --name myapp --fail-on critical
sbom-sentinel run --target docker:nginx:1.27 --name nginx --fail-on critical
sbom-sentinel run --target https://github.com/org/repo --name repo --fail-on critical
```

Each stage is also available standalone:

```bash
sbom-sentinel sbom   --target ./myapp --name myapp
sbom-sentinel scan   --sbom sbom_output/myapp_*.spdx.json --name myapp
sbom-sentinel report --scan artifacts/json/myapp_*.json   --name myapp
```

## Commands

| Command | Purpose |
|---------|---------|
| `sbom` | Generate an SPDX-JSON SBOM via Syft |
| `scan` | Scan an SBOM via Grype, output JSON or SARIF |
| `report` | Render Markdown or HTML report with KEV enrichment |
| `diff` | Compare two scans, surface new / resolved CVEs |
| `pdf` | Convert an edited markdown report into a PDF audit deliverable |
| `run` | Orchestrate the full pipeline end-to-end |

Pass `--help` to any command for the complete option reference.

## Workflows

### VEX suppression with KEV conflict detection

```bash
sbom-sentinel run --sbom sbom.spdx.json --name myapp --vex statements.vex.json
```

Findings marked `not_affected` in the VEX document are suppressed. If a suppressed CVE is also in the CISA KEV catalog, the report flags it as a conflict requiring manual review.

### PDF audit deliverables

```bash
sbom-sentinel run --target ./myapp --name myapp        # produces markdown
$EDITOR artifacts/reports/markdown/myapp_*.md          # fill Assessment + Conclusion blocks
sbom-sentinel pdf                                      # latest markdown -> PDF
```

Each Conclusion blockquote should contain `Not applicable`, `Acceptable`, or `Unacceptable`. The PDF includes an auto-populated Assessment Matrix derived from those classifications. Unfilled entries are auto-classified by a heuristic (Negligible -> Not applicable; KEV-flagged Critical/High -> Unacceptable) or surfaced as Pending.

### Diff between scans

```bash
sbom-sentinel diff \
  --old artifacts/json/myapp_20260101.json \
  --new artifacts/json/myapp_20260201.json \
  --name myapp
```

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Runtime error — tool not found, scan threshold met, timeout, or parse failure |
| `2` | Usage error — missing required option or invalid argument |

## Development

```bash
git clone https://github.com/Dashtid/sbom-sentinel.git
cd sbom-sentinel
uv sync
uv run pytest
```

Coverage gate: 100% line + 100% branch. Lint, type, and security checks all run in CI. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for an overview of the codebase.

## License

[MIT](LICENSE)
