Metadata-Version: 2.4
Name: selvo
Version: 0.1.9
Summary: Linux dependency blast-radius ranker — surfaces highest-value CVE patch opportunities
Project-URL: Homepage, https://github.com/sethc5/selvo-report
Project-URL: Repository, https://github.com/sethc5/selvo-report
Project-URL: Bug Tracker, https://github.com/sethc5/selvo-report/issues
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: anyio>=4.4
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: networkx>=3.3
Requires-Dist: packaging>=24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer[all]>=0.12
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# selvo

**Linux Security & Dependency Blast-Radius Ranker**

[![Pages](https://github.com/sethc5/selvo-report/actions/workflows/pages.yml/badge.svg)](https://sethc5.github.io/selvo-report/) &nbsp; [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> **Live report** → **[sethc5.github.io/selvo-report](https://sethc5.github.io/selvo-report/)** — auto-refreshed weekly via GitHub Actions.

`selvo` maps the most popular "core" Linux packages across major ecosystems (Debian/apt, Fedora/rpm, Arch/pacman, Alpine/apk, NixOS), builds transitive dependency graphs, enriches with CVE/EPSS/CVSS v4/KEV data, evaluates policy-as-code gates, and surfaces the highest-value patch opportunities—ranked by real blast radius and exploitation probability.

---

## Sample Output

```
$ selvo analyze --ecosystem debian --limit 10

╭──────────────────────────────────────────────────── selvo — Top 10 Packages ────────────────────────────────────────────────────╮
│  #  Package          Ecosystem  Installed  Upstream  CVEs  EPSS%  CVSS  Repos  Upstream Repo                        Score      │
│ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │
│  1  openssl          debian     3.0.11     3.3.1     12    94%    9.8   4821   github.com/openssl/openssl           91.4       │
│  2  curl             debian     7.88.1     8.7.1     8     87%    9.1   3204   github.com/curl/curl                 84.7       │
│  3  libssl3          debian     3.0.11     3.3.1     12    94%    9.8   2917   github.com/openssl/openssl           81.2  🔑KEV │
│  4  libgnutls30      debian     3.7.9      3.8.5     5     61%    8.1   2104   gitlab.com/gnutls/gnutls             73.9       │
│  5  zlib1g           debian     1.2.13     1.3.1     3     42%    7.5   3891   github.com/madler/zlib               71.3       │
│  6  libexpat1        debian     2.5.0      2.6.2     6     78%    9.8   1823   github.com/libexpat/libexpat         68.8  💣    │
│  7  libpcre2-8-0     debian     10.42      10.44     2     31%    7.4   2201   github.com/PCRE2Project/pcre2        62.1       │
│  8  libc6            debian     2.36       2.39      4     55%    8.2   9104   sourceware.org/git/glibc.git         61.7       │
│  9  libsystemd0      debian     252.30     255.4     3     28%    7.1   1432   github.com/systemd/systemd           54.3       │
│ 10  libpam0g         debian     1.5.2      1.6.1     2     19%    6.8    988   github.com/linux-pam/linux-pam       41.8       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

🔑 KEV = CISA Known Exploited Vulnerability  💣 = weaponized exploit in the wild
```

---

## Features

- **Multi-ecosystem discovery** — Debian Packages.gz, Fedora Core, Arch Linux, Alpine, NixOS, lockfiles (11 formats), container images, SBOM input, scanner import
- **Transitive dependency graph** — BFS + networkx; betweenness centrality for chokepoint detection
- **Version gap analysis** — distro-packaged vs latest upstream (Repology), supply-chain lag tracking
- **CVE enrichment** — OSV.dev, CVSS v4 (NVD), EPSS (FIRST.org), CISA KEV, exploit maturity
- **Policy-as-code** — YAML gates for KEV, weaponized exploits, CVSS/EPSS thresholds, SLA enforcement, CVE allow-list
- **Time-series trending** — SQLite snapshot store; `selvo diff` shows per-package EPSS velocity and score shifts
- **Exploit intelligence** — weaponized/PoC detection, OSS-Fuzz coverage discount, exposure-days urgency
- **Dependency confusion & typosquatting detection** — Levenshtein-1, version confusion, namespace squatting
- **Compliance mapping** — NIST 800-53, FedRAMP, SOC 2, PCI-DSS control tagging per CVE
- **Reachability analysis** — filter CVEs to those reachable from your actual call graph (Go via `govulncheck`, Python via AST walk)
- **Fleet & SBOM awareness** — multi-host fleet scanning, CycloneDX/SPDX input
- **Multiple output formats** — terminal, JSON, Markdown, HTML (interactive), SARIF 2.1.0, VEX, CycloneDX SBOM, compliance report
- **Notifications** — Slack Block Kit and PagerDuty Events v2
- **MCP server** — 15 tools for AI assistant integration (`selvo-mcp`)
- **FastAPI server** — REST scan/report API (`selvo-api`)
- **GitHub Actions** — composite action for CI integration with SARIF upload and KEV/score gate

---

## Installation

```bash
pip install -e ".[dev]"
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv pip install -e ".[dev]"
```

---

## Usage

### Discover top packages

```bash
selvo discover --ecosystem debian --limit 50
selvo discover --ecosystem all --limit 100 --output json --file report.json
```

### Build a dependency graph

```bash
selvo graph libc6 openssl --ecosystem debian --depth 3
```

### Full analysis (version gap + CVE + EPSS + CVSS + priority score)

```bash
selvo analyze --ecosystem all --limit 50
selvo analyze --ecosystem debian --output html --file report.html
selvo analyze --ecosystem alpine --output sbom --file sbom.cdx.json
selvo analyze --ecosystem nixos --output json --file report.json
```

### Scan a lockfile or SBOM

```bash
selvo scan requirements.txt
selvo scan pyproject.toml --output sarif --file results.sarif
selvo scan sbom.cdx.json --output vex --file vex.json
selvo scan --reachability --entrypoint src/main.py  # filter to reachable CVEs only
```

### Policy enforcement

```bash
selvo policy check                          # evaluate selvo.policy.yml
selvo policy check --policy ci.policy.yml   # custom policy file
selvo test                                  # CI gate: baseline diff + policy check
```

### Surface upstream patch opportunities

```bash
selvo patch --ecosystem all --limit 50
selvo patch --ecosystem debian --scorecard   # include OpenSSF Scorecard scores
selvo patch --ecosystem all --llm            # LLM-generated PR descriptions
```

### Compliance reporting

```bash
selvo compliance --framework fedramp --out fedramp-audit.json
selvo compliance --framework nist --format markdown --out nist-controls.md
```

### Trend tracking — diff since last run

```bash
selvo diff --ecosystem all --limit 50        # shows new CVEs, EPSS jumps, score changes
```

### Fleet scanning

```bash
selvo fleet scan hosts.txt                  # scan multiple hosts
selvo fleet report --output html            # aggregate fleet report
```

### Cache management

```bash
selvo cache stats    # show cache size and entry count
selvo cache prune    # remove expired entries
selvo cache clear    # wipe everything
```

---

## Architecture

```
selvo/
├── cli.py                  # typer CLI entrypoint (21 commands)
├── mcp_server.py           # MCP server (15 tools for AI assistant integration)
├── discovery/              # ecosystem scrapers + input parsers
│   ├── base.py             # PackageRecord / PrOpportunity dataclasses
│   ├── debian.py           # Debian Packages.gz + popcon
│   ├── fedora.py           # Fedora Core packages
│   ├── arch.py             # Arch Linux API
│   ├── alpine.py           # Alpine Linux packages
│   ├── nixos.py            # NixOS / nixpkgs
│   ├── ubuntu.py           # Ubuntu PPAs
│   ├── lockfile.py         # 11-format lockfile parser (pip, cargo, go.sum, …)
│   ├── container.py        # Container image layer scanning
│   ├── sbom_input.py       # CycloneDX / SPDX SBOM input
│   └── scanner_import.py   # Import from Grype / Trivy / Syft output
├── graph/
│   └── builder.py          # networkx BFS dependency graph
├── analysis/               # enrichment pipeline (28 enrichers)
│   ├── cache.py            # SQLite-backed cache + snapshot/diff tracking
│   ├── versions.py         # Repology upstream version lookup
│   ├── cve.py              # OSV.dev CVE enrichment
│   ├── epss.py             # FIRST.org EPSS exploitation probability
│   ├── cvss.py             # NVD CVSS v3/v4 severity scores
│   ├── exploit.py          # Exploit maturity + KEV enrichment
│   ├── distro_status.py    # Filter CVEs resolved in distro backport
│   ├── distro_compare.py   # Cross-distro version comparison + lag
│   ├── distro_tracker.py   # Distro patch date tracking
│   ├── rdeps.py            # Repology reverse-dep count proxy
│   ├── graph_metrics.py    # Transitive blast radius + betweenness centrality
│   ├── upstream.py         # GitHub/GitLab upstream repo detection
│   ├── patch.py            # Fix ref extraction + PR opportunity builder
│   ├── patch_safety.py     # Patch regression risk scoring
│   ├── github.py           # GitHub PR existence check
│   ├── scorecard.py        # OpenSSF Scorecard maintainer health
│   ├── advisories.py       # Vendor advisory enrichment (USN, RHSA, …)
│   ├── changelog.py        # LLM changelog summarisation
│   ├── cve_timeline.py     # CVE exposure-days tracking
│   ├── dep_confusion.py    # Dependency confusion + typosquatting detection
│   ├── fleet.py            # Multi-host fleet scanning
│   ├── local_context.py    # Local package manager context (dpkg/rpm/pacman)
│   ├── ossfuzz.py          # OSS-Fuzz coverage lookup
│   ├── policy.py           # Policy-as-code enforcement engine
│   ├── reachability.py     # Call-graph reachability filtering
│   ├── compliance.py       # NIST/FedRAMP/SOC 2/PCI control mapping
│   ├── sla.py              # SLA breach tracking
│   ├── trend.py            # Time-series metrics + sparklines
│   ├── watcher.py          # Slack / PagerDuty notification dispatch
│   └── llm.py              # OpenRouter LLM integration
├── prioritizer/
│   └── scorer.py           # Weighted composite priority scorer
├── reporters/
│   ├── terminal.py         # Rich table + diff output
│   ├── json_reporter.py    # JSON export
│   ├── markdown.py         # Markdown report
│   ├── html.py             # Self-contained HTML report (GitHub Pages)
│   ├── sarif.py            # SARIF 2.1.0 (GitHub Code Scanning)
│   ├── sbom.py             # CycloneDX 1.4 SBOM export
│   ├── vex.py              # VEX (Vulnerability Exploitability eXchange)
│   └── compliance.py       # Compliance audit report (JSON / Markdown)
└── api/
    └── server.py           # FastAPI REST scan/report server
```

---

## Scoring

| Factor | Weight |
|---|---|
| Transitive reverse-dep blast radius | 22% |
| EPSS exploitation probability (FIRST.org) | 20% |
| Betweenness centrality (dep chokepoint) | 15% |
| Version gap (major/minor versions behind) | 14% |
| Exploit maturity (weaponized/PoC/KEV) | 8% |
| Direct reverse-dep count (Repology) | 7% |
| CVSS severity score (NVD, worst CVE) | 10% |
| CVE exposure days | 2% |
| Download popularity | 2% |

Score range: **0–100** (higher = higher update value). Packages with no security signal are capped at 20.

---

## Policy-as-code

Drop a `selvo.policy.yml` at your repo root:

```yaml
version: 1
sla:
  critical: 7
  high: 30
block:
  on_kev: true
  on_weaponized: true
  min_cvss: 9.0
warn:
  on_poc: true
  min_cvss: 7.0
allow:
  cves:
    - id: CVE-2023-12345
      reason: "Not reachable via our call graph"
      expires: 2024-12-31
```

Run `selvo policy check` or use `selvo test` as a CI gate.

---

## MCP Server (Claude / AI assistant integration)

selvo ships a full [Model Context Protocol](https://modelcontextprotocol.io) server with 14 tools. Add to your Claude Desktop or Cursor config:

```json
{
  "mcpServers": {
    "selvo": {
      "command": "selvo-mcp",
      "args": []
    }
  }
}
```

Or run directly:

```bash
selvo-mcp
```

Available tools: `analyze_packages`, `get_snapshot`, `check_local_risk`, `describe_package`, `list_cves`, `get_upstream_watchlist`, `patch_plan`, `fleet_scan`, `distro_lag`, `check_exploits`, `get_epss_velocity`, `get_distro_patch_dates`, `get_sla_report`, `check_advisories`, `get_changelog_summary`

---

## GitHub Actions

```yaml
- uses: sethc5/selvo/.github/actions/selvo-scan@main
  with:
    ecosystem: debian
    limit: "50"
    format: sarif
    post-comment: "true"
```

---

## GitHub Pages (live report)

A GitHub Actions workflow ([`.github/workflows/pages.yml`](.github/workflows/pages.yml)) rebuilds and publishes the report automatically:

- **Triggers:** every Sunday at 02:00 UTC, on push to `main`, or manually
- **Outputs:** `index.html` (interactive dashboard), `data.json` (raw), `report.sbom.json` (CycloneDX SBOM)
- **No secrets required** — all APIs used (OSV.dev, Repology, EPSS, OpenSSF Scorecard) are public

### One-time setup

1. Go to **Settings → Pages** in your fork
2. Set **Source** to **"GitHub Actions"**
3. *(Optional)* Add `NVD_API_KEY` secret for faster CVSS lookups

---

## License

MIT
