Skip to content

Security gates

Repository security is checked through four distinct controls: static source analysis, installed dependency audit, frozen dependency audit, and an exact root runtime-dependency contract. They answer different questions and none substitutes for the others.

flowchart TD
    source["Python source"] --> bandit["Bandit static analysis"]
    environment["installed distributions"] --> audit["pip-audit"]
    lock["uv.lock registry versions"] --> frozen["locked dependency audit"]
    frozen --> verdict["exact policy verdict"]
    pyproject["pyproject.toml project.dependencies"] --> dependency["root dependency policy gate"]
    policy["root-runtime-dependency-policy.toml"] --> dependency
    bandit --> reports["artifacts/<package>/security/"]
    audit --> reports
    audit --> interpreter["pip_audit_gate.py"]
    dependency --> verdict["exact policy verdict"]
    interpreter --> verdict

Gate matrix

Gate Input Pass condition Evidence or diagnostic
Bandit configured Python source paths no unaccepted finding at the configured severity policy JSON and text reports below the package security artifact directory
pip-audit resolved dependency audit JSON no vulnerability remains after explicit identifier and alias matching pip-audit.json, pip-audit.txt, affected distribution, installed version, identifier, fix versions
frozen dependency audit every registry name/version pair in uv.lock, including optional and platform forks every expected version is reported without skips or vulnerabilities; no advisory ignores artifacts/security/locked-dependencies/ requirements, JSON reports and logs
root runtime dependency policy root [project].dependencies and configs/package-governance/root-runtime-dependency-policy.toml normalized declared and approved distribution sets are identical missing approvals and stale policy entries are reported separately

Run the repository-level policy directly with:

make security-dependency-allowlist

Package security targets compose Bandit and pip-audit through the shared Make security contract. Their reports belong below artifacts/; report files are run evidence, not reviewed security policy.

Frozen dependency coverage

Installed-profile audits cover only the packages that their interpreter resolved. They can omit an optional extra or use a newer version than the lockfile. The frozen audit queries every locked PyPI distribution directly, without installing or executing optional scientific engines. Separate batches retain each version when the lockfile contains platform or interpreter forks of one package.

Run it directly with make security-locked-dependencies. Root make security and the developer package security target include this gate, so the package CI matrix checks the whole frozen graph. Local workspace packages remain covered by source and package checks; unsupported external sources fail admission.

The frozen audit does not apply SECURITY_IGNORE_IDS. A missing, skipped, unexpected, duplicate or vulnerable entry fails, as does an unsuccessful tool invocation. Keep the updated lockfile and its exact-version audit together when reviewing a dependency security repair.

Root runtime dependency contract

The root project is an orchestration workspace and currently ships no runtime dependencies. Its test, development, provider, and optional tool sets live in named dependency groups. The deny-by-default policy records that empty runtime surface explicitly.

The gate performs an exact comparison rather than a one-sided allowlist check:

  • a new root runtime dependency fails until policy review approves it;
  • an approval with no corresponding declaration also fails, preventing stale permission from silently broadening future changes;
  • a missing or malformed project file or policy file fails closed;
  • distribution names are normalized before comparison, while version constraints remain owned by pyproject.toml.

The executable policy is TOML under configs/package-governance/. The public handbook explains the contract and its consequence; it does not carry a list that security code parses from prose.

Vulnerability verdicts

pip_audit_gate.py accepts pip-audit's list form and its object form with a dependencies list. For each vulnerability it considers the primary identifier and aliases, so an explicit ignore cannot be bypassed merely by the identifier that pip-audit chooses to display.

An ignore is a risk decision, not a parser convenience. Review the exact identifier, aliases, affected version, available fix, exposure, and owner before changing SECURITY_IGNORE_IDS. Keep the decision visible in the Make security configuration and remove it when the accepted condition no longer applies.

Strict mode is the trust-bearing path:

Condition Strict result
report missing, invalid JSON, or unsupported shape invocation/evidence failure
unignored vulnerability remains security failure
valid report contains no remaining vulnerability pass

Non-strict mode supports local diagnosis but cannot establish release safety. The console verdict always distinguishes ignored findings, remaining findings, and unreadable evidence.

Process boundary

Security automation that starts another program must use the trusted-process boundary and an absolute executable path. This prevents repository-relative files or a modified working directory from changing which executable is run. The process call, report path, and strictness setting must remain explicit at the calling edge.

Interpreting a failure

Do not silence the first failing layer:

  1. If the tool could not run or its report is unreadable, repair evidence production and rerun it.
  2. If a source or vulnerability finding remains, fix or explicitly assess that finding; passing unit tests do not discharge it.
  3. If dependency policy fails, review the root runtime declaration and policy together. Move development-only tooling to a dependency group rather than approving it as runtime.
  4. Preserve the failing report under the governed artifact path when it is needed for review, but never commit it as a replacement for the policy.

A green security target means its named controls completed under the configured strictness. It is not a complete product threat model, supply-chain attestation, or guarantee that every transitive risk has been discovered.