Komondor

A security layer for AI agents. Define what tools your agents can use, block everything else, and log every attempt.

Quickstart

npx komondor-cli demo

  Komondor Demo
  Your AI agent wants to do 8 things. Should it be allowed?

    ALLOW  List files                 Allow safe read-only commands
    ALLOW  Read a config file         Allow reading files under /app/
    ALLOW  Post to #eng-alerts        Allow Slack messages to #eng-* channels only
    DENY   Delete a database file     Block all file deletion
    DENY   Run rm -rf /               Block dangerous shell commands
    DENY   Post to #general           Block all other Slack operations
    DENY   Run sudo shutdown          Block dangerous shell commands
    DENY   Read /etc/shadow           deny-by-default

  8 tool calls evaluated. 3 allowed, 5 blocked.
  Zero config. Deny-by-default.

No setup, no files — the demo runs a built-in policy against simulated agent tool calls so you can see exactly how it works.

The problem

AI agents can call tools — send Slack messages, run shell commands, read files, hit APIs. Most agents get broad access to everything because it's easier to set up that way. Nobody tracks exactly what each agent is doing. If an agent deletes something it shouldn't, sends a message to the wrong channel, or runs a dangerous command, there's no guardrail stopping it and no clear record of what happened.

What Komondor does

Komondor wraps your agent's tools. When your agent tries to call a tool, the call goes through Komondor first. Komondor checks it against a policy you define (simple YAML rules like "allow Slack messages to #eng-* channels only" or "block rm commands"), then either allows the call through or blocks it. Every attempt is logged.

Agent calls a tool
       |
       v
  Komondor intercepts it
       |
       +-- Checks policy: is this tool call allowed?
       +-- Logs the attempt (inputs, decision, output)
       |
       v
  Allowed? --> Forward to actual tool
  Denied?  --> Block it, throw error

Think of it as a firewall between your AI agent and the things it can do.

Install

npm install komondor-cli

How it works

1. Write a policy — a YAML file that says what's allowed and what's not:

version: "1"
name: my-policy
rules:
  - effect: allow
    tools: ["slack:send"]
    conditions:
      parameters:
        channel:
          pattern: "^#eng-.*"
    description: "Only allow Slack to #eng-* channels"

  - effect: deny
    tools: ["shell:exec"]
    conditions:
      parameters:
        command:
          pattern: "\\b(rm|sudo|chmod)\\b"
    description: "Block dangerous shell commands"

If a tool call doesn't match any allow rule, it's blocked. Deny-by-default.

2. Wrap your tools — Komondor sits between your agent and the actual tool:

import { Komondor } from 'komondor-cli';
import { readFileSync } from 'fs';

const k = new Komondor({
  policies: [readFileSync('./policy.yaml', 'utf-8')],
  agent: { name: 'my-agent', labels: { env: 'production' } },
});

// Wrap any tool — the handler only runs if the policy allows it
const slackSend = k.wrap({
  name: 'slack:send',
  handler: async (params) => await slack.chat.postMessage(params),
});

await slackSend({ channel: '#eng-alerts', text: 'Deploy done' });  // allowed
await slackSend({ channel: '#general', text: 'Hey everyone' });    // blocked — throws ToolCallDenied

Every call is checked against your policy and logged before the tool ever executes.

Policy language

Rules are evaluated top-to-bottom. First match wins. No match = deny.

version: "1"
name: policy-name
priority: 100          # higher priority wins in multi-policy setups (default: 0)
rules:
  - effect: allow|deny
    tools: ["namespace:tool", "namespace:*"]
    conditions:
      parameters:
        param_name:
          eq: "exact"
          pattern: "^regex$"
          in: ["a", "b", "c"]
          # also: neq, notIn, lt, lte, gt, gte
      agent:
        label_name:
          eq: "value"
    description: "what this rule does"

More examples in examples/.

CLI

# Run the demo
komondor demo

# Validate policy files
komondor validate policy.yaml

# Test a policy against a simulated call (no actual execution)
komondor dry-run \
  --policy policy.yaml \
  --tool slack:send \
  --params '{"channel":"#general"}' \
  --agent '{"name":"test","labels":{}}'

# Pretty-print audit logs
komondor audit audit.log

MCP adapter

Komondor works with the Model Context Protocol:

import { Komondor, wrapMcpTool } from 'komondor-cli';

const wrapped = wrapMcpTool(k, {
  tool: mcpToolDefinition,
  handler: async (params) => { /* ... */ },
});

// tool name becomes "mcp:tool_name" in policies and audit
await wrapped.handler({ url: 'https://example.com' });

Audit

Every tool call emits a JSON-line audit event (stdout by default, or file):

import { Komondor, FileAuditEmitter } from 'komondor-cli';

const k = new Komondor({
  policies: [policy],
  agent: { name: 'my-agent', labels: {} },
  audit: { emitter: new FileAuditEmitter('./audit.log') },
});

Custom emitters: implement the AuditEmitter interface (emit(event: AuditEvent): Promise<void>).

API

import {
  Komondor,                    // main class
  wrapMcpTool,                 // MCP adapter
  loadPolicyFromFile,          // async policy loader
  loadPolicyFromString,        // sync policy loader
  ToolCallDenied,              // thrown on deny
  ToolCallAuditError,          // thrown on audit failure
  FileAuditEmitter,            // file-based audit
  StdoutAuditEmitter,          // stdout audit (default)
} from 'komondor-cli';

Full type exports: Policy, PolicyRule, AgentIdentity, AuditEvent, ToolDefinition, KomondorTool, etc.

Development

npm run build          # compile
npm test               # vitest
npm run test:coverage  # coverage report
npm run lint           # eslint
npm run typecheck      # tsc --noEmit

License

Apache 2.0