Skip to content

Demo Guide

Jump to bottom
Ranesh Rajit edited this page Oct 8, 2026 · 3 revisions

Demo Guide

End-to-end steps for running every live scenario. All scenarios are reversible; none need a restart unless noted.

0. Start the engine

javac -d out (Get-ChildItem -Recurse java/src/*.java)
java -cp out integrity.Main

Dashboard: http://localhost:8080. Fresh clone boots GREEN immediately.

Optional: http://localhost:8080/metrics serves Prometheus text. Set $env:PORT=9090 to move the dashboard and $env:RPC_URL to point the chain client at another node.

1. Config tamper (primary attack)

  1. Open config/agent-config.json, change "threshold": 100 to 999, save.
  2. Next 5s cycle flips RED POLICY_CFG_CHANGED comp=config (sustained, not one-off).
  3. Restore 100, save. GREEN returns next cycle.

Byte safety: prefer the dashboard Tamper/Restore buttons (they never touch line endings). If a manual save rewrote line endings, the engine correctly stays RED (the bytes did change) - fix with:

git checkout -- config/agent-config.json

2. Memory tamper (no file edit)

Open http://localhost:8080/tamper/memory?limit=999 -> next cycle RED POLICY_MEM_CHANGED comp=memory. Clear with http://localhost:8080/tamper/memory/clear -> GREEN.

3. Stale detection (heartbeat stall)

powershell -File scripts/demo-stale.ps1

Locks the heartbeat files -> CYCLE_ERR with the cause first, then STALE after 12s (1s watchdog), then recovery to GREEN on release.

4. Real on-chain anchoring

cd contract
npm install
npx hardhat node --port 8545
# new terminal
npm run deploy        # writes ../config/chain.json (rpcUrl, contractAddr, from, gas, chainId)
                      # local deploys (chainId 31337) also write a dev privateKey

Run the Enroller once while config/chain.json exists to pin chainContract + chainId into the baseline (mismatch refuses chain mode). Restart the engine (boot log shows RAW TX: local secp256k1 signing enabled when a dev key is present; the engine then signs each tx itself and submits it via eth_sendRawTransaction). Every cycle becomes a real anchor() tx: chainUp=true, ledgerRef = tx hash, chain badge shows UP, and the detail line shows readback=ok after the Boss reads the record back from the chain (CHAIN_MISMATCH if it ever diverges). History is queryable as Anchored events. With the node down, the engine keeps running on ledger.jsonl (chainUp=false).

5. Key-swap attack (needs one-time pinning)

# stop the engine, then pin the current key into the baseline
java -cp out integrity.enroll.Enroller "java/src/integrity/agent/AgentState.java" "config/agent-config.json"

Restart the engine (boot log shows KEY PIN: pinned ...). Now simulate theft:

  1. Stop the engine, replace keys/agent-private.pkcs8 + keys/agent-public.x509 with a fresh pair (or delete them so they regenerate).
  2. Start the engine -> RED KEY_MISMATCH comp=key, detail: "signing key replaced since enrollment".
  3. Restore the original keys -> GREEN.

Re-run Enroller to move the pin after an intentional key rotation (the same run also pins contract + chainId when config/chain.json is present). A fresh clone ships an unpinned baseline on purpose so it boots GREEN without setup.

6. Witness audit panel

The dashboard's Witness audit card shows live chain verification of witness.jsonl (boss-signed, hash-chained):

  • entries grows every cycle, head is the SHA-256 of the last line (click to copy).
  • Past 50k lines the file rotates to a timestamped archive; a signed carry line at the top of the new file keeps verification continuous across the rotation.
  • To see the failure state: stop the engine, edit any middle line of witness.jsonl, restart -> panel shows BROKEN (boot log: WITNESS chain=BROKEN ... audit trail failed verification). The agent itself stays GREEN: the witness is the Boss's own trail.
  • Restore the file -> verified again.

Recovery notes

  • Keep config/baseline.json in view before tampering - that is what "good" is.
  • If anything is stuck RED after a bad edit: git checkout -- <file> restores byte-identical bytes -> GREEN next cycle.
  • Re-baseline only after intentional source/config changes:
java -cp out integrity.enroll.Enroller "java/src/integrity/agent/AgentState.java" "config/agent-config.json"

Never auto-overwrite the baseline from the chain.

Decentralized Runtime Integrity Engine

Clone this wiki locally