Immutability and Attestation

4 min readOperator · Security engineer · EvaluatorPer ADR-016

What this page is

Operator guide for hardening a Stigmem node against storage-layer tampering. R-23 is admin-level storage tampering: a privileged attacker with database access rewrites stored facts or security metadata below the HTTP/API layer.

The mitigation is layered.

Each layer catches a different failure mode. Operators get the strongest posture by enabling external attestations and storing evidence outside the mutable node.

Control stack

Layer

Control

What it detects or prevents

L1

append-only journal + projection tables

Normal write paths preserve insertion evidence; mutable read state is derived from projections.

L2

SQLite trigger enforcement

Direct UPDATE/DELETE attempts on facts are rejected and recorded as fact_mutation_attempted audit evidence.

L3

content-addressed fact IDs

Fact-body rewrites produce cid_mismatch on direct reads, queries, and recall hydration.

L4

local fact hash chain

Removed, reordered, or rewritten local inserts break sequence/link verification.

L5

transparency-log checkpoints

Chain heads are periodically anchored outside the mutable node through the configured transparency-log backend.

Client / peer

verification helpers and inbound checks

Clients and federation peers can reject mismatched CIDs and compact proof metadata.

The stack is defense in depth. CIDs catch body tampering; the local chain catches sequence and removal tampering; checkpoints make the chain head externally accountable; client/peer verification prevents a consumer from silently accepting bad proof material.

Runtime configuration

Use a transparency-log backend for production attestations:

STIGMEM_TL_BACKEND=rekor
STIGMEM_TL_REKOR_URL=https://rekor.sigstore.dev

For disconnected test environments, use the local append-only log backend and put the log on storage that ordinary node processes cannot rewrite:

STIGMEM_TL_BACKEND=local
STIGMEM_TL_LOCAL_PATH=/var/lib/stigmem/stigmem_tl.jsonl

Fact-chain checkpoints are created on count or age cadence:

STIGMEM_FACT_CHAIN_CHECKPOINT_INTERVAL=1000
STIGMEM_FACT_CHAIN_CHECKPOINT_MAX_AGE_S=60
STIGMEM_FACT_CHAIN_CHECKPOINT_RETRY_S=60

If Rekor is unavailable, writes proceed and checkpoints remain pending for retry. Follow Rekor unavailable response if pending checkpoints accumulate.

Verification

Request full verification metadata on recall:

curl -s http://localhost:8000/v1/recall \
  -H "Authorization: Bearer $STIGMEM_API_KEY" \
  -H "Stigmem-Verify: full" \
  -H "Content-Type: application/json" \
  -d '{"query":"project status","scope":"company","token_budget":1000}' \
  | jq '.chain_proof'

Python clients can fail closed on CID or compact chain-proof mismatches:

from stigmem import StigmemClient, verify_fact_chain_proof, verify_fact_cid

client = StigmemClient(url="https://your-node.example.com", api_key="sk-...")
result = client.recall("project status", scope="company", verify_full=True)

for scored in result.facts:
    verify_fact_cid(scored.fact)
verify_fact_chain_proof(result.chain_proof, require_checkpoint=True)

Federation pulls request full verification metadata and reject inbound facts when a supplied CID does not match the canonical fact body. Rejections emit federation_integrity_rejected evidence.

WORM storage

For high-assurance deployments, export evidence to write-once-read-many storage.

Audit rows to retention-locked object storage

Ship fact_audit_log and federation_audit rows to object storage with retention lock.

Local TL on immutable storage

Store local transparency-log files on immutable storage if STIGMEM_TL_BACKEND=local.

Signed database snapshots

Preserve database snapshots with signed manifests and retention policies. See Backup & Restore.

Rekor checkpoint metadata

Keep Rekor checkpoint metadata with your incident timeline so a restored node can be compared against the external chain head.

WORM storage does not replace Rekor or CID verification.

It protects operational evidence when the node host itself is under administrator control.

TEE deployment option

A trusted execution environment can reduce the blast radius of a compromised host administrator.

TEE-capable runtime

Run the Stigmem node inside a TEE-capable runtime when available.

Pin and verify images

Pin container images by digest and verify SBOM/provenance before deployment.

Seal credentials to measurement

Seal transparency-log credentials and node private keys to the measured runtime.

Emit attestation evidence

Emit remote-attestation evidence to the same audit destination used for fact-chain checkpoints.

TEE deployment is an additional assurance layer, not a protocol requirement. The default mitigation still depends on CIDs, local chain verification, external checkpoints, and client/peer rejection behavior.

Operator checklist

1. Enable Rekor-backed transparency-log checkpoints or place the local TL file on immutable storage.
2. Alert on sustained pending checkpoints.
3. Export audit rows to immutable storage before local retention expiry.
4. Exercise Stigmem-Verify: full recall and SDK verification in staging.
5. Include CID mismatch, chain-proof mismatch, and Rekor-unavailable scenarios in incident drills.
6. Review Harden a Deployment and Container Hardening before production rollout.