Policy Configuration

Deconvolute uses a strict policy-as-code approach to govern tool execution. Security rules in the deconvolute_policy.yaml file are enforced using a First Match Wins strategy. Rules are evaluated in order from top to bottom. The first rule that matches the tool name (and its condition, if present) determines the final action.

The policy is always loaded at the beginning of a session. This means any changes to the policy take effect after the next time a session is initialized.

The Override Pattern

Because of the First Match Wins strategy, you can create specific exceptions at the top of your policy and general fallback rules at the bottom.

version: "2.0"
default_action: block

servers:
  filesystem:
    tools:
      # 1. Specific restriction (Checked First)
      - name: "unsafe_tool"
        action: "block"
      
      # 2. General fallback (Checked Second)
      - name: "*"
        action: "allow"

If your default_action is block, explicit block rules are technically redundant. However, explicit blocks are highly recommended for clarity and safety. They document exactly why a tool is forbidden and protect the system in case the default action is changed to allow in the future.

Server Version Validation

The Model Context Protocol specification requires servers to report their implementation version during the initial connection handshake. Deconvolute strictly enforces this protocol requirement. If a server attempts to connect without declaring a version string, the connection is inherently distrusted and blocked.

Optionally, you can define a version constraint for any server in your policy to prevent unauthorized server downgrades (such as supply chain attacks where a vulnerable older version is swapped in). This constraint uses standard Semantic Versioning (SemVer) specifiers.

version: "2.0"
default_action: block

servers:
  production-database:
    # Enforce that the server must be at least version 1.2.0 but less than 2.0.0
    version: ">=1.2.0, <2.0.0"
    tools:
      - name: "query_db"
        action: "allow"

If a server connects and its reported version does not satisfy the SemVer constraint defined in the policy, the SDK will immediately raise a ServerIdentityError and close the connection before any tools can be discovered or executed.

If the version field is omitted from the policy, the server is still required to report a valid version string to comply with the protocol, but its specific value will not be evaluated against a constraint.

Advanced Conditions (CEL)

While basic configurations can rely on allow or block actions based purely on a tool's name, Deconvolute utilizes the Common Expression Language (CEL) for evaluating advanced, cross-variable security policies. CEL provides a memory-safe and deterministic execution environment, making it an industry standard for strict compliance and zero-trust security.

Advanced users can define a condition string to inspect the runtime arguments passed to the tool before execution is permitted.

The Evaluation Context

Every condition is evaluated against the specific arguments provided by the AI agent to the tool. These arguments are exposed in the policy under the args variable.

If a tool expects {"filepath": "/tmp/test.txt", "force": true}, you can access these values in your policy using args.filepath and args.force.

Supported Operators

CEL syntax is highly intuitive and uses standard programmatic operators:

Comparisons: ==, !=, <, >, <=, >=

Logical: && (and), || (or), ! (not)

Membership: in (e.g. args.role in ["admin", "user"])

Common Macros & Functions

CEL provides powerful built-in macros for robust string matching and data validation:

• startsWith(string): args.path.startsWith("/public/")
• endsWith(string): args.filename.endsWith(".csv")
• contains(string): args.query.contains("SELECT")
• matches(regex): args.email.matches("^[a-zA-Z0-9]+@company\\.com$")
• size(): args.data.size() < 500

Example Usage

Here is how you can implement a fine-grained condition to restrict a tool based on its arguments:

tools:
  - name: "execute_script"
    action: block
    condition: 'args.script_name == "rm" || args.force_delete == true'
    reason: "Prevent forceful deletions or execution of rm command"