Metadata-Version: 2.4
Name: sbom-sentinel
Version: 0.1.0
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 :: 3 - Alpha
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)

SBOM generation and vulnerability intelligence pipeline for local directories, container images, and Git repositories.

Wraps [Syft](https://github.com/anchore/syft) and [Grype](https://github.com/anchore/grype) behind a four-command CLI, enriches results with the CISA Known Exploited Vulnerabilities (KEV) catalog, and produces a timestamped Markdown report per run. A GitHub Actions workflow ships with the repo for continuous scanning on every push.

## Features

- Generate SPDX-JSON SBOMs from local directories, container images, or Git URLs
- Scan for vulnerabilities via Grype with optional severity gating (`--fail-on`)
- Enrich results with the CISA KEV catalog; flagged CVEs are marked `[KEV]` in the report
- Suppress findings via OpenVEX or CSAF documents; KEV conflicts are called out explicitly
- Output scan results as JSON (default) or SARIF for GitHub Code Scanning
- Date-stamped KEV cache; degrades gracefully when the catalog is unreachable

## Prerequisites

| Tool | Purpose | Install |
|------|---------|---------|
| [Syft](https://github.com/anchore/syft) | SBOM generation | `curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \| sh -s -- -b /usr/local/bin` |
| [Grype](https://github.com/anchore/grype) | Vulnerability scanning | `curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh \| sh -s -- -b /usr/local/bin` |
| Python >= 3.11 | Runtime | [python.org](https://www.python.org/downloads/) |
| [uv](https://docs.astral.sh/uv/) | Package manager | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |

## Installation

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

To install into an existing project without cloning:

```bash
uv add git+https://github.com/Dashtid/sbom-sentinel.git
```

## Quick Start

Full three-stage pipeline against a local directory:

```bash
# Stage 1 — generate SBOM
sbom-sentinel sbom --target ./myapp --name myapp

# Stage 2 — scan (fail the build if High or Critical CVEs are found)
sbom-sentinel scan \
  --sbom sbom_output/myapp.spdx.json \
  --name myapp \
  --fail-on high

# Stage 3 — generate Markdown report with CISA KEV enrichment
sbom-sentinel report \
  --scan results/json/myapp_<timestamp>.json \
  --name myapp
```

Stages 2 and 3 can be run together with `run`:

```bash
sbom-sentinel run \
  --sbom sbom_output/myapp.spdx.json \
  --name myapp \
  --fail-on high
```

Container image target:

```bash
sbom-sentinel sbom --target docker:nginx:latest --name nginx
```

Remote Git repository:

```bash
sbom-sentinel sbom --target https://github.com/org/repo --name repo
```

## Commands

| Command | Description |
|---------|-------------|
| `sbom` | Stage 1: generate an SPDX-JSON SBOM via Syft |
| `scan` | Stage 2: scan an SBOM for vulnerabilities via Grype |
| `report` | Stage 3: generate a Markdown report with KEV enrichment |
| `run` | Orchestrator: run stages 2 and 3 in sequence |

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

```bash
sbom-sentinel scan --help
```

### 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 in the report as a conflict requiring manual review.

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

## CI/CD

[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on every push to `main` and on pull requests:

- **Lint** — `ruff check` with GitHub annotations
- **Type check** — `mypy` in strict mode
- **Test** — `pytest` with coverage

[Dependabot](.github/dependabot.yml) opens PRs weekly for GitHub Actions and Python dependency updates.

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup and contribution guidelines.

```bash
uv sync                        # install all dependencies
uv run pytest                  # run the test suite
uv run ruff check .            # lint
uv run mypy sbom_sentinel      # type check
```
