Skip to content

WALKTHROUGH.md

Latest commit

 

History

History
189 lines (141 loc) · 8.14 KB

WALKTHROUGH.md

File metadata and controls

189 lines (141 loc) · 8.14 KB

SpineFrame: Audit-Grade Assurance in One Runtime

What it is: A checkpointable, replayable, forkable DAG execution engine with built-in provenance tracking, approval gates, domain assertions, and signed evidence export — purpose-built for compliance-heavy AI agent workflows.

What it isn't: Another agent framework. SpineFrame is the execution backbone that sits under any agent framework, providing the provenance and traceability layer that enterprises need before they deploy autonomous agents into production.

The Audit Evidence Loop

This is the workflow that makes SpineFrame relevant. One command runs the entire loop — evidence gathering, control mapping, gap analysis, approval gating, fork-and-compare, signed export. Run it yourself:

pip install -e ".[signing]"
python examples/compliance_e2e_scenario.py --verbose

Step 1: Evidence Gathered and Mapped to Controls

The pipeline ingests evidence files (policies, configs, audit logs), normalizes them, and maps each to framework-specific controls. Gap analysis identifies coverage holes with severity ratings (representative output — run the script for exact values):

  Run ID:  soc2-type-audit-acme-corp-6a30
  Status:  completed
    ✓ target_parse              [Collection]
    ✓ evidence_gather (3 batches) [Collection]
    ✓ normalize                 [Analysis]
    ✓ map_to_controls           [Analysis]
    ✓ gap_analysis              [Review]
    ✓ export_package            [Export]

  Coverage: 10/15 controls (66.7%)
  Findings: 9
    [high    ] GAP-CC6.2: Access Registration
    [high    ] GAP-CC6.3: Access Removal
    [medium  ] GAP-CC1.2: COSO Principle 2
    [medium  ] GAP-CC3.1: COSO Principle 6
    [medium  ] GAP-CC9.1: Risk Mitigation

Step 2: Policy Asserted — Approval Required

Domain policy evaluation checks assertions before export is allowed. The export_requires_approval assertion blocks the signed package until a human approves:

  Policy passed:      True
  Approval required:  True
    ✗ export_requires_approval [approval_required]:
      Run has not been approved — export blocked

Step 3: Signed Approval Attestation

A compliance officer approves the run. The approval is cryptographically signed with Ed25519 — non-repudiable, timestamped, tied to a specific actor:

  Approved by:  compliance-officer@acme.com
  Signature:    valid=True
  Algorithm:    Ed25519

  Re-evaluated policy:
    ✓ export_requires_approval:
      Run approved at 2026-03-12T02:05:52+00:00

Step 4: Fork to a Different Framework

The approved SOC2 run is forked to ISO 27001. Same underlying evidence corpus, different control framework. The engine re-executes the pipeline against Annex A controls:

  Fork ID:   map-evidence-iso-27001-annex-97cd
  Parent:    soc2-type-audit-acme-corp-6a30

  Coverage: 5/9 controls (55.6%)
  Findings: 8
    [medium  ] GAP-A.12: Operations Security
    [medium  ] GAP-A.18: Compliance
    [medium  ] GAP-A.6: Organization of Information Security
    [medium  ] GAP-A.8: Asset Management
    [low     ] WEAK-A.9: Access Control
    [low     ] WEAK-A.10: Cryptography
    [low     ] WEAK-A.16: Incident Management
    [low     ] WEAK-A.17: Business Continuity

Step 5: Diff Against Approved Baseline

The two runs are compared artifact-by-artifact with SHA-256 content hashing. Because the control framework changed, every artifact diverges — this is expected and the diff makes that auditable:

  Modified:  12 artifacts
  Each shows: stage of origin, content hash (before/after)

This is the core value of fork-and-diff: you can answer "what changed and why" across any two runs. Quarterly evidence refresh? Re-run, diff against last approved state, review only what moved. Framework migration? Fork, remap, diff the gap deltas.

Step 6: Signed Export Package

The provenance bundle is signed with Ed25519 for tamper-proof export:

  Signer:           compliance-officer@acme.com
  Signature valid:  True
  Algorithm:        Ed25519

Final packages:

  SOC2:      15 controls, 6 evidence items, 9 findings (66.7% coverage)
  ISO 27001:  9 controls, 6 evidence items, 8 findings (55.6% coverage)

The Problem This Solves

AI agents are executing multi-step workflows — research, analysis, compliance audits, OSINT investigations — and producing outputs that affect real decisions. But there's no standard way to:

  • Prove what happened — which tools were called, what data was used, what the agent decided
  • Enforce policy — which tools each stage can access, which domains are blocked, whether approval is required before export
  • Replay and compare — run the same workflow with different parameters and diff the outputs
  • Sign and export — produce a cryptographically signed evidence package that an auditor can verify

SpineFrame combines replay/fork, approval-aware diff, signed provenance, tool policy, and domain assertions in one runtime. Few systems combine all of these in one runtime — LangGraph has checkpointing but no signing or policy gates, AutoGen has orchestration but no approval workflows, CrewAI has delegation but no audit trail or fork/diff.

Architecture

┌─────────────────────────────────────────────────────┐
│  CLI (14 commands)  │  Web UI (React SPA + FastAPI) │
├─────────────────────────────────────────────────────┤
│                    Engine                            │
│  DAG execution · checkpoint · resume · replay · fork│
├───────────────┬─────────────────┬───────────────────┤
│  Providers    │  Assurance      │  Pipelines        │
│  model (2)    │  auth (API key) │  research (11)    │
│  search (5)   │  signing (Ed25519)  compliance (6)  │
│  fetch (1)    │  tool policy    │  OSINT (10)       │
│  extract (1)  │  domain policy  │                   │
│  tool/MCP (1) │  provenance     │                   │
├───────────────┴─────────────────┴───────────────────┤
│  Artifacts (JSON/JSONL, SHA-256) · Events (JSONL)   │
│  Checkpoints (immutable snapshots) · Signatures     │
└─────────────────────────────────────────────────────┘

Core Engine

  • DAG execution with checkpoint/resume/replay/fork
  • Budget controls (cost, time, stage count)
  • Expandable stages (plan → batch → collect pattern)
  • Dynamic replanning based on coverage signals
  • Content-addressed artifacts with SHA-256 hashing

Assurance Layer

  • Auth: API key authentication with actor tracking on mutating operations
  • Tool Policy: Declarative per-stage tool allowlists (deny-by-default). Pluggable — ships with native evaluator + AgentWard adapter
  • Domain Policy: 5 built-in assertion types (evidence coverage, source count, blocked domains, confidence floor, export-requires-approval)
  • Signing: Ed25519 approval attestations and provenance bundle signatures
  • Provenance: Claim → chunk → source → URL traceability with Merkle hash chain

Pipelines

  • Compliance (6 stages): Evidence gathering, control mapping, gap analysis, signed export
  • Research (11 stages): Web research with claim extraction, evidence mapping, and provenance
  • OSINT (10 stages): Domain reconnaissance with 13 stdlib-only source clients (zero API keys required)

Try It

git clone https://github.com/[org]/spineframe.git
cd spineframe
pip install -e ".[signing]"

# Full audit evidence loop
python examples/compliance_e2e_scenario.py --verbose

# CLI
spineframe run --query "SOC2 audit for Acme" --pipeline compliance

# Web UI
spineframe web --port 8080

Apache 2.0 · 3 pipelines · 20k lines · Zero external deps for core engine