csl-core

CSL-Core solves the problem inherent in writing security rules into prompts: rules in prompts are only suggestions, the model can be persuaded to bypass them, the rules work most of the time but not every time, and there is no record. CSL-Core places the rules outside the model, compiles them into policies that have been proven consistent, and checks them on every tool call.

1. Main uses and core capabilities

• Discovery: cslcore venom reads code (parses but does not run), assistant and MCP configurations, cron, systemd and launchd, process lists, run history, and existing policies to find every AI agent on the host and its reachable scope. Each agent's tools are classified by risk (read, write, external, execute, spend, destructive), along with guard coverage and findings (such as "agent runs as root" or "inbound webhook can reach public publishing tools"). The scan is read-only and does not modify the host; credential values, prompts, and conversation records do not appear in the output. Reports are located in .csl/venom/reports/, and cslcore venom --check can be used as a CI gate; --check --fail-on-new-reach can make CI fail when new reachable paths appear.
• Reachability chains and reachability map: an agent may look harmless on its own, but the risk lies in chains - an agent that reads web content may modify the code of another agent running as root, or reach cloud credentials and transfer funds. Venom builds a reachability graph based on the discovery results and finds escalation chains that require passing through two or more agents to reach. cslcore venom map opens the map in full screen; use the arrow keys or the numbers 1 to 9 to select, and the panel shows what can reach the node and what it can reach; press d to drill down into an agent, s to switch to a 3D globe view, n to hide names, and r to replay the spread. The most severe direct exposures are also shown step by step on the scan screen and in the report.
• Installation and setup: cslcore setup provides ten resumable steps: scope, discovery, inventory, findings and recommendations, exemptions, policy (protection board), verification, mapping, execution mode and wiring, activation. On the protection board, press Enter to provide standard protection for agents without a policy, numbers open the cycle for a single agent, s leaves it unchanged, and o provides other ways (use an existing policy, write it in the studio or editor, have the assistant draft it). Each policy isBefore activation, everything passes through the same gate: parsing, validation, Z3, and mapping tests. Agents activated for the first time default to block mode (unless log is chosen).
• Policy language and studio: A policy is a small, readable plain-text file; the syntax specification is in syntax-spec.md. cslcore studio is a complete policy editor in the terminal; F5 (or Ctrl+R) runs Z3 to check for rule contradictions and rules that never trigger, and F8 (or Ctrl+T) runs TLA+ and the real TLC model checker when Java is available. Suggestions can be applied by pressing Enter; the Agents tab can replay recorded decisions against edits before changes, Ctrl+B binds an agent, Ctrl+L brings it online, and running guards switch on the next invocation.
• Mapping tests: cslcore map --test tests each mapping with case variants, unknown values, missing keys, wrong types, and range boundaries, and tests each derived check (path in range, command allowed, target allowed) with bypass techniques such as path traversal, similar folders, chained and substituted commands, credentials in URLs, and similar hosts. Red-team findings are kept as regression cases. Guidance is in MAPPING.md.
• Runtime monitoring: cslcore watch is a live panel showing an agent's mode and interception rate, decision stream, and rules sorted by interception frequency. You can switch between log and block (m), disable an agent or a single tool (kill switch), exempt a rule with a recorded reason, or open the rule in the studio. l modifies limits, w wires or unwires, and a lists calls awaiting approval. Changes reach running agents on the next invocation without a restart and are recorded in .csl/venom/audit.jsonl. Press g to view the live reachability map, where ALLOW is shown in cyan light and WOULD BLOCK flashes in purple.

II. How to Use

• First installation: cslcore setup completes the entire first-time installation, scans the machine, explains what it finds, and opens the protection board, sorted from highest to lowest risk. Before confirming wiring changes, it only writes within the folder where it is running.
• Look without installing: with uv, you can first run a read-only scan in about one second. Add --share to generate a machine reachability map card for posting (without hostnames, usernames, or paths; --anonymize also hides agent names). You can also try the full workflow against a sample host after cloning this repository (sample host and traffic scriptThis is in the repository, not in the package).
• Wiring: after the policy is activated, the guard enters each agent's call path. Claude Code uses the PreToolUse hook in the project's .claude/settings.local.json; every tool call passes through it, including tools added by plugins afterward. Python tools (LangChain @tool, OpenAI Agents @function_tool, CrewAI, plain functions) are wired by adding @_csl_guard.tool("name") directly beneath the framework decorator; the tool keeps its name, docstring and signature. Tools that exist only as schemas cannot be wired automatically and get an exact guard.check line, and the summary states that they are not wired. Each modified file is first copied to the workspace, and cslcore wire --undo restores it.
• Limits: cslcore limits shows and modifies what each agent may do (--set transfer_funds=100k..300k, --set export_rows.limit=..1000, --decide delete_user=block), and regenerates the policy, checks it and runs the check. The repository can store limits in csl-limits.ini for review in a pull request; cslcore apply makes them take effect, and cslcore apply --check checks them in CI.
• Approval: calls that exceed the free allowance do not stop outright; Claude Code asks (the hook answers ask), wired Python tools return ApprovalPending and wait in cslcore watch (press a); after approval, the same call runs once within ten minutes. Calls that no approval can permit (exceeding the maximum, destructive commands) still stop.
• Using from code: the guard is used when the agent starts and follows its bindings, modes and kill switch in real time; the policy can also be used independently of the workspace. By default, blocked calls throw ChimeraError, and the agent cannot ignore the result and continue. Existing guards (0.5.1) can add a decision log, log mode and a live panel in one line while keeping block mode. The values in inject come from your system, not the model, and the model cannot override them. The MCP server provides assistants (Claude Desktop, Cursor, VS Code) with tools to validate, simulate, explain and scaffold policies, reads findings and saves drafts; drafts are validated by the assistant but never activated, and activation is up to you.

III. Applicable scenarios Suitable for running multiple AI agents, MCP servers, scheduled tasks and scripts with tool access on your own machine or server, when you need to know which agents exist, what they can reach, and to set boundaries for them that are provable and deterministically enforced. Also suitable for teams that gate policy consistency in CI, review limit changes, and need to record every tool-call decision.

IV. Limitations and notes Policies are validated before running, and at runtime the guard only evaluates; policies that do not pass Z3 are not compiled, and when a mapping cannot read a value it blocks the call instead of guessing. The workspace should be on a local disk: file locks on NFS and some container volumes are unreliable. Schema-only tools that are not wired automatically require adding a guard.check line manually. A multi-machine hosted control plane (unified view, centralized policy publishing, long-term audit retention), more framework integrations and Linux packaging are still on the roadmap. The project uses Apache 2.0, and everything in the repository is free for any use; Chimera Protocol and CSL are trademarks of Chimera Protocol, Apache 2.0 grants rights to the code, and the trademark is reserved. Contact for collaboration: aytug@chimera-protocol.com.