Open-source supply chain threat detection platform for Linux infrastructure.
How OpenBOM compares to Syft, Grype, Trivy, OSV-Scanner, cdxgen, Dependency-Track and Socket: docs/comparison.md.
OpenBOM continuously inventories every package on your endpoints, OS packages, Python libraries, NPM modules, and container images, then cross-references them against vulnerability databases, exploit intelligence feeds, and behavioral heuristics to surface the threats that actually matter: actively exploited CVEs, packages with public proof-of-concept exploits, and newly installed code exhibiting malware patterns.
Modern infrastructure runs on thousands of open-source dependencies. A single compromised package in PyPI or NPM can give an attacker code execution across your entire fleet. Traditional vulnerability scanners tell you what could be exploited. OpenBOM tells you what is being exploited right now, on your systems.
The software supply chain is under siege:
- Dependency confusion attacks inject malicious packages into private registries
- Typosquatting campaigns publish near-identical package names with embedded backdoors
- Compromised maintainer accounts push silent updates to trusted libraries
- Known exploited vulnerabilities remain unpatched for months across production systems
OpenBOM was built to close the gap between vulnerability discovery and threat response.
Make the software supply chain ecosystem more secure by giving defenders real-time visibility into what's installed, what's vulnerable, and what's actively under attack — across every endpoint, in every ecosystem.
OpenBOM is not another vulnerability scanner. It is a threat hunting platform that combines:
- Software Bill of Materials (SBOM) generation across OS, language, and container ecosystems
- Vulnerability intelligence from OSV.dev with severity classification and remediation guidance
- Exploit prediction via EPSS scores to prioritize what's likely to be weaponized
- Active exploitation tracking through CISA's Known Exploited Vulnerabilities catalog
- Proof-of-concept monitoring by detecting exploit-db, PacketStorm, and GitHub PoC references
- Zero-day heuristic detection that scans newly installed packages for malware IOC patterns
- Centralized fleet management with a FastAPI backend that aggregates findings from all endpoints
+-----------------------+
| OpenBOM Backend |
| (FastAPI Server) |
| |
| PostgreSQL / SQLite |
| Asset ←M:N→ Package |
| Package ←M:N→ Vuln |
+-----------+------------+
|
POST /api/v1/ingest
|
+----------------------------+----------------------------+
| | |
+--------+--------+ +---------+---------+ +---------+---------+
| Endpoint Agent | | Endpoint Agent | | Endpoint Agent |
| (web-server-01) | | (db-server-01) | | (ci-runner-03) |
| | | | | |
| RPM + PyPI + | | Debian + PyPI + | | RPM + NPM + |
| NPM + Podman | | Podman | | PyPI |
+------------------+ +--------------------+ +--------------------+
| | |
+---------+ +---------+ +---------+
| OSV.dev | | EPSS | | CISA |
| API | | API | | KEV |
+---------+ +---------+ +---------+
OpenBOM started from a simple observation: security teams don't need more CVE numbers — they need signal.
When a scan returns 500 vulnerabilities, what do you patch first? CVSS scores alone don't answer that. OpenBOM layers multiple intelligence sources to produce a prioritized, actionable threat picture:
| Signal | Source | What It Tells You |
|---|---|---|
| Vulnerability exists | OSV.dev | This package version has a known flaw |
| Severity classification | CVSS v3 + database_specific | How bad the flaw is in theory |
| Exploit probability | FIRST.org EPSS | How likely it is to be weaponized in the next 30 days |
| Active exploitation | CISA KEV catalog | It is being exploited right now in the wild |
| Public exploit code | PoC link detection | Exploit code is freely available to attackers |
| Malware indicators | Heuristic IOC scan | The package itself contains suspicious code patterns |
| Change detection | Delta/diff scanning | This package was just installed or downgraded |
By fusing these signals, OpenBOM transforms a wall of CVEs into a short list of things that demand immediate action.
| Feature | Description |
|---|---|
| Multi-ecosystem SBOM | Host RPM / dpkg / apk, global pip & npm, running Podman/Docker containers |
| Scan targets | --path repos (requirements, Poetry/uv/Pipfile, npm/yarn/pnpm, go.mod, Cargo, Gemfile, Composer, NuGet, Maven/Gradle, venvs, node_modules, nested JAR/WAR), --rootfs, --image (podman/docker), --sbom (CycloneDX/SPDX from Syft, Trivy, cdxgen…) |
| Known-malicious packages | OpenSSF malicious-package advisories (OSV MAL-*) flagged CRITICAL with "treat host as compromised" guidance |
| License compliance | Licenses from rpm/apk/Debian copyright/PyPI/npm/lockfiles, optional deps.dev enrichment, --license-deny policy gate |
| End-of-life | OS, Python and Node.js EOL via endoflife.date |
| VEX & ignore | --vex (OpenVEX / CycloneDX VEX) and --ignore (with expiry dates) suppress triaged findings |
| SPDX / SARIF | --spdx (SPDX 2.3) and --sarif (GitHub/GitLab code scanning) alongside CycloneDX |
| OSV.dev integration | PyPI, npm, Debian, Ubuntu, AlmaLinux, Rocky Linux (OS + container packages, source-package/epoch aware). Async batch + enrichment with retry/backoff |
| Accurate scoring | Real CVSS v3.1 base-score calculation, GHSA/Ubuntu/RHEL qualitative ratings, fix version chosen from the range that contains the installed version, GHSA↔PYSEC alias de-duplication |
| EPSS scoring | Queries FIRST.org for exploit prediction probability on every CVE |
| CISA KEV cross-reference | Downloads the KEV catalog (24h cache) and flags actively exploited CVEs |
| PoC/exploit detection | Scans OSV references for exploit-db, PacketStorm, and GitHub PoC links |
| Heuristic IOC scanner | Strong indicators (exec(base64), reverse shells, miners, curl | sh npm install hooks) → CRITICAL; co-occurring weak indicators (credential paths + Discord/Telegram exfil, .pth auto-exec…) → HIGH. Scope: --heuristics new|all|off |
| Typosquat detection | Flags PyPI/npm packages one edit away from popular names (reqeusts, lodahs) with a curated allowlist of legitimate look-alikes |
| Package locations | Every package records where it lives: *.dist-info / node_modules dir on hosts, lockfile/venv/manifest for --path and --rootfs scans. It is shown in the CLI, HTML report, JSON and console, so you know which copy to fix |
| Delta/diff scanning | Labels [NEW], [UPGRADED], [DOWNGRADED] with rpm/dpkg/PEP 440/semver ordering; lists removed packages |
| CycloneDX 1.5 export | --cyclonedx PATH writes a standard SBOM with purls and vulnerabilities |
| Backend push | --server-url / --push-file upload results directly (API-key aware) |
| Interactive menu | Run with no flags on a terminal for a guided menu (scan, hunt, view, push, export, cache management) |
| CI gating | --fail-on critical|high|… controls exit code 2 |
| Rich CLI output | Progress bars, severity tables, KEV/IOC alert panels (with "found in" paths) |
| HTML/PDF reporting | Professional dark-theme reports via Jinja2 + Tailwind CSS + WeasyPrint |
| Safe caching | 12h OSV / 24h KEV caches in a private 0700 state dir (never /tmp), atomic writes, failed lookups never cached as "clean" |
| Webhook alerting | POST to Slack/Teams/Discord when CRITICAL, KEV or IOC findings are detected |
| Feature | Description |
|---|---|
| Async FastAPI | Fully async with SQLAlchemy 2.0 + asyncpg/aiosqlite |
| Flexible database | PostgreSQL for production, SQLite for development — auto-detected |
| Snapshot ingestion | Idempotent bulk upsert; uninstalled/upgraded packages are unlinked so findings reflect what is installed now |
| Web console (Arco Design) | http://server:8000/ — Overview, Assets, Threat Hunt (Malicious/KEV/IOC/Critical/EPSS), Vulnerabilities, Package Search, Licenses, End-of-Life, Triage & VEX, SBOM Import, Reports & Export, Agent Setup, Settings. Shows the path of every affected package. Dark/light theme with smooth motion (respects reduced-motion), offline (vendored assets), strict CSP |
| Triage & VEX | Fleet-wide or per-asset decisions (not_affected, false_positive, …) suppress findings; resolved findings that are still detected are flagged; OpenVEX import/export |
| SBOM import & continuous monitoring | Upload CycloneDX/SPDX from any tool; re-match stored inventories against fresh OSV/EPSS/KEV on demand or every OPENBOM_REANALYZE_HOURS |
| Threat hunting API | KEV, heuristic IOC, severity, EPSS, fleet-wide package search ("who has xz 5.6.0, and where?"), vuln → affected hosts and paths |
| Risk scoring & history | Per-asset 0-100 risk score, stale-asset detection, per-scan history |
| API-key auth | OPENBOM_API_KEY protects all /api/v1 routes |
| CycloneDX export | /api/v1/assets/{host}/sbom |
| OpenAPI docs | Auto-generated Swagger UI at /docs |
OpenBOM auto-detects the package manager at runtime and adapts its extraction strategy accordingly. No configuration needed — just run the agent.
Vulnerability coverage of OS packages depends on OSV.dev advisory feeds: Debian, Ubuntu, AlmaLinux, Rocky Linux and Alpine packages (host and Podman containers) are checked. Fedora, RHEL, CentOS Stream, openSUSE and Amazon Linux packages are inventoried and diffed, but OSV publishes no advisories for them. PyPI and npm packages are checked on every distribution.
These distributions are actively tested and used in development. All features work out of the box.
| Distribution | Versions | Package Manager | Container Engine |
|---|---|---|---|
| Fedora | 39, 40, 41, 42 | rpm / dnf |
Podman (native) |
| RHEL | 8, 9 | rpm / dnf |
Podman (native) |
| CentOS Stream | 8, 9 | rpm / dnf |
Podman (native) |
| Ubuntu | 22.04, 24.04 | dpkg-query / apt |
Podman / Docker |
| Debian | 11 (Bullseye), 12 (Bookworm) | dpkg-query / apt |
Podman / Docker |
These distributions use the same package managers and should work without modification, but receive less frequent testing.
| Distribution | Package Manager | Notes |
|---|---|---|
| AlmaLinux 8, 9 | rpm / dnf |
RHEL binary-compatible |
| Rocky Linux 8, 9 | rpm / dnf |
RHEL binary-compatible |
| Oracle Linux 8, 9 | rpm / dnf |
RHEL binary-compatible |
| openSUSE Leap 15.x, Tumbleweed | rpm / zypper |
RPM extraction works; zypper not used directly |
| SUSE Linux Enterprise 15 | rpm / zypper |
Same as openSUSE |
| Amazon Linux 2, 2023 | rpm / dnf / yum |
Common on AWS EC2 |
| Linux Mint 21, 22 | dpkg-query / apt |
Ubuntu-based |
| Pop!_OS 22.04 | dpkg-query / apt |
Ubuntu-based |
| Kali Linux | dpkg-query / apt |
Debian-based |
| Arch Linux | Not supported (pacman) | Contribution welcome |
| Alpine Linux 3.x | apk (/lib/apk/db/installed) |
OS packages OSV-checked (Alpine:vX.Y); also in images/containers |
Package extraction is independent of the host OS — these work on any supported distribution:
| Ecosystem | Detection Method | Requirement |
|---|---|---|
| Python (PyPI) | pip3 freeze --all |
Python 3.12+ with pip |
| Node.js (NPM) | npm list -g --depth=0 --json |
npm installed globally |
| Containers (Podman) | podman exec <id> rpm -qa or dpkg-query |
Podman with running containers |
| Containers (Docker) | docker exec <id> rpm -qa / dpkg-query / apk db |
Docker with running containers |
| Container images | --image REF → podman/docker create + export → rootfs scan |
podman or docker |
| Project lockfiles | --path DIR — Python, npm/yarn/pnpm, Go, Cargo, RubyGems, Composer, NuGet, Maven/Gradle, JAR/WAR |
none (pure parsing) |
The backend server runs on any OS with Python 3.12+, but is tested on:
| Platform | Database | Status |
|---|---|---|
| Linux (any distribution) | PostgreSQL 14+ / SQLite | Fully supported |
| macOS | PostgreSQL / SQLite | Works (development use) |
| Windows (WSL2) | PostgreSQL / SQLite | Works (development use) |
- Python 3.12+
- Linux (any Tier 1 or Tier 2 distribution above)
pip,rpmordpkg-query(auto-detected)
git clone https://github.com/Masriyan/OpenBOM.git
cd OpenBOM
# Agent + backend + test dependencies
pip install -r requirements.txt
# Optional: PDF reports / PostgreSQL
pip install weasyprint asyncpg
# Run the test suite
python3 -m pytest# Interactive menu (on a terminal, no flags)
python3 agent/openbom_agent.py
# Scan only — generate SBOM (no network calls)
python3 agent/openbom_agent.py --scan-only
# Full threat hunt — OSV + EPSS + KEV + reporting
python3 agent/openbom_agent.py --check-osv --report --diff
# With webhook alerts
python3 agent/openbom_agent.py --check-osv --report --diff \
--webhook-url https://hooks.slack.com/services/YOUR/WEBHOOK/URL
# Hunt and push straight to the backend
OPENBOM_API_KEY=... python3 agent/openbom_agent.py --check-osv --diff --server-url http://openbom:8000# Development (SQLite)
uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
# Production (PostgreSQL + API key)
export DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/openbom
export OPENBOM_API_KEY=$(openssl rand -hex 24)
uvicorn server.main:app --host 0.0.0.0 --port 8000 --workers 4Open http://localhost:8000/ for the dashboard (enter the API key under Settings) and /docs for the API.
# Run agent and pipe output to backend
python3 agent/openbom_agent.py --check-osv --diff -o scan.json
python3 agent/openbom_agent.py --push-file scan.json --server-url http://your-backend:8000 --api-key "$OPENBOM_API_KEY"
# or: curl -X POST http://your-backend:8000/api/v1/ingest -H "Content-Type: application/json" \
# -H "X-API-Key: $OPENBOM_API_KEY" -d @scan.jsonusage: openbom_agent [--scan-only | --check-osv | --push-file JSON | --menu] [options]
Modes (none on a terminal = interactive menu; a scan target alone implies --check-osv):
--scan-only Collect SBOM only (no network calls)
--check-osv Full scan: OSV + MAL + EPSS + KEV + EOL
--push-file JSON Upload an existing scan JSON to --server-url
--menu Interactive menu
Scan targets (default: this host):
--path DIR Repository / build tree (repeatable)
--rootfs DIR Unpacked root filesystem
--image REF Container image via podman or docker
--sbom FILE Existing CycloneDX / SPDX JSON SBOM
--ecosystems LIST Host sources: os,pypi,npm,podman,docker
Outputs:
-o, --output PATH JSON report path --output-dir DIR (default ./output)
--report HTML + PDF report --cyclonedx PATH CycloneDX 1.5
--spdx PATH SPDX 2.3 --sarif PATH SARIF 2.1.0
Analysis & policy:
--diff Delta vs. previous scan of the same target
--heuristics MODE new (default; needs --diff) | all | off
--vex FILE OpenVEX / CycloneDX VEX suppressions (repeatable)
--ignore FILE 'VULN-ID [package|purl] [until=YYYY-MM-DD] # reason'
--license-deny LIST e.g. GPL-3.0,AGPL,SSPL (fails the run)
--deps-dev Fill missing licenses from deps.dev
--no-eol Skip end-of-life checks
--fail-on LEVEL any | critical | high | medium | low | never
--no-cache Bypass the 12-hour OSV cache
Other:
--hostname NAME --webhook-url URL --server-url URL --api-key KEY -v --version
| Code | Meaning |
|---|---|
0 |
Scan complete, no vulnerabilities found |
1 |
No packages found (empty system) |
2 |
Findings at/above --fail-on, any KEV / malicious package, or a license-policy violation |
130 |
Interrupted by user (Ctrl+C) |
See docs/api-reference.md for complete endpoint documentation.
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Service health check |
POST |
/api/v1/ingest |
Receive agent scan payload |
GET |
/api/v1/threats/summary |
Fleet-wide threat statistics |
GET |
/api/v1/threats/kev |
Assets with actively exploited CVEs |
GET |
/api/v1/threats/heuristics |
Assets with malware IOC detections |
GET |
/api/v1/threats/critical |
Assets with CRITICAL vulnerabilities |
GET |
/api/v1/threats/high-epss |
Assets above EPSS exploit probability threshold |
GET |
/api/v1/assets |
List all managed assets |
GET |
/api/v1/assets/{hostname} |
Single asset detail |
GET |
/api/v1/assets/{hostname}/packages |
Packages installed on an asset |
GET |
/api/v1/assets/{hostname}/vulnerabilities |
Vulnerabilities affecting an asset (with per-package fix) |
GET |
/api/v1/assets/{hostname}/scans |
Scan history |
GET |
/api/v1/assets/{hostname}/sbom |
CycloneDX 1.5 export |
DELETE |
/api/v1/assets/{hostname} |
Decommission an asset |
GET |
/api/v1/packages/search |
Which hosts have package X (version Y) |
GET |
/api/v1/vulnerabilities |
Fleet vulnerability list with filters |
GET |
/api/v1/vulnerabilities/{vuln_id} |
Vulnerability detail + affected hosts |
POST |
/api/v1/maintenance/prune |
Remove orphaned packages/vulns |
GET |
/api/v1/threats/malicious |
Assets with known-malicious packages |
GET/PUT/DELETE |
/api/v1/triage |
Analyst decisions (fleet-wide or per asset) |
GET/POST |
/api/v1/vex |
Export / import OpenVEX |
GET |
/api/v1/licenses, /api/v1/licenses/packages |
License inventory |
GET |
/api/v1/eol |
Assets running end-of-life software |
POST |
/api/v1/sbom |
Import a CycloneDX/SPDX SBOM (optionally analysed server-side) |
POST |
/api/v1/reanalyze, /api/v1/assets/{hostname}/reanalyze |
Continuous monitoring: re-match stored inventories |
OpenBOM/
├── agent/
│ ├── openbom_agent.py # Endpoint agent (single file by design)
│ └── templates/
│ └── report_template.html # Jinja2 + Tailwind HTML report template
├── server/
│ ├── main.py # FastAPI app, dashboard route, security headers
│ ├── config.py / security.py # Env settings, API-key auth
│ ├── database.py # Async engine, SQLite pragmas, init + column migration
│ ├── models.py # ORM models (Asset, Package, Vulnerability, ScanRecord, Triage)
│ ├── schemas.py # Pydantic request/response schemas
│ ├── queries.py / sbom.py # Shared joins, triage suppression, risk score, CycloneDX export
│ ├── analyzer.py # Reuses the agent engine for SBOM uploads + re-analysis
│ ├── static/ # Arco Design console: index.html, app.js, app.css, logos, vendor/
│ └── routers/
│ ├── ingest.py # POST /api/v1/ingest
│ ├── threats.py # GET /api/v1/threats/*
│ ├── assets.py # /api/v1/assets/*
│ ├── hunt.py # packages/search, vulnerabilities, maintenance
│ └── governance.py # triage, VEX, licenses, EOL, SBOM import, re-analysis
├── tests/ # pytest suite (agent, API, governance, console checks)
├── .github/ # issue + pull request templates
├── docs/
│ ├── architecture.md # System architecture deep-dive
│ ├── agent-guide.md # Endpoint agent deployment guide
│ ├── api-reference.md # Backend API documentation
│ ├── threat-model.md # Threat intelligence methodology
│ ├── deployment.md # Production deployment guide
│ └── … # configuration, dashboard, CI, SBOM/VEX, detection rules,
│ # development, troubleshooting, comparison (see docs/README.md)
├── CHANGELOG.md · ROADMAP.md · SECURITY.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md
├── output/ # Generated reports (JSON, HTML, PDF) — git-ignored
├── logs/ # Agent log files — git-ignored
└── README.md
Full index: docs/README.md
| Document | Description |
|---|---|
| Agent Guide | Scan modes, targets (host, repo, image, rootfs, SBOM), outputs, menu, scheduling |
| Dashboard Guide | Every console menu, triage workflow, SBOM import, exports |
| Configuration Reference | All CLI flags, environment variables, files and limits |
| CI/CD Integration | GitHub Actions, GitLab CI, Jenkins, SARIF upload, build gating |
| SBOM, VEX & Triage | CycloneDX/SPDX/OpenVEX exchange, purls, suppression semantics |
| Detection Rules | Heuristic IOC, typosquat and malicious-package logic, tuning |
| Architecture | Agent pipeline, data model, ingestion, console |
| API Reference | REST API |
| Threat Model | How intelligence layers become priorities |
| Deployment Guide | PostgreSQL, systemd, TLS, fleet rollout, alerting |
| Troubleshooting | Common problems and fixes |
| Development Guide | Dev setup, tests, extending parsers/rules/console |
| Market Comparison | OpenBOM vs. Syft, Grype, Trivy, OSV-Scanner, Dependency-Track, Socket |
| Changelog · Roadmap · Security · Contributing · Code of Conduct | Project policies |
| Source | URL | Usage |
|---|---|---|
| OSV.dev | https://osv.dev | Vulnerability database (batch + individual queries) |
| FIRST.org EPSS | https://www.first.org/epss/ | Exploit Prediction Scoring System |
| CISA KEV | https://www.cisa.gov/known-exploited-vulnerabilities-catalog | Known Exploited Vulnerabilities catalog |
| Exploit-DB | https://www.exploit-db.com | PoC reference detection |
| PacketStorm | https://packetstormsecurity.com | PoC reference detection |
Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request.
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes
- Push to the branch (
git push origin feature/your-feature) - Open a Pull Request at https://github.com/Masriyan/OpenBOM/pulls
This project is licensed under the MIT License. See LICENSE for details.
- OSV.dev by Google for the open vulnerability database
- FIRST.org for the EPSS exploit prediction model
- CISA for the Known Exploited Vulnerabilities catalog
- The open-source security community for building the tools that make this possible
OpenBOM — Because knowing what's installed is the first line of defense.
https://github.com/Masriyan/OpenBOM

