name: Security # Security gate: dependency vulnerability scanning (SCA), static analysis # (CodeQL/SAST), and secret scanning. Runs on every PR to main, on push to # main, weekly (to catch newly-disclosed CVEs without a code change), and on # demand. Each job is an independent required check. on: push: branches: [main] pull_request: branches: [main] schedule: # Mondays 06:00 UTC — surface CVEs disclosed since the last commit. - cron: "0 6 * * 1" workflow_dispatch: permissions: contents: read concurrency: group: security-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} jobs: # ---- SCA: dependency vulnerability scan ------------------------------- # Audits the PRODUCTION dependency set ([all]) exported from uv.lock. The # `benchmark` extra is intentionally excluded from [all] (it pulls lm-eval's # sqlitedict/nltk, which carry unpatchable upstream High CVEs and are never # installed in production), so this gate fails only on actionable findings. dependency-audit: name: Dependency audit (pip-audit) runs-on: ubuntu-latest timeout-minutes: 15 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Set up Python uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: "3.12" - name: Install uv uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 - name: Export production dependency set from uv.lock run: | uv export --frozen --no-dev --no-emit-project --no-hashes \ --extra all --format requirements-txt > requirements-prod.txt echo "Production dependencies audited:" wc -l requirements-prod.txt - name: Audit dependencies (pip-audit) # The export is uv.lock's fully pinned set, overrides applied: audit it # as is. pip must not re-resolve it (fastembed's pillow<13 cap would # fail; see [tool.uv] override-dependencies), and the pip-audit action # has no --disable-pip input, so pip-audit runs directly. run: uvx pip-audit==2.10.1 -r requirements-prod.txt --no-deps --disable-pip # ---- SCA: what `pip install headroom-ai[all]` gets --------------------- # The job above audits uv.lock, which the release image also installs # (overrides applied). pip ignores [tool.uv] and resolves the package # metadata, where fastembed caps pillow <13: audit that set too. Its Pillow # advisories fixed in 13 are accepted only because headroom/image/ # decoder_guard.py never decodes an image on Pillow <13, which the guard step # proves on that same Pillow first. Any other finding fails the job. # `uv pip compile` stands in for pip's resolver on Linux/Python 3.12, so it # approximates, not reproduces, every user's install; on Python 3.10 pip # also gets Pillow 12 (guarded) and filelock <4.2.1 (no fixed release there). # It resolves live from PyPI, so a new upstream advisory would fail PRs that # did not cause it: on pull requests it runs only when pyproject.toml changes; # pushes to main and the weekly schedule always run it. published-install-audit: name: Dependency audit (pip install from package metadata) runs-on: ubuntu-latest timeout-minutes: 15 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - name: Run on this event? id: gate run: | if [ "${{ github.event_name }}" != "pull_request" ] || \ git diff --name-only "${{ github.event.pull_request.base.sha }}" HEAD | grep -qx pyproject.toml; then echo "run=true" >> "$GITHUB_OUTPUT" else echo "pyproject.toml unchanged in this PR; main and the weekly run cover it." fi - name: Set up Python if: steps.gate.outputs.run == 'true' uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: "3.12" - name: Install uv if: steps.gate.outputs.run == 'true' uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 - name: Resolve what pip installs from the package metadata if: steps.gate.outputs.run == 'true' run: | uv --no-config pip compile pyproject.toml --extra all --python-version 3.12 \ --no-header --no-annotate -o published.txt uv --no-config pip compile pyproject.toml --python-version 3.12 \ --no-header --no-annotate -o core.txt grep -iE '^(pillow|fastembed)==' published.txt - name: The decoder guard holds on that Pillow if: steps.gate.outputs.run == 'true' run: | uv venv -p 3.12 .published uv --no-config pip install -p .published -r core.txt \ "$(grep -i '^pillow==' published.txt)" pytest pytest-asyncio .published/bin/python -m pytest -p no:cacheprovider tests/test_image_decoder_guard.py PINNED="$(grep -i '^pillow==' published.txt | cut -d= -f3)" .published/bin/python - <<'PY' import os import PIL from headroom.image.decoder_guard import FIXED_PILLOW_MAJOR, pillow_is_safe # The guard reads the Pillow that is imported; it must be pip's pick. assert PIL.__version__ == os.environ["PINNED"], (PIL.__version__, os.environ["PINNED"]) fixed = int(PIL.__version__.split(".")[0]) >= FIXED_PILLOW_MAJOR assert pillow_is_safe() is fixed, (PIL.__version__, pillow_is_safe()) print("Pillow", PIL.__version__, "decodes images:", fixed) PY - name: Audit it (pip-audit) if: steps.gate.outputs.run == 'true' run: | uvx pip-audit==2.10.1 -r published.txt --no-deps --disable-pip \ --format json -o audit.json || true python - <<'PY' import json deps = json.load(open("audit.json"))["dependencies"] findings = [(d["name"], d["version"], v) for d in deps for v in d.get("vulns", [])] guarded = [ f for f in findings # The guard turns off all decoding below Pillow 13, whatever the fix. if f[0].lower() == "pillow" and int(f[1].split(".")[0]) < 13 ] for name, ver, v in findings: note = " (guarded: decoder_guard)" if (name, ver, v) in guarded else "" print(f"{name} {ver} {v['id']} fix {v['fix_versions']}{note}") assert len(deps) > 50, "pip-audit produced no dependency list" if len(findings) > len(guarded): raise SystemExit("Unguarded advisories in the pip-installed set; see above.") PY # ---- SCA: Rust dependency advisories ----------------------------------- # `cargo audit` reads Cargo.lock only (no build, about a minute), so it runs # unconditionally: every PR, every push to main, and the weekly schedule # above. It used to live in rust.yml behind the `rust-changes` path filter; # pushes that touched no Rust path reported it `skipped`, and rust.yml's own # schedule stopped firing after 2026-09-08, so no advisory scan ran for three # weeks. Blocking: an accepted advisory goes in .cargo/audit.toml with a # written reason. cargo-audit: name: Rust advisories (cargo audit) runs-on: ubuntu-latest timeout-minutes: 15 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Install cargo-audit + cargo-deny uses: taiki-e/install-action@cfdb7ed4ccc7c7dce37759eae89dc5674b469b39 # v2.90.3 with: tool: cargo-audit,cargo-deny - name: cargo audit (blocking; exceptions in .cargo/audit.toml) run: cargo audit # Licence allow-list from deny.toml. Advisory decisions stay with # cargo-audit above, so there is one place that decides what is accepted. - name: cargo deny check licenses continue-on-error: true run: cargo deny check licenses # Audit every maintained npm lock, including development dependencies. # Lockfile audits do not install packages or execute their lifecycle scripts. npm-audit: name: npm audit (${{ matrix.directory }}) runs-on: ubuntu-latest timeout-minutes: 10 strategy: fail-fast: false matrix: directory: - docs - sdk/typescript - plugins/openclaw - plugins/opencode - e2e/wrap/tools steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 with: node-version: ">=24.16.0 <25" # A directory may hold npm-audit-exceptions.json for advisories in copies # bundled inside a package, which overrides cannot replace. A listed # advisory is accepted only at its listed path, only while the lock has # that exact version there as a bundled copy, and only until `expires`. # Any other finding fails, and so does an entry that no longer matches. - name: Audit locked dependencies at every severity working-directory: ${{ matrix.directory }} run: | if [ ! -f npm-audit-exceptions.json ]; then npm audit --package-lock-only --audit-level=low exit fi npm audit --package-lock-only --audit-level=low || true npm audit --package-lock-only --json > "$RUNNER_TEMP/audit.json" || true python3 - "$RUNNER_TEMP/audit.json" <<'PY' import datetime import json import sys exceptions = json.load(open("npm-audit-exceptions.json")) if datetime.date.today().isoformat() > exceptions["expires"]: sys.exit(f"npm-audit-exceptions.json expired on {exceptions['expires']}: recheck upstream.") allowed = exceptions["advisories"] # {advisory: {lock path: bundled version}} locked = json.load(open("package-lock.json"))["packages"] vulns = json.load(open(sys.argv[1])).get("vulnerabilities", {}) seen, unexpected = set(), [] for name, vuln in vulns.items(): for via in vuln["via"]: if isinstance(via, str): # Inherited: its advisories are checked on that package's # own entry, which therefore has to be in the report. if via not in vulns: unexpected.append(f"{name} via {via} (no entry for {via})") continue advisory = via["url"].rsplit("/", 1)[-1] for node in vuln["nodes"]: entry = locked.get(node, {}) pinned = allowed.get(advisory, {}).get(node) if pinned and entry.get("version") == pinned and entry.get("inBundle"): seen.add((advisory, node)) else: found = f"{entry.get('version')}{' bundled' if entry.get('inBundle') else ''}" unexpected.append(f"{advisory} {node} {found} ({via['severity']})") stale = [f"{a} {n}" for a, nodes in allowed.items() for n in nodes if (a, n) not in seen] for line in unexpected: print("NOT EXCEPTED:", line) for line in stale: print("STALE EXCEPTION (fixed? remove it):", line) if unexpected or stale: sys.exit(1) print(f"Only excepted bundled advisories remain ({len(seen)}), until {exceptions['expires']}.") PY # ---- SAST: CodeQL static analysis ------------------------------------ codeql: name: CodeQL (${{ matrix.language }}) runs-on: ubuntu-latest timeout-minutes: 30 permissions: contents: read security-events: write actions: read strategy: fail-fast: false matrix: language: [python, javascript-typescript, actions] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Initialize CodeQL uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 with: languages: ${{ matrix.language }} queries: security-extended # Test code never ships. Its alerts were all test idioms (asserting a # URL appears in output, a fake server binding 0.0.0.0), so scanning # it only buried the real findings. config: | paths-ignore: - tests - name: Perform CodeQL analysis uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 with: category: "/language:${{ matrix.language }}" # ---- Secret scanning ------------------------------------------------- # Uses the gitleaks BINARY (MIT-licensed, no key) instead of # gitleaks-action, which requires a paid GITLEAKS_LICENSE for organization # repos. On PRs we scan only the PR's commits so pre-existing history can't # block a PR; on push/schedule we scan the working tree. Config + allowlist # live in .gitleaks.toml at the repo root (auto-loaded). secret-scan: name: Secret scan (gitleaks) runs-on: ubuntu-latest timeout-minutes: 10 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - name: Install gitleaks run: | version=8.18.4 curl -sSfL \ "https://github.com/gitleaks/gitleaks/releases/download/v${version}/gitleaks_${version}_linux_x64.tar.gz" \ -o /tmp/gitleaks.tar.gz tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks sudo install /tmp/gitleaks /usr/local/bin/gitleaks gitleaks version - name: Scan for secrets env: BASE_SHA: ${{ github.event.pull_request.base.sha }} run: | if [ -n "$BASE_SHA" ]; then echo "Scanning PR commits ${BASE_SHA}..HEAD" gitleaks detect --source . --log-opts="${BASE_SHA}..HEAD" --redact --no-banner else echo "Scanning working tree" gitleaks detect --source . --no-git --redact --no-banner fi