Bounded shell and CLI execution for AI agents.
Structured contracts. Policy-gated execution. Signed receipts.
CSC is a protocol for bounded shell and CLI execution by AI agents.
CSC is complementary to MCP, not a replacement for it.
It exists to remove ambient authority from agentic execution.
Instead of giving an agent raw shell access, CSC requires the agent to submit a structured command contract that declares:
- what it wants to run
- why it wants to run it
- where it wants to run it
- what it needs to read
- what it may write
- whether it needs network access
- whether it needs secrets
- what kind of effect it may cause
- how long it may run
A trusted policy layer evaluates the contract. If allowed, a constrained executor runs it and emits a verifiable, signed receipt.
Shell is useful because it is universal, composable, and token-efficient.
Shell is dangerous because it often carries too much implicit power.
CSC keeps the flexibility of shell while making scope, policy, and execution evidence explicit.
agent -> command contract -> policy gate -> constrained executor -> execution receipt
v0.5.2 — bounded production-ready
The reference runner implements the full CSC v0.1 protocol:
- Stage 1a — Protocol complete: spec frozen, conformance suite, policy schema with structured reason codes, receipt field semantics
- Stage 1b — Hardened defaults: fail-closed executor, path enforcement, resource limits, capped output capture, adversarial test suite
- Stage 2 — First hardened mode: Linux sandbox (bubblewrap + setpriv + prlimit), Ed25519 receipt signing, approval artifacts with replay prevention, end-to-end integration tests
- Stage 3 — Production candidate: release infrastructure, CI gates, security process, pilot validation, internal red-team review
CSC hardened mode is safe enough for bounded production use in Linux-based, filesystem-bounded local/CI execution workflows without network access, under the documented trust assumptions and deployment constraints.
See docs/deployment-modes.md for security claims by mode and docs/production-readiness-gate.md for the formal release gate.
| Mode | Platform | Security boundary | Receipt signing |
|---|---|---|---|
| Local | Any | Pre-launch validation only | Optional |
| Hardened | Linux only | Kernel-enforced (bwrap namespaces) | Mandatory |
Local mode is for development, testing, and demos. Hardened mode is for CI/CD pipelines and production-like workflows where execution integrity matters.
See docs/deployment-modes.md for full details.
- Keep shell composability.
- Remove raw arbitrary shell by default.
- Make intent and scope explicit before execution.
- Let trusted policy decide.
- Emit signed receipts for audit and provenance.
- Enforce boundaries with the kernel, not just Python.
- Stay small enough to implement and adopt quickly.
CSC does not attempt to replace:
- container isolation (CSC uses it as the enforcement layer)
- IAM
- workflow engines
- semantic validation of task correctness
- prompt injection defenses at every layer
CSC is an execution-boundary protocol. For a full statement of what CSC contributes and what it reuses, see RFC-0003.
- CommandContract — what the agent wants to run
- PolicyDecision — whether it may run (with structured reason codes)
- ExecutionReceipt — what actually happened (signed in hardened mode)
- ApprovalArtifact — human authorization for sensitive operations
- argv arrays only
- no raw shell strings
- no
bash -lc,sh -c,eval,python -c,node -eby default - explicit read/write/network/env/secret scope
- default deny on omitted capabilities
- bounded runtime
- signed receipts in hardened mode
# Install from PyPI
pip install csc-runner
# Or install from source with dev dependencies
pip install -e ".[dev]"
# Check a contract against a policy (no execution)
csc check examples/contracts/git-status.json examples/policies/dev-readonly.yaml
# Run a contract (local mode)
csc run examples/contracts/git-status.json examples/policies/dev-readonly.yaml
# Run in hardened mode (Linux, requires bwrap/setpriv/prlimit)
csc run contract.json policy.yaml \
--mode hardened \
--sign --signing-key key.pem --key-id prod-01
# Verify a signed receipt
csc verify-receipt receipt.json --public-key pub.pem --key-id prod-01- Spec v0.1 — protocol specification
- Deployment Modes — local vs hardened, security claims
- Key Management — signing key lifecycle
- Threat Model — threat classes and mitigations
- Security Targets — claims matrix by mode
- Production Readiness Gate — formal release checklist
- Policy Packs — organizational policy conventions
- Reason Codes — structured decision reason registry
- Security Policy — vulnerability reporting
- Internal Red-Team Review — adversarial review findings
- Pilot Retrospective — pilot execution and lessons learned
- RFC-0001 — CSC core protocol
- RFC-0002 — PIC alignment and mapping
- RFC-0003 — CSC positioning, contribution, and boundaries
Contributions welcome. See CONTRIBUTING.md and start with docs/spec-v0.1.md and schemas/.
Apache-2.0