{"id":48293695,"url":"https://github.com/madeinplutofabio/command-scope-contract","last_synced_at":"2026-04-04T23:26:07.291Z","repository":{"id":345637728,"uuid":"1186628741","full_name":"madeinplutofabio/command-scope-contract","owner":"madeinplutofabio","description":"Bounded shell and CLI execution for AI agents: structured contracts, policy-gated execution, hardened Linux runtime enforcement, and signed receipts.","archived":false,"fork":false,"pushed_at":"2026-03-25T20:51:15.000Z","size":5745,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T19:47:23.999Z","etag":null,"topics":["agent-governance","agent-safety","agent-security","agentic-ai","ai-agents","approval-workflows","bubblewrap","capability-security","cli","command-execution","devsecops","ed25519","mcp","open-protocol","policy-engine","provenance","sandboxing","secure-execution","shell-security","signed-receipts"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madeinplutofabio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-19T20:35:53.000Z","updated_at":"2026-03-26T13:41:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/madeinplutofabio/command-scope-contract","commit_stats":null,"previous_names":["madeinplutofabio/command-scope-contract"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/madeinplutofabio/command-scope-contract","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeinplutofabio%2Fcommand-scope-contract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeinplutofabio%2Fcommand-scope-contract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeinplutofabio%2Fcommand-scope-contract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeinplutofabio%2Fcommand-scope-contract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madeinplutofabio","download_url":"https://codeload.github.com/madeinplutofabio/command-scope-contract/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeinplutofabio%2Fcommand-scope-contract/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31418522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-governance","agent-safety","agent-security","agentic-ai","ai-agents","approval-workflows","bubblewrap","capability-security","cli","command-execution","devsecops","ed25519","mcp","open-protocol","policy-engine","provenance","sandboxing","secure-execution","shell-security","signed-receipts"],"created_at":"2026-04-04T23:26:06.870Z","updated_at":"2026-04-04T23:26:07.279Z","avatar_url":"https://github.com/madeinplutofabio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/madeinplutofabio/command-scope-contract/main/docs/assets/logo.png\" alt=\"CSC — Command Scope Contract\" width=\"140\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCSC — Command Scope Contract\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Bounded shell and CLI execution for AI agents.\u003cbr\u003e\n  Structured contracts. Policy-gated execution. Signed receipts.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/madeinplutofabio/command-scope-contract/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/madeinplutofabio/command-scope-contract/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/madeinplutofabio/command-scope-contract/actions/workflows/hardened-tests.yml\"\u003e\u003cimg src=\"https://github.com/madeinplutofabio/command-scope-contract/actions/workflows/hardened-tests.yml/badge.svg\" alt=\"Hardened Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/csc-runner/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/csc-runner.svg\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/csc-runner/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/csc-runner.svg\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.11%2B-blue.svg\" alt=\"Python 3.11+\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-green.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nCSC is a protocol for bounded shell and CLI execution by AI agents.\n\nCSC is complementary to MCP, not a replacement for it.\n\nIt exists to remove **ambient authority** from agentic execution.\n\nInstead of giving an agent raw shell access, CSC requires the agent to submit a structured command contract that declares:\n\n- what it wants to run\n- why it wants to run it\n- where it wants to run it\n- what it needs to read\n- what it may write\n- whether it needs network access\n- whether it needs secrets\n- what kind of effect it may cause\n- how long it may run\n\nA trusted policy layer evaluates the contract. If allowed, a constrained executor runs it and emits a verifiable, signed receipt.\n\n## Why CSC exists\n\nShell is useful because it is universal, composable, and token-efficient.\n\nShell is dangerous because it often carries too much implicit power.\n\nCSC keeps the flexibility of shell while making scope, policy, and execution evidence explicit.\n\n## Execution model\n\n```text\nagent -\u003e command contract -\u003e policy gate -\u003e constrained executor -\u003e execution receipt\n```\n\n## Status\n\n**v0.5.2 — bounded production-ready**\n\nThe reference runner implements the full CSC v0.1 protocol:\n\n- **Stage 1a** — Protocol complete: spec frozen, conformance suite, policy schema with structured reason codes, receipt field semantics\n- **Stage 1b** — Hardened defaults: fail-closed executor, path enforcement, resource limits, capped output capture, adversarial test suite\n- **Stage 2** — First hardened mode: Linux sandbox (bubblewrap + setpriv + prlimit), Ed25519 receipt signing, approval artifacts with replay prevention, end-to-end integration tests\n- **Stage 3** — Production candidate: release infrastructure, CI gates, security process, pilot validation, internal red-team review\n\n### Bounded production claim\n\n\u003e 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.\n\nSee [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.\n\n## Deployment modes\n\n| Mode | Platform | Security boundary | Receipt signing |\n|---|---|---|---|\n| **Local** | Any | Pre-launch validation only | Optional |\n| **Hardened** | Linux only | Kernel-enforced (bwrap namespaces) | Mandatory |\n\nLocal mode is for development, testing, and demos. Hardened mode is for CI/CD pipelines and production-like workflows where execution integrity matters.\n\nSee [docs/deployment-modes.md](docs/deployment-modes.md) for full details.\n\n## Design goals\n\n- Keep shell composability.\n- Remove raw arbitrary shell by default.\n- Make intent and scope explicit before execution.\n- Let trusted policy decide.\n- Emit signed receipts for audit and provenance.\n- Enforce boundaries with the kernel, not just Python.\n- Stay small enough to implement and adopt quickly.\n\n## Non-goals\n\nCSC does not attempt to replace:\n\n- container isolation (CSC uses it as the enforcement layer)\n- IAM\n- workflow engines\n- semantic validation of task correctness\n- prompt injection defenses at every layer\n\nCSC is an execution-boundary protocol. For a full statement of what CSC contributes and what it reuses, see [RFC-0003](rfcs/0003-csc-positioning.md).\n\n## Core objects\n\n- **CommandContract** — what the agent wants to run\n- **PolicyDecision** — whether it may run (with structured reason codes)\n- **ExecutionReceipt** — what actually happened (signed in hardened mode)\n- **ApprovalArtifact** — human authorization for sensitive operations\n\n## v0.1 rules\n\n- argv arrays only\n- no raw shell strings\n- no `bash -lc`, `sh -c`, `eval`, `python -c`, `node -e` by default\n- explicit read/write/network/env/secret scope\n- default deny on omitted capabilities\n- bounded runtime\n- signed receipts in hardened mode\n\n## Quickstart\n\n```bash\n# Install from PyPI\npip install csc-runner\n\n# Or install from source with dev dependencies\npip install -e \".[dev]\"\n\n# Check a contract against a policy (no execution)\ncsc check examples/contracts/git-status.json examples/policies/dev-readonly.yaml\n\n# Run a contract (local mode)\ncsc run examples/contracts/git-status.json examples/policies/dev-readonly.yaml\n\n# Run in hardened mode (Linux, requires bwrap/setpriv/prlimit)\ncsc run contract.json policy.yaml \\\n  --mode hardened \\\n  --sign --signing-key key.pem --key-id prod-01\n\n# Verify a signed receipt\ncsc verify-receipt receipt.json --public-key pub.pem --key-id prod-01\n```\n\n## Documentation\n\n- [Spec v0.1](docs/spec-v0.1.md) — protocol specification\n- [Deployment Modes](docs/deployment-modes.md) — local vs hardened, security claims\n- [Key Management](docs/key-management.md) — signing key lifecycle\n- [Threat Model](docs/threat-model.md) — threat classes and mitigations\n- [Security Targets](docs/security-targets.md) — claims matrix by mode\n- [Production Readiness Gate](docs/production-readiness-gate.md) — formal release checklist\n- [Policy Packs](docs/policy-packs.md) — organizational policy conventions\n- [Reason Codes](docs/reason-codes.md) — structured decision reason registry\n- [Security Policy](SECURITY.md) — vulnerability reporting\n- [Internal Red-Team Review](docs/internal-red-team-review.md) — adversarial review findings\n- [Pilot Retrospective](docs/pilot-retrospective.md) — pilot execution and lessons learned\n\n## RFCs\n\n- [RFC-0001](rfcs/0001-csc-core.md) — CSC core protocol\n- [RFC-0002](rfcs/0002-pic-alignment.md) — PIC alignment and mapping\n- [RFC-0003](rfcs/0003-csc-positioning.md) — CSC positioning, contribution, and boundaries\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and start with `docs/spec-v0.1.md` and `schemas/`.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeinplutofabio%2Fcommand-scope-contract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadeinplutofabio%2Fcommand-scope-contract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeinplutofabio%2Fcommand-scope-contract/lists"}