⭐ osv-vuln-bot — Always-Green OSV Scanner (Python CLI)

A lean, production-grade Python CLI to audit dependencies against OSV.dev.
It mirrors CI locally, enables CodeQL, enforces a strict always-green workflow (linear history + required checks), and fails builds when risk thresholds are met.

---

Repo layout

.
├── scripts/                      # Utilities (e.g., gen_deps_from_poetry.py)
├── examples/deps.sample.json     # Example dependency inventory
├── src/osv_vuln_bot/             # Python package + CLI
├── tests/                        # pytest (95%+ coverage)
└── .github/workflows/            # build.yml, codeql.yml, etc.

---

🚀 Quick Start (Python)

cd /home/user/Proyectos/osv-vuln-bot
poetry install --no-interaction

# Local gates (mirror CI)
poetry run ruff check .
poetry run black --check .
PYTHONPATH=src poetry run pytest -q
poetry run mypy src

CLI usage

Generate inventory from poetry.lock and scan:

cd /home/user/Proyectos/osv-vuln-bot
poetry run python scripts/gen_deps_from_poetry.py poetry.lock > deps.json
poetry run osv-vuln-bot --deps deps.json --fail-on high

Help & options:

cd /home/user/Proyectos/osv-vuln-bot
poetry run osv-vuln-bot --help

Notes

• --deps expects a JSON array of { "ecosystem":"PyPI", "name":"<pkg>", "version":"<ver>" }.
• --fail-on supports: none | low | moderate | high | critical.
• If the threshold is met or exceeded, the process exits non-zero (perfect for CI gating).

---

🧪 Local Developer Workflow (mirrors CI)

cd /home/user/Proyectos/osv-vuln-bot
poetry run ruff check .
poetry run black --check .
PYTHONPATH=src poetry run pytest -q
poetry run mypy src

---

🔧 CI (GitHub Actions)

• Linux matrix Python 3.11 / 3.12 with steps matching local gates.
• OSV scan integrated (job fails when the risk threshold is hit).
• Artifacts with per-job logs for troubleshooting.
• CodeQL runs on PRs and main.

Relevant Python job fragment:

- run: python -m pip install --upgrade pip
- run: pip install poetry
- run: poetry install --no-interaction
- run: poetry run ruff check .
- run: poetry run black --check .
- env:
    PYTHONPATH: src
  run: poetry run pytest -q
- run: poetry run mypy src
- name: Generate deps from poetry.lock
  run: poetry run python scripts/gen_deps_from_poetry.py poetry.lock > deps.ci.json
- name: OSV scan (fail on high)
  run: poetry run osv-vuln-bot --deps deps.ci.json --fail-on high

---

🗺 When to Use This Project

• You need security gating with OSV on PRs and main.
• Python repos that must stay green (branch protections + auto-merge).
• Prefer linear history via squash-merge.

---

🧩 Customization

• Tune --fail-on to match your risk appetite.
• Swap the inventory source (e.g., generate JSON from requirements.txt).
• Extend the CI matrix or add OS runners if required.

---

🛡 Security

• Private disclosures via GitHub Security Advisories.
• CodeQL enabled; OSV runs on every PR and main.
• Secret scanning is enabled; never commit secrets.

---

🙌 Contributing

• Small, atomic PRs using Conventional Commits.
• Keep local gates green before pushing.
• Enable auto-merge once checks pass.

---

📈 SEO Keywords

osv scanner python cli, osv.dev vulnerability audit, poetry lock deps to osv,
always green ci python, ruff black pytest mypy, github actions matrix, codeql analysis,
branch protection required checks, squash merge linear history, dependency security gating

---

👤 Author

CoderDeltaLAN (Yosvel)
Email: [email protected]
GitHub: https://github.com/CoderDeltaLAN

---

💚 Donations & Sponsorship

If this project saves you time, consider supporting ongoing maintenance. Thank you!

---

📄 License

Released under the MIT License. See LICENSE.