Metadata-Version: 2.4
Name: ubuntu-vulnerability-engine
Version: 1.1.1
Summary: A production-quality, read-only Ubuntu vulnerability auditing engine.
Author-email: Developer <developer@example.com>
Project-URL: Homepage, https://github.com/yourusername/ubuntu-vuln-tracker
Project-URL: Bug Tracker, https://github.com/yourusername/ubuntu-vuln-tracker/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: SQLAlchemy>=2.0.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: opentelemetry-api>=1.26.0
Requires-Dist: opentelemetry-sdk>=1.26.0
Requires-Dist: Jinja2>=3.1.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: pip-audit; extra == "dev"
Requires-Dist: types-toml; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-requests; extra == "dev"

<div align="center">
  <h1>🛡️ Ubuntu Vulnerability Engine (UVE)</h1>
  <p><i>A production-quality, read-only Ubuntu vulnerability auditing engine with advanced threat intelligence.</i></p>

  [![CI Pipeline](https://img.shields.io/github/actions/workflow/status/yourusername/ubuntu-vulnerability-engine/test.yml?branch=main&label=CI%20Pipeline)](https://github.com/yourusername/ubuntu-vulnerability-engine/actions)
  [![PyPI Version](https://img.shields.io/pypi/v/ubuntu-vulnerability-engine.svg)](https://pypi.org/project/ubuntu-vulnerability-engine/)
  [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
  [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
</div>

---

## 📖 High-Level System Overview

The **Ubuntu Vulnerability Engine (UVE)** is a specialized, read-only security auditing platform. It accurately determines whether installed Ubuntu/Debian packages or container images are affected by known security vulnerabilities. It dynamically correlates local software footprints with Canonical's real-time OSV database, the CISA Known Exploited Vulnerabilities (KEV) catalog, and FIRST.org Exploit Prediction Scoring System (EPSS).

**Core Directive**: UVE operates on a strict **read-only** policy. The engine will *never* patch, remove, execute, or otherwise modify the scanned target. It is designed purely for deep-dive laboratory research, CI/CD DevSecOps integration, and compliance reporting.

## ✨ Features

- **Native Container Scanning**: Deep-scan Docker/OCI images without executing them (`docker cp` filesystem extraction).
- **SBOM Ingestion**: Natively parse and scan CycloneDX v1.5 JSON Software Bill of Materials.
- **Advanced Threat Intelligence**: Autonomously cross-references vulnerabilities against **EPSS probabilities** and the **CISA KEV** catalog.
- **Canonical OSV Integration**: Connects directly to Ubuntu's authoritative vulnerability database with local caching.
- **Rich Reporting**: Outputs human-readable terminal tables, JSON for machine processing, and SARIF v2.1.0 for native GitHub Advanced Security ingestion.
- **Advanced Policy Engine**: Enforce explicit CI/CD failure thresholds (`fail_on`, `minimum_epss`) alongside time-bound false-positive suppression via `uvt-ignore.yml`.
- **Docker Ready**: Run scans seamlessly using the official lightweight container image.

## 🏗️ Architecture Diagram

```mermaid
flowchart TD
    subgraph Targets
        L[Local System] -->|dpkg / os-release| E(Risk Engine)
        D[Docker Image] -->|docker cp extraction| E
        O[CycloneDX SBOM] -->|JSON Parser| E
    end

    subgraph Intelligence
        C[Canonical OSV] --> CA[(Intelligence Cache)]
        K[CISA KEV] --> CA
        P[FIRST.org EPSS] --> CA
        CA --> E
    end

    subgraph Policy
        I[uvt-ignore.yml] -->|Filter/Thresholds| E
    end

    subgraph Output
        E --> R1[Terminal Table]
        E --> R2[SARIF File]
        E --> R3[JSON Export]
    end
```

## 🚀 Quick Start

### Installation

UVE is distributed via PyPI and requires Python 3.10+:

```bash
pip install ubuntu-vulnerability-engine
```

### Running Scans

Scan the **local host machine** (must be Ubuntu/Debian):
```bash
uvt scan
```

Scan a **Docker container image** (requires local Docker daemon):
```bash
uvt scan image ubuntu:22.04
```

Scan a **CycloneDX SBOM**:
```bash
uvt scan sbom application-sbom.json
```

## 🐳 Docker Support

UVE is fully containerized. You can run the scanner without installing Python on your host.

To scan your host machine using the Docker image:
```bash
docker run --rm -v /:/hostfs:ro ubuntu-vulnerability-engine scan --root /hostfs
```
*(The `--root` flag tells the engine to scan the mounted filesystem instead of the container's own filesystem).*

## 🖼️ Example Outputs

### Terminal Console
```text
                            Vulnerability Findings                             
+-----------------------------------------------------------------------------+
| Package  | Installed       | Fixed Version   | CVE/USN          | Status  |
|----------+-----------------+-----------------+------------------+---------|
| openssl  | 3.0.2-0ubuntu1  | 3.0.2-0ubuntu1.1| CVE-2022-2068    | FIXED   |
| curl     | 7.81.0-1ubuntu1 | None            | CVE-2023-38545   | VULN    |
+-----------------------------------------------------------------------------+
```

## ⚙️ Configuration Reference

### Policy Engine (`uvt-ignore.yml`)
You can suppress false positives and enforce CI/CD failure thresholds by dropping a `uvt-ignore.yml` file into your project. 

```yaml
version: 1

# Fail the CI pipeline if these thresholds are met
fail_on:
  - critical
  - high
minimum_epss: 0.30

# Ignore specific CVEs
ignore:
  - cve: CVE-2026-0001
    reason: "Service is isolated behind a WAF; risk accepted."
    expires: "2026-12-31"  # Will trigger as VULNERABLE again after this date
```

Run the scan using the policy:
```bash
uvt scan image myapp:latest --ignore-file uvt-ignore.yml
```

## 📁 Folder Structure

```text
ubuntu_vulnerability_engine/
├── src/ubuntu_vulnerability_engine/
│   ├── analysis/       # Vulnerability comparison and Risk Engine
│   ├── discovery/      # Target parsing (Local, Docker, SBOM)
│   ├── intelligence/   # OSV, KEV, and EPSS data providers
│   ├── models/         # Pydantic data models (Target, Finding)
│   ├── policy/         # Thresholds and Ignore rule engine
│   ├── reporting/      # Output formatters (Console, SARIF, JSON)
│   ├── cli.py          # Typer CLI entrypoint
│   └── config.py       # Global configurations
├── tests/              # Comprehensive Pytest regression suite
├── lab/                # Test fixtures and offline payloads
├── pyproject.toml      # PyPI package metadata
├── Dockerfile          # Production container image definition
└── README.md
```

## 🚥 CI/CD Status
UVE natively supports CI/CD environments. Use the `--format sarif` flag to output results ready for ingestion by GitHub Advanced Security or GitLab SAST.

```bash
uvt scan image myapp:latest --format sarif > results.sarif
```
If the `uvt-ignore.yml` thresholds are breached, the CLI will exit with code `1`, instantly failing the pipeline build.

## 🛤️ Roadmap

- **Completed**: Advanced Intelligence (EPSS/KEV), Container scanning, SBOM parsing, Policy thresholds, PyPI deployment.
- **Future Enhancements**:
  - Webhook alerts for newly discovered CISA KEV entries.
  - Interactive HTML reporting dashboards.

## 🔐 Security Considerations

- **Read-Only**: The CLI requires absolutely no root privileges to perform container image scans or SBOM generation.
- **Air-Gapped Ready**: Once the intelligence cache (`~/.cache/uvt/`) is populated, UVE can operate entirely offline without external network calls.
- **Zero-Execution Scanning**: Untrusted Docker images are *never* executed. Their filesystems are extracted entirely using the `docker create` API safely.

## 🛠️ Contributing Guide

We welcome contributions! To set up your development environment:

1. Clone the repository.
2. Install development dependencies: `pip install -e ".[dev]"`
3. Run linting: `ruff check .`
4. Run static type checking: `mypy src/`
5. Run the test suite: `pytest`

Please ensure all 26+ tests pass and your code is strictly typed before opening a Pull Request.

## 📝 Changelog

- **v0.1.0**
  - Renamed from tracker to Ubuntu Vulnerability Engine (UVE).
  - Implemented non-executing Docker image scanning.
  - Implemented CycloneDX SBOM ingestion.
  - Integrated CISA KEV and EPSS threat intelligence.
  - Upgraded Policy Engine with CI/CD failure thresholds.
  - Published to PyPI.

## ❓ Troubleshooting & FAQ

**Q: I get `Cannot find /var/lib/dpkg/status` when running `uvt scan` on Windows/Mac.**
A: The standard `uvt scan` command only works natively on Ubuntu/Debian hosts. On Windows or Mac, scan a container image instead (`uvt scan image ubuntu:22.04`).

**Q: Why does the first scan take a few seconds longer?**
A: UVE downloads the authoritative OSV, KEV, and EPSS datasets on the first run. Subsequent runs load instantly from the local cache (`~/.cache/uvt/`).

**Q: How do I force a cache refresh?**
A: Run your scan with the `--no-cache` flag, or run `uvt cache --clear` (coming soon!).

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
