01→
Observe
Collect kernel events once, in causal delivery order, with explicit loss and coverage state.
syscalls · task identity · security transitions Predicate-guided attack surface discovery
Seed any node. Expose what control can reach.
Cuscuta reconstructs process and object channels from runtime evidence, preserves their security predicates over time, and measures the surface gained by each compromise hypothesis.
Any node can be the seed Every channel keeps its predicates Every gain remains evidence-backed
Runtime observability usually tells you what happened.
Cuscuta asks what becomes reachable if this node is compromised.
How to use Cuscuta
Install once.
Capture once. Ask many seeds.
Follow one supported path from a content-locked runtime to an auditable state graph. Every command either names its completed evidence product or refuses without launching the target.
$ python3 provenance/tools/cuscuta.py install \
--runtime-root /absolute/path/to/cuscuta-runtime-linux-x86_64-v1Copies the CLI, semantics, and five content-locked executables into ~/.local without building on the target host.
INSTALL PASS · COMMAND READYHOST CONTRACT
Capture: Linux/x86-64 · Python 3.10+ · PyYAML · util-linux · active BPF LSM · root
Analyze: accepted capture + installed runtime · no KVM/QEMU requirement
THE CONTRACT
TRUE opens a required clause, FALSE blocks it, and UNKNOWN stays visible. No second best-effort mode exists.
The system
One evidence path.
Four explicit transformations.
The process graph is a readable projection—not the source of truth. Security state stays attached to the smallest observed execution context at the exact interaction order.
02→
Canonicalize
Turn raw events into typed, replayable observations without silently inventing missing facts.
stable IDs · evidence links · field status03→
Reconstruct
Recover FD/OFD lifetimes, task security state, inheritance, transfers, and communication channels.
ledger · intervals · cross-process edges04
Project
Produce human-sized process views while keeping every security decision attached to its exact task.
timelines · channel graph · evidence drill-downWhat we observe
A temporal evidence model, not a syscall scrapbook.
Every graph edge is backed by typed observations and causal order. Missing evidence remains visible, so downstream analysis can distinguish “not observed” from “proved absent.”
Execution identity
process, task, image and files-table identity across fork, clone and exec
Security state
credentials, capabilities, namespaces, no_new_privs and seccomp mode over time
Object access
open-file descriptions, FD slots, access modes, mappings and object identity
Communication
pipes, AF_UNIX sockets, producer/consumer operations and message correlation
Capability movement
fork inheritance, dup lineage and SCM_RIGHTS transfer between subjects
Evidence quality
coverage, loss boundaries, provenance IDs and replay authority for every result
Captured systems
Real applications.
Evidence you can inspect.
Switch between retained Chrome and Firefox capture artifacts. Process groups make the topology legible; task endpoints retain the actual security state.
CHROME · CAPTURE V6
From a browser process tree to exact channel and capability flow.
The projection joins task identity, FD holdings, seccomp state, channel actions, inheritance, and descriptor transfer at each interaction endpoint.
20process groups
153task contexts
4,061channels
13,788channel actions
488capability transfers
0unresolved channels
STATUSAll 4,061 channels resolved in this run
TASK 591security state observedroot context
TASK 62653 transfers receivedseccomp exact
TASK 65557 interactionsinherited state
TASK 60117 interactionsFD holdings
AF_UNIXchannel objectresolved
SCM_RIGHTSWRITEINHERIT task context channel observed flow