snodo

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.

Development happens continuously on the public main branch, not only at release
points. Every change lands as an individual commit visible at
https://github.com/snodo-dev/snodo/commits/main, with agent and human work merged as
reviewable units between releases. Releases are tags on that history
(https://github.com/snodo-dev/snodo/releases), so the full interim state between any
two releases is available for review.

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

Each release carries a unique semantic version, set in pyproject.toml, published to
PyPI (https://pypi.org/project/snodo/) and tagged in git. A release gate
(scripts/check_release_version.py) runs in make release and in the release
workflow, and refuses to publish unless the git tag, the pyproject.toml version and
a matching CHANGELOG section all agree.

Every release is an annotated git tag of the form vX.Y.Z, created by the release
process and pushed with the release commit. Tags are listed at
https://github.com/snodo-dev/snodo/tags and each has a corresponding GitHub Release
carrying the changelog body and the built distribution artifacts.

Non-trivial release notes file in repository: https://github.com/snodo-dev/snodo/blob/main/CHANGELOG.md.

No CVE or equivalent has ever been assigned against snodo itself, so no release notes have had a vulnerability to identify. The criterion excludes dependencies; dependency advisories are handled separately by pip-audit and OpenSSF Scorecard in CI, and dependency upgrades that clear advisories are recorded in CHANGELOG.md.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/snodo-dev/snodo/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues: https://github.com/snodo-dev/snodo/issues

All bug reports are triaged and responded to. 170 issues have been closed against 10 open at time of writing, and issues are referenced by the commits that fix them (Fixes #N), so every report has a traceable response.

Enhancement requests are triaged in the same tracker as bug reports and receive the same response rate; the project is single-maintainer with a low volume of external requests, all of which have been answered.

https://github.com/snodo-dev/snodo/issues?q=is%3Aissue — the full issue history,
open and closed, is public and searchable, along with all responses.

https://github.com/snodo-dev/snodo/blob/main/SECURITY.md publishes the reporting
process, and it is linked from the README badge row on the project site.

https://github.com/snodo-dev/snodo/blob/main/SECURITY.md states that vulnerabilities
must not be reported as public GitHub issues, and gives a private reporting channel:
email security@snodo.dev, with the requested contents (description and impact,
reproduction steps, suggested fix). It commits to acknowledgement within 72 hours and
a fix within 14 days of a confirmed vulnerability.

No vulnerability reports have been received in the last 6 months, so there is no response time to report. SECURITY.md commits to acknowledgement within 72 hours, well inside the 14-day requirement.

Non-trivial build file in repository: https://github.com/snodo-dev/snodo/blob/main/Makefile.

Non-trivial build file in repository: https://github.com/snodo-dev/snodo/blob/main/Makefile.

snodo is pure Python. The build backend is hatchling and the workspace/dependency
manager is uv, both FLOSS. Test and lint tooling (pytest, ruff, import-linter,
hypothesis) is FLOSS. No proprietary tool is needed to build, test or release:
https://github.com/snodo-dev/snodo/blob/main/pyproject.toml

The project has an automated test suite (pytest, with hypothesis for property-based
tests) covering unit, integration and end-to-end levels. Instructions for running it
are in CONTRIBUTING.md under "Testing and checks":
https://github.com/snodo-dev/snodo/blob/main/CONTRIBUTING.md
Tests live in https://github.com/snodo-dev/snodo/tree/main/tests

The suite is invoked in the standard Python way: uv run pytest tests/
(end-to-end subset: uv run pytest tests/e2e/ -m e2e). The same command is used
locally and in CI: https://github.com/snodo-dev/snodo/blob/main/.github/workflows/ci.yml

Statement coverage is ~78%, enforced by a 75% minimum gate in CI. Coverage is
concentrated on the protocol engine and its invariants; the invariants INV1-INV5 are
additionally covered by property-based tests using hypothesis rather than by
example-based tests alone.

GitHub Actions runs the full test suite, ruff, and import-linter contract checks on
every push and pull request:
https://github.com/snodo-dev/snodo/blob/main/.github/workflows/ci.yml

CONTRIBUTING.md states the policy under "Testing and checks" and in the pull
request checklist: "Tests required for new behaviour" and "All existing tests must
pass, including e2e". Change classes carry specific requirements: a change to a
merge gate must add a test that injects the violation the gate exists to catch, and
a change touching tokens or invariants must extend the INV1-INV5 property suite in
tests/properties/test_invariants.py rather than adding only unit tests.
https://github.com/snodo-dev/snodo/blob/main/CONTRIBUTING.md

Recent feature work ships with its tests in the same commit. Examples: the ADR 040
"coder observes declared test runner" work, the worktree-isolation enforcement
(ADR 024/025), and the audit-log resolution fix on the merge path each added tests
alongside the change. The change log and commit history show the pattern:
https://github.com/snodo-dev/snodo/commits/main

The requirement is written into the pull request checklist in CONTRIBUTING.md
("Tests required for new behaviour"), which is the instruction document for change
proposals: https://github.com/snodo-dev/snodo/blob/main/CONTRIBUTING.md

ruff is run over the whole repository (uv run ruff check .) in CI on every push
and pull request. The rule set is pinned and explicitly enumerated in pyproject.toml
[tool.ruff.lint]: ruff's default F + E4/E7/E9 set, plus B904 and a flake8-bandit
subset (S105, S110, S311, S314, S602, S603, S607) added deliberately, each after its
existing violations were cleared. import-linter additionally enforces six
architectural layering contracts.
https://github.com/snodo-dev/snodo/blob/main/pyproject.toml

ruff, import-linter and the test suite are blocking checks in CI, so warnings are
fixed before merge rather than accumulating. Rules are added one at a time with
their violations fixed in the same release. Where a bandit finding is intentional it
carries a scoped # noqa with a written reason rather than a blanket suppression;
test and experiment trees ignore the bandit subset only, since those rules describe
a shipped binary's threat model and not a test harness.

All enabled lint findings are blocking in CI — there is no warning tier that is
tolerated. Strictness is ratcheted rather than maximal-by-default: the ruff rule set
is pinned and widened one rule at a time, each added only after its existing
violations are cleared, because an unpinned ruff bump would take the repo from clean
to thousands of findings with no code change and no way to tell a real regression
from a rule-set change. Intentional exceptions carry a scoped # noqa with a written
reason rather than a blanket suppression. import-linter additionally enforces six
architectural layering contracts as hard failures.
https://github.com/snodo-dev/snodo/blob/main/pyproject.toml

The primary developer designs the system around least privilege, containment and
tamper-evidence rather than trust. Concrete evidence in the codebase: agent coders
run inside per-task git worktrees with enforced containment (ADR 024/025); tool
access is a declared, whitelisted capability set per protocol mode rather than
ambient authority (ADR 035); the audit log is a SHA-256 hash chain so tampering is
detectable; human adjudication records are RS256-signed JWTs with the algorithm
pinned and the signing key held only by the CLI adjudicate path, with a separate
verify-only issuer that structurally cannot mint. Security-relevant design decisions
are recorded as ADRs with their rationale:
https://github.com/snodo-dev/snodo/tree/main/docs/decisions

The relevant error classes for this kind of software — a tool that executes untrusted model output — are command injection, path traversal / sandbox escape, privilege escalation via ambient credentials, secret leakage into logs, and tampering with the integrity record. Each has a counter in the codebase: subprocess invocation is argv-list only with no shell and a whitelisted binary; file and execution scope is bounded to the task worktree; capability grants are declared per mode and denied by default; the audit chain is hash-linked so retroactive edits are detectable; adjudication tokens moved from HS256 to RS256 with the algorithm pinned at verify time so an attacker cannot downgrade the signature scheme. The relevant bandit rules (S602/S603/S607/S105/S110/S311/S314) are enabled in ruff and enforced in CI, with each intentional exception carrying a scoped noqa and a written reason.

Only standard, publicly reviewed primitives are used: SHA-256 for the audit log's
hash chain and RS256 (RSASSA-PKCS1-v1_5 with SHA-256) for signing human adjudication
records, via the pyjwt library. No custom or proprietary algorithm is used. The
verify path pins algorithms=["RS256"] so a token declaring another algorithm is
rejected rather than accepted; the earlier HS256 scheme was retired and stale HS256
records are explicitly rejected and audited.
https://github.com/snodo-dev/snodo/blob/main/packages/snodo-foundation/src/snodo/infrastructure/decisions.py

snodo's purpose is protocol enforcement for AI-assisted development, not
cryptography. It implements none of its own: hashing uses Python's stdlib hashlib
(SHA-256), and JWT signing and verification use pyjwt backed by the cryptography
library (OpenSSL). Keypair generation uses cryptography's rsa.generate_private_key.
https://github.com/snodo-dev/snodo/blob/main/packages/snodo-foundation/src/snodo/infrastructure/signing_keys.py

Every cryptographic dependency is FLOSS and runs on FLOSS: Python's stdlib hashlib, pyjwt (MIT), and the cryptography library (Apache-2.0 / BSD, over OpenSSL). No proprietary or hardware-bound component is required for any crypto-dependent functionality.

The only asymmetric mechanism is RS256 for adjudication records. snodo generates the
keypair itself at RSA 2048-bit, which meets the NIST minimum through 2030; the size
is fixed in code rather than user-supplied, so a smaller key cannot be configured at
all. Hashing is SHA-256 throughout (audit chain and JWT digest).
https://github.com/snodo-dev/snodo/blob/main/packages/snodo-foundation/src/snodo/infrastructure/signing_keys.py

The defaults are SHA-256 and RS256 only. No broken algorithm appears anywhere in the
codebase: there is no MD4, MD5, SHA-1, DES, RC4 or Dual_EC_DRBG usage, and no cipher
modes are selected by the project since no bulk encryption is performed. The earlier
symmetric HS256 scheme was deliberately retired; the verify path pins
algorithms=["RS256"], so a token presenting any other algorithm is rejected and the
rejection is written to the audit log rather than silently accepted.

No SHA-1 and no CBC-mode construction is used. Integrity uses SHA-256 hash chaining;
signatures use RS256 (RSASSA-PKCS1-v1_5 with SHA-256) with the algorithm pinned at
verification. No TLS or SSH cipher suites are configured by the project — outbound
HTTPS uses the platform's defaults via requests/httpx.

snodo implements no key agreement or session-key negotiation protocol. Its only cryptographic mechanisms are SHA-256 hash chaining for audit integrity and RS256 signatures on adjudication records; there are no long-term keys used to derive session keys. Perfect forward secrecy for outbound HTTPS is provided by the TLS stack of the platform and its libraries, not by anything this project configures.

snodo stores no passwords and authenticates no external users. It is a single-operator local CLI. The only secrets it handles are model-provider API keys, which are read from environment variables and never persisted by the project.

All security-relevant random material comes from a CSPRNG. The RS256 keypair is
generated by the cryptography library's rsa.generate_private_key, which draws from
the OS entropy source; API token generation uses secrets.token_hex, and session
identifiers use secrets.token_hex. The single use of the random module is a
six-character human-readable short id for a local tunnel — not a credential, not
used in any security decision — and it carries a scoped # noqa: S311 stating that.
The flake8-bandit rule S311 is enabled in ruff repo-wide, so any new non-CSPRNG use
fails CI unless it is deliberately annotated.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

The project retrieves no hashes over http. Dependencies are resolved from PyPI over
HTTPS and pinned in uv.lock, which records a cryptographic hash for every artifact,
so installs are verified against the lockfile rather than against a hash fetched at
install time. Releases are published to PyPI over HTTPS from a GitHub Actions
workflow and git tags are the release record; nothing in the build or install path
downloads a checksum over plain http.
https://github.com/snodo-dev/snodo/blob/main/uv.lock

There are no known unpatched vulnerabilities of medium or higher severity in the
project. Dependencies are watched by Dependabot (.github/dependabot.yml) and the code
is scanned by CodeQL on every push (.github/workflows/codeql.yml), with an OpenSSF
Scorecard workflow running alongside. No vulnerability has been reported against
snodo to date; the project is young (first public release 2026) and has had no CVEs.
https://github.com/snodo-dev/snodo/blob/main/.github/workflows/codeql.yml

The project's stated response process is in SECURITY.md: reports are acknowledged
promptly and critical issues are fixed and released ahead of other work. Releases are
frequent (patch releases ship within days), so a fix reaches users quickly once
made. No critical vulnerability has been reported to date, so this reflects the
committed process rather than a track record of past incidents.
https://github.com/snodo-dev/snodo/blob/main/SECURITY.md

No credential is committed. The repository tracks no .pem, .key, .env or credential
file, and the RS256 signing keypair is generated at runtime outside the repository
(~/.ssh/NO-AGENT/) rather than shipped. Provider API keys are read from environment
variables only. Any key material appearing in tests is a fixture generated for the
test run, not a working credential. GitHub secret scanning with push protection is
enabled on the repository, and CI secrets are referenced as GitHub Actions secrets
rather than inlined.

CodeQL runs on every push and pull request, including the commits that become a
release (.github/workflows/codeql.yml). ruff also runs repo-wide with a
flake8-bandit subset enabled (S105, S110, S311, S314, S602, S603, S607), and
import-linter enforces six architectural layering contracts. All are FLOSS and all
are blocking checks, so no release ships without them having passed.
https://github.com/snodo-dev/snodo/blob/main/.github/workflows/codeql.yml

CodeQL's Python query suite targets exactly the common vulnerability classes for this language — injection, path traversal, unsafe deserialization, and similar. The enabled ruff bandit rules cover the ones most relevant to a tool that executes model output: subprocess and shell invocation (S602/S603/S607), unsafe XML parsing (S314), hardcoded secrets (S105), swallowed exceptions (S110) and non-CSPRNG randomness (S311).

CodeQL and ruff are blocking checks on every push and pull request, so a finding
stops the change rather than accumulating as a backlog item — findings are addressed
before merge. No medium-or-higher exploitable finding is currently open. Where a
bandit rule fires on an intentional construct, the site carries a scoped # noqa
with a written justification rather than a blanket suppression, so the exceptions are
individually reviewable.

CodeQL, ruff and import-linter all run on every push and every pull request via
GitHub Actions — not on a schedule, so analysis is never more than one commit stale.
https://github.com/snodo-dev/snodo/blob/main/.github/workflows/codeql.yml
https://github.com/snodo-dev/snodo/blob/main/.github/workflows/ci.yml

The full test suite runs under CI on every push and on every release commit,
including 124 end-to-end tests that invoke the snodo CLI as a subprocess against
real git repositories rather than mocks. Hypothesis property-based tests generate
inputs to attack the INV1-INV5 invariants
(tests/properties/test_invariants.py) — dynamic analysis in the fuzzing sense: the
tool generates the inputs, not the author. Assertions are active throughout.
https://github.com/snodo-dev/snodo/tree/main/tests

snodo is pure Python with no C or C++ extension modules of its own. It produces no software written in a memory-unsafe language.

Tests run under pytest with assertions enabled (Python is never invoked with -O in CI or in the documented local commands), and pytest's assertion rewriting is active, so every assertion in the suite and in the code under test is checked. Hypothesis is configured to shrink and report counterexamples rather than suppress them. Assertions are a test-time mechanism only; the shipped package makes no behavioural guarantee dependent on them.

No medium-or-higher exploitable vulnerability has been found by dynamic analysis. The suite is a blocking gate on every push and pull request, so a failure stops the change rather than being triaged later; defects it surfaces are fixed before merge.