docs: sb-runtime integration guide (a Veritas Acta receipt format implementation)#1202
Merged
imran-siddique merged 2 commits intoApr 19, 2026
Merged
Conversation
Adds docs/integrations/sb-runtime.md mirroring the openshell.md structure. Positions sb-runtime as a Veritas Acta-conformant runtime backend that combines Cedar policy evaluation, Landlock + seccomp sandboxing, and Ed25519-signed decision receipts in a single binary. Covers: - When sb-runtime is the right pick (build-vs-buy tradeoffs vs OpenShell, nono) - Architecture with request flow - Both in-process Python shim and standalone binary setup paths - Ring 2 vs Ring 3 semantics against the same binary - Cedar policy example - Policy layering example with allow/deny receipt flow - Field mapping from AGT primitives to sb-runtime equivalents - Veritas Acta receipt format reference (cross-links Tutorial 33) - Monitoring metrics compatible with AGT's OpenTelemetry patterns - FAQ covering OpenShell/nono relationships, multi-OS story, offline verification, open-source status, key rotation - Related links including IETF draft, reference verifier, integration profile repo No code changes, no new API surface; anchors on the already-merged examples/protect-mcp-governed/ (PR microsoft#1159), examples/physical-attestation-governed/ (PR microsoft#1168), and Tutorial 33 (PR microsoft#1197). Part of the three-PR sequence proposed on microsoft#748: 1. This PR: integration doc 2. Provider shim in packages/agent-runtime/ 3. Worked example in examples/sb-runtime-governed/
|
Welcome to the Agent Governance Toolkit! Thanks for your first pull request. |
1 task
github-actions
Bot
added
documentation
Positions the Veritas Acta receipt format as the interoperable artifact and sb-runtime as one of several AGT-compatible signers. Adds explicit guidance for operators who want nono as the Linux sandbox primitive: run sb-runtime in --ring 2 mode inside a nono capability set and let nono own the sandbox layer. Changes: - Title and intro lead with "Veritas Acta receipt format implementation" rather than "Ring 2/3 governance backend". The longer-lived object is the receipt format, not the specific signer. - New section 'sb-runtime's role in the Veritas Acta receipt model' enumerates sb-runtime / nono / OpenShell as peer paths, with routing guidance for each. - New section 'Composing sb-runtime with nono' documents the recommended Linux composition: nono for sandbox, sb-runtime --ring 2 for Cedar + receipts. Includes the architecture diagram and operator steps. - FAQ 'What about nono?' rewritten to position nono as the recommended Linux sandbox primitive for Veritas Acta deployments, not a competitor. - Policy Layering Example updated to name nono explicitly. No changes to the signed receipt format, the receipt store, or the verification path. @veritasacta/verify accepts Ring 2 receipts produced under any sandbox layer; the sandbox choice is not part of the receipt's trust boundary.
tomjwxf
changed the title
tomjwxf
pushed a commit
to tomjwxf/agent-governance-toolkit
that referenced
this pull request
Apr 19, 2026
Adds a new AgentMesh integration under packages/agentmesh-integrations/sb-runtime-skill/ parallel to the existing openshell-skill. Same policy contract; adds Ed25519-signed decision receipts in the Veritas Acta receipt format (draft-farley-acta-signed-receipts-02). Three supported deployment shapes, all recording the sandbox layer in the signed payload for auditor visibility: - sandbox_backend=sb_runtime_builtin, ring=3: one binary owns Cedar + Landlock/seccomp + receipts (default). - sandbox_backend=nono, ring=2: nono wraps the agent process and owns the sandbox; this skill contributes only Cedar + receipts. Recommended Linux composition per docs/integrations/sb-runtime.md. - sandbox_backend=openshell, ring=2: OpenShell owns the container boundary; this skill contributes Cedar + receipts. Receipts verify offline against @veritasacta/verify without dependency on this skill, sb-runtime, or AgentMesh. Policy digest (sha256 of the canonicalized ruleset) is pinned into every receipt; chain linkage via previousReceiptHash across successive decisions. Tests: 23 passing, covering policy contract parity with openshell-skill (9), receipt signing / verification / tampering (6), sandbox-backend recording (4), policy digest determinism (2), and signer key loading (2). Part of PR microsoft#1202 (integration doc) + this shim + a forthcoming worked example.
imran-siddique
approved these changes
Apr 19, 2026
Member
imran-siddique
left a comment
imran-siddique
left a comment
There was a problem hiding this comment.
Well-structured integration guide. Correctly positions sb-runtime as one implementation of the Veritas Acta receipt format rather than a standalone governance primitive. The nono composition section is especially useful. Merging.
imran-siddique
pushed a commit
that referenced
this pull request
Apr 19, 2026
Adds a new AgentMesh integration under packages/agentmesh-integrations/sb-runtime-skill/ parallel to the existing openshell-skill. Same policy contract; adds Ed25519-signed decision receipts in the Veritas Acta receipt format (draft-farley-acta-signed-receipts-02). Three supported deployment shapes, all recording the sandbox layer in the signed payload for auditor visibility: - sandbox_backend=sb_runtime_builtin, ring=3: one binary owns Cedar + Landlock/seccomp + receipts (default). - sandbox_backend=nono, ring=2: nono wraps the agent process and owns the sandbox; this skill contributes only Cedar + receipts. Recommended Linux composition per docs/integrations/sb-runtime.md. - sandbox_backend=openshell, ring=2: OpenShell owns the container boundary; this skill contributes Cedar + receipts. Receipts verify offline against @veritasacta/verify without dependency on this skill, sb-runtime, or AgentMesh. Policy digest (sha256 of the canonicalized ruleset) is pinned into every receipt; chain linkage via previousReceiptHash across successive decisions. Tests: 23 passing, covering policy contract parity with openshell-skill (9), receipt signing / verification / tampering (6), sandbox-backend recording (4), policy digest determinism (2), and signer key loading (2). Part of PR #1202 (integration doc) + this shim + a forthcoming worked example. Co-authored-by: tommylauren <[email protected]>
tomjwxf
pushed a commit
to tomjwxf/agent-governance-toolkit
that referenced
this pull request
Apr 20, 2026
…pt portability) PR 3 in the three-PR sequence proposed on microsoft#748 (after microsoft#1202 integration doc and microsoft#1203 provider shim, both merged). Demonstrates the architectural claim of the sb-runtime integration: a single Cedar policy produces semantically-equivalent signed receipts regardless of which sandbox layer wraps the agent process, and the sandbox_backend field is covered by the Ed25519 signature (not sidecar metadata). The demo runs six governed actions (three allowed, three denied) through three sandbox-backend configurations using the same Cedar policy and the same operator key: 1. standalone sandbox_backend=sb_runtime_builtin ring=3 2. nono sandbox_backend=nono ring=2 3. openshell sandbox_backend=openshell ring=2 Then: - Cross-verifies all 18 receipts against the single operator public key (zero dependency on the sb_runtime_agentmesh skill at verify time; matches what @veritasacta/verify would do offline). - Demonstrates tamper-evidence by flipping sandbox_backend on a receipt and confirming verification fails (the field is inside the signature scope). - Confirms chain linkage: receipt[1].previousReceiptHash equals sha256(canonical(receipt[0])). - Writes the receipts + operator public key to disk under examples/sb-runtime-governed/receipts/ (gitignored) so the output is inspectable and re-verifiable with external tooling. Files: - README.md: walkthrough with expected output - getting_started.py: ~280-line demo, three scenarios + verification - policies/sandbox-policy.yaml: shared across all three scenarios - .gitignore: excludes receipts/ and __pycache__ No changes outside examples/sb-runtime-governed/. Depends on: - pyyaml>=6,<7 (same as openshell-skill) - cryptography>=41 (for Ed25519 + JCS canonicalization) Both are declared in the sb-runtime-skill pyproject.toml (microsoft#1203). Cc @imran-siddique (closing the three-PR sequence as committed), @lukehinds (the nono scenario uses sandbox_backend="nono" matching the composition pattern documented in microsoft#1202; happy to match nono's native CLI flag conventions when the nono Python library is wired in for actual runtime enforcement).
This was referenced Apr 20, 2026
Merged
imran-siddique
pushed a commit
that referenced
this pull request
Apr 22, 2026
… 3 of 3 from #748) (#1205) * examples: add sb-runtime-governed worked example (multi-backend receipt portability) PR 3 in the three-PR sequence proposed on #748 (after #1202 integration doc and #1203 provider shim, both merged). Demonstrates the architectural claim of the sb-runtime integration: a single Cedar policy produces semantically-equivalent signed receipts regardless of which sandbox layer wraps the agent process, and the sandbox_backend field is covered by the Ed25519 signature (not sidecar metadata). The demo runs six governed actions (three allowed, three denied) through three sandbox-backend configurations using the same Cedar policy and the same operator key: 1. standalone sandbox_backend=sb_runtime_builtin ring=3 2. nono sandbox_backend=nono ring=2 3. openshell sandbox_backend=openshell ring=2 Then: - Cross-verifies all 18 receipts against the single operator public key (zero dependency on the sb_runtime_agentmesh skill at verify time; matches what @veritasacta/verify would do offline). - Demonstrates tamper-evidence by flipping sandbox_backend on a receipt and confirming verification fails (the field is inside the signature scope). - Confirms chain linkage: receipt[1].previousReceiptHash equals sha256(canonical(receipt[0])). - Writes the receipts + operator public key to disk under examples/sb-runtime-governed/receipts/ (gitignored) so the output is inspectable and re-verifiable with external tooling. Files: - README.md: walkthrough with expected output - getting_started.py: ~280-line demo, three scenarios + verification - policies/sandbox-policy.yaml: shared across all three scenarios - .gitignore: excludes receipts/ and __pycache__ No changes outside examples/sb-runtime-governed/. Depends on: - pyyaml>=6,<7 (same as openshell-skill) - cryptography>=41 (for Ed25519 + JCS canonicalization) Both are declared in the sb-runtime-skill pyproject.toml (#1203). Cc @imran-siddique (closing the three-PR sequence as committed), @lukehinds (the nono scenario uses sandbox_backend="nono" matching the composition pattern documented in #1202; happy to match nono's native CLI flag conventions when the nono Python library is wired in for actual runtime enforcement). * fix: use Microsoft copyright header per imran-siddique review Per @imran-siddique in #1205, swap the Tom Farley (ScopeBlind) header for the repo's standard Microsoft Corporation / MIT License header. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: tommylauren <[email protected]> Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
imran-siddique
pushed a commit
to imran-siddique/agent-governance-toolkit
that referenced
this pull request
May 4, 2026
… 3 of 3 from microsoft#748) (microsoft#1205) * examples: add sb-runtime-governed worked example (multi-backend receipt portability) PR 3 in the three-PR sequence proposed on microsoft#748 (after microsoft#1202 integration doc and microsoft#1203 provider shim, both merged). Demonstrates the architectural claim of the sb-runtime integration: a single Cedar policy produces semantically-equivalent signed receipts regardless of which sandbox layer wraps the agent process, and the sandbox_backend field is covered by the Ed25519 signature (not sidecar metadata). The demo runs six governed actions (three allowed, three denied) through three sandbox-backend configurations using the same Cedar policy and the same operator key: 1. standalone sandbox_backend=sb_runtime_builtin ring=3 2. nono sandbox_backend=nono ring=2 3. openshell sandbox_backend=openshell ring=2 Then: - Cross-verifies all 18 receipts against the single operator public key (zero dependency on the sb_runtime_agentmesh skill at verify time; matches what @veritasacta/verify would do offline). - Demonstrates tamper-evidence by flipping sandbox_backend on a receipt and confirming verification fails (the field is inside the signature scope). - Confirms chain linkage: receipt[1].previousReceiptHash equals sha256(canonical(receipt[0])). - Writes the receipts + operator public key to disk under examples/sb-runtime-governed/receipts/ (gitignored) so the output is inspectable and re-verifiable with external tooling. Files: - README.md: walkthrough with expected output - getting_started.py: ~280-line demo, three scenarios + verification - policies/sandbox-policy.yaml: shared across all three scenarios - .gitignore: excludes receipts/ and __pycache__ No changes outside examples/sb-runtime-governed/. Depends on: - pyyaml>=6,<7 (same as openshell-skill) - cryptography>=41 (for Ed25519 + JCS canonicalization) Both are declared in the sb-runtime-skill pyproject.toml (microsoft#1203). Cc @imran-siddique (closing the three-PR sequence as committed), @lukehinds (the nono scenario uses sandbox_backend="nono" matching the composition pattern documented in microsoft#1202; happy to match nono's native CLI flag conventions when the nono Python library is wired in for actual runtime enforcement). * fix: use Microsoft copyright header per imran-siddique review Per @imran-siddique in microsoft#1205, swap the Tom Farley (ScopeBlind) header for the repo's standard Microsoft Corporation / MIT License header. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: tommylauren <[email protected]> Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
A new integration document at
docs/integrations/sb-runtime.mdthat positions sb-runtime as one implementation of the Veritas Acta receipt format (draft-farley-acta-signed-receipts), rather than as a standalone governance primitive. Mirrors the structure ofopenshell.md.The doc makes the architecture explicit: the receipt format is the interoperable artifact, and sb-runtime / nono / OpenShell are peer signer/runtime paths an AGT operator can choose between. For operators whose sandbox layer is already nono, sb-runtime runs in
--ring 2mode inside a nono capability set and contributes only Cedar evaluation + receipt signing (documented in the new "Composing sb-runtime with nono" section).Why this belongs
Per discussion on #748, AGT benefits from documenting every Veritas Acta-conformant backend as a complementary path. This is PR 1 of a proposed three-PR sequence:
packages/agentmesh-integrations/sb-runtime-skill/(parallel to the existingopenshell-skill), exposing sb-runtime as a drop-in governance skill with a first-class option to delegate sandboxing to nono and run sb-runtime in--ring 2mode.examples/sb-runtime-governed/showing (a) standalone sb-runtime at Ring 2 and Ring 3 and (b) sb-runtime + nono composition.Structure
The doc follows
openshell.md's pattern:Verification
docs/integrations/openshell.mdsection ordering and prose styleNotes
@veritasacta/verify(Apache-2.0 reference verifier) without any AGT or sb-runtime dependency. Receipts produced under a nono sandbox verify identically.Cc @imran-siddique (thanks for the #748 scoping guidance on positioning this as a receipt format implementation), @lukehinds (the nono-as-preferred-Linux-sandbox framing reflects your point on #748; let me know if anything in the revised framing still reads off and I will iterate).