C ChronicleVM GitHub

Rust systems/security project

ChronicleVM

Replayable sandboxing for safe plugins.

A Rust VM that runs plugins through typed capability negotiation, records provenance-rich traces, and replays executions deterministically for audit and debugging.

View on GitHub Open Trace Viewer
Runtime
Rust VM
Model
Typed capabilities
Evidence
Trace replay
Hardening
Property tests
audit_plugin · execution replay
    open full trace viewer →

    Recruiter snapshot

    What this project demonstrates.

    Systems design Custom bytecode, verifier, VM runtime, trace format, and replay engine.
    Security thinking Explicit threat model, deny-by-default powers, bounded execution, malformed input hardening.
    Product polish CLI workflow, browser trace viewer, embeddable SDK, docs, CI, and benchmark checks.

    Five-minute demo

    Run, audit, replay, and inspect a plugin trace.

    cargo run -p chronicle-cli -- trace examples/audit-plugin.chr \
  --policy examples/audit-policy.toml \
  --out /tmp/audit.ctrace

cargo run -p chronicle-cli -- audit /tmp/audit.ctrace
cargo run -p chronicle-cli -- replay /tmp/audit.ctrace
cargo run -p chronicle-cli -- debug /tmp/audit.ctrace \
  --commands "source;next;regs;caps;jump 20;why;quit"

    Typed host powers

    Plugins declare versioned capabilities. Hosts grant, deny, or mock them before execution.

    Deterministic evidence

    Trace events capture source lines, register changes, capability calls, results, errors, and checksums.

    Browser inspection

    The static trace viewer loads .ctrace files locally and exposes timelines, diffs, source maps, and raw events.

    Security posture

    Designed around explicit boundaries.

    01

    Capability negotiation

    Host access is mediated by versioned signatures and policy decisions. Missing or denied capabilities fail before plugin code runs.

    02

    Default sandbox limits

    CLI runs are bounded by instruction count, call depth, register count, and array size unless --unbounded is explicit.

    03

    Malformed input hardening

    The binary decoder rejects oversized lengths, bad tags, truncation, and random mutated inputs with structured errors.

    Design decisions

    Why these trade-offs.

    01

    Why not WASM?

    WebAssembly gives you portable sandboxing. ChronicleVM gives you inspectable sandboxing.

    • Per-instruction event recording with register snapshots — WASM does not expose this
    • Typed capability negotiation before execution begins, not at import time
    • Replay from a recorded trace without re-calling live host functions
    • CLI debugger that steps backward through recorded events
    • Embeds as a pure Rust library — no JS runtime or browser dependency
    02

    Why deterministic replay?

    "The plugin ran fine in CI" is not evidence when CI used live clocks and real randomness.

    • Production failures can be re-examined without reproducing original conditions
    • chronicle audit checksums the trace and re-runs it, verifying the same result
    • Capability values come from the recorded trace — not new calls to live hosts
    • The exact inputs, decisions, and outputs are preserved as auditable evidence

    Execution lifecycle

    From source to auditable evidence.

    01 .chr source High-level plugin language
    02 Compile + verify Bytecode · structure checks
    03 VM + cap gate Bounded · intercepted · logged
    04 .ctrace file Events · checksums · provenance
    audit replay debug viewer
    chronicle-core Bytecode model · VM runtime · trace · replay · host SDK
    chronicle-lang  ·  chronicle-asm High-level compiler · assembly parser
    chronicle-cli run · trace · audit · replay · debug · inspect