chock

The latest release line (0.1.x) is the supported version, stated in SECURITY.md's supported-versions table. The upgrade path is documented and deliberately predictable: CHANGELOG.md describes every release's changes, and the project's versioning contract makes upgrades safe to reason about — PATCH releases never change compiled output (enforced mechanically by a golden-file test suite), and MINOR releases document what changed. Upgrading is pip install --upgrade chock followed by chock sync, which recompiles the repo's artifacts deterministically.
https://github.com/open-coder-ai/chock/blob/main/CHANGELOG.md

GitHub Issues on the repository (https://github.com/open-coder-ai/chock/issues), with issue templates, labels (good first issue, roadmap; the catalog repo adds policy wanted), and all current issues triaged.

N/A: no vulnerability reports have been received or resolved in the last 12 months (the project's first public release was August 2026). The policy is already in place for when one arrives: SECURITY.md commits to crediting reporters unless they request otherwise.
https://github.com/open-coder-ai/chock/blob/main/SECURITY.md

SECURITY.md documents the full response process: reports come through GitHub private security advisories (with an explicit instruction not to open public issues for exploitable findings), what a report should include, acknowledgment within 7 days and initial assessment within 14 days, fixes shipped in a patch release, reporter credit unless anonymity is requested, and a new enforcement-matrix invariant (SEC-* entry) when the fix requires one.
https://github.com/open-coder-ai/chock/blob/main/SECURITY.md

Python is the sole implementation language. The coding style is defined by the Ruff configuration committed in pyproject.toml (lint ruleset + formatter, line length, target Python version), supplemented by the repository's coding rules in AGENTS.md. CONTRIBUTING.md requires contributions to pass these checks, and CI enforces them on every pull request.
https://github.com/open-coder-ai/chock/blob/main/pyproject.toml

Enforced automatically by Ruff (FLOSS): ruff check and ruff format --check run in CI on every pull request as part of the required validate jobs, and locally in the repository's own pre-commit conformance gate — a style violation fails the build rather than relying on reviewer attention.
https://github.com/open-coder-ai/chock/blob/main/.github/workflows/ci.yml

N/A: the project is pure Python and generates no native binaries; there is no compiler or linker invocation in the build.

N/A: pure Python — there is no compilation step that could strip debugging information; installed files are the source files themselves, and Python tracebacks retain full source context.

The project builds as a single Python package via the standard PEP 517 build backend (python -m build); there is no recursive sub-directory build, so no cross-dependency ordering problem can arise.

N/A: Python is used directly from source rather than compiled — the distribution is a pure-Python wheel containing the source files, with no build-time code generation. (Separately, the artifacts the tool itself generates into adopter repositories are deterministic and byte-identical across platforms and reruns, enforced by a golden-file test suite in CI, but that is the software's runtime behavior rather than a build step.)

Installation and uninstallation follow the standard Python packaging convention: pip install chock and pip uninstall chock. The package is published on PyPI, works in any virtualenv, and is also runnable without installation via pipx run chock. Uninstalling removes the tool cleanly; artifacts the tool wrote into an adopter's repository are ordinary committed files under the adopter's control.

Installation is delegated entirely to pip, which honors the standard Python installation conventions: virtual environments (VIRTUAL_ENV), --prefix, --root (the DESTDIR equivalent for Python packaging), --target, --user, and PIP_* environment variables. The project defines no custom installer and overrides none of these locations.

CONTRIBUTING.md opens with a numbered quick-setup block using standard Python conventions: clone, then pip install -e '.[dev]' (editable install with the dev extra, which brings in the full test and lint environment), followed by an explicit verification sequence the contributor runs to confirm the environment works — pytest -q, ruff check ., ruff format --check ., and the project's own conformance checks. No custom tooling or bespoke bootstrap script is required.
https://github.com/open-coder-ai/chock/blob/main/CONTRIBUTING.md

Runtime and development dependencies are declared in pyproject.toml in the standard PEP 621 computer-processable form (project.dependencies and project.optional-dependencies). CI and build dependencies are additionally pinned in compiled requirements files under requirements/ (generated by pip-compile), each carrying exact versions and sha256 hashes and installed with --require-hashes.
https://github.com/open-coder-ai/chock/blob/main/pyproject.toml

Dependabot is enabled on the repository for both security alerts and version updates (grouped into a single weekly PR to keep the update stream reviewable), so newly disclosed vulnerabilities in external dependencies surface automatically and are fixed by merging the update. GitHub secret scanning and CodeQL run alongside it. The project vendors no convenience copies of third-party code — every external dependency arrives via pip from the declared manifests — and CI installs are hash-pinned with --require-hashes, so a tampered or substituted dependency fails the build closed rather than installing silently.
https://github.com/open-coder-ai/chock/blob/main/.github/dependabot.yml

Both apply. The project uses the standard Python library wherever possible — notably, the vendored pre-tool-use adapter and gate runner that Chock writes into adopter repositories are stdlib-only by contract, so they carry no third-party surface at all. The remaining externally-maintained components are ordinary pip dependencies declared in pyproject.toml (and hash-pinned in requirements/ for CI), so identifying one is reading a single manifest and updating it is a version bump — which Dependabot proposes automatically.
https://github.com/open-coder-ai/chock/blob/main/pyproject.toml

The project targets Python 3.11+ and uses current standard-library APIs (e.g. pathlib, tomllib, importlib.resources, datetime with explicit timezones) rather than their deprecated predecessors. Deprecation warnings are treated as defects rather than noise: the test suite surfaces them and Ruff's lint ruleset flags outdated constructs in CI, so a deprecated call fails review rather than accumulating.

The full automated test suite (712 tests) runs in GitHub Actions on every push and every pull request to main, across Python 3.11 and 3.12, alongside an acceptance tier, a packaged-binary check, lint/format checks, and CodeQL. Results are reported as GitHub status checks on the commit and PR, and the core jobs are required checks under branch protection — a failing suite blocks the merge rather than merely reporting
https://github.com/open-coder-ai/chock/blob/main/.github/workflows/ci.yml

The project's practice is 100%, not 50%: every bug fix ships with a regression test in the same pull request, and CONTRIBUTING.md requires it. Recent examples each landed with a dedicated test module — the gate-runner bypass fixes (tests/test_gate_bypasses.py), manifest-id validation (tests/test_manifest_id_safety.py), coverage-honesty overclaims (tests/test_coverage_honesty*.py), Windows line-ending defects (tests/test_windows_line_endings.py), adopter-data-loss fixes (tests/test_adopter_safety.py), and the policy-id trailing-newline fix found by the property suite (tests/test_properties.py).
https://github.com/open-coder-ai/chock/tree/main/tests

Measured with coverage.py (FLOSS): 81% statement coverage across 712 tests. The measured figure understates actual coverage, because a substantial share of the CLI and hook code paths execute in subprocesses during the acceptance tier — coverage.py cannot attribute those lines to the parent run — and the installed hooks execute vendored copies of the source rather than the source files themselves. The test suite itself is FLOSS (pytest + Hypothesis), and coverage is reproducible locally with pytest --cov.

CONTRIBUTING.md states the policy in writing: behavior changes require tests in the same pull request, and the project's review standards name the test suite as non-negotiable for new functionality. It is enforced rather than aspirational — CI runs the full suite plus an acceptance tier on every pull request as required status checks, and the repository's own committed policies (agent-discipline) additionally block weakening or deleting assertions to make a change pass.
https://github.com/open-coder-ai/chock/blob/main/CONTRIBUTING.md

Documented in CONTRIBUTING.md, the instructions contributors are pointed at for change proposals: tests are expected for behavior changes, and required CI must pass before merge.

The linters run at strict settings repo-wide with no ignore-baseline; the one deliberately pinned choice (ruff minor version) exists to keep formatting deterministic in CI, not to relax rules. Beyond linting, the project holds itself to stricter-than-typical machine-enforced contracts: byte-identical compiled outputs across PATCH releases (golden suite) and a documented line-budget/style check on its own sources.

he design applies the standard principles where they bear on a repo-local governance tool. Least privilege: workflow tokens are read-only by default with write scopes granted per-job, and the tool requests no credentials of its own. Fail-safe defaults: gates fail closed — an unresolvable CI base ref exits non-zero rather than passing, the hook installer bakes an absolute interpreter path (a missing interpreter previously meant exit 127, which a host reads as "allow"), and empty or uninstalled surfaces claim nothing. Complete mediation: the CI gate re-checks the same compiled gates server-side, where local hook bypasses cannot reach. Input validation by allowlist: policy ids, manifests, agent selections, URL schemes, and catalog paths are all validated against fixed patterns or schemas. Economy of mechanism: one compiled gate definition drives every surface, so there is a single place to reason about behavior. Untrusted-input separation: repository and web content processed by the tool is treated as data, never as instructions. No dynamic code execution (eval/exec) exists anywhere in the codebase. The full argument, with the test suite proving each mechanism, is in docs/assurance-case.md.
https://github.com/open-coder-ai/chock/blob/main/docs/assurance-case.md

No weakened algorithms either: SHA-256 only — no SHA-1, no CBC or any cipher modes (nothing is encrypted), no legacy fallbacks.

N/A: the software never processes authentication credentials or private cryptographic keys. It runs locally against a repository, and its one network path is an unauthenticated HTTPS document fetch. Publishing to PyPI uses OIDC Trusted Publishing, so the release pipeline holds no stored token or key either.

The software's network surface is minimal and HTTPS-only. The one fetch path enforces the scheme explicitly — a URL that is not https:// is refused with a warning and returns empty rather than falling back, so http://, file://, and custom schemes cannot be used even if a future caller passed one. Catalog installs use git clone over HTTPS (or the user's own SSH configuration). There is no insecure-protocol option to disable, because none is implemented.

TLS is used through Python's standard library (urllib over the ssl module) with default settings on Python 3.11+, where the minimum protocol version is TLS 1.2 and older SSL/TLS versions are disabled. The project does not lower or override these defaults.

Certificate verification is on by default and never disabled: the fetch path uses Python's standard urllib.request.urlopen with the default SSL context, which verifies the server certificate and hostname against the system trust store. The codebase contains no unverified context (ssl._create_unverified_context), no verify=False equivalent, and no certificate-check bypass flag for users to enable.

Met, and vacuously safe: certificate verification is performed by the standard library as part of establishing the connection, before any request headers are sent. The software additionally sends no private information at all over its network path — the fetch is an unauthenticated GET of a public documentation page, with no cookies, credentials, or authorization headers.

Every release is cryptographically signed via Sigstore: the tag-triggered release workflow generates a build-provenance attestation for each distribution artifact, binding the artifact's digest to the exact source commit and workflow that produced it. Signing uses Sigstore's keyless flow with short-lived certificates issued against the workflow's OIDC identity, so there is no long-lived private signing key at all — and therefore none stored on PyPI or any distribution site. Publishing itself uses PyPI Trusted Publishing (OIDC), so no static credential exists in the pipeline either.

The verification process is documented in SECURITY.md under "Verifying a release", pinned to the signing workflow and the version tag rather than to the repository alone:

gh attestation verify chock-0.1.1-py3-none-any.whl --repo open-coder-ai/chock --signer-workflow open-coder-ai/chock/.github/workflows/release.yml --source-ref refs/tags/v0.1.1

Trust roots come from Sigstore's public transparency log, so users need no project-specific key distribution. This command was verified against the published v0.1.1 wheel.
https://github.com/open-coder-ai/chock/blob/main/SECURITY.md

All untrusted inputs are validated against allowlists and rejected on mismatch, never sanitized into something "close enough" — a rewritten value would silently disagree with the identifier every other artifact is keyed by. Specifically: policy ids are checked with an anchored fullmatch against a fixed character pattern with a length bound, and must equal their folder name; manifests are validated against committed JSON Schemas; agent selections are checked against a fixed set of known agents; URLs must begin with https:// or the fetch is refused; catalog paths and artifact ids are confined to a single path component within the catalog root, blocking traversal; and content processed from repositories and the web is treated as data, never as instructions. These parsers are covered by property-based tests and weekly coverage-guided fuzzing — which is how a trailing-newline acceptance bug in the id validator was found and fixed in 0.1.1.
https://github.com/open-coder-ai/chock/blob/main/docs/assurance-case.md

Hardening is applied both to the project's own supply chain and to the artifacts it produces. Supply chain: every GitHub Action is pinned to an immutable commit SHA, workflow tokens default to read-only with write scopes granted per job, pip installs use compiled requirements with --require-hashes so substituted content fails closed, publishing uses OIDC with no stored credentials, and all repositories are under branch-protection rulesets requiring passing checks. Produced artifacts: generated hooks and guards are stdlib-only with no third-party imports, no eval/exec exists in the codebase, subprocess calls avoid shell interpretation and use explicit argument lists, hook commands are written with absolute interpreter paths so a missing interpreter is a hard failure rather than a silent allow, and hooks run under a timeout. Static analysis (CodeQL plus Ruff's security rules) runs on every pull request with findings triaged to zero.

The assurance case is published at docs/assurance-case.md. It contains all four required elements as named sections:

Threat model — six threat classes with their adversaries: agent misbehavior in-session (destructive commands, guardrail tampering, secret commits), malicious or compromised catalog content (policy folders ship executable guard scripts), tampering with installed artifacts, gate bypass by construction (renames, merge commits, non-ASCII paths, unresolvable CI ranges, missing interpreters), overclaim — the project reporting enforcement no installed mechanism provides — and supply-chain compromise of the project itself.

Trust boundaries — four, identified explicitly: the adopter repository (trusted, versioned), the agent session (untrusted executor that may ignore or attempt to modify guidance), the catalog (semi-trusted remote shipping executable content, trust-on-first-use with hash pinning), and CI (the enforcement floor a local actor cannot bypass).

Secure design principles applied — least privilege, fail-safe defaults, complete mediation, economy of mechanism, separation of data from instructions, and open design, each tied to the concrete decision implementing it in this codebase.

Common implementation weaknesses countered — a table mapping CWE classes (command/argument injection, path traversal, improper input validation, insecure transport, improper handling of exceptional conditions, prompt injection, hardcoded credentials) to the counter and the test suite or gate that evidences it, plus CodeQL and Ruff security rules on every pull request.

The document also states residual risks plainly rather than claiming completeness: no catalog signing (hash pinning gives detection, not prevention), git hooks bypassable outside gated agents, guards are best-effort filters rather than a security boundary, and fail-open agent hosts.
https://github.com/open-coder-ai/chock/blob/main/docs/assurance-case.md

CodeQL runs with its security query packs for Python — the queries specifically target common vulnerability classes (injection, path traversal, clear-text logging of sensitive data, uninitialized use). They have produced real findings here that were fixed (e.g., statically-unprovable parser exits, a dead re-export), not just noise.

N/A: the project is written entirely in Python, a memory-safe language, with no C/C++ extension modules. (Beyond what this criterion requires, the project does run coverage-guided fuzzing with atheris weekly against its id-validation and agent-selection parsers.)