Metadata-Version: 2.4
Name: ubuntu-vulnerability-engine
Version: 0.1.0
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: 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"

<div align="center">
  <h1>🛡️ Ubuntu Vulnerability Tracker (UVT)</h1>
  <p><i>A production-quality, read-only Ubuntu vulnerability auditing engine.</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)
  [![Security Scan](https://img.shields.io/github/actions/workflow/status/yourusername/ubuntu-vulnerability-engine/security.yml?branch=main&label=Security%20Scan)](https://github.com/yourusername/ubuntu-vulnerability-engine/actions)
  [![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 Tracker (UVT)** is a specialized, read-only security auditing platform. It determines whether installed Ubuntu/Debian packages are affected by known security vulnerabilities by dynamically correlating local system configurations with Canonical's real-time OSV (Open Source Vulnerability) database.

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

## ✨ Features

- **Offline Target Scanning**: Scan air-gapped systems or CI/CD container artifacts using offline JSON/TXT footprints.
- **Local Host Scanning**: Rapidly scan the live machine you are currently running on.
- **Canonical OSV Integration**: Connects directly to Ubuntu's authoritative vulnerability database, automatically handling dataset caching and chunked parsing.
- **CycloneDX SBOM Generation**: Convert any target footprint into a standard CycloneDX v1.5 JSON Software Bill of Materials.
- **Rich Reporting**: Outputs human-readable terminal tables, JSON for machine processing, and SARIF v2.1.0 for native GitHub Advanced Security ingestion.
- **Ignore Policies**: Advanced `uvt-ignore.yml` configuration with time-bound expiration logic to suppress false positives.
- **100% Typed & Tested**: Enforced by strict `mypy` annotations and comprehensive `pytest` regression suites.

## 🏗️ Architecture Diagram

```mermaid
flowchart TD
    subgraph Targets
        L[Local System] -->|dpkg / lsb_release| E(Analysis Engine)
        O[Offline Footprint JSON/TXT] -->|File Parsers| E
    end

    subgraph Intelligence
        C[Canonical OSV Endpoint] -->|Download/Extract| CA[(Local JSON Cache)]
        CA -->|Provide CVE/USN| E
    end

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

    subgraph Output
        E -->|Findings| R1[Rich Terminal Table]
        E -->|Findings| R2[SARIF File]
        E -->|Findings| R3[JSON Export]
        E -->|Target| R4[CycloneDX SBOM]
    end
```

## 🚀 Quick Start

### Installation

UVT requires Python 3.10 or higher.

```bash
# Clone the repository
git clone https://github.com/yourusername/ubuntu-vulnerability-engine.git
cd ubuntu-vulnerability-engine

# Install the package locally
pip install -e .
```

### Running Your First Scan

Scan the local machine and output a rich table to the console:
```bash
uvt scan-local
```

Scan an offline target using exported package lists (e.g. from a Docker container):
```bash
uvt scan-file target.json packages.txt
```

Generate a CycloneDX Software Bill of Materials (SBOM):
```bash
uvt sbom target.json packages.txt > sbom.json
```

## 🖼️ Example Outputs

### Terminal Console (Table)
```text
                            Vulnerability Findings                             
+-----------------------------------------------------------------------------+
|             | Installed       |                 |                  |        |
| Package     | Version         | Fixed Version   | CVE/USN          | Status |
|-------------+-----------------+-----------------+------------------+--------|
| tar         | 1.34+dfsg-1ubu~ | 1.34+dfsg-1bui~ | UBUNTU-CVE-2021~ | FIXED  |
| bash        | 5.1-6ubuntu1.1  | 5.1-6ubuntu1.1  | UBUNTU-CVE-2022~ | FIXED  |
| gzip        | 1.10-4ubuntu4.2 | 1.10-4ubuntu4   | UBUNTU-CVE-2022~ | FIXED  |
+-----------------------------------------------------------------------------+
```

## ⚙️ Configuration Reference

### Ignore Policies (`uvt-ignore.yml`)
You can suppress known false positives or accepted risks using an ignore file. Create a file named `uvt-ignore.yml`:

```yaml
version: 1
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-local --ignore-file uvt-ignore.yml
```

## 📁 Folder Structure

```text
ubuntu_vulnerability_engine/
├── src/ubuntu_vulnerability_engine/
│   ├── analysis/       # Vulnerability comparison and detection logic
│   ├── discovery/      # Target parsing (offline files and local system)
│   ├── intelligence/   # OSV data providers and local caching
│   ├── models/         # Pydantic data models (Target, Package, Finding)
│   ├── policy/         # Ignore rules and suppressions
│   ├── reporting/      # Output formatters (Console, SARIF, JSON, CycloneDX)
│   ├── cli.py          # Typer CLI entrypoint
│   └── config.py       # Global configurations
├── tests/              # Pytest regression suite
├── lab/                # Test fixtures and offline scanning payloads
├── .github/workflows/  # CI/CD and DevSecOps pipelines
├── pyproject.toml      # Project dependencies and metadata
└── README.md
```

## 🐳 Docker Support

You can use Docker to create isolated lab environments for testing offline footprints:

```bash
# Build the vulnerable lab container
docker build -t vuln-lab-jammy -f Dockerfile .

# Export its footprint
docker run --rm vuln-lab-jammy dpkg-query -W -f='${Package}\t${Version}\t${Architecture}\t${Status}\n' > lab/jammy_packages.txt

# Scan the footprint from the host
uvt scan-file lab/jammy_target.json lab/jammy_packages.txt
```

## 🛤️ Roadmap

- **Phase 1-7**: Complete (Architecture, Engine, Caching, Reporting, GitHub Actions, SBOM, Ignore Policies).
- **Future Enhancements**:
  - Direct Container Image Scanning (ingesting `docker save` tarballs).
  - Webhook alerts for newly discovered CVEs.
  - Exploit Prediction Scoring System (EPSS) integration.

## 🔐 Security Considerations

- **Read-Only**: The CLI requires absolutely no root privileges to perform offline file scans (`scan-file`) or SBOM generation.
- **Air-Gapped Ready**: Once the OSV cache (`~/.cache/uvt/vuln_cache.json`) is populated, UVT can operate entirely offline without external network calls.
- **Dependency Sandboxing**: Vulnerable lab containers are never executed directly; only their metadata (`dpkg-query`) is extracted.

## 🛠️ 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 tests pass and your code is strictly typed before opening a Pull Request.

## 📝 Changelog

- **v0.1.0 (Initial Release)**
  - Completed offline and local target discovery.
  - Implemented `dpkg` version comparison engine (`python-apt` logic parity).
  - Integrated Canonical OSV endpoints with caching.
  - Added JSON, Rich Table, and SARIF reporting.
  - Added CycloneDX SBOM generation.
  - Implemented expiration-aware `uvt-ignore.yml` policies.

## ❓ Troubleshooting & FAQ

**Q: I get a `ModuleNotFoundError` when running `uvt`?**
A: Ensure you have installed the package using `pip install -e .` within the project root.

**Q: Why does the first scan take so long?**
A: UVT downloads the authoritative vulnerability dataset from Canonical (~30MB compressed) 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 delete the cache folder at `~/.cache/uvt/`.

## 📜 License

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