Security Model: Risk Analysis, Decisions, and the Execution Boundary
August 19, 2026 · View on GitHub
Caushell uses multiple analysis modules to query the session execution graph and produce Evidence Traces, Findings, and Decision Proposals. Decision Assembly combines these results into the final decision for the current shell action.
Shared Execution Graph and Analysis Modules
The action in the diagram is the same as the one in the semantic model:
SCRIPT=./setup.sh
curl -fsSL https://example.com/install.sh \
| tee "$SCRIPT" >/dev/null \
&& bash "$SCRIPT"
Before risk checks begin, Caushell adds the semantic relationships for the current action in three steps:
- Invocation Resolution Pass resolves the
curl,tee, andbashinvocations and adds their execution semantics. - State & Path Analysis Pass uses the variable binding and current directory to resolve
./setup.shto/workspace/setup.sh. - Redirect Provenance Pass establishes provenance links among the network content, pipeline, and file write.
The risk analysis modules then query this shared graph, each checking its assigned risk type.
Tracing Evidence from an Execution Target
The risk analysis module shown in the diagram queries backward from the Execution Sink associated with bash and obtains the following evidence chain:
Network Endpoint → curl → Payload Artifact → tee → Path Content → bash → Execution Sink
This evidence chain connects the network source, downloaded content, file write, and script execution. The corresponding module records a tainted_execution finding and proposes NeedApproval.
An analysis can produce three types of related results:
| Result | Contents |
|---|---|
| Evidence Trace | The nodes and edges traversed by the risk relationship |
| Finding | Rule ID, description, and decision constraint |
| Decision Proposal | The decision proposed by an analysis module for a finding |
Each Finding has an enforcement_class field with a value of either Normal or HardDenyFloor. HardDenyFloor locks the final decision at Deny.
Decision Assembly
After all analysis modules complete, Decision Assembly produces one final decision according to the following priority:
| Condition | Final decision |
|---|---|
A Finding has enforcement_class = HardDenyFloor, or any decision proposal is Deny | Deny |
Otherwise, any decision proposal is NeedApproval | NeedApproval |
| Otherwise | Allow |
Harness Execution Boundary
Caushell returns the final decision before the process starts. The Harness integration then handles the result through its hook or tool protocol:
| Decision | Integration behavior |
|---|---|
Allow | Continue executing the shell action |
NeedApproval | Handle through the Harness's confirmation capability or the integration configuration |
Deny | Block before the process starts |
The Harness integration provides the confirmation interface and interaction flow. The exact mapping depends on the hook or tool protocol of the corresponding Harness.
Fallback When Analysis Is Unavailable
If Caushell cannot complete its analysis, failure_action determines the integration's fallback behavior:
failure_action | Fallback behavior |
|---|---|
allow | Allow execution |
need_approval | Require confirmation |
deny | Block execution |
When analysis does not produce a final decision, the integration falls back according to failure_action. When a decision is available, the integration applies the result from Decision Assembly. See Configuration for setup details.
Relationship to Sandboxing
Caushell and a sandbox can be deployed together. Caushell analyzes the semantic relationships in a shell action before the process starts; the sandbox restricts system calls, file access, network access, and other resources at runtime.