Metadata-Version: 2.4
Name: csc-runner
Version: 0.5.0
Summary: Reference runner for Command Scope Contract
Project-URL: Homepage, https://github.com/madeinplutofabio/command-scope-contract
Project-URL: Repository, https://github.com/madeinplutofabio/command-scope-contract
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,cli,policy,provenance,security
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: cryptography>=43.0
Requires-Dist: jsonschema>=4.23
Requires-Dist: pydantic>=2.8
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

[![CI](https://github.com/madeinplutofabio/command-scope-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/madeinplutofabio/command-scope-contract/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

# CSC — Command Scope Contract

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.

## Why CSC exists

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.

## Execution model

```text
agent -> command contract -> policy gate -> constrained executor -> execution receipt
```

## Status

**v0.1 — hardened mode available**

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 (in progress): release infrastructure, CI gates, security process, pilot validation

### Bounded production claim

> 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](docs/deployment-modes.md) for security claims by mode and [docs/production-readiness-gate.md](docs/production-readiness-gate.md) for the formal release gate.

## Deployment modes

| 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](docs/deployment-modes.md) for full details.

## Design goals

- 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.

## Non-goals

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.

## Core objects

- **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

## v0.1 rules

- argv arrays only
- no raw shell strings
- no `bash -lc`, `sh -c`, `eval`, `python -c`, `node -e` by default
- explicit read/write/network/env/secret scope
- default deny on omitted capabilities
- bounded runtime
- signed receipts in hardened mode

## Quickstart

```bash
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
```

## Documentation

- [Spec v0.1](docs/spec-v0.1.md) — protocol specification
- [Deployment Modes](docs/deployment-modes.md) — local vs hardened, security claims
- [Key Management](docs/key-management.md) — signing key lifecycle
- [Threat Model](docs/threat-model.md) — threat classes and mitigations
- [Security Targets](docs/security-targets.md) — claims matrix by mode
- [Production Readiness Gate](docs/production-readiness-gate.md) — formal release checklist
- [Policy Packs](docs/policy-packs.md) — organizational policy conventions
- [Reason Codes](docs/reason-codes.md) — structured decision reason registry
- [Security Policy](SECURITY.md) — vulnerability reporting

## Contributing

Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and start with `docs/spec-v0.1.md` and `schemas/`.

## License

Apache-2.0
