Palimpsests

The project provides a clear upgrade path to newer versions rather than backporting to old ones, which is the appropriate model for a pre-1.0 project. SECURITY.md states the version policy explicitly: Palimpsests is pre-1.0 and evolving, security fixes land on main and in the latest published release, older 0.x releases are not maintained, and users should track the latest version. The upgrade path itself is simple — the package is installed and updated through pip in the standard way — and the changes that affect an upgrade are documented per release in CHANGELOG.md, which follows a Keep-a-Changelog structure with explicit Changed and Breaking sections and upgrade notes where behaviour shifts (for example, the changelog records that before v1.0 minor versions may include breaking changes, and calls out cases such as a first post-upgrade write being required before verify() reports fully). So where an upgrade is non-trivial, the interfaces that changed and the recommended steps are documented.

The project uses GitHub Issues as its issue-tracking system to track individual bugs, tasks, and enhancement requests. CONTRIBUTING.md directs contributors to open or link an issue when submitting work, and security-sensitive reports are routed separately through the private channel described in SECURITY.md. URL: https://github.com/Assault-Consulting/Palimpsests/issues

No externally reported vulnerabilities have been fixed in the last 12 months, so there is no reporter to credit — which makes this criterion not applicable for the current period. The project is nonetheless set up to credit reporters when the situation arises: SECURITY.md commits to crediting reporters in the release notes unless they ask to remain anonymous. When the first such report is fixed, the reporter will be credited there.

The project has a documented process for responding to vulnerability reports, published in SECURITY.md. It sets out how to report privately (GitHub private security advisories and a maintainer email, not a public issue), a response commitment (the maintainers will acknowledge a report within a few business days and agree on a disclosure timeline before any public disclosure), how reporters are credited (in the release notes, unless anonymity is requested), and which versions receive fixes (security fixes land on main and in the latest release; older 0.x releases are not maintained). This gives a reporter a clear, end-to-end path from private report to coordinated disclosure.
https://github.com/Assault-Consulting/Palimpsests/blob/main/SECURITY.md

The project identifies a specific coding style standard for its main language (Python) and requires contributions to comply with it. CONTRIBUTING.md has a "Code style" section naming the standard: ruff with the rule set ["E", "F", "I", "B", "UP"] (pycodestyle/PEP 8, Pyflakes, isort import ordering, flake8-bugbear, pyupgrade), a line length of 100, and target Python 3.11 — with the instruction to run ruff check . before pushing. This is not just documented but enforced: the ruleset is pinned in pyproject.toml ([tool.ruff] / [tool.ruff.lint]), and lint is a merge-blocking status check on main, so every contribution must generally conform before it can be merged.
https://github.com/Assault-Consulting/Palimpsests/blob/main/CONTRIBUTING.md

The project automatically enforces its chosen coding style. The style is defined as ruff with the rule set ["E", "F", "I", "B", "UP"], line length 100, target Python 3.11 (pyproject.toml, [tool.ruff] / [tool.ruff.lint]). ruff is an open-source style/lint tool for Python, and it is run automatically as a merge-blocking status check in CI on every push and pull request — a change that does not conform to the ruleset cannot be merged into main. Contributors also run ruff check . locally before pushing, per CONTRIBUTING.md. So enforcement is automated by an open-source tool for the project's main language, not left to manual review.

The project does not build native binaries, so compiler/linker environment variables (CC, CFLAGS, CXX, CXXFLAGS, LDFLAGS) do not apply. Palimpsests is pure Python, packaged with a PEP 517 build backend (hatchling); the build produces platform-independent wheels and an sdist, with no compilation step of its own. The one native component it can use — the llama.cpp C library — is not compiled by this project; it is consumed at runtime through the optional [native] extra as a separately built dependency. There is therefore no compiler or linker invocation in the project's build for these variables to be honored by.

There is no compilation or install step in this project that could strip debug information. Palimpsests is pure Python, built with a PEP 517 backend (hatchling) into platform-independent wheels — there are no compiled artifacts and no install -s-style stripping to avoid. Python source is shipped as-is and remains fully inspectable/debuggable; nothing in the build or install removes debug information. (The one native component, llama.cpp, is a separately built runtime dependency behind the optional [native] extra, not something this project's build or install produces.) This criterion therefore does not apply.

This criterion concerns recursive Make-style builds over subdirectories that have cross-dependencies (the classic "recursive make considered harmful" problem). It does not apply here: Palimpsests is pure Python with a PEP 517 build backend (hatchling), which builds the package as a single unit into wheels and an sdist — there is no recursive per-subdirectory build and therefore no opportunity for a recursive build to mishandle cross-directory dependencies. There is no Makefile or equivalent recursive build system in the project.

Palimpsests is a pure-Python project: the source is used directly rather than compiled into a different form. There is no compilation step whose output would need to be reproduced bit-for-bit — the .py files that run are the same source files kept in the repository, and packaging (a PEP 517 wheel/sdist via hatchling) simply archives that same source with metadata, it does not transform it. The criterion's own escape clause applies here — "scripting languages where source is used directly rather than compiled" — so this is not applicable.

Installation and removal use the standard, conventional mechanism for Python: pip. The software is published on PyPI and installed with pip install palimpsests (with optional extras — e.g. [native] — enabling the higher execution levels). It is a PEP 517/518 package built with hatchling, so it installs cleanly into any environment via the normal Python packaging path, and it is removed just as conventionally with pip uninstall palimpsests. No custom installer, build-from-source step, or manual file placement is required — the common practice for the language is exactly what the project uses.
https://pypi.org/project/palimpsests/

The project has no custom end-user installation system that writes compiled files to system locations, so conventions like DESTDIR do not apply. Installation is handled entirely by pip installing a PEP 517 wheel — pip already places files according to the active Python environment's standard scheme (site-packages / the environment prefix, honoring virtualenv/--prefix/--target as pip defines them), and the project neither overrides that placement nor ships a Makefile-style install target that would need to honor DESTDIR. There are also no compiled files of the project's own to place (pure Python). The criterion's escape clause — no separate install system of the project's own — therefore applies.

The project lets a potential developer set up the full change-making environment quickly, using common Python practice. CONTRIBUTING.md gives the steps: clone the repository, then python -m pip install -e ".[dev]" — an editable install of the project plus the [dev] extra, which pulls in the developer and test tooling (ruff pinned, pytest, pytest-httpx, numpy). After that, ruff check . runs the linter and python -m pytest runs the full test suite. So one standard editable-install command brings in the software, the supporting tools, and the test environment together, and tests are run with the standard Python invocation — no bespoke bootstrap script or manual dependency wrangling.

External dependencies are declared in a computer-processable format in pyproject.toml — the standard machine-readable manifest for a PEP 621 Python project. Runtime dependencies are listed under [project.dependencies], and the optional feature sets (e.g. [native] for the level-3 backend, [dev] for the developer/test tooling) under [project.optional-dependencies], each with version constraints (lower bounds; the lint tool pinned). Any standard tool — pip, build back-ends, dependency scanners, Dependabot — parses this file directly, and Dependabot is enabled on the repository to monitor those dependencies.
https://github.com/Assault-Consulting/Palimpsests/blob/main/pyproject.toml

The project monitors its external dependencies for known vulnerabilities on an ongoing basis. Dependabot is enabled on the repository, which continuously watches the dependencies declared in pyproject.toml against vulnerability databases and opens alerts/update pull requests when a known-vulnerable dependency is identified. The project also runs OpenSSF Scorecard, whose checks include dependency-update and vulnerability signals (badge shown on the repository front page). When an alert surfaces, it is handled through the normal pull-request process — updating the dependency, or confirming non-exploitability — under the response practice documented in SECURITY.md. There are currently no known unaddressed vulnerable dependencies.

Reused external components are easy to identify and update. The project does not vendor or copy third-party code into the tree; every externally maintained component is a normal, versioned dependency declared in pyproject.toml ([project.dependencies] and the optional-dependency groups), resolved from PyPI. Because they are standard packaged dependencies rather than embedded copies, updating one when a vulnerability is found is a routine version bump — pip resolves it, Dependabot proposes the update automatically, and no in-tree fork has to be patched by hand. The project also favors standard, widely used components delivered by the platform (e.g. SQLCipher/keyring for at-rest encryption and credential storage, httpx for transport) rather than bespoke implementations, so fixes flow from upstream maintenance.

The project avoids deprecated or obsolete functions and APIs where supported open-source alternatives exist. It targets current, actively supported Python (3.11+), and modern-Python usage is enforced automatically: the ruff ruleset includes UP (pyupgrade), which flags legacy idioms and pushes code to current language constructs, and lint is a merge-blocking gate — so deprecated patterns do not accumulate. Dependencies are kept current through Dependabot rather than pinned to end-of-life versions, and the components chosen are current, maintained ones (httpx for HTTP, SQLCipher/keyring, hatchling/PEP 517 packaging, Sigstore for signing) rather than deprecated predecessors. There are no known uses of obsolete APIs for which a readily available alternative is being ignored.

An automated test suite runs on every change to the shared repository. GitHub Actions CI is triggered on push and on pull request against main (.github/workflows/ci.yml) and executes the full pytest suite across a matrix of three operating systems and Python 3.11/3.12. It produces a clear pass/fail report: the run's success or failure is reported back as a required status check on the commit/PR (and gates merge into main), and the CI status is shown as a live badge on the repository front page. So each change gets an automated suite with an explicit success-or-failure result, not a manual or best-effort check.

Regression tests are added for well over 50% of bugs fixed — it is the project's standing policy, enforced in review. CONTRIBUTING.md mandates that tests ship with every behavioral change, and a bug fix is a behavioral change, so fixes land with a test that exercises the corrected behavior; because the test suite is a merge-blocking gate, a fix without its covering test does not get merged. Recent fixes demonstrate the practice: for example, a defect in the audit-format test vectors (an anchor-completeness inconsistency) was fixed together with regression tests that assert the exact diagnosis — tests/test_pala_codec.py and tests/test_pala_cli.py verify that a lagging anchor is reported as an unanchored tail with the correct lag count — and earlier subsystem fixes (e.g. in the state validator and the native scheduler) each landed with their own tests/ additions. The per-PR history shows the test-with-fix pattern throughout.

The project's automated test suite achieves statement coverage above the 80% threshold, measured by a FLOSS tool. Coverage is measured in CI with pytest-cov / coverage.py (both open source), and the CI coverage job is gated: the build fails if statement coverage drops below 80%. Current statement coverage is ~87% across the codebase. The one module that sits low is the hardware-only ctypes backend (llamacpp_backend.py), which requires a real GGUF model and GPU and is validated on hardware per benchmarks/RUNBOOK.md rather than in CI; excluding that hardware-gated path, the pure-software surface is well covered, and the overall figure still clears 80% comfortably.

The project has a formal written policy requiring tests for new significant functionality to be added to the automated test suite. CONTRIBUTING.md states, as a ground rule for contributions, that tests ship with every behavioral change — so adding new functionality obliges adding the tests that cover it, in the same pull request. The policy is not advisory: the automated suite is a merge-blocking status check on main, so a change introducing new functionality without its covering tests cannot be merged. The requirement is documented in writing, applied to every contributor, and enforced automatically.

The policy of adding tests for new functionality is documented in the contribution guidelines. CONTRIBUTING.md states, under its Tests section, "Every behavioral change ships with tests in the same PR," and additionally requires security-sensitive code to test escape and denial paths explicitly. This places the policy directly in the instructions contributors read before submitting changes. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/CONTRIBUTING.md

The project enforces a curated, deliberately-chosen strict rule set that is practical for the codebase: ruff with ["E","F","I","B","UP"] — pycodestyle/pyflakes correctness rules, import ordering, flake8-bugbear (which catches likely bugs and unsafe patterns), and pyupgrade. The linter is pinned to a fixed version and enforced as a required, merge-blocking CI check on every push and pull request, so the strictness is applied consistently rather than advisory. The rule set was chosen for signal over noise rather than enabling every available rule, which is the practical maximum for this project. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/pyproject.toml

The project implements secure-design principles concretely, not just documents them:
Fail-safe / secure defaults. TLS verification is on by default and no insecure transport is enabled by default; in the audit format, an unknown time source (time_trust = UNKNOWN) is required to carry a zero timestamp — the design refuses a confident-but-unjustified value rather than guessing.
Least privilege. The release workflow grants only the scopes it needs (id-token for OIDC publish, contents for the release), and publishing uses short-lived OIDC identity rather than a broad stored token.
Minimize / separate the attack surface. Header-only chain verification needs no key and touches no bodies, so a verifier sees no sensitive data; the audit codec is stdlib-only; and the one memory-unsafe boundary (the llama.cpp C library) is isolated behind an optional extra rather than in the core.
Defense in depth. Untrusted persisted state is bounds-checked by a validator and fuzzed; changes must pass branch protection, non-author review, green tests, coverage, SAST, and signed provenance — layered, not a single control.
Separation of privilege / keys apart from data. Encryption keys live outside the log (addressed by key_id, in an OS keychain or injected), so the data, its keys, config, and logs are separated; the audit path observes safety events rather than controlling them.
Open design (no security through obscurity). The audit format is fully specified and independently verifiable — its guarantees rely on the published mechanism, not on secrecy, to the point that a third party can verify a log with their own tool.
SECURITY.md maps vulnerability classes to these implemented mitigations, and docs/THREAT_MODEL.md and docs/ASSURANCE-CASE.md carry the design reasoning.

The project's default security mechanisms do not depend on any cryptographic algorithm or mode with known serious weaknesses. It does not use SHA-1 for security purposes, and it does not use SSH or the SSH CBC mode. At-rest encryption uses SQLCipher (AES-256 with HMAC-SHA-256/512, not SHA-1), and transport security uses the platform TLS stack with modern negotiated algorithms. No SHA-1-based or otherwise seriously-weakened primitive is relied upon. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/SECURITY.md

Authentication credentials and private cryptographic keys are kept separate from other information and are replaceable without recompiling.
Audit-log encryption keys are not stored inside the project's own files. They are addressed by key_id and held outside the log — in an OS keychain or supplied by explicit injection — so keys live apart from the data, config, and logs they protect. Rotating or replacing a key is a runtime operation (the format even records key destruction as a KEY_SHRED record), never a code change or recompile; and because it is a pure-Python project there is no compilation step to redo regardless.
Release/publishing identity uses GitHub Trusted Publishing (OIDC), so there is no long-lived private token stored in the repository at all — the credential is short-lived and issued at publish time, not embedded in code or config.
At-rest secrets (where the desktop/persistence path applies) go through SQLCipher/keyring, which hold them in their own dedicated stores, separate from application data.
No credential or private key is embedded in source, config files, databases, or logs; each can be updated or replaced independently of the code.

Where the software makes network communication, it uses secure protocols only. Outbound network access (e.g. talking to model/back-end endpoints and to release/publishing infrastructure) goes through httpx over HTTPS/TLS — TLS 1.2+ as negotiated by the platform's TLS stack — and release publishing uses HTTPS with OIDC Trusted Publishing and Sigstore. The project does not implement or default to any insecure protocol (no plain HTTP fetch-and-trust, no FTP/telnet/SSLv3/SSHv1); an insecure transport is not enabled anywhere by default. The core product is a local-first, on-device inference engine, so most operation involves no network at all, and what network communication exists is over TLS.

The software uses TLS and supports TLS 1.2 or later. All HTTPS communication goes through httpx, which uses Python's standard TLS stack (OpenSSL via the ssl module); on the supported Python versions (3.11+) that stack negotiates TLS 1.2 and 1.3 and treats older SSL/TLS versions as disabled by default. The project does not force, pin, or fall back to any pre-1.2 protocol (no SSLv3/TLS 1.0/1.1), so TLS 1.2+ is the effective floor for every TLS connection it makes.

Where the software uses TLS, it verifies TLS certificates by default. HTTPS communication goes through httpx, which performs certificate verification (chain and hostname) by default — the project does not disable it (no verify=False, no custom context that turns verification off) and does not weaken it for any request or sub-resource. So certificate validation is on for every TLS connection the software makes, as the library's secure default, and nothing in the project overrides that.

Where the software uses TLS, certificate validation happens before any request data is sent, so no sensitive HTTP header is transmitted ahead of verification. HTTPS goes through httpx, which completes the TLS handshake — including certificate chain and hostname verification — as part of establishing the connection, before the request line and headers are written; the project keeps this default (no verify=False, no verification deferral or override). In practice the project also does not rely on browser-style secret headers: publishing authentication uses short-lived OIDC tokens over verified HTTPS rather than long-lived secured cookies. Either way, verification precedes the transmission of any header.

Releases intended for wide use are cryptographically signed, and there is a documented verification process. Distribution artifacts are published to PyPI via Trusted Publishing (OIDC) with Sigstore-backed PEP 740 attestations and signed SLSA Build Level 2 provenance binding the artifact digest to the release workflow, the tag, and the OIDC issuer (.github/workflows/release.yml). How a user obtains the verification material and checks a release is documented in RELEASING.md (referenced from SECURITY.md and the assurance case), and the attestations are also surfaced on the artifact's PyPI "Provenance" section. Crucially, signing is keyless: Sigstore issues short-lived certificates tied to the workflow's OIDC identity and logs them in the Rekor transparency log, and PyPI publishing uses OIDC rather than a stored token — so there is no long-lived private signing key held anywhere, and in particular none on the distribution site. That satisfies the "private key not on the distribution site" requirement by construction.

The project validates input from potentially untrusted sources against an allowlist of what is structurally valid and rejects anything that does not conform.
Persisted KV-state blobs (the surface reachable through load_state) are checked by a dedicated validator before use: it requires the correct PALKV1 magic and validates the structure, rejecting malformed or unexpected blobs rather than trusting them. This validator is the target of a coverage-guided fuzz harness (Atheris), precisely because it is the untrusted-input boundary.
The PALA-1 audit wire format is parsed defensively by the codec: every fixed-header field and every TLV is bounds-checked, the container is parsed by frozen-field offsets, and violations (bad lengths, TLV overruns, truncated tails, unexpected values) are reported/rejected rather than accepted. Verification is allowlist-shaped — records are accepted only if they satisfy the specified constraints — and unknown record/TLV types are handled as explicitly-defined "uninterpretable", not silently trusted.
So untrusted input is validated against known constraints and invalid input is rejected wherever the format imposes constraints.

The software uses hardening mechanisms so that a defect is less likely to become a security vulnerability. The primary mechanism is language choice: all code the project produces is written in a memory-safe language (Python), eliminating whole classes of defect-to-vulnerability paths (buffer overflows, use-after-free). The single memory-unsafe boundary — the third-party llama.cpp C library — is isolated behind an optional [native] extra, and the untrusted-input surface in front of it (the KV-state validator guarding load_state) is coverage-guided fuzzed with Atheris, so malformed input is rejected before any byte reaches C. Additional mechanisms: SQL is parameterized throughout (no injection); there is no unsafe deserialization (pickle/eval/shell=True are absent); cryptographic keys come from a CSPRNG (secrets.token_bytes); the at-rest audit store is encrypted (SQLCipher/AES-256) with the key held in the OS keychain, and the design fails closed — it refuses to open rather than fall back to plaintext if SQLCipher is unavailable; the audit chain's canonical serialization is length-prefixed so field boundaries cannot be forged; provider exception text is clipped before it enters the log to prevent secret leakage; and the CI/release pipeline runs with least-privilege permissions, SHA-pinned actions, and OIDC-scoped publishing. These mechanisms, and the security argument for them, are documented in docs/ASSURANCE-CASE.md, with the asset-to-mechanism mapping in docs/THREAT_MODEL.md. As a local-first library with no network service of its own, HTTP transport-hardening headers do not apply to the software itself; the project website's hardening headers are covered separately under hardened_site.
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/ASSURANCE-CASE.md

The project provides a structured assurance case in docs/ASSURANCE-CASE.md — a defeasible Claims → Arguments → Evidence argument that Palimpsests provides the security and record-keeping properties it claims. It contains all four required elements:
Threat model description — the assurance case is built on and cross-references docs/THREAT_MODEL.md, which states the threats and guarantees precisely; the assurance case's Scope and top-level claim (G0 → C1–C5) frame what is defended.
Clear trust boundaries — the threat model and the per-claim scope define the boundaries (e.g. the audit chain vs. the device owner at the base tier, host-resident at-rest data, the untrusted-input validator surface), and a "Defeaters" section names the conditions under which each claim breaks.
Argument that secure-design principles are applied — claims C1–C5 argue tamper-evidence, at-rest confidentiality, supply-chain verifiability, declared capabilities, and the engineering-quality substrate, each with its supporting evidence.
Argument that common implementation vulnerabilities are prevented — C5 (the quality substrate) plus SECURITY.md map vulnerability classes to the implemented mitigations (memory-safe language, validated/fuzzed untrusted input, SAST, no hardcoded secrets), and each claim carries a stated residual so the argument is honest about limits rather than overclaiming.
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/ASSURANCE-CASE.md

Yes. Bandit — the SAST tool added for the static-analysis criterion — is designed specifically to find common security vulnerabilities in Python. Its rule set targets known vulnerability patterns: hardcoded credentials, injection via unsafe subprocess/shell=True/eval/exec, unsafe deserialization (pickle/yaml), weak or misused cryptographic calls, insecure temp-file handling, and unsafe network/SSL defaults. It runs on the package source on every push and pull request. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/.github/workflows/sast.yml

The project does not develop software in a memory-unsafe language. Palimpsests is written entirely in Python, a memory-safe language; it works above the attention kernel and contains no C, C++, or other memory-unsafe code of its own. The only native code involved (llama.cpp) is an external, separately-maintained dependency invoked through the [native] extra, not code developed within this project. Per the criterion's own guidance, N/A is selected because the project develops no memory-unsafe software. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/README.md