chock

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

The repository carries every interim change, not just releases: all development lands as individually reviewable pull requests on main (PR-only, enforced by branch protection), with the full commit history public between tagged releases. Releases (v0.1.0) are tags on that history, not code drops.

Repository on GitHub, which uses git. git is distributed.

Every release has a unique identifier: git tags (v0.1.0) and matching immutable PyPI versions (https://pypi.org/project/chock/#history — PyPI forbids re-uploading a version). A validator check additionally enforces that the CHANGELOG's top entry matches the pyproject version, so a release cannot ship with a mismatched identifier.

Every release is a git tag: v0.1.0 (the release), plus a v1 major tag tracking the latest compatible release for GitHub Action consumers (uses: open-coder-ai/chock@v1). Tags: https://github.com/open-coder-ai/chock/tags

Non-trivial release notes file in repository: https://github.com/open-coder-ai/chock/blob/main/CHANGELOG.md.

No publicly known vulnerabilities (CVE or otherwise) have existed in any release to date (first public release v0.1.0, August 2026). SECURITY.md commits that future vulnerability fixes ship in patch releases and are identified in the CHANGELOG.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/open-coder-ai/chock/blob/main/SECURITY.md. [osps_do_02_01]

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.

The project is newly public (August 2026); every issue filed to date has been acknowledged and triaged, and the maintainer's practice is to acknowledge all bug reports — the current issue set is fully labeled and responded to (https://github.com/open-coder-ai/chock/issues). SUPPORT.md sets response expectations.

All enhancement requests to date have been responded to — several became labeled roadmap issues with written rationale (e.g., the MCP-gateway surface and the rate-limit/budget gate kind), and GitHub Discussions is seeded for ideas. Same newly-public caveat: the practice is established, the volume is early.

https://github.com/open-coder-ai/chock/issues?q= — GitHub Issues (including closed) is the public, searchable archive of reports and responses; Discussions (https://github.com/open-coder-ai/chock/discussions) archives questions and answers the same way.

https://github.com/open-coder-ai/chock/blob/main/SECURITY.md — publishes the process: report privately via the GitHub security advisory form (direct link included: https://github.com/open-coder-ai/chock/security/advisories/new), never via public issues for exploitable findings; what to include in a report; acknowledgment within 7 days and initial assessment within 14;

Private reporting is supported and documented in SECURITY.md: GitHub private vulnerability reporting is enabled on the repository, and the advisory form (https://github.com/open-coder-ai/chock/security/advisories/new) delivers the report privately to the maintainer — nothing transits a public channel. SECURITY.md explicitly instructs not to open public issues for exploitable findings.

No vulnerability reports have been received to date (project newly public, August 2026), so none has ever waited — and SECURITY.md commits the standard: acknowledgment within 7 days, initial assessment within 14.

Standard Python build: python -m build produces the sdist and wheel from source (PEP 517, pyproject.toml). CI rebuilds on every PR across Python 3.11 and 3.12, the release workflow builds the published PyPI artifacts the same way, and standalone binaries are built with PyInstaller on Linux/macOS/Windows. Anyone can rebuild from a clean checkout with stock FLOSS tooling.

Only ecosystem-standard tools: pip, python -m build (setuptools backend), pytest, ruff — nothing custom or exotic in the build path.

Entirely buildable with FLOSS: Python, pip, setuptools/build, pytest, ruff, PyInstaller — all open source. No proprietary tool appears anywhere in the build, test, or release path.

The test suite ships in the repository under the same Apache-2.0 license: ~680 pytest tests plus a Gherkin acceptance tier (pytest-bdd) and replayed policy evals. How to run is documented in CONTRIBUTING.md and demonstrated by CI itself (.github/workflows/ci.yml runs python -m pytest on Python 3.11 and 3.12 on every PR): pip install -e '.[dev]' && python -m pytest

python -m pytest — the standard Python invocation, from the repo root, exactly as CI runs it.

Test-to-source ratio is above 1:1 (~680 tests over a deliberately small codebase). Coverage spans unit tests, an end-to-end Gherkin acceptance tier (init → add → sync → blocked commit), golden-file suites over compiled outputs, replayed evals for every published policy, Hypothesis property tests over the security-critical parsers, and coverage-guided fuzzing (atheris) in CI. Adversarial branches — the ones that matter here — are tested on purpose: gate bypto attempts, malformed manifests, injection-shaped ids.

GitHub Actions CI runs the full test matrix (Python 3.11 + 3.12), lint, binary build, and acceptance tier on every pull request and every push to main; branch protection makes green CI a required condition to merge (https://github.com/open-coder-ai/chock/actions/workflows/ci.yml). Additionally, the repo's own commit hooks run a fast subset locally before a commit is even created.

CONTRIBUTING.md states the policy: behavior changes are expected to come with tests, and CI (required to merge) enforces the suite stays green. The history demonstrates the practice — every feature PR to date has carried its tests (examples: the agent-selection regression suite added with the selection funnel, property-based tests added alongside the id-validation hardening).

Recent major changes each carry their tests, visible in the repo history: the arm-on-clone feature landed with SessionStart-hook tests; the Cursor pre-tool-use surface landed with envelope-identity and end-to-end blocking tests; the sync-wires-guards change landed with a byte-stability regression suite; the id-validation hardening landed with the Hypothesis property suite (which itself found and fixed a real bug on first run). The test suite has grown in

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.

ruff (FLOSS) runs in two enforced places: ruff check plus ruff format --check gate CI on every PR, and the repository's own committed pre-commit policy runs them repo-wide before a commit is created. CodeQL additionally runs security-and-quality queries on every PR.

Warnings block: CI fails on any ruff finding, so the tree is kept at zero — there is no suppressed baseline or warning backlog. CodeQL alerts are triaged publicly to zero actionable (each fixed or dismissed with a written reason on the alert).

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.

The sole developer (by the criterion's definition, the primary developer: initiated the project, accepts commits, performs releases, receives private vulnerability reports) understands and applies these principles; the project's own design is the evidence, principle by principle:

• Economy of mechanism: stdlib-only vendored runtime, three declarative gate kinds instead of a policy language, deliberately small codebase.
• Fail-safe defaults: a malformed policy manifest compiles to nothing rather than partial enforcement; atomic recompile means a failed sync can never strand a repo with its enforcement deleted; CI gate ranges fail closed.
• Complete mediation: the coverage taxonomy exists precisely to document where mediation is and is not complete per agent — surfaces that can be bypassed are labeled, never assumed.
• Open design: everything (policies, compiler, hooks, evals) is public source; the guarantees rest on hashes (chock.lock content pinning), not on secrecy of mechanism.
• Separation of privilege: enforcement is layered so defeating one layer (deleting a local hook) does not defeat the CI gate; changes to agent-config protected paths additionally require an explicit diff-visible approval marker.
• Least privilege: all CI workflows run with top-level read-only tokens; the one contents:write is job-scoped to release creation; PyPI publishing uses short-lived OIDC (Trusted Publishing), no long-lived tokens.
• Least common mechanism: per-repo, per-agent compiled artifacts — no shared service, daemon, or global state between adopters.
• Psychological acceptability: block messages carry the policy's reasoning and remediation; every hard guard has a documented, diff-visible escape hatch, because an unsatisfiable guard gets disabled by its users.
• Limited attack surface: no network calls at enforcement time, no LLM in the decision path, no dynamic code loading; installing a policy is reviewed content, hash-pinned.
• Input validation with allowlists: policy ids are validated against an allowlist pattern (fullmatch of [a-z][a-z0-9-]{2,63}) before ever becoming a path or shell token — enforced at the compiler choke point, with property-based tests proving acceptance implies shell/path safety.

Countering these error classes is the project's subject matter, and the countermeasures are implemented, not just known:

• Injection into generated shell/paths (the project's most relevant class): allowlist-validated identifiers at the compiler choke point; property tests and coverage-guided fuzzing prove acceptance implies shell/path safety; a real trailing-newline acceptance bug was found by these tests and fixed.
• Credential leakage: secret scanning + push protection on the repo; the scan-secrets policy (with documented allowlist pragmas) guards staged content; no long-lived publish tokens (OIDC Trusted Publishing).
• Supply-chain tampering: all CI actions pinned to commit SHAs; pip installs hash-pinned; catalog installs hash-verified before anything is written to disk (chock.lock); build-provenance attestation on releases.
• Hidden-text/homoglyph attacks (Trojan Source, CVE-2021-42574): the block-invisible-unicode gate exists specifically for this class.
• TOCTOU/partial-state failures: atomic recompile with post-swap verification.
• Overclaiming as a security failure: the coverage honesty mechanism — treating an unenforced-but-reported control as the vulnerability it is.
  Each is documented in SECURITY.md's threat model or the enforcement-surfaces docs.

The only cryptographic algorithm used anywhere is SHA-256 (publicly published, expert-reviewed, NIST FIPS 180-4), via Python's stdlib hashlib, for content pinning: chock.lock hashes policy sources and compiled artifacts, and catalog installs verify content hashes before writing. The project implements no cryptographic protocols of its own — TLS for delivery is provided by PyPI/GitHub infrastructure.

Cryptography is never re-implemented: the single cryptographic operation (SHA-256 content hashing for chock.lock pinning and install verification) calls Python's stdlib hashlib exclusively.

The only cryptography-dependent functionality (SHA-256 content hashing) uses Python's stdlib hashlib — FLOSS (PSF license) end to end. Nothing depends on proprietary cryptographic components.

No keys exist anywhere in the software: no key generation, storage, exchange, or configuration. The sole cryptographic use is SHA-256 hashing for content pinning, which has no keylength parameter (and SHA-256 itself meets NIST's through-2030 requirements).

No broken algorithms or inappropriate cipher modes anywhere: the only cryptographic primitive in the codebase is SHA-256 (via stdlib hashlib) for content pinning. No MD4/MD5/DES/RC4/Dual_EC_DRBG, no cipher modes at all (nothing is encrypted), and no interoperability constraint forcing legacy algorithms.

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

No key-agreement protocols are implemented and no long-term keys exist; transport security is provided by the PyPI/GitHub TLS infrastructure, not by this software.

The software stores no passwords or authentication credentials of any kind — there are no user accounts, no authentication, and its own policies (scan-secrets) exist to keep credentials out of the repositories it governs.

No cryptographic keys or nonces are generated anywhere in the software — no security-relevant randomness exists (no tokens, session ids, or keys). The only cryptographic operation is deterministic SHA-256 content hashing.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

No hash is ever retrieved over HTTP: catalog installs fetch over HTTPS (git clone of the catalog), and the expected hash is supplied out-of-band by the user (--verify-sha) or recorded in the committed chock.lock — content is verified against it BEFORE anything is written to disk. Delivery of the package itself is PyPI over HTTPS with pip's hash checking; CI dependencies are hash-pinned (--require-hashes) and workflow actions are pinned to commit SHAs.

No publicly known vulnerabilities of any severity exist in the project (first public release August 2026; no CVEs, no advisories). Dependency alerts are monitored via Dependabot and GitHub security advisories; SECURITY.md commits fixes to patch releases well inside the 60-day window.

None reported to date; the documented commitment (SECURITY.md) is acknowledgment within 7 days, assessment within 14, and critical fixes shipped as immediate patch releases. The project's demonstrated internal practice matches: security-relevant defects found by its own tooling (e.g., an identifier-validation bypass found by property tests) have been fixed within hours of discovery.

No valid credentials exist in the repository or its history: the public repo was created as a clean single-commit export, GitHub secret scanning and push protection are enabled, and releases publish via short-lived OIDC (Trusted Publishing) so no long-lived tokens exist to leak. The only secret-scanner hits ever raised were the scan-secrets policy's own synthetic, pattern-shaped eval fixtures (EXAMPLE/zeros bodies, marked with in-file

CodeQL (FLOSS-implemented analysis for Python) runs on every pull request and every push to main — so every release, major or not, is analyzed before it ships (.github/workflows/codeql.yml). OpenSSF Scorecard runs weekly on top. Pre-release, bandit and pip-audit were also run over the full tree. All findings are triaged publicly: fixed, or dismissed with a written reason attached to the alert.

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.

Every static-analysis finding to date was resolved within a day of confirmation: the error-level findings (uninitialized-variable class) were fixed the same day with a provably-terminating helper; the high-severity flagged items were analyzed, confirmed as false positives (diagnostics of repo-local files, no credential flow), and dismissed with individual written reasons on the alerts. Zero confirmed exploitable findings remain open.

CodeQL runs on every pull request and every push to main — effectively every commit that matters (main is PR-only). ruff runs even earlier: on every local commit via the repo's own committed pre-commit policy.

Two forms run continuously: coverage-guided fuzzing with atheris (fuzz/fuzz_policy_id.py via .github/workflows/fuzz.yml — weekly, on demand, and on any PR touching the parsers under test) and property-based testing with Hypothesis (tests/test_properties.py) in the main suite. The property suite found a real bug on its first run — the id validator accepted a trailing newline on an identifier spliced into generated bash — fixed the same hour.

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.)

The dynamic analysis is assertion-driven by design: the atheris fuzz harness asserts the safety invariants on every input (an accepted id must contain only shell/path-safe characters; selections returned must be known, deduplicated, and idempotent), and the Hypothesis property suite asserts the same contracts across generated inputs. These assertions are test/fuzz-time constructs, not production-path code.

The single exploitable finding from dynamic analysis to date — the id validator accepting a trailing newline (Python's $ anchor matching before it) on an identifier spliced into generated bash — was confirmed and fixed within the hour of discovery, with a regression property added to the suite. Nothing found by dynamic analysis remains open.