runtimetruth 0.2.0__tar.gz

runtimetruth-0.2.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

runtimetruth-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Test
+        run: pytest
+
+  package:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tooling
+        run: python -m pip install "build>=1.2"
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Install wheel in clean environment
+        run: |
+          python -m venv /tmp/runtimetruth-smoke
+          /tmp/runtimetruth-smoke/bin/python -m pip install dist/*.whl
+          /tmp/runtimetruth-smoke/bin/runtimetruth --version
+
+
+  attestation-smoke:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install RuntimeTruth
+        run: python -m pip install -e ".[dev]"
+
+      - name: Install Cosign
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+
+      - name: Keyless sign and verify baseline
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          baseline="tests/fixtures/snapshots/before.json"
+          statement="${RUNNER_TEMP}/runtimetruth-baseline.intoto.json"
+          bundle="${RUNNER_TEMP}/runtimetruth-baseline.sigstore.json"
+          identity="https://github.com/${GITHUB_WORKFLOW_REF}"
+
+          runtimetruth digest "${baseline}"
+
+          runtimetruth attest "${baseline}" \
+            --statement "${statement}" \
+            --bundle "${bundle}"
+
+          runtimetruth verify-attestation \
+            "${baseline}" \
+            "${baseline}" \
+            --statement "${statement}" \
+            --bundle "${bundle}" \
+            --certificate-identity "${identity}" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

runtimetruth-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Verify tag matches package version
+        shell: bash
+        run: |
+          set -euo pipefail
+          expected="v$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+          data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          print(data["project"]["version"])
+          PY
+          )"
+
+          if [[ "${GITHUB_REF_NAME}" != "${expected}" ]]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match package version ${expected}" >&2
+            exit 1
+          fi
+
+      - name: Install build tooling
+        run: python -m pip install "build>=1.2"
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Smoke-test wheel
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/runtimetruth-release-smoke
+          /tmp/runtimetruth-release-smoke/bin/python -m pip install dist/*.whl
+          /tmp/runtimetruth-release-smoke/bin/runtimetruth --version
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/runtimetruth
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: Create GitHub release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Download distributions
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}"             dist/*             --title "RuntimeTruth ${GITHUB_REF_NAME}"             --notes-file "docs/release-${GITHUB_REF_NAME}.md"             --verify-tag

runtimetruth-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+.venv/
+venv/
+
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.env
+.env.*
+!.env.example
+
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+.runtimetruth/

runtimetruth-0.2.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable user-facing changes to RuntimeTruth are documented here.
+
+RuntimeTruth is pre-release software. Snapshot and report schemas are versioned independently from the package version, and compatibility guarantees may evolve before a stable 1.0 release.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-06
+
+RuntimeTruth v0.2.0 adds an explicit trust chain for reviewed baselines, persisted runtime policy selectors, and the first normal PyPI distribution path.
+
+### Added
+
+- RFC 8785 canonical baseline serialization and SHA-256 digest output via `runtimetruth digest`
+- identity-backed baseline attestations using canonical in-toto Statement v1 and Sigstore Cosign
+- `runtimetruth attest` for canonical statement + keyless Sigstore bundle generation
+- `runtimetruth verify-attestation` for exact signer identity, baseline digest and runtime verification
+- machine-readable identity/baseline/runtime verification reports via `--json`
+- explicit schema-v1 TOML verification policies for persisted runtime selectors
+- policy support for both plain and signed-baseline runtime verification
+- PyPI release automation through GitHub OIDC Trusted Publishing
+
+### Security
+
+- signed-attestation verification fails closed before current-runtime collection when signer identity or baseline binding cannot be verified
+- snapshot and attestation JSON parsing rejects duplicate object keys
+- RuntimeTruth validates the exact canonical in-toto statement after Cosign verifies its signature and signer identity
+- runtime policy selection is evaluated only after signed-baseline trust verification succeeds
+- the PyPI release job uses short-lived OIDC credentials instead of a long-lived package token
+
+## [0.1.0] - 2026-10-06
+
+First public pre-release.
+
+### Added
+
+- versioned schema-v1 runtime snapshots with explicit evidence provenance
+- local systemd unit/runtime inspection
+- procfs process identity inspection
+- Git repository identity inspection
+- composed systemd -> process -> repository evidence
+- semantic snapshot diff with missing-vs-null preservation
+- Codex runtime/version inspection
+- Codex canonical resolved workspace configuration through app-server
+- optional ephemeral-thread resolution for effective model/provider, approval and sandbox state
+- Codex-reported instruction source inventory
+- SHA-256 fingerprints of instruction source files without storing plaintext
+- opt-in thread-scoped Codex MCP runtime inventory without MCP tool execution
+- bounded MCP tool-name snapshots plus deterministic full-catalog fingerprints
+- strict baseline verification with stable PASS / DRIFT / ERROR exit codes
+- live Codex verification against a baseline without an intermediate current-snapshot file
+- repeatable `--protect` selectors for agent-runtime invariants
+- versioned machine-readable verification reports via `--json`
+- CI integration guidance for pinned source installs and self-hosted runtime verification
+- trust model, data-handling, support and security documentation
+
+### Security and privacy
+
+- allowlist-based collection near sensitive runtime data
+- no RuntimeTruth telemetry or hosted control plane
+- no instruction plaintext, environment values, auth tokens, MCP resource contents or tool schemas serialized by current collectors
+- explicit side-effect boundary for MCP runtime status probing
+
+### Known boundaries
+
+- Codex thread resolution observes a newly-created ephemeral thread, not an existing user's active thread
+- PASS is not a security or compliance certification
+- RuntimeTruth does not classify MCP contract compatibility; MCP server contract testing is intentionally outside the product boundary

runtimetruth-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to RuntimeTruth
+
+RuntimeTruth is intentionally validation-driven. Changes should strengthen a concrete runtime-verification workflow rather than broaden the project surface speculatively.
+
+## Before opening a pull request
+
+For non-trivial changes, open or reference an issue that states:
+
+- the runtime-verification problem being solved
+- the evidence source involved
+- what RuntimeTruth can establish directly versus what would be inferred
+- the security/privacy boundary
+- how the behavior can be validated against a real or faithful fixture runtime
+
+Small documentation and maintenance fixes do not need a design issue.
+
+## Development setup
+
+Requires Python 3.12+.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+
+ruff check .
+ruff format --check .
+pytest
+python -m build
+```
+
+## Change guidelines
+
+Prefer small, reviewable slices.
+
+- keep evidence provenance explicit
+- do not silently infer unavailable runtime state
+- use allowlists when collecting data near secrets or prompts
+- do not add runtime dependencies without a concrete need
+- preserve deterministic snapshot/report output
+- add fixture-backed tests for new evidence or comparison behavior
+- validate agent-specific behavior against the real runtime when practical
+- reuse existing diff/verification paths rather than creating parallel semantics
+
+For Codex probes, avoid starting model turns unless a feature explicitly requires and documents that behavior. MCP inspection must not call tools unless a future feature makes that side effect explicit.
+
+## Pull requests
+
+A pull request should explain:
+
+- what changed
+- the evidence/trust boundary
+- deliberate non-goals
+- automated test coverage
+- any real-runtime validation performed
+
+The project normally uses squash merges so one feature lands on `main` as one coherent commit.
+
+## Security
+
+Do not open a public issue containing vulnerability details or secrets. Follow [SECURITY.md](SECURITY.md).

runtimetruth-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sidelobe Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runtimetruth-0.2.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.5
+Name: runtimetruth
+Version: 0.2.0
+Summary: Runtime verification and drift detection for AI agents.
+Project-URL: Homepage, https://sidelobe.dev/open-source/runtimetruth/
+Project-URL: Repository, https://github.com/sidelobe-labs/runtimetruth
+Project-URL: Issues, https://github.com/sidelobe-labs/runtimetruth/issues
+Project-URL: Documentation, https://github.com/sidelobe-labs/runtimetruth/tree/main/docs
+Project-URL: Changelog, https://github.com/sidelobe-labs/runtimetruth/blob/main/CHANGELOG.md
+Author: Sidelobe Labs
+License: MIT
+License-File: LICENSE
+Keywords: agent-security,ai-agents,drift-detection,mcp,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: rfc8785==0.1.4
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RuntimeTruth
+
+**Verify what your AI agent is actually running.**
+
+_An open-source Sidelobe project._
+
+[Project case study](https://sidelobe.dev/open-source/runtimetruth/) · [Engineering case study](https://artur.panek.tech/work/runtimetruth/) · [Engineering note](https://artur.panek.tech/notes/ai-agent-config-vs-runtime/) · [v0.2.0 release](https://github.com/sidelobe-labs/runtimetruth/releases/tag/v0.2.0)
+
+RuntimeTruth is an open-source runtime verification and drift-detection tool for AI agents. It compares evidence from declared, resolved, and live runtime state so teams can identify changes in effective models, instructions, tools, MCP servers, permissions, runtime versions, and execution environment.
+
+> Status: v0.2.0 pre-release. The local CLI, schema-v1 snapshots, Codex runtime inspection, semantic diff, persisted verification policy and identity-backed signed-baseline verification have been validated in CI and against real local runtimes.
+
+## Why
+
+AI agents have more mutable runtime state than ordinary applications:
+
+- model and provider routing
+- system and project instructions
+- tools and MCP schemas
+- skills and plugins
+- sandbox and network permissions
+- executable/runtime versions
+- environment and process identity
+- repository/code state
+
+A deployment can therefore look unchanged while the effective agent runtime has drifted.
+
+RuntimeTruth currently focuses on two questions:
+
+1. **What runtime state can be established with explicit evidence?**
+2. **What changed since a known baseline?**
+
+Broader policy evaluation and organizational provenance remain later phases.
+
+## Project model
+
+RuntimeTruth is currently distributed as free, local-first open-source software. There is no RuntimeTruth hosted control plane, account system, telemetry service, paid support plan or SLA.
+
+A verification result is deliberately narrow: **PASS means the selected evidence matched the selected baseline.** It does not mean the agent is secure, compliant, safe, or correctly configured in ways RuntimeTruth did not inspect.
+
+See the [trust model](docs/trust-model.md), [data handling](docs/data-handling.md), [support policy](SUPPORT.md), and [MIT License](LICENSE) for the current project boundary.
+
+## Origin
+
+RuntimeTruth grew out of operating self-hosted workers and noticing that source code and deployment configuration were not enough to answer a simple question: **what is actually running right now?**
+
+The project is built from evidence outward. It started with systemd, procfs, and Git identity, then used the same model to inspect agent-specific Codex state.
+
+[Read the origin story](docs/origin.md).
+
+## Installation
+
+For the CLI, use an isolated tool environment:
+
+```bash
+pipx install runtimetruth
+```
+
+or:
+
+```bash
+uv tool install runtimetruth
+```
+
+Standard `pip` is also supported inside a virtual environment:
+
+```bash
+python -m pip install runtimetruth
+```
+
+Then verify the install:
+
+```bash
+runtimetruth --version
+```
+
+For CI workflows that require an exact source revision, pin the Git commit rather than following a moving branch. See [CI integration](docs/ci.md).
+
+## Quick start
+
+Capture effective Codex runtime state:
+
+```bash
+runtimetruth inspect codex . --resolve-thread --pretty > baseline.json
+```
+
+Verify the current runtime against that baseline:
+
+```bash
+runtimetruth verify baseline.json --codex . --resolve-thread
+```
+
+Protect only selected runtime invariants when strict snapshot equality is too broad:
+
+```bash
+runtimetruth verify baseline.json --codex . --resolve-thread \
+  --protect codex.thread.model \
+  --protect codex.instructions
+```
+
+Persist repeated selectors in an explicit TOML policy:
+
+```toml
+version = 1
+protect = [
+  "codex.thread.model",
+  "codex.thread.sandbox",
+  "codex.instructions",
+]
+```
+
+```bash
+runtimetruth verify baseline.json --codex . --resolve-thread \
+  --policy .runtimetruth/policy.toml
+```
+
+The same policy can be used with `verify-attestation`; signer identity and baseline binding are verified before policy evaluation.
+
+Add `--json` for a versioned machine-readable PASS/DRIFT report.
+
+Bind a reviewed baseline to an identity-backed Sigstore attestation:
+
+```bash
+runtimetruth digest baseline.json
+
+runtimetruth attest baseline.json \
+  --statement baseline.intoto.json \
+  --bundle baseline.sigstore.json
+
+runtimetruth verify-attestation \
+  baseline.json \
+  --statement baseline.intoto.json \
+  --bundle baseline.sigstore.json \
+  --certificate-identity "EXPECTED_IDENTITY" \
+  --certificate-oidc-issuer "EXPECTED_ISSUER" \
+  --codex . \
+  --resolve-thread
+```
+
+Attestation uses RFC 8785 canonical JSON, SHA-256, in-toto Statement v1 and Sigstore Cosign rather than a RuntimeTruth-specific signature scheme. See [signed baseline attestations](docs/attestation.md).
+
+## Current CLI
+
+Inspect a local target:
+
+```console
+runtimetruth inspect systemd <unit>
+runtimetruth inspect git <path>
+runtimetruth inspect codex <cwd>
+runtimetruth inspect codex <cwd> --resolve-thread
+runtimetruth inspect codex <cwd> --resolve-mcp
+```
+
+Compare two snapshots:
+
+```console
+runtimetruth diff <before.json> <after.json>
+```
+
+Verify a current snapshot against a baseline:
+
+```console
+runtimetruth verify <baseline.json> <current.json>
+```
+
+Or collect the current Codex runtime and verify it directly:
+
+```console
+runtimetruth verify <baseline.json> --codex <cwd> --resolve-thread
+runtimetruth verify <baseline.json> --codex <cwd> --resolve-mcp
+```
+
+Verification uses stable process exit codes:
+
+- `0` — runtime matches the baseline
+- `2` — semantic runtime drift detected
+- `1` — collection, input, or comparison error
+
+Selective runtime invariants can be protected explicitly:
+
+```console
+runtimetruth verify baseline.json --codex <cwd> --resolve-thread \
+  --protect codex.thread.model \
+  --protect codex.instructions
+```
+
+For automation, add `--json` to emit a versioned structured PASS/DRIFT report without changing the exit-code contract.
+
+Canonical baseline identity and signed verification are separate commands:
+
+```console
+runtimetruth digest <baseline.json>
+
+runtimetruth attest <baseline.json> \
+  --statement <baseline.intoto.json> \
+  --bundle <baseline.sigstore.json>
+
+runtimetruth verify-attestation <baseline.json> [current.json] \
+  --statement <baseline.intoto.json> \
+  --bundle <baseline.sigstore.json> \
+  --certificate-identity <expected-identity> \
+  --certificate-oidc-issuer <expected-issuer>
+```
+
+`verify-attestation` can also use `--codex <cwd>`, `--resolve-thread`, `--resolve-mcp`, `--policy <file>`, repeatable `--protect`, and `--json`.
+
+Creating or verifying identity-backed attestations requires a recent [Sigstore Cosign](https://docs.sigstore.dev/cosign/system_config/installation/) executable. Normal inspect/diff/verify commands do not require Cosign.
+
+`--resolve-thread` creates an ephemeral Codex thread without starting a turn. `--resolve-mcp` additionally probes thread-scoped MCP runtime state and may contact configured MCP servers or refresh authentication; it does not call MCP tools.
+
+## Evidence currently collected
+
+The intentionally narrow implementation includes:
+
+- systemd unit/runtime state
+- procfs process identity
+- Git repository identity
+- Codex executable/version
+- Codex canonical resolved workspace configuration
+- effective state materialized for an ephemeral Codex thread
+- Codex-reported instruction source paths
+- SHA-256 fingerprints of those instruction source files without storing their plaintext
+- thread-scoped MCP server status and bounded tool-catalog fingerprints
+
+Each evidence record keeps its provenance and is classified as declared, resolved, or live where the source supports that claim.
+
+## Project boundary
+
+RuntimeTruth is not intended to become a generic process monitor, LLM trace backend, MCP proxy/firewall, GitOps controller, or hosted observability dashboard.
+
+The current focus is external validation of the baseline, attestation and policy model before adding additional agent adapters or cloud features.
+
+See:
+
+- [Origin](docs/origin.md)
+- [Vision](docs/vision.md)
+- [Landscape and positioning](docs/landscape.md)
+- [Roadmap](docs/roadmap.md)
+- [Architecture](docs/architecture.md)
+- [CI integration](docs/ci.md)
+- [Signed baseline attestations](docs/attestation.md)
+- [Verification policy](docs/policy.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+- [Trust model](docs/trust-model.md)
+- [Data handling](docs/data-handling.md)
+- [Support](SUPPORT.md)
+
+## Development
+
+Requires Python 3.12+.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest
+```
+
+## License
+
+MIT.