Metadata-Version: 2.4
Name: sbom-sentinel
Version: 1.0.2
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
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)
[![PyPI](https://img.shields.io/pypi/v/sbom-sentinel)](https://pypi.org/project/sbom-sentinel/)

SBOM generation and vulnerability intelligence pipeline.

Wraps [Syft](https://github.com/anchore/syft) and [Grype](https://github.com/anchore/grype) behind a five-command CLI, enriches results with the CISA Known Exploited Vulnerabilities (KEV) catalog, and produces a timestamped Markdown report.

## Installation

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

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

## Quick Start

Run the full pipeline (SBOM + scan + report) in one command:

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

Or run each stage individually:

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

Generate an HTML report instead of Markdown:

```bash
sbom-sentinel run --target ./myapp --name myapp --report-format html
```

Compare two scans to see what changed:

```bash
sbom-sentinel diff --old artifacts/json/myapp_old.json --new artifacts/json/myapp_new.json --name myapp
```

## Features

- SPDX-JSON SBOMs from local directories, container images, or Git URLs
- Vulnerability scanning via Grype with severity gating (`--fail-on`)
- CISA KEV enrichment with date-stamped local cache
- OpenVEX / CSAF suppression with KEV conflict detection
- Markdown or standalone HTML reports
- JSON or SARIF scan output for GitHub Code Scanning
- Verbose mode (`-v`) for diagnostic output

## Commands

| Command | Description |
|---------|-------------|
| `sbom` | Generate an SPDX-JSON SBOM via Syft |
| `scan` | Scan an SBOM for vulnerabilities via Grype |
| `report` | Generate a Markdown or HTML report with KEV enrichment |
| `diff` | Compare two scans and report new / resolved CVEs |
| `run` | Run the full pipeline (sbom + scan + report, or scan + report from an existing SBOM) |

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

### VEX suppression

Pass an OpenVEX or CSAF document to suppress findings marked `not_affected`. Any suppressed CVE that also appears in CISA KEV is flagged as a conflict requiring manual review.

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

## 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
uv run ruff check .
uv run mypy sbom_sentinel
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
