vulnctl 0.1.0__tar.gz

vulnctl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+      - name: Mypy
+        run: uv run mypy src/
+
+      - name: Pytest (with 100% branch-coverage gate on ssvc/)
+        run: uv run pytest --cov=vulnctl.ssvc --cov-branch --cov-report=term-missing --cov-fail-under=100

vulnctl-0.1.0/.github/workflows/live-smoke.yml

@@ -0,0 +1,59 @@
+# Weekly live-smoke: exercise every adapter against real upstream APIs to catch
+# schema drift before it silently degrades production runs. This is the ONLY
+# workflow that hits the network — PR/push CI stays fixture-only. On failure it
+# opens a tracking issue. Never triggered by pull_request.
+name: live-smoke
+
+on:
+  schedule:
+    - cron: "17 6 * * 1" # Mondays 06:17 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write # open a tracking issue when an upstream source drifts/breaks
+
+jobs:
+  live-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Live adapter smoke (real APIs)
+        env:
+          VULNCTL_LIVE: "1"
+          # Optional secrets: raise NVD/GitHub rate limits. Anonymous also works.
+          VULNCTL_NVD_API_KEY: ${{ secrets.VULNCTL_NVD_API_KEY }}
+          VULNCTL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run pytest tests/live -v
+
+      - name: Open an issue on failure
+        if: failure()
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        with:
+          script: |
+            const run = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `live-smoke failed — upstream drift or outage (${new Date().toISOString().slice(0, 10)})`,
+              body: [
+                `The weekly [live-smoke run](${run}) failed.`,
+                '',
+                'An adapter returned no data for a known-good CVE. Because every adapter',
+                'parses upstream responses through strict Pydantic models, this usually',
+                'means an upstream API changed its schema (the adapter degraded to',
+                '`Unavailable`) — or the source is temporarily down.',
+                '',
+                'Check the run logs to see which source failed, then update the adapter',
+                'and its recorded fixtures if the schema changed.',
+              ].join('\n'),
+              labels: ['live-smoke', 'upstream-drift'],
+            });

vulnctl-0.1.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,29 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write # OIDC trusted publishing — no stored token
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          repository-url: https://test.pypi.org/legacy/

vulnctl-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,237 @@
+name: release
+
+# Cut a signed release of vulnctl.
+#
+# Pipeline (in order, each stage gates the next):
+#   build   → build sdist+wheel (uv), install the wheel into a clean env,
+#             SBOM that runtime closure (Syft, CycloneDX JSON), scan it (Grype),
+#             and gate: (1) no critical-with-fix vuln, (2) dogfood vulnctl's own
+#             --fail-on act against the Grype report.
+#   sign    → cosign keyless (OIDC) signatures for the wheel, sdist, and SBOM.
+#   publish → PyPI via trusted publishing (OIDC, no stored token).
+#   release → GitHub Release with wheel, sdist, SBOM, and signatures attached.
+#
+# Triggers:
+#   - push of a `v*` tag → the full pipeline, including publish + GitHub Release.
+#   - workflow_dispatch  → DRY RUN: build, SBOM, scan, gates, and signing all
+#     run (so the release path is fully exercised), but publish + release are
+#     skipped. Every produced artifact is downloadable from the run.
+#
+# Security posture: every action is pinned to a full commit SHA; permissions are
+# least-privilege per job; `id-token: write` (OIDC) is granted only to the jobs
+# that actually sign or publish.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+# Deny everything by default; each job opts in to exactly what it needs.
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build, SBOM, scan & gate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Verify tag matches package version
+        if: github.event_name == 'push'
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(grep -m1 -E '^version\s*=' pyproject.toml | sed -E 's/.*=\s*"([^"]+)".*/\1/')"
+          echo "tag=$tag  pyproject=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag v$tag does not match pyproject version $pkg — bump pyproject first"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Resolve built wheel path
+        run: echo "WHEEL=$(ls dist/*.whl)" >> "$GITHUB_ENV"
+
+      - name: Install the release artifact into a clean environment
+        # Installs exactly what a `pipx install vulnctl` user receives, so the
+        # SBOM and scan below describe the real shipped runtime closure.
+        run: |
+          set -euo pipefail
+          uv venv .relenv
+          uv pip install --python .relenv "$WHEEL"
+
+      - name: Generate CycloneDX SBOM of the runtime closure (Syft)
+        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0
+        with:
+          path: .relenv
+          format: cyclonedx-json
+          output-file: sbom.cdx.json
+          upload-artifact: false
+
+      - name: Install Grype
+        id: grype
+        uses: anchore/scan-action/download-grype@e1165082ffb1fe366ebaf02d8526e7c4989ea9d2 # v7.4.0
+
+      - name: Scan the SBOM (Grype → JSON)
+        run: ${{ steps.grype.outputs.cmd }} sbom:sbom.cdx.json -o json=grype.json
+
+      - name: "Gate 1 — no critical vulnerability that already has a fix"
+        run: |
+          set -euo pipefail
+          count="$(jq '[.matches[]
+            | select(.vulnerability.severity == "Critical"
+                     and .vulnerability.fix.state == "fixed")] | length' grype.json)"
+          if [ "$count" -gt 0 ]; then
+            echo "::error::$count critical vulnerability(ies) with an available fix — release blocked"
+            jq -r '.matches[]
+              | select(.vulnerability.severity == "Critical" and .vulnerability.fix.state == "fixed")
+              | "  - \(.artifact.name) \(.artifact.version): \(.vulnerability.id) → fix \(.vulnerability.fix.versions | join(", "))"' grype.json
+            exit 1
+          fi
+          echo "OK: no critical-with-fix findings."
+
+      - name: "Gate 2 — dogfood vulnctl on its own Grype report (fail on ACT)"
+        env:
+          # Optional: raises NVD rate limits. vulnctl fails open if unset/down.
+          VULNCTL_NVD_API_KEY: ${{ secrets.VULNCTL_NVD_API_KEY }}
+        run: |
+          # Run the exact wheel we're about to ship against its own scan. A
+          # KEV-listed dependency resolves to exploitation=active → ACT → exit 2.
+          ./.relenv/bin/vulnctl enrich --grype grype.json --fail-on act
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+      - name: Upload SBOM and scan report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: reports
+          path: |
+            sbom.cdx.json
+            grype.json
+          if-no-files-found: error
+
+  sign:
+    name: Sign artifacts (cosign keyless)
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: read
+      id-token: write # OIDC identity for keyless signing (Fulcio); no private key
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist
+
+      - name: Download SBOM
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: reports
+          path: .
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+        with:
+          cosign-release: "v3.0.6"
+
+      - name: Sign wheel, sdist, and SBOM (keyless)
+        run: |
+          set -euo pipefail
+          mkdir -p sigs
+          # cosign v3 defaults to the Sigstore "new bundle format": one bundle
+          # file per artifact carrying the signature, certificate, and Rekor
+          # entry. (The old --output-signature/--output-certificate flags are
+          # deprecated and ignored under this format.)
+          for f in dist/*.whl dist/*.tar.gz sbom.cdx.json; do
+            base="$(basename "$f")"
+            echo "signing $f"
+            cosign sign-blob --yes \
+              --bundle "sigs/$base.sigstore.json" \
+              "$f"
+          done
+
+      - name: Upload signatures
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: signatures
+          path: sigs/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    runs-on: ubuntu-latest
+    needs: [build, sign]
+    if: github.event_name == 'push'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/vulnctl
+    permissions:
+      id-token: write # OIDC for PyPI trusted publishing — no stored API token
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        # Uploads only dist/*.whl and dist/*.tar.gz (signatures/SBOM live in
+        # separate artifacts). Generates PEP 740 attestations via the same OIDC
+        # identity by default.
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+
+  release:
+    name: GitHub Release
+    runs-on: ubuntu-latest
+    needs: [build, sign, publish]
+    if: github.event_name == 'push'
+    permissions:
+      contents: write # create the release and upload assets
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist
+
+      - name: Download SBOM and scan report
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: reports
+          path: .
+
+      - name: Download signatures
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: signatures
+          path: signatures
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@2bb465e97f322d3cb2a965294d483e0d26a67aa9 # v3.0.1
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            sbom.cdx.json
+            signatures/*

vulnctl-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environments / uv
+.venv/
+.python-version.local
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

vulnctl-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# Runs the same four checks CI runs, via the project venv (uv), so hook and CI
+# tool versions can never drift apart.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --force-exclude
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format --check --force-exclude
+        language: system
+        types_or: [python, pyi]
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true

vulnctl-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

vulnctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to vulnctl are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-07
+
+First public release. `vulnctl` turns CVE lists, SBOMs, and scanner output into
+auditable, SSVC-based remediation verdicts — each with the full decision path
+that produced it.
+
+### Added
+
+- **`enrich` command** accepting three input modes (exactly one per run): one or
+  more CVE IDs, a CycloneDX 1.4–1.6 SBOM (`--sbom`, components resolved to CVEs
+  via OSV), or Grype JSON (`--grype <file>` or `-` for stdin).
+- **Fused enrichment** from six public intelligence sources: FIRST EPSS
+  (exploit probability + percentile), CISA KEV (known-exploited + ransomware
+  flag), NVD (CVSS vector/score, CWE), OSV and GHSA (affected/fixed versions,
+  advisories), and exploit presence (Exploit-DB, Metasploit, nuclei).
+- **SSVC decision engine**: a pure, deterministic tree-walker bundling the
+  CISA-style deployer tree `cisa-deployer-v1`. Every verdict carries a full
+  `DecisionPath` — each node visited, its value, and the source that supplied
+  it — and flags when a degraded input fell back to a tree default. Bring your
+  own tree with `--tree`.
+- **Organizational context** via `--context context.yaml`: `exposure`,
+  `mission_impact`, `asset_tier`, and per-decision-point `overrides`, with
+  conservative defaults when absent and hard errors on unknown keys.
+- **Offline mode** (`--offline`): runs from cached data and bundled EPSS/KEV/
+  exploit snapshots with zero network access.
+- **Output formats**: rich terminal table (with `--show-path`), machine-readable
+  `--format json` (versioned, schema-documented), `--format sarif` (SARIF 2.1.0
+  for GitHub code scanning), and `--format md` (stakeholder report).
+- **CI gating**: `--fail-on track|track*|attend|act` exits `2` when any finding
+  meets or exceeds the threshold; output is written before the gate is applied.
+- **Response cache**: SQLite with per-source TTLs; `cache stats` and
+  `cache purge` subcommands.
+- **`--version`** sourced from installed package metadata (single source of
+  truth in `pyproject.toml`).
+- **Documentation**: README with quickstart, plus `docs/` references for the
+  context file, tree format, JSON schema, exit codes, and the release runbook;
+  a `vhs` demo tape; and an example CI gate under `examples/ci/`.
+
+### Security
+
+- All GitHub Actions pinned by full commit SHA; least-privilege token scopes per
+  workflow.
+- Strict Pydantic validation of every external JSON payload before it becomes a
+  model; response- and file-size bounds on all inputs; no `eval`, no `pickle` of
+  untrusted data, no shelling out to parse files.
+- Signed release pipeline: build with `uv`, generate a CycloneDX SBOM (Syft),
+  scan the artifact (Grype, dogfooded through vulnctl's own `--fail-on` gate),
+  sign with keyless cosign (OIDC), and publish to PyPI via trusted publishing
+  (no stored token).
+
+[Unreleased]: https://github.com/NokiGuard/vulnctl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/NokiGuard/vulnctl/releases/tag/v0.1.0

vulnctl-0.1.0/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md — vulnctl
+
+## What this project is
+
+`vulnctl` is a Python CLI that ingests CVE identifiers, SBOMs (CycloneDX/SPDX), or scanner output (Grype/Trivy JSON), enriches each finding from multiple threat-intelligence sources (EPSS, CISA KEV, NVD, OSV, GHSA, exploit-presence feeds), evaluates it against a declarative SSVC decision tree with user-supplied organizational context, and emits a prioritized, **auditable** ranking. The differentiator is that every verdict ships with its full decision path — not just a score.
+
+Read `SPEC.md` for the product spec and `FRAMEWORK.md` for architecture before making structural changes.
+
+## Tech stack & conventions
+
+- **Python 3.11+**, packaged with `pyproject.toml` (hatchling or setuptools), managed with `uv`
+- **CLI:** Typer. Entry point: `vulnctl` console script
+- **HTTP:** `httpx` with async batching for source adapters; respect per-source rate limits
+- **Models:** Pydantic v2 for ALL data structures crossing module boundaries. No bare dicts across interfaces.
+- **Cache:** SQLite via `sqlite3` stdlib (no ORM), single file at `~/.cache/vulnctl/cache.db`, per-source TTLs
+- **Terminal output:** `rich` tables
+- **Config/trees:** YAML via `ruamel.yaml` (round-trip safe, preserves comments in user files)
+- **Tests:** pytest + pytest-asyncio; adapters tested against recorded fixtures (JSON files in `tests/fixtures/`), never live APIs in CI
+- **Lint/format:** ruff (lint + format), mypy --strict on `src/`
+- **Line length 100. Google-style docstrings.**
+
+## Commands
+
+```bash
+uv sync                       # install deps
+uv run pytest                 # run tests
+uv run pytest -k adapter      # adapter tests only
+uv run ruff check --fix .     # lint
+uv run ruff format .          # format
+uv run mypy src/              # type check
+uv run vulnctl --help         # smoke-test the CLI
+```
+
+All four (pytest, ruff check, ruff format, mypy) must pass before any commit.
+
+## Repository layout
+
+```
+src/vulnctl/
+├── cli.py               # Typer app; thin — no business logic here
+├── models.py            # Pydantic: Finding, Enrichment, Verdict, DecisionPath
+├── ingest/              # cve_list.py, cyclonedx.py, spdx.py, grype.py, trivy.py
+├── adapters/            # one module per intel source; all implement SourceAdapter ABC
+│   ├── base.py          # SourceAdapter ABC + registry
+│   ├── epss.py, kev.py, nvd.py, osv.py, ghsa.py, exploits.py
+├── cache.py             # SQLite cache: get/set with TTL, per-source namespacing
+├── ssvc/                # engine.py (tree walker), trees/ (bundled YAML trees)
+├── context.py           # org context loading + validation (context.yaml)
+├── output/              # table.py, json_out.py, sarif.py, markdown.py
+└── __init__.py
+tests/
+├── fixtures/            # recorded API responses, sample SBOMs, scanner JSON
+└── ...mirrors src layout
+```
+
+## Architecture rules (do not violate without discussion)
+
+1. **Adapters are isolated.** An adapter may import from `base.py`, `cache.py`, and `models.py` only. Adapters never import each other or the SSVC engine.
+2. **The SSVC engine is pure.** `ssvc/engine.py` takes `(Enrichment, OrgContext, tree)` and returns a `Verdict` with a `DecisionPath`. No I/O, no network, no cache access. Fully deterministic and unit-testable.
+3. **Fail open on enrichment, fail loud on input.** A source being down degrades the enrichment (mark the field `unavailable`, note it in the decision path) — it never crashes a run. Malformed SBOMs/scanner files are hard errors with actionable messages.
+4. **Every verdict is explainable.** `DecisionPath` records each tree node visited, the input value used, and which source supplied it. If you add a scoring signal, you must thread it through `DecisionPath`.
+5. **Offline mode is first-class.** `--offline` must work using only cached/bundled data (EPSS CSV snapshot, KEV JSON snapshot). Adapters declare whether they support offline.
+6. **No secrets in code or fixtures.** NVD API key comes from `VULNCTL_NVD_API_KEY` env var only. Scrub any recorded fixtures of keys before committing.
+
+## Security posture (this is a security tool — hold the bar)
+
+- Pin all GitHub Actions by full SHA
+- Dependabot/renovate on; lockfile committed
+- No `eval`, no `pickle` for untrusted data, no shelling out to parse files
+- Validate and bound all external JSON before model construction (Pydantic strict mode)
+- SARIF output must validate against the 2.1.0 schema (test enforces this)
+
+## Style notes for Claude Code
+
+- Prefer small PRs/commits scoped to one adapter or one output format
+- When adding a source adapter: implement ABC → add fixtures → add tests → register in `base.py` registry → update `SPEC.md` source table
+- Never mock `httpx` inline in tests; use the fixture-loading helper in `tests/conftest.py`
+- Update `FRAMEWORK.md` diagrams when module boundaries change
+- Keep `cli.py` under ~150 lines; push logic down into modules