{"id":49964746,"url":"https://github.com/codethor0/llm-agent-control-plane","last_synced_at":"2026-05-24T23:00:57.373Z","repository":{"id":358430853,"uuid":"1241367590","full_name":"codethor0/llm-agent-control-plane","owner":"codethor0","description":"Production-oriented defensive reference implementation for securing tool-connected LLM agents.","archived":false,"fork":false,"pushed_at":"2026-05-18T03:34:13.000Z","size":265,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T04:42:30.111Z","etag":null,"topics":["ai-security","appsec","defensive-security","fastapi","llm-security","owasp","prompt-injection","python","rag-security","red-team","security-by-design","tool-calling"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codethor0.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-CONTROLS.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T09:50:13.000Z","updated_at":"2026-05-18T03:32:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codethor0/llm-agent-control-plane","commit_stats":null,"previous_names":["codethor0/llm-agent-control-plane-lab","codethor0/llm-agent-control-plane"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/codethor0/llm-agent-control-plane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethor0%2Fllm-agent-control-plane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethor0%2Fllm-agent-control-plane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethor0%2Fllm-agent-control-plane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethor0%2Fllm-agent-control-plane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codethor0","download_url":"https://codeload.github.com/codethor0/llm-agent-control-plane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethor0%2Fllm-agent-control-plane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33453557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["ai-security","appsec","defensive-security","fastapi","llm-security","owasp","prompt-injection","python","rag-security","red-team","security-by-design","tool-calling"],"created_at":"2026-05-18T04:16:58.657Z","updated_at":"2026-05-24T23:00:57.366Z","avatar_url":"https://github.com/codethor0.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/llm-agent-control-plane-logo.svg\" alt=\"LLM Agent Control Plane logo\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eProduction-oriented defensive reference implementation for securing tool-connected LLM agents.\u003c/strong\u003e\n\u003c/p\u003e\n\n# llm-agent-control-plane\n\n[![CI](https://github.com/codethor0/llm-agent-control-plane/actions/workflows/ci.yml/badge.svg)](https://github.com/codethor0/llm-agent-control-plane/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/codethor0/llm-agent-control-plane)](https://github.com/codethor0/llm-agent-control-plane/releases)\n[![Python 3.12](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/downloads/release/python-3120/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-293%20passing-brightgreen)](https://github.com/codethor0/llm-agent-control-plane/actions)\n[![Security](https://img.shields.io/badge/security-deny--by--default-critical)](SECURITY-CONTROLS.md)\n[![Docker](https://img.shields.io/badge/docker-verified-blue)](Dockerfile)\n\nProduction-oriented defensive reference implementation for securing tool-connected LLM agents with an **external control plane**.\n\n**Core idea:** LLM agents may propose actions, but only the external control plane can authorize them.\n\nThis repository is a **local, simulated** demonstration. It shows how to keep authorization, policy, provenance checks, human approval, output filtering, and audit logging **outside** the model. It is intended for security engineers, defenders, and builders learning control-plane patterns.\n\n**Boundary:** This is not a drop-in production service yet. Production deployment still requires identity, persistence, key management, enterprise DLP, observability, deployment hardening, and operational review.\n\n## Publication status\n\n| Item | Status |\n|------|--------|\n| Repository | https://github.com/codethor0/llm-agent-control-plane |\n| CI | GitHub Actions on `main` (badge above); supply-chain: CodeQL, Gitleaks, Trivy, SBOM; tag releases get unsigned `SHA256SUMS` (see [release provenance](docs/release-provenance.md)) |\n| Latest release | [v0.3.0](https://github.com/codethor0/llm-agent-control-plane/releases/tag/v0.3.0) (clean public history and release readiness) |\n\n## One-command quick start\n\nRequires **Python 3.12** (see [Python version](#python-version)).\n\n```bash\nmake setup \u0026\u0026 make demo\n```\n\nFull validation (including Docker when the daemon is running):\n\n```bash\nmake setup \u0026\u0026 make validate\n```\n\n## Python version\n\n| Environment | Python |\n|-------------|--------|\n| Project target | **3.12.x** (`requires-python = \u003e=3.12,\u003c3.13`) |\n| Docker / GitHub Actions | 3.12 |\n| Local host on 3.14+ | **Mismatch** — use `pyenv install 3.12`, `asdf`, or Docker |\n\nVerify your venv:\n\n```bash\n.venv/bin/python scripts/check_python_version.py\n```\n\n## Docker quick start\n\n```bash\ndocker compose build\ndocker compose run --rm app python -m pytest\nmake demo\n```\n\nProduction-oriented reference Compose profile (fake secrets only):\n\n```bash\ndocker compose -f docker-compose.production.yml build\ndocker compose -f docker-compose.production.yml up\n```\n\nSee [docs/deployment-checklist.md](docs/deployment-checklist.md) and `.env.production.example`.\n\n### Docker troubleshooting\n\n| Symptom | Action |\n|---------|--------|\n| `Cannot connect to the Docker daemon` | Start Docker Desktop or the system Docker service, then retry `docker compose build`. |\n| Build fails on `pip install` | Ensure network access; rebuild with `docker compose build --no-cache`. |\n| Tests differ from host | Docker runs the image copy of the code (no bind mounts). Rebuild after changes. |\n\nDocker validation is **not** claimed unless `docker compose build` and `docker compose run --rm app python -m pytest` succeed on your machine.\n\n## What this repo does\n\n- Demonstrates a deterministic **external control plane** around a simulated LLM agent\n- Enforces **deny-by-default** policy, **tool broker** authorization, **provenance** rules, **human approval**, and **output filtering**\n- Writes structured, **redacted JSONL** audit events\n- Provides a local **FastAPI** API and **CLI demo**\n- Maps [security invariants](docs/defensive-controls.md) to **293** automated tests\n- Exposes a safe [LLM adapter interface](docs/llm-adapter.md) (simulated by default; no live API calls)\n- Provides [audit taxonomy](docs/audit-event-taxonomy.md), [SIEM export guidance](docs/siem-export.md), and [operator playbooks](docs/audit-review-playbook.md) for review and response\n- Ships [deployment reference profiles](docs/deployment-boundaries.md) (Compose, Kubernetes manifests, checklists; not a managed platform)\n- Blocks prompt artifacts from the repository via `scripts/validate_repo.py`\n\n## What this repo does not do\n\n- Call production LLM APIs by default\n- Execute real shell commands, send real email, or scan networks\n- Store or exfiltrate real credentials\n- Provide exploit chains, jailbreak libraries, or offensive tooling\n- Test or attack third-party systems\n- Guarantee safety for production deployments\n\n## Architecture\n\n**Core idea:** LLM agents may propose actions, but only the external control plane can authorize them. Model output is untrusted; the tool broker is the authority boundary for policy, provenance, approval, and simulated execution.\n\nDetailed diagrams: [docs/architecture.md](docs/architecture.md). Threat framing: [docs/threat-model.md](docs/threat-model.md). Optional exported assets: [SVG](docs/assets/llm-agent-control-plane.svg), [PNG](docs/assets/llm-agent-control-plane.png).\n\n### End-to-end control plane (protected path)\n\n```mermaid\nflowchart TD\n  ui[Untrusted inputs]\n  pa[Prompt assembly]\n  ac[Simulated agent core]\n  of[Output filter]\n  sv[Schema validator]\n  tb[Tool broker]\n  pe[Policy engine]\n  pr[Provenance checks]\n  ag[Approval gate]\n  st[Simulated tools]\n  al[Audit logger JSONL]\n\n  ui --\u003e pa\n  pa --\u003e ac\n  ac --\u003e|\"untrusted output\"| of\n  of --\u003e sv\n  sv --\u003e tb\n  tb --\u003e pe\n  tb --\u003e pr\n  tb --\u003e ag\n  pe --\u003e tb\n  pr --\u003e tb\n  ag --\u003e tb\n  tb --\u003e|\"allow only\"| st\n  st --\u003e al\n  of -.-\u003e|\"block leaks\"| al\n  tb -.-\u003e|\"allow or deny\"| al\n```\n\n### Security zones\n\n```mermaid\nflowchart LR\n  subgraph untrusted[\"Untrusted zone\"]\n    u1[User input]\n    u2[Retrieved documents]\n    u3[Tool output]\n    u4[Model output]\n  end\n\n  subgraph boundary[\"Deterministic control boundary\"]\n    b1[Schema validation]\n    b2[Tool broker]\n    b3[Policy engine]\n    b4[Provenance checks]\n    b5[Approval gate]\n    b6[Output filter]\n  end\n\n  subgraph execution[\"Execution and evidence zone\"]\n    e1[Simulated tools]\n    e2[JSONL audit logs]\n    e3[Demo and API results]\n  end\n\n  untrusted --\u003e boundary\n  boundary --\u003e execution\n```\n\n### Threat-to-control map\n\n```mermaid\nflowchart LR\n  t1[Prompt injection] --\u003e c1[Prompt segmentation and broker]\n  t2[RAG poisoning] --\u003e c2[Provenance checks]\n  t3[Tool misuse] --\u003e c3[Policy engine and approval gate]\n  t4[Secret leakage] --\u003e c4[Output filter]\n  t5[Cross-tenant exposure] --\u003e c5[Tenant validation]\n  t6[Unsafe execution] --\u003e c6[disabled run_shell and simulated tools]\n  t7[Audit gaps] --\u003e c7[JSONL audit logger]\n  t8[Prompt artifact leakage] --\u003e c8[Repo hygiene scanner]\n```\n\n### Validation pipeline\n\n```mermaid\nflowchart TD\n  ch[Developer change]\n  rh[Repo hygiene scanner]\n  rf[Ruff]\n  my[Mypy]\n  py[Pytest 293 tests]\n  bd[Bandit]\n  pa[pip-audit]\n  dk[Docker build]\n  dt[Docker pytest]\n  ga[GitHub Actions]\n  rel[Release tag]\n\n  ch --\u003e rh --\u003e rf --\u003e my --\u003e py --\u003e bd --\u003e pa --\u003e dk --\u003e dt --\u003e ga --\u003e rel\n```\n\nVulnerable path (`path=vulnerable`): skips the control boundary for labeled unsafe simulation only (no real execution). See [docs/architecture.md](docs/architecture.md#paths).\n\n## Demo scenarios\n\n| Scenario | Protected path |\n|----------|----------------|\n| `safe_read` | Allowed (simulated read) |\n| `internal_reviewed_read` | Allowed (internal reviewed provenance) |\n| `shell_attempt` | Blocked (`run_shell` disabled) |\n| `injection_send_email` | Blocked (retrieved provenance) |\n| `send_email_approved` + `human_approval=true` | Allowed |\n| `output_secret_leak` | Blocked (output filter) |\n| `export_no_approval` | Blocked (approval gate) |\n| `export_approved` + `role=admin` + `human_approval=true` | Allowed |\n| `cross_tenant_read` | Blocked (tenant isolation) |\n\nVulnerable path (`path=vulnerable` on `/run`): simulates unsafe decisions **without** broker enforcement (still no real execution).\n\n```bash\nmake demo\n```\n\n## Validation matrix\n\n| Check | Command | Notes |\n|-------|---------|-------|\n| All checks | `make validate` | lint, types, 293 tests, repo hygiene, policy integrity, bandit, pip-audit, Docker |\n| Tests | `python -m pytest` | 293 security-focused tests (includes enterprise doc honesty, release provenance, deployment artifacts) |\n| Repo hygiene | `python scripts/validate_repo.py` | Blocks prompt artifacts |\n| Policy integrity | `python scripts/validate_policy.py` | Schema, invariants, SHA-256 vs `policies/default.sha256` |\n| Demo | `make demo` | Seven CLI scenarios |\n| Supply chain (CI) | CodeQL, Gitleaks, Trivy, SBOM; checksums on tag | See [docs/supply-chain.md](docs/supply-chain.md); checksums are not signatures |\n\n## API example\n\n```bash\nsource .venv/bin/activate\nuvicorn agent_control_plane.api:app --reload --port 8080\n```\n\n```bash\ncurl -s -X POST http://127.0.0.1:8080/run \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"request_id\": \"demo-1\",\n    \"user_id\": \"user-1\",\n    \"session_id\": \"sess-1\",\n    \"tenant_id\": \"tenant-a\",\n    \"role\": \"user\",\n    \"user_message\": \"Read my records\",\n    \"scenario\": \"safe_read\",\n    \"path\": \"protected\"\n  }'\n```\n\n## Security principles\n\n- Deny by default.\n- Treat model output as untrusted.\n- Keep authorization outside the model.\n- Use the broker as the authority boundary.\n- Treat schema validation as input validation, not authorization.\n- Require provenance and approval checks for sensitive actions.\n- Filter and audit outputs outside the model.\n- Simulate tools in this reference implementation.\n\nSecurity controls matrix: [SECURITY-CONTROLS.md](SECURITY-CONTROLS.md). Invariants: [docs/defensive-controls.md](docs/defensive-controls.md). Threat model: [docs/threat-model.md](docs/threat-model.md).\n\n## Safe use\n\nUse only in **authorized local lab** environments. Do not point this project at production systems, real customer data, or third-party targets. Report issues per [SECURITY.md](SECURITY.md).\n\nFor deployment guardrails (API auth, CORS, request limits, container profile), see [docs/production-hardening.md](docs/production-hardening.md) and [docs/deployment-threat-model.md](docs/deployment-threat-model.md). Production mode improves posture but does **not** make this a certified production service.\n\n## Contributing and roadmap\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) — tests required for security changes\n- [ROADMAP.md](ROADMAP.md) — planned future work\n- [docs/release-checklist.md](docs/release-checklist.md) — pre-release validation\n- [docs/release-security-checklist.md](docs/release-security-checklist.md) — supply-chain release gates\n- [docs/release-provenance.md](docs/release-provenance.md) — release trust model (unsigned limitations)\n- [docs/artifact-verification.md](docs/artifact-verification.md) — verify tags, CI, SBOM, checksums\n- [docs/supply-chain.md](docs/supply-chain.md) — CodeQL, Gitleaks, Trivy, SBOM, Dependabot\n- [docs/github-actions-trust.md](docs/github-actions-trust.md) — Actions pinning and maintenance\n- [docs/enterprise-integration-plan.md](docs/enterprise-integration-plan.md) — enterprise IdP, KMS, SIEM, approvals (guidance only)\n- [docs/enterprise-readiness-checklist.md](docs/enterprise-readiness-checklist.md) — operator readiness gates\n- [docs/branch-protection.md](docs/branch-protection.md) — recommended `main` protection (guidance)\n- [docs/production-hardening.md](docs/production-hardening.md) — deployment profile and checklist\n- [docs/deployment-threat-model.md](docs/deployment-threat-model.md) — deployment threats and mitigations\n- [docs/github-publication-readiness.md](docs/github-publication-readiness.md) — first push checklist\n- GitHub issue templates under `.github/ISSUE_TEMPLATE/`\n\n## Configuration\n\nCopy `.env.example` to `.env` (optional). Policy: `policies/default.yaml`.\n\n## License\n\nMIT — [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodethor0%2Fllm-agent-control-plane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodethor0%2Fllm-agent-control-plane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodethor0%2Fllm-agent-control-plane/lists"}