DEV Community: Umang Kumar

Hash-chained audit logs for AI agent actions, in 40 lines

Umang Kumar — Fri, 09 Oct 2026 15:00:17 +0000

When an AI agent calls a tool — reads a file, applies a manifest, installs a package — you want an audit log you can trust weeks or months later. Tamper-evident doesn't require a blockchain or a signing service. A SHA-256 hash chain over append-only entries is enough to detect a rewrite.

Here's a minimal TypeScript example you can drop into an MCP server, a tool proxy, or an agent harness.

The entry shape

Each event captures the who, what, and when:

interface AuditEvent {
  id: string;             // unique id, e.g. ulid or uuid
  timestamp: number;      // epoch ms, set by the log
  caller: string;         // agent / client identity
  action: string;         // tool name or operation
  input: string;          // canonicalized, redacted JSON string
  outcome: "ok" | "err" | "denied";
  priorHash: string;      // hash of the previous event
}

priorHash is the chain. Event 0's priorHash is a fixed genesis constant; every subsequent event's priorHash is the SHA-256 of the previous event's serialized text.

The logger

import { createHash } from "crypto";

const GENESIS = "0000000000000000000000000000000000000000000000000000000000000000";

function eventHash(event: AuditEvent): string {
  return createHash("sha256")
    .update(JSON.stringify(event, null, 0))
    .digest("hex");
}

class ChainedLog {
  private events: AuditEvent[] = [];

  append(event: Omit<AuditEvent, "timestamp" | "priorHash">): AuditEvent {
    const priorHash =
      this.events.length === 0
        ? GENESIS
        : eventHash(this.events[this.events.length - 1]);

    const entry: AuditEvent = {
      ...event,
      timestamp: Date.now(),
      priorHash,
    };

    this.events.push(entry);
    return entry;
  }

  /** Serialize one event to the canonical line you'd write to a file. */
  line(event: AuditEvent): string {
    return JSON.stringify(event, null, 0);
  }
}

To make it append-only on disk, each line(entry) is appended to a file with O_APPEND (Node's fs/promises fd.appendFile), and no write removes or overwrites prior bytes.

How to verify

Verification walks the chain forward and recomputes each hash. If any priorHash in the log doesn't match the recomputed hash of its predecessor, the log was rewritten between those two entries.

function verify(events: AuditEvent[]): { valid: boolean; badAt: number | null } {
  let expectedPrior = GENESIS;

  for (let i = 0; i < events.length; i++) {
    const e = events[i];

    if (e.priorHash !== expectedPrior) {
      return { valid: false, badAt: i };
    }

    expectedPrior = eventHash(e);
  }

  return { valid: true, badAt: null };
}

Usage is straightforward:

const log = new ChainedLog();

log.append({ id: "evt-1", caller: "agent-42", action: "read_file", input: '{"path":"README.md"}', outcome: "ok" });
log.append({ id: "evt-2", caller: "agent-42", action: "kubectl_apply", input: '{"manifest":"deploy.yaml","namespace":"prod"}', outcome: "denied" });

const snap = log.events;
const result = verify(snap);
console.log(result); // { valid: true, badAt: null }

If someone replaces evt-1's action with write_file or deletes evt-2, verify returns badAt: 1 on the first walk. The chain catches insertions, deletions, and in-place edits without any cryptography heavier than SHA-256.

Two things the chain doesn't do

A hash chain makes rewriting detectable. It does not, by itself:

Anchor the chain in time or to a principal. Bind the head or a periodic checkpoint to something outside the log — a signed attestation, a write to a remote append store, or a human-reviewed summary — and the chain becomes evidence rather than just a local checksum.
Prevent the writer from appending whatever they like. If the agent controls the logger, it can append favorable entries. That's a policy problem, not a hashing problem. The chain still proves that whatever is there wasn't altered afterward, which is the useful half.

Where to put it

In an MCP server: log every tool invocation and its outcome.
In a tool proxy: log every forwarded call and the policy decision (allow / deny / hold).
In an agent harness: log every tool grant and every approval the harness surfaced.

The chain is the same everywhere. The identity in caller is what makes the entries attributable.

I'm building Cirvix AgentControl, an open-source default-deny policy layer for agent tool calls: https://github.com/CIRVIX/agent-control (try npx @cirvix_ai/agent-control scan).

Securing MCP servers: a practical checklist for 2026

Umang Kumar — Fri, 09 Oct 2026 14:41:29 +0000

MCP servers look harmless because they expose tools, not endpoints. A client calls a tool and gets a result. But the tools often touch a filesystem, a database, a package manager, or a deployment API. That makes the MCP server the authorization boundary, whether you planned it or not.

Here are the five failure modes I've seen show up in production and a short checklist you can run through before exposing a server to agents.

Tool-definition drift

The client decides what a tool does by reading its declaration: name, description, and parameter schema. If the declaration lies, or drifts from what the handler actually does, the client's policy is enforcing the wrong thing.

Real examples: a tool declared as "read a file at this path" that silently tails a log stream; a "list packages" tool whose handler also accepts a --resolve flag that performs installs; a parameter added server-side that the client's declaration doesn't mention yet the agent keeps sending.

Mitigation: the client should pin the tool schema it authorized (hash it) and reject handlers whose live declaration diverges. Server-side, version the tool manifest and log every declaration change. Treat a declaration update the same way you treat a dependency bump — it's an authority surface.

Over-broad filesystem tools

A filesystem tool that accepts any path is a filesystem tool that accepts /etc/shadow, ~/.ssh, and every mounted secret. I've seen MCP servers ship a single read_file(path) and a single write_file(path, content) and then rely on the client to pass safe paths.

Clients are agents. Agents are given goals. If the goal is "fix this deploy" and the agent has a write_file that accepts any path, the shortest path to the goal sometimes writes to /etc or to a directory that the CI pipeline reads from.

Narrow the tools. Ship read_project_file(glob) scoped to the repo root, write_project_file(glob, content) scoped the same way, and a separate, explicitly-named tool for anything outside the project. Make the default "no" for the rest of the filesystem.

Secrets in the environment

MCP servers run as processes. Processes inherit environment variables. It is common to run an MCP server inside a container or a CI step that also carries DATABASE_URL, AWS_ACCESS_KEY_ID, or a signing key.

An agent with a "run command" tool or a filesystem tool can read /proc/self/environ or list the directory a shell writes .env files to. The server didn't ship a "read secrets" tool, but the tools it did ship composed into one.

Drop sensitive variables at the server boundary, not at the agent boundary. Run the MCP server with a minimal environment and pass only what its tools need. If a tool needs a credential, pass it through the server's own secret store, not through the process environment the agent can observe.

Egress allowlists

A tool that fetches a URL, installs a package, or calls a registry can turn an MCP server into a data exfiltration or supply-chain hop. The client authorized the tool; the tool's network destination is what determines the blast radius.

Treat outbound connections from the MCP server like outbound connections from any service that runs untrusted input: an allowlist of destinations, and nothing else. Package installs go to the pinned registry. API calls go to the declared host. Everything else is dropped.

You don't need a full egress proxy to get started. Even iptables rules or a container runtime's network policy on the MCP server process surface is enough to make the difference between "the agent fetched a template" and "the agent phoned home with a config file."

Audit logging

You cannot defend what you cannot replay. Every tool invocation the server executes should be logged with: the calling client identity, the tool name, the input parameters (redacted for credentials), the outcome, and a server-side timestamp.

Logs should be append-only after the fact and shipped out of the host the server runs on. If an agent has a filesystem tool on that host, it has a write tool on the log file.

Checklist

Run this against every MCP server you expose to an agent before you let it run workloads:

[ ] Pin and hash each tool declaration on the client; reject handlers that drift.
[ ] Replace blanket filesystem tools with path/glob-scoped tools rooted to the project.
[ ] Strip secrets from the server's process environment; pass credentials only through the server's own store.
[ ] Apply an egress allowlist to the server's outbound connections (registry + declared API hosts only).
[ ] Log every tool invocation with caller identity, tool, redacted inputs, outcome, and server timestamp; ship logs off-host.
[ ] Review the server's tool manifest after every update the same way you review a dependency bump.

MCP servers aren't untrusted in the browser sense. They're more like a CI runner that an agent can steer. Secure them like one.

I'm building Cirvix AgentControl, an open-source default-deny policy layer for agent tool calls: https://github.com/CIRVIX/agent-control (try npx @cirvix_ai/agent-control scan).

Why approval prompts don't work as a security boundary for coding agents

Umang Kumar — Fri, 09 Oct 2026 14:40:53 +0000

When a coding agent asks a human to approve a file change, a database call, or a deploy, the approval prompt feels like a security boundary. It's not.

In practice, approval prompts leak authority for three reasons: approval fatigue, approvals that never expire, and stale pending approvals that outlive the decision they capture.

Approval fatigue

An agent that runs an entire PR lifecycle can surface dozens of prompts in a single session. Most of them are low-risk: formatting a config, reading a log, re-running tests. A few are high-risk: writing to a deployment manifest, touching secrets, changing network rules.

When everything looks the same in the prompt, humans stop reading. They learn to click "Approve" to keep the agent moving and catch up later. That later is when the deploy went to the wrong environment and the rollback took thirty minutes.

The fix isn't more prompts. It's making every prompt distinguishable.

Approvals that never expire

Most agent toolkits record an approval as a boolean decision on a category of action: "approve kubectl apply" or "approve writes to /etc". There is no time bound attached.

An approval granted at 9:00 AM should not authorize the same action at 4:00 PM, after the incident context has changed, the on-call has handed off, and the agent's mission scope has drifted.

Without an expiry, the approval becomes a standing credential. The human reviewed a point-in-time description and unknowingly minted a persistent grant.

Stale pending approvals

The flip side: a prompt sits in a queue while the human is on a call or asleep. Three hours later, the agent replays the pending request against a newer snapshot of the environment.

The description the human approved no longer matches what would execute. The approval was sound when issued; it is unsound when fulfilled.

This is why "pending approvals" and "authorized actions" are not the same thing. A pending approval captures a decision about a specific action at a specific time. Once that time window closes, the decision must be withdrawn.

A better shape: expiring HOLD approvals bound to the exact action hash

A practical fix that keeps humans in the loop without minting standing credentials:

Halt the action, don't queue it. The agent emits a HOLD with a deterministic hash of exactly what would execute.
Bind the approval to the hash, not the category. The human's "yes" signs off on that hash. If anything about the inputs, target, or arguments changes, the hash changes and the approval doesn't apply.
Attach a short, non-extendable expiry. Five to fifteen minutes is enough for a focused review; long enough that the human isn't forced to answer while a deployment countdown hits zero.
Fail closed on expiry. When the timer expires, the HOLD transitions to DENY. The agent re-emits a fresh request with a fresh hash if it still wants the action.

This is how Cirvix AgentControl structures an approval:

import { createHash } from "crypto";

function actionHash(action: Record<string, unknown>): string {
  return createHash("sha256")
    .update(JSON.stringify(action, null, 0))
    .digest("hex");
}

interface HoldApproval {
  id: string;
  actionHash: string;
  expiresAt: number; // epoch ms
  approvedBy: string;
  approvedAt: number;
  status: "pending" | "approved" | "denied" | "expired";
}

function verifyApproval(
  hold: HoldApproval,
  requestedAction: Record<string, unknown>
): boolean {
  const freshHash = actionHash(requestedAction);

  return (
    hold.status === "approved" &&
    hold.actionHash === freshHash &&
    Date.now() < hold.expiresAt
  );
}

const call = { tool: "kubectl_apply", manifest: "deploy.yaml", namespace: "prod" };
const hold: HoldApproval = {
  id: "hold-001",
  actionHash: actionHash(call),
  expiresAt: Date.now() + 10 * 60 * 1000,
  approvedBy: "human@example.com",
  approvedAt: Date.now(),
  status: "approved",
};

console.log(verifyApproval(hold, call)); // true

const drifted = { ...call, namespace: "prod-backup" };
console.log(verifyApproval(hold, drifted)); // false

The three checks — status approved, hash matches the exact action, and current time is still inside the expiry — make the approval a verifiable ticket for one execution, not a standing credential.

What changes for the agent

The agent's loop gains an explicit HOLD/DENY transition instead of silently retrying a pending queue.
Tool wrappers compute the action hash before execution and refuse to run if the hash doesn't match the approval that cleared them.
Observability becomes simpler: every approval event carries the hash and the expiry, so you can diff a denied execution against what was approved and see exactly which field drifted.

What doesn't change

Humans still review. The difference is that their review is scoped: a short window, a specific action, and a clear failure mode when the scope shifts.

Prompt-based approvals are still useful as a UX. They just shouldn't be the boundary. The boundary is the hash-bound, time-bound decision that the enforcement layer verifies at execution.

I'm building Cirvix AgentControl, an open-source default-deny policy layer for agent tool calls: https://github.com/CIRVIX/agent-control (try npx @cirvix_ai/agent-control scan).

5 permission rules every coding agent should ship with

Umang Kumar — Fri, 09 Oct 2026 12:22:26 +0000

Coding agents now run shell commands, edit files, and push branches on real repos. Most teams give them either everything or a pile of "are you sure?" prompts that people click through.

There is a middle ground: a small set of rules that stop the handful of actions that actually cause incidents, and stay out of the way for everything else. Below are five I think every coding agent should ship with, written in the policy format of Cirvix, an open-source runtime authorization layer that sits in the tool-call path of Claude Code, Cursor, Codex, and MCP clients. Each call gets ALLOW, HOLD, or DENY, with deny as the default.

Every snippet below validates with cirvix policy check and is either taken from the repo's policies/ files or written in the same shape.

1. Deny reads of `.env` and credential files

Reading .env is the shortest path from a prompt injection to a live credential. The agent does not need the raw value to do its job.

deny:
  name = deny-dotenv
  tool = filesystem.read
  path = **/.env
  reason = "Reading .env is the shortest path from a prompt injection to a live credential."
  remediation = "Request the value as a handle: secrets.get(\"NAME\")"

deny:
  name = deny-dotenv-variants
  tool = filesystem.read
  path = **/.env.*
  reason = ".env.production and friends hold the credentials that matter most."

The repo's secrets.policy extends this to ~/.aws, ~/.ssh, .kube/config, .npmrc, .netrc and Docker config. The remediation line matters: it tells the agent what to do instead, so it does not just retry. If a secret-shaped read does slip through, a session taint rule then blocks external egress for the rest of that session.

2. HOLD destructive shell in production

Not every shell command is dangerous, and blocking all of them makes the agent useless. In production, though, a person should see it first.

require_approval:
  name = hold-shell-in-production
  tool = shell.exec
  env = production
  approvers = platform-oncall
  reason = "Shell in production is held for a named human."

require_approval is a HOLD: the call does not fail, it waits on a named approver. By default it returns "pending" right away with an approval id, so the agent can say what it is waiting for instead of looking like a hung tool call. The default policy also ships approve-high-risk-shell (risk >= HIGH) and a flat deny on rm -rf.

3. Deny force-push

Force-push discards commits other people may already have. The repo's default policy denies it outright:

deny:
  name = deny-history-rewrite
  tool = shell.exec
  command = "git push --force"
  reason = "Force-push discards commits other people may already have. Recoverable only if somebody still has the objects."

deny:
  name = deny-history-rewrite-short
  tool = shell.exec
  command = "git push -f"
  reason = "Same rule, short flag."

command = compiles to a contains match, so git push -f origin main is caught. It is still a literal string match, so cover the variants you care about (the second rule is my addition) and prove it with a test block in the same file:

test "force push short flag":
  tool = shell.exec
  command = "git push -f origin main"
  expect deny

I deny force-push everywhere rather than only on main. An agent rewriting history on any shared branch is a bad day, and humans can still force-push themselves.

4. Keep writes inside the workspace

An agent scoped to a repo has no reason to write to /etc/hosts or your shell profile.

deny:
  name = deny-workspace-escape-write
  tool = filesystem.write
  workspace = false
  reason = "Writes outside the workspace root are outside what this run was scoped to change."

allow:
  name = allow-workspace-write
  tool = filesystem.write
  workspace = true

workspace is decided after path canonicalization: traversal like ./src/../../etc/hosts is collapsed and encoding tricks are normalised before the check, so the rule sees where the write actually lands. Deny always wins over allow, so a looser rule in another file cannot reopen it.

5. Make approvals expire

A HOLD is only as good as its approval. "Yes, do that" means yes to the situation the approver was looking at, not to the same call next Tuesday.

In Cirvix this is enforced by the approval queue rather than a policy line. The defaults from src/core/approvals.mjs:

An unanswered approval expires after 15 minutes instead of hanging.
A granted approval is spendable for 10 minutes.
A grant is single use: one yes authorises one execution.
It is matched by fingerprint, not by tool: approving a database.write on one table does not release a database.write on another.

Pair it with a hold rule like the repo's:

require_approval:
  name = approve-database-migrate
  tool = database.migrate
  approvers = platform-oncall
  reason = "A migration changes the shape of data every other system reads."

and work the queue with cirvix approvals, cirvix approve, and cirvix deny. Every transition goes into the local SHA-256 hash-chained audit log, so "what did that approval authorise?" has an answer afterwards.

Try it

npx @cirvix_ai/agent-control scan
cirvix policy check --policy cirvix.policy
cirvix policy test  --policy cirvix.policy

Zero runtime dependencies, no phone-home, and it only enforces on calls routed through its MCP gateway or SDK, so check your client actually goes through it.

Repo: https://github.com/CIRVIX/agent-control
Site: https://cirvix.com

What would be your sixth rule?

Stop the read-then-exfiltrate chain: session taint for AI agents

Umang Kumar — Fri, 09 Oct 2026 12:22:26 +0000

Most AI agent incidents people worry about are not one bad tool call. They are two ordinary ones in a row.

The agent reads a file. Maybe it is .env, maybe config/credentials.yml, maybe a token pasted into a ticket it was asked to summarise.
The agent makes an outbound HTTP request. Maybe to "fetch the docs", maybe to a URL that a prompt injection planted in a README.

Each call, judged on its own, can look fine. Agents read files all day. Agents fetch URLs all day. A per-call allowlist that says "reads inside the workspace are OK" and "HTTP to public hosts is OK" will happily approve both, and the secret leaves in the second request's query string.

This is the read-then-exfiltrate chain, and it is the reason a policy layer for agents needs at least a little memory.

Why per-call rules are not enough

Cirvix is an open-source runtime authorization layer that sits in the tool-call path of agents like Claude Code, Cursor, Codex, and anything speaking MCP. Every call gets a verdict: ALLOW, HOLD (wait for a named human), or DENY. The default is deny.

The obvious first rules are about what is touched:

deny:
  name = deny-dotenv
  tool = filesystem.read
  path = **/.env
  reason = "Reading .env is the shortest path from a prompt injection to a live credential."
  remediation = "Request the value as a handle: secrets.get(\"NAME\")"

Those matter, and they catch the obvious case. But secret-shaped material turns up in places no path rule anticipated: a log file, a test fixture, a tool result. You cannot enumerate every place a credential might live. You can notice that one was read.

Session taint: one bit, set once

Cirvix keeps a session flag, session.touchedSecret. It is set the moment a session successfully reads something matching /secret|credential|token|password|\.env/i, and it never resets for that session.

Policies can then condition on it. This is the real rule from the repo's starter set (docs/examples/cirvix.policy.json):

{
  "name": "deny-external-egress-after-secret",
  "effect": "forbid",
  "actions": ["http.request", "net.*"],
  "resources": ["*"],
  "when": [
    { "path": "egress.external", "op": "eq", "value": true },
    { "path": "session.touchedSecret", "op": "eq", "value": true }
  ],
  "reason": "This session read secret material, so outbound requests to external destinations are blocked for the remainder of it."
}

And the same idea in the .policy DSL, from policies/network.policy:

deny:
  name = deny-egress-after-secret-read
  tool = network.request
  touched_secret = true
  reason = "This session read secret-shaped material, so outbound requests are blocked for the remainder of it."

Read it as: once this session has seen a secret, nothing it does may leave the machine to an external host. Both conditions must hold. A session that never touched a secret can still fetch docs. A session that did can still read, write, and run tests locally. It just cannot phone out.

Deny wins over allow in Cirvix, always. So even if a later file adds allow-allowlisted-egress, the taint rule still blocks the request. Composing policy files can only tighten, never loosen.

What the agent sees

A refusal an agent cannot read is a refusal it cannot recover from, so the decision comes back structured: the verdict, the rule name, the reason, and a trace of every rule considered. In practice the agent gets "denied by deny-external-egress-after-secret: this session read secret material", and it can tell the user why instead of retrying in a loop.

Every decision is also written to a local audit log where each record carries a SHA-256 hash of the previous one, so you can check the chain is internally consistent with cirvix audit verify. Nothing is sent anywhere; Cirvix has no phone-home and zero runtime dependencies.

Secret handles do not taint

The taint rule is blunt on purpose, and blunt rules need an escape hatch. If the agent genuinely needs a credential to do its job, it should not read the raw value at all. Cirvix's secret brokering gives the agent a handle (secrets.get("STRIPE_KEY")) instead of the material. Spending a handle does not set touchedSecret, because the agent never held the secret. That is the whole point of a handle.

So the healthy pattern is: raw reads of secret-shaped files taint and lock egress; brokered handles keep working.

Honest limits

Session taint is one specific two-step pattern, hard-coded as a boolean the engine tracks. It is not a general sequence language. You cannot yet write "deny step C if steps A and B happened in that order within five calls" or express arbitrary multi-step chains in policy. General multi-step sequence policies are still open work.

A few more things worth knowing:

Taint is per session and, unless an embedder persists it, process-local. A restart starts a clean session.
The pattern match on what counts as "secret-shaped" is a heuristic. Pair it with explicit path denies for the files you know about.
Cirvix enforces on calls that are routed through it (the MCP gateway, the SDK guard, the wrappers). It is not machine-wide interception; an editor's built-in tools or a subprocess that bypasses the gateway are outside that boundary.

Try it

npx @cirvix_ai/agent-control scan

The scan looks at your local agent configuration and which credential paths are reachable. Then put the taint rule in your policy and test it:

cirvix policy check --policy cirvix.policy
cirvix policy test  --policy cirvix.policy

Repo: https://github.com/CIRVIX/agent-control
Site: https://cirvix.com

If you have a real chain you want to express that taint does not cover, open an issue. That is exactly the input the sequence-policy work needs.

MCP Security: Where to Put the Authorization Boundary

Umang Kumar — Fri, 09 Oct 2026 08:29:01 +0000

An MCP tool call passes through the model, the client, possibly a proxy, and the server before anything happens. Only one of those places sees every call in structured form and is controlled by you rather than by the agent or a third party: the seam between client and servers. That is where an MCP security gateway belongs, and this page shows how to put one there.

One seam: client ↔ servers

server__tool: namespaced per upstream

Default deny: unlisted tools refused

Hash-chained: audit per decision

The question

Five places you could enforce. One that works.

Every MCP security control is really a decision about where the authorization boundary sits.

The MCP security overview covers what goes wrong: broad-scope tools, poisoned tool descriptions, credentials leaking through results. This page answers the follow-up question teams ask once they accept that per-call policy is needed: where should the decision be made?

Where the boundary sits	What it sees	Who controls it	Verdict
In the prompt or system message	Text	The model, which can be talked out of it	Advisory at best
Inside each MCP server	Its own calls only	Whoever wrote that server, often a third party	Inconsistent across servers, no shared context
Network or HTTP proxy	Hosts and bytes; nothing for stdio servers	You	Misses local servers and argument meaning
Gateway at the client–server seam	Every routed `tools/call`: server, tool, arguments	You, independent of agent and server	The authorization boundary
In-process wrapper (`guard.wrap`)	Calls to tools you own	You	Use for non-MCP tools alongside the gateway

The prompt is the wrong place because the same channel that carries policy also carries injected instructions. The server is the wrong place because you will run servers you did not write, each with its own idea of safety, and none of them knows what the agent did on another server a moment ago. A network proxy is the wrong place because most local MCP servers speak stdio and never open a socket, and a proxy sees a hostname, not that the tool is drop_table.

The client–server seam has none of these problems. Every tools/call crosses it as structured JSON-RPC with a server, a tool name and arguments. It sits outside the model, so nothing the model reads can rewrite it. And it is one place, so one policy governs every server behind it.

Why the seam

What a gateway at the seam can do that nothing else can.

From the Cirvix gateway's documented behavior and its public source.

Evaluate before forwarding

Each tools/call is decoded, evaluated against policy, recorded and then forwarded, refused or held. Every governed agent action routed through Cirvix is evaluated before execution; a refused call never reaches the upstream server.

Keep servers apart

Tool names are namespaced as server__tool. Two servers that both expose search stay distinct, so a rule written for one cannot silently govern the other. Rules read the server and tool as mcp.server and mcp.tool.

Pin tool definitions

A tool description enters the model's context as instruction text supplied by the server. The gateway fingerprints each definition when it first sees it and withholds a tool whose definition later drifts from that pin.

Return denials the agent can read

A refusal comes back as a tool result with the rule, reason and remediation, not as a transport error. The agent can re-plan instead of treating the server as broken.

Record one chain for every server

Decisions from every upstream land in the same SHA-256 hash-chained audit log, and results are scanned on the way back.

Setup

The artifact: a gateway in front of two servers.

Three files. Upstreams in one, the client's gateway-only map in another, policy in the third.

mcp-upstreams.json — what the gateway connects tojson

{
  "mcpServers": {
    "github":   { "command": "npx", "args": ["-y", "<your-github-mcp-server>"],
                  "env": { "GITHUB_TOKEN": "<token>" } },
    "postgres": { "command": "npx", "args": ["-y", "<your-postgres-mcp-server>", "<connection-string>"] }
  }
}

.mcp.json (or your client's MCP config) — the only server the client seesjson

{
  "mcpServers": {
    "cirvix": {
      "command": "cirvix",
      "args": ["gateway",
               "--servers", "/abs/path/mcp-upstreams.json",
               "--policy",  "/abs/path/cirvix.policy.json",
               "--cwd",     "/abs/path/workspace"]
    }
  }
}

cirvix.policy.json — per-server, per-tool rulesjson

{
  "rules": [
    { "name": "hold-github-writes", "effect": "hold",
      "when": [
        { "path": "mcp.server", "op": "eq", "value": "github" },
        { "path": "mcp.tool",   "op": "in", "value": ["create_pull_request", "merge_pull_request", "push_files"] }
      ],
      "approvers": ["maintainers"],
      "reason": "Writes to GitHub need a maintainer." },

    { "name": "allow-github-reads", "effect": "permit",
      "when": [
        { "path": "mcp.server", "op": "eq", "value": "github" },
        { "path": "mcp.tool",   "op": "in", "value": ["get_file_contents", "search_issues", "list_issues"] }
      ] },

    { "name": "allow-postgres-query", "effect": "permit",
      "when": [
        { "path": "mcp.server", "op": "eq", "value": "postgres" },
        { "path": "mcp.tool",   "op": "eq", "value": "query" }
      ] }
  ]
}

The policy names tools explicitly with mcp.tool rather than relying on action classes like fs.write. Cirvix classifies tool names into actions heuristically, which is useful for generic rules, but for third-party MCP tools an explicit tool list is clearer to review and cannot be surprised by a name the classifier reads differently. After your first real calls, check cirvix logs to see exactly how each tool was normalized.

Walkthrough

Four calls through the gateway.

Output from @cirvix_ai/agent-control 0.2.5 with the policy above, against stub upstream servers named postgres and github. Responses trimmed.

JSON-RPC transcripttext

# client -> gateway: tools/call  postgres__query  {"sql":"select count(*) from orders"}
<- result: "upstream ran query ..."                       # PERMIT  allow-postgres-query

# client -> gateway: tools/call  postgres__drop_table  {"table":"orders"}
<- isError: true
   "Denied by policy: default-deny
    No rule permits this call. The policy set is default-deny: an action must be explicitly allowed."
   _meta: { "cirvix/verdict": "deny", "cirvix/rule": null, "cirvix/decision_id": "dec_..." }

# client -> gateway: tools/call  github__create_pull_request  {"title":"Bump deps"}
<- isError: true
   "Held for human approval: hold-github-writes
    Writes to GitHub need a maintainer.
    Waiting on: maintainers"
   _meta: { "cirvix/verdict": "hold", "cirvix/rule": "hold-github-writes", "cirvix/approval_id": "apr_..." }

# client -> gateway: tools/call  github__get_file_contents  {"path":"README.md"}
<- result: "upstream ran get_file_contents ..."           # PERMIT  allow-github-reads

$ cirvix audit verify      # Hash chain intact · 4 records verified
$ cirvix approvals         # 1 call waiting: create_pull_request, policy hold-github-writes

The read query runs because allow-postgres-query names it. drop_table is refused with rule: null: nobody wrote a rule forbidding it, and nobody had to, because nothing permits it. The pull request is held for maintainers and shows up in cirvix approvals; approving records a single-use grant for a retry, and nothing resumes on its own. The file read passes. Four calls, four decisions, one verified chain.

Limits

What the gateway does not cover.

Be exact about this in your threat model.

Calls that don't route through it

Direct upstream entries left in a client config, editor built-in tools, unwrapped callables and arbitrary subprocesses are outside the boundary.

General network egress

The gateway speaks MCP. Setting HTTP_PROXY does not route ordinary agent traffic through its policy engine.

Authentication

It does not replace MCP authentication or the server's own credential checks. It adds a per-call decision on top of them.

Prompt injection itself

It does not detect injected instructions. It limits what an injected agent can get the servers to do. The AI agent authorization walkthrough shows the same rules applied to non-MCP calls.

Live policy reload

Rules are chosen when the gateway starts. Plan a controlled restart after a policy change.

Deployment checklist

Putting an MCP security gateway in front of your servers.

Ten steps. The full command reference is in the MCP guide.

Inventory your MCP servers

Run npx @cirvix_ai/agent-control scan. It reads known client configs and flags mcp-broad-scope, mcp-inline-secrets and mcp-duplicated. A server with filesystem scope / is the first one to put behind policy; see broad filesystem scope.

Move upstreams into their own file

Copy the server entries into mcp-upstreams.json. The gateway accepts mcpServers, servers or a bare map, with command/args/env for stdio or url/headers for HTTP upstreams. Never point the gateway at the client's own gateway-only file.

Install the CLI globally

npm install -g @cirvix_ai/agent-control. A project-local install is generally not on your editor's PATH, so the client could not launch cirvix.

Make the gateway the only server the client launches

Replace the client's server map with the single cirvix entry and absolute paths. Any direct upstream entry left behind is an ungoverned route.

Write rules per server and per tool

Scope permits with mcp.server and mcp.tool. Unlisted tools on listed servers, and every tool on unlisted servers, fall through to default deny.

Hold the writes that matter

Merges, pushes, migrations, payments: use hold with named approvers rather than a blanket permit or a blanket deny.

Validate and test before restarting

Run cirvix policy check and cirvix policy test. Gateway rules are loaded once at startup, so restart the client deliberately after a policy change.

Prove routing with real calls

From the client, make one call you expect to pass and one you expect to be refused. Then cirvix logs and cirvix audit verify: expect both decision IDs and a non-zero record count. Starting the gateway is not proof that the client uses it.

Keep HTTP mode on loopback

cirvix gateway --http --host 127.0.0.1 --port 8787 serves Streamable HTTP. Do not expose an unauthenticated gateway on a public interface; non-loopback use needs a token and a reviewed TLS and network boundary.

Cover what the gateway can't see

Built-in editor tools and subprocesses are outside the boundary. Restrict them with host and editor permissions, and wrap any non-MCP tools you own with guard.wrap.

FAQ

MCP security gateways, asked directly.

Short answers.

What is an MCP security gateway?

A process that sits between an MCP client and its upstream MCP servers, presents itself to the client as a single server, and evaluates each tools/call against policy before forwarding it. Cirvix runs one locally with cirvix gateway.

Is an MCP gateway the same as MCP authentication or OAuth?

No. Authentication establishes who is on each side of a connection and which credentials a server accepts. A gateway decides whether each specific call may execute. You want both: authentication on the connection, authorization on every call.

Can I just use an HTTP proxy for MCP security?

Not for stdio servers, which never touch the network, and not for decisions about tool arguments, which a network proxy sees only as bytes. The Cirvix gateway speaks MCP; it is not an HTTP_PROXY egress proxy and does not govern ordinary agent HTTP traffic.

Does the gateway protect editor built-in tools?

No. Every governed agent action routed through Cirvix is evaluated before execution, and built-in editor tools, direct upstream entries and arbitrary subprocesses do not route through the gateway. Use host permissions for those, and guard.wrap for tools you own.

How do I know my client is actually using the gateway?

Remove every direct upstream entry from the client config, generate a benign call and a call you expect to be denied, then run cirvix logs and cirvix audit verify. You should see both decision IDs and a non-zero record count.

Next step

Put one MCP server behind the gateway.

Start with the server that has the broadest scope, watch the first deny land, then expand. The MCP guide walks through install, connect, policy, test and verify.

Read the MCP guide →Runtime authorization guide MCP security overview

Originally published on cirvix.com. Cirvix is open source: try it locally with npx @cirvix_ai/agent-control scan or see github.com/CIRVIX/agent-control.

AI Agent Authorization: Control What Agents Can Do

Umang Kumar — Fri, 09 Oct 2026 08:22:31 +0000

AI agent authorization decides whether a specific agent may take a specific action on a specific resource, in the current context, before the action runs. Credentials say what an agent can reach. Authorization says what it may do with that reach, one call at a time. Below is a worked policy and six real requests traced to their verdicts.

4 inputs: agent · action · resource · context

3 verdicts: permit / hold / deny

Default deny: rule: null

Remediation: agents can re-plan

The gap

Credentials grant reach. Nobody is deciding use.

Most agents run with someone else's permissions and no per-call decision at all.

When you start a coding agent, it inherits your shell, your cloud profile, your SSH keys and your repository access. When you connect it to an MCP server, every tool on that server becomes available to every prompt the agent reads. The question "should this particular call happen?" is never asked. If the call is technically possible, it runs.

That is fine until the agent reads a poisoned pull request title, misunderstands a task, or chains two harmless steps into a harmful one. At that point the only thing standing between the model's choice and the side effect is whatever you configured weeks ago. AI agent authorization adds the missing step: a deterministic decision on each call, made outside the model, that the model cannot argue with.

Mechanism	Granted to	Decides per call?	Sees resource and context?
API key / OAuth scope	A credential	No	No
RBAC role	An identity	No	Rarely
System-prompt rules	The model	The model decides	Only as text it can be talked out of
Agent authorization policy	Each agent, each call	Yes	Yes

Identity still matters: a policy can only scope by agent if each agent has a distinct name rather than a shared key. Our page on agent IAM covers that half.

The model

Four inputs, three verdicts.

Cirvix rules match on exactly the things an authorization decision needs.

Agent

Who is asking. Rules use the agents glob. One permit for release-bot says nothing about pr-triage.

Action

What kind of operation: fs.read, k8s.apply, db.migrate. Tool names are classified into actions heuristically; unknown tools keep a mcp.<server>.<tool> or tool.<name> identity, so you can always target one tool by name.

Resource

What the action touches, canonicalized before matching so traversal, relative paths and case differences resolve to one value.

Context

Conditions in when: environment, path.insideWorkspace, egress.external, egress.allowlisted, session.touchedSecret, mcp.server, mcp.tool. Conditions are data, never code.

Every request resolves to one verdict. Permit lets the call run. Hold refuses it until a named approver signs off. Deny refuses it, with a reason and a remediation. Precedence is fixed: forbid beats hold, hold beats permit, and no match is a deny. The full grammar is on the policy engine page.

Walkthrough

Six requests, one policy, every verdict explained.

A release agent that may read the repo, deploy to staging on its own, and deploy to production only with approval.

cirvix.policy.jsonjson

{
  "rules": [
    { "name": "deny-dotenv-read", "effect": "forbid",
      "actions": ["fs.*"], "resources": ["**/.env", "**/.env.*"],
      "reason": "Reading .env files is denied outside an approved secrets flow.",
      "remediation": "Request the deploy token as a secret handle." },

    { "name": "deny-egress-after-secret", "effect": "forbid",
      "when": [
        { "path": "session.touchedSecret", "op": "eq", "value": true },
        { "path": "egress.external", "op": "eq", "value": true },
        { "path": "egress.allowlisted", "op": "eq", "value": false }
      ],
      "reason": "This session has read secret material; external egress is closed." },

    { "name": "hold-prod-deploys", "effect": "hold",
      "agents": ["release-bot"], "actions": ["k8s.apply"],
      "when": [{ "path": "environment", "op": "eq", "value": "production" }],
      "approvers": ["release-managers"],
      "reason": "Production deploy. A release manager must approve." },

    { "name": "allow-staging-deploys", "effect": "permit",
      "agents": ["release-bot"], "actions": ["k8s.apply"],
      "when": [{ "path": "environment", "op": "eq", "value": "staging" }] },

    { "name": "allow-workspace-read", "effect": "permit",
      "actions": ["fs.read", "fs.list"],
      "when": [{ "path": "path.insideWorkspace", "op": "eq", "value": true }] }
  ]
}

#	Request	Verdict	Deciding rule	Why
1	`release-bot` · `fs.read` · `src/app.ts`	PERMIT	`allow-workspace-read`	The canonical path resolves inside the workspace and no forbid or hold matches.
2	`release-bot` · `fs.read` · `.env.production`	DENY	`deny-dotenv-read`	The file is inside the workspace, so the permit also matches, but forbid always wins. The agent receives the remediation and can ask for a handle instead.
3	`release-bot` · `k8s.apply` · `production/checkout` · env `production`	HOLD	`hold-prod-deploys`	Consequential and environment-specific. The call is refused pending approval by `release-managers`.
4	`release-bot` · `k8s.apply` · `staging/checkout` · env `staging`	PERMIT	`allow-staging-deploys`	Same action, different context, different answer. This is the decision a static scope cannot make.
5	`pr-triage` · `k8s.apply` · `staging/checkout` · env `staging`	DENY	none (`rule: null`)	The permit names `release-bot` only. Nothing matches another agent, so default deny applies.
6	`release-bot` · outbound POST to `https://paste.example.net`, after reading `deploy/token.txt`	DENY	`deny-egress-after-secret`	Reading a file whose path looks like a token sets `session.touchedSecret`, which never resets for the session. Each call was fine alone; the sequence is not.

Three lessons fall out of the table. First, the order you write rules in does not create holes: row 2 shows a broad permit losing to a narrow forbid. Second, context, not the tool, carries the risk: rows 3 and 4 are the same tool call with different answers. Third, default deny is what keeps a policy small: you never had to write "pr-triage may not deploy" for row 5 to be refused.

Test an action

Reproduce the walkthrough yourself.

No account, no agent, nothing executed. check evaluates one hypothetical call.

Terminalbash

# Reproduce rows 1-5 with the policy saved as cirvix.policy.json. Nothing executes.
P="--policy cirvix.policy.json"
npx @cirvix_ai/agent-control check $P --agent release-bot --action fs.read   --resource src/app.ts
npx @cirvix_ai/agent-control check $P --agent release-bot --action fs.read   --resource .env.production
npx @cirvix_ai/agent-control check $P --agent release-bot --action k8s.apply --resource production/checkout --env production
npx @cirvix_ai/agent-control check $P --agent release-bot --action k8s.apply --resource staging/checkout --env staging
npx @cirvix_ai/agent-control check $P --agent pr-triage   --action k8s.apply --resource staging/checkout --env staging
# Add --json to any line for the full decision record, including the "considered" trace.

check exits 1 on deny and 0 on permit or hold, so do not treat a zero exit as permission. It also builds a deliberately minimal context, with egress.* and session.touchedSecret set to false, which is why row 6 belongs in a test that passes context explicitly:

policy.test.mjsjavascript

// policy.test.mjs  —  run with: node --test policy.test.mjs
import test from "node:test";
import assert from "node:assert/strict";
import { evaluate } from "@cirvix_ai/agent-control/testing";

test("production deploys by release-bot are held", async () => {
  const d = await evaluate({ policyFile: "cirvix.policy.json", agent: "release-bot",
    action: "k8s.apply", resource: "production/checkout",
    context: { environment: "production" } });
  assert.equal(d.verdict, "hold");
  assert.deepEqual(d.approvers, ["release-managers"]);
});

// Row 6 needs session context, which `check` always sets to false.
// The rule matches on context, so the action name here is illustrative.
test("no external egress after a secret was read", async () => {
  const d = await evaluate({ policyFile: "cirvix.policy.json", agent: "release-bot",
    action: "http.post", resource: "https://paste.example.net/upload",
    context: { session: { touchedSecret: true }, egress: { external: true, allowlisted: false } } });
  assert.equal(d.verdict, "deny");
  assert.equal(d.rule, "deny-egress-after-secret");  // not just default deny
});

At runtime

What the agent experiences.

Enforcement only counts if the agent's calls actually pass through it.

A deny is a structured error

Through guard.wrap, a denied call throws CirvixDenied carrying the rule name and a decision ID, and the tool function is never invoked. The remediation text is what lets the agent re-plan instead of retrying the same call.

A hold is not a failure

SDKs raise a distinct CirvixHeld. An approver reviews pending calls with cirvix approvals; approval records a single-use grant for a later retry. Nothing resumes automatically, and local approval records name a reviewer rather than carrying an authenticated signature.

Every decision can be recorded

With an audit sink configured, decisions land in a SHA-256 hash-chained log. cirvix why <decision-id> explains one decision, and cirvix audit verify checks the chain's internal consistency.

Routing is your job

Register the returned wrapped tools with your framework, and make the MCP gateway the only server your client launches. Every governed agent action routed through Cirvix is evaluated before execution; a tool the agent reaches directly is not.

Pitfalls

Four ways agent authorization quietly fails.

Wrapping tools but registering the originals

The executor keeps calling unwrapped functions and nothing is enforced. Check by triggering a known deny.

Leaving a direct MCP entry next to the gateway

The agent has two routes and only one is governed. Remove upstream entries from the client config.

Writing rules against raw strings

Cirvix canonicalizes resources, but your globs still need to match the canonical form. Inspect check --json output to see the resource the engine compared.

Holds with nobody to approve them

validateRules flags a hold without approvers. A hold nobody watches becomes a deny that frustrates users into loosening policy.

FAQ

AI agent authorization, asked directly.

Short answers.

What is AI agent authorization?

Deciding whether a specific AI agent may perform a specific action on a specific resource in the current context, and enforcing that decision before the action runs. It is narrower than authentication, which establishes who is calling, and finer-grained than the scopes on the agent's credentials.

Why aren't OAuth scopes enough to authorize an agent?

Scopes are granted to a credential once and apply to every call made with it. They cannot see the resource of a single call, the environment, or what the agent did earlier in the session. Agent authorization evaluates each call with that context.

What should happen when an agent is denied?

The agent should get a structured refusal it can act on: the rule that matched, a reason and a remediation that names the legitimate path. Cirvix SDKs raise CirvixDenied for a deny and a distinct CirvixHeld for a hold, so an agent does not abandon work a person is about to approve.

How do I test an authorization rule without running the agent?

Use npx @cirvix_ai/agent-control check --action <action> --resource <resource> for a single hypothetical call, and evaluate() from @cirvix_ai/agent-control/testing inside node --test for assertions in CI. Neither executes a tool.

Does Cirvix authorize every action an agent takes?

Every governed agent action routed through Cirvix is evaluated before execution. That means calls made through the returned SDK wrappers, the MCP gateway or the local control socket. Editor built-in tools, unwrapped functions and arbitrary subprocesses are outside the boundary.

Try it on your own action

Pick the call you are most nervous about. Test it.

Run npx @cirvix_ai/agent-control check against the action your agent should never take unattended, then put that agent's tools behind policy.

Test an action →Read the quickstart Pricing

Originally published on cirvix.com. Cirvix is open source: try it locally with npx @cirvix_ai/agent-control scan or see github.com/CIRVIX/agent-control.

Runtime Authorization for AI Agents: A Practical Guide

Umang Kumar — Fri, 09 Oct 2026 08:21:56 +0000

Runtime authorization for AI agents is a decision made on every tool call, after the agent proposes it and before it runs: may this agent perform this action on this resource, here, now? This guide covers what that decision needs, where to enforce it, and a checklist for putting your first agent under policy with Cirvix.

PERMIT / HOLD / DENY: one verdict per call

Default deny: no rule, no execution

Forbid wins: permits can't override

Apache-2.0: runs locally

Definition

What runtime authorization means for an agent.

Capability is not authority. An agent that can call a tool has not been authorized to call it with these arguments.

An AI agent turns text into consequences: it reads files, queries databases and calls MCP tools and APIs, usually with the credentials of whoever launched it. Most stacks decide what an agent may touch once, at configuration time. After that, every individual call is trusted by default.

Runtime authorization moves the decision to the moment of action. The agent proposes a structured request (who is asking, which action, which resource, in what context), a deterministic policy engine evaluates it, and the tool runs only if the verdict allows it. With Cirvix, every governed agent action routed through Cirvix is evaluated before execution, and the decision can be recorded in a SHA-256 hash-chained audit log.

Control	When it decides	What it sees	What it can't do
Authentication / IAM	When a credential is issued	Identity and scopes	Judge a single call's resource or context
Prompt guardrails	When text goes in or out of the model	Text	Stop a tool call the model has already chosen
Post-hoc monitoring	After execution	Logs	Undo a side effect
Runtime authorization	Before each governed call executes	Agent, action, canonical resource, context	Evaluate calls that bypass its enforcement point

These layers compose. Keep IAM and prompt defenses, and add runtime authorization where side effects happen. The category overview is on the AI-agent security page.

Why runtime

Why the decision has to happen at runtime.

Three properties of agents break configuration-time permissions.

Agent inputs are untrusted by design

Pull request titles, web pages, documents and tool results can all carry instructions the model will follow. You cannot vet the inputs, so you have to evaluate the actions they produce.

The same tool means different things in different contexts

Writing a file in a scratch workspace is routine. Applying a manifest in production is not. A static grant cannot tell the two apart; a rule with a when condition on environment can.

Harm comes from sequences

Reading a credential and making an outbound request are each ordinary. Together they are exfiltration. Cirvix tracks session.touchedSecret, so the starter rule deny-external-egress-after-secret refuses external egress for the rest of a session that has read secret-shaped material.

Anatomy

Anatomy of one decision.

Request in, canonical resource, ordered rules, exactly one verdict, an explanation out.

Each request carries an agent name, an action such as fs.read or k8s.apply, a resource, and context (environment, whether the path is inside the workspace, whether the session has touched a secret, which MCP server and tool). Before any rule is compared, the resource is canonicalized: ./x/../.env, .env and an absolute path to the same file become one resource.

Then precedence does the rest:

Forbid always wins

A matching forbid short-circuits evaluation. No permit, however specific, overrides it.

Hold outranks permit

If any rule says a human must see this call, another permissive rule cannot skip that person.

Permit allows the call

Only an explicit permit lets the call run.

No match means deny

A request that matches nothing is denied with rule: null. An empty rule set denies everything, so a policy that fails to load fails closed.

The output is a decision record, not a boolean: considered traces the rules examined, and remediation gives the agent a legitimate path so it can re-plan instead of retrying.

Decision returned by evaluate()json

{
  "verdict": "deny",
  "rule": "deny-dotenv-read",
  "reason": "Reading .env files is denied outside an approved secrets flow.",
  "remediation": "Ask for the value as a secret handle instead.",
  "considered": [
    { "rule": "deny-dotenv-read", "effect": "forbid", "matched": true }
  ],
  "resource": "/workspace/.env.production"
}

Enforcement points

Where to enforce it.

A decision nobody enforces is a log line. Cirvix enforces at three points, and each has an edge.

Enforcement point	Use it when	Boundary
`guard.wrap` (Node or Python SDK)	You own the agent's tool functions	Only the returned wrapped tools. Originals still held by an executor are not governed.
`cirvix gateway`	The agent uses MCP servers (Claude Code, Cursor, any MCP client)	Only `tools/call` requests routed through the gateway. Direct upstream entries and editor built-ins are outside it.
`cirvix runtime` control socket	A cooperating client speaks the local protocol	Only clients that use the socket. Starting it does not instrument an existing agent.

Cirvix does not intercept all activity on a machine. Subprocesses, unwrapped callables and host processes stay outside the boundary, so host permissions still matter. The smallest in-process example, where the denied call never reaches the tool function:

guard.wrap: enforce in-processjavascript

import { readFile } from "node:fs/promises";
import { guard, CirvixDenied, STARTER_RULES } from "@cirvix_ai/agent-control";

// Register the RETURNED tools with your agent's executor, not the originals.
const tools = guard.wrap(
  { read_file: async ({ path }) => readFile(path, "utf8") },
  { agent: "pr-triage", rules: STARTER_RULES },
);

await tools.read_file({ path: "src/index.mjs" });      // runs
try {
  await tools.read_file({ path: ".env.production" });  // refused before the tool is invoked
} catch (err) {
  if (!(err instanceof CirvixDenied)) throw err;
  console.log(err.policy, err.decisionId);             // "deny-dotenv-read", "dec_..."
}

Artifact

A starter policy for a coding agent.

Two prohibitions, one hold, one scoped permit. Everything else is denied by default.

cirvix.policy.jsonjson

{
  "rules": [
    {
      "name": "deny-dotenv-read",
      "effect": "forbid",
      "actions": ["fs.read", "fs.*"],
      "resources": ["**/.env", "**/.env.*"],
      "reason": "Reading .env files is denied outside an approved secrets flow.",
      "remediation": "Ask for the value as a secret handle instead."
    },
    {
      "name": "deny-workspace-escape",
      "effect": "forbid",
      "actions": ["fs.*"],
      "when": [{ "path": "path.insideWorkspace", "op": "eq", "value": false }]
    },
    {
      "name": "hold-prod-deploys",
      "effect": "hold",
      "actions": ["k8s.apply", "db.migrate"],
      "when": [{ "path": "environment", "op": "eq", "value": "production" }],
      "approvers": ["platform-oncall"],
      "reason": "Production change. Held for a named approver."
    },
    {
      "name": "allow-workspace-read-write",
      "effect": "permit",
      "actions": ["fs.read", "fs.list", "fs.write"],
      "when": [{ "path": "path.insideWorkspace", "op": "eq", "value": true }]
    }
  ]
}

Read it top to bottom the way the engine does. A read of config/.env.local matches deny-dotenv-read and is denied even though allow-workspace-read-write would also match. A write to a file outside the workspace root is denied by deny-workspace-escape. A k8s.apply with --env production is held for platform-oncall. An outbound HTTP request, or any action you have not named, matches no rule and is denied with rule: null until you write a permit for it. The full rule grammar, including all when operators, is on the policy engine page.

Deployment checklist

Putting your first agent under runtime authorization.

Eight steps, in order. Each one has a check you can run.

Inventory what you are about to govern

Run npx @cirvix_ai/agent-control scan, a local, heuristic inventory of agent runtimes, MCP configs and reachable credential paths (findings such as runtime-ungoverned and mcp-broad-scope). Treat it as a map, not proof of what a running agent can do.

Pick one agent and one enforcement point

Start with a single agent: guard.wrap if you own its tool code, cirvix gateway if it uses MCP servers.

Start from the starter rules, then narrow

With no workspace policy, Cirvix falls back to nine starter rules (print them with cirvix policy --json). Copy what you need into cirvix.policy.json and add the rules specific to this agent's job. Rule names appear in every decision, so make them meaningful.

Validate and test the policy like code

Run cirvix policy check --policy cirvix.policy.json, then write tests with evaluate() from @cirvix_ai/agent-control/testing and run them with node --test in CI. Assert the denials and holds you care about, not only the happy path. For policy pull requests, expectNoLoosening from the same module compares a before and after rule set.

Wire enforcement so there is no side door

Hand the framework the returned wrapped tools. For MCP, keep upstreams in a separate mcp-upstreams.json and make the gateway the only server the client launches. A direct upstream entry left in the client config is an ungoverned route.

Give every hold a named approver

Use hold for consequential actions such as production deploys, migrations and deletes. validateRules flags a hold without approvers. Approvals are local records that authorize a retry; they are not authenticated signatures, and nothing resumes on its own.

Turn on a record and verify it

Supply an AuditChain sink (Node) or an on_decision callback (Python). Generate a benign allowed call and a denied one, then run cirvix audit verify and cirvix logs. Confirm the expected decision IDs and a non-zero record count, because an empty or missing file verifies as an empty chain.

Expand one rule at a time

Add the next agent or tool once the first runs cleanly. Because forbid always wins, a new permit cannot open a hole through an existing prohibition.

Try it

Test a decision before you install anything.

check evaluates one hypothetical call. It reads no file, runs no tool and writes no audit record.

Terminalbash

# Node 20+. No account. Nothing is read or executed by `check`.
npx --yes @cirvix_ai/agent-control check --action fs.read --resource .env.production
#   DENY  fs.read /workspace/.env.production
#   rule    deny-dotenv-read

npx @cirvix_ai/agent-control check --action fs.read --resource src/index.mjs
#   PERMIT  fs.read /workspace/src/index.mjs
#   rule    allow-workspace-read          (exit 0)

# With the policy above, a production deploy is held, not run:
npx @cirvix_ai/agent-control check --policy cirvix.policy.json \
  --action k8s.apply --resource production/checkout --env production
#   HOLD  k8s.apply /workspace/production/checkout
#   rule    hold-prod-deploys
#   waits   platform-oncall                (exit 0: a hold is not permission)

Note the exit codes: check exits 1 on deny and 0 on both permit and hold, so exit status alone is not authorization to execute. When you are ready to enforce, install the package with npm install @cirvix_ai/agent-control (or pip install cirvix for the Python evaluator) and follow the quickstart. For MCP clients, the MCP guide and our article on where to put the MCP authorization boundary cover the gateway setup.

Honest limits

What runtime authorization does not do.

Stated plainly so you can design around it.

It does not prevent prompt injection

It limits what a manipulated agent is permitted to do afterward.

It cannot evaluate what it never sees

Coverage is exactly the set of calls routed through the wrappers, the gateway or the socket. Remove alternate routes.

It honours the policy you wrote

A permissive rule is applied as written. Test rules in CI.

The audit chain is tamper-evident, not tamper-proof

SHA-256 chaining detects internal inconsistencies. Detecting tail deletion or a fully recomputed history needs a trusted external checkpoint. A record shows authorization, not that the tool succeeded.

FAQ

Runtime authorization, asked directly.

Short answers.

What is runtime authorization for AI agents?

A per-action decision, made on the execution path, about whether a specific agent may perform a specific action on a specific resource in the current context. The decision happens after the agent proposes the call and before the tool runs, so a refused action never produces a side effect.

How is runtime authorization different from API scopes or IAM roles?

Scopes and roles are granted once, at configuration time, to a credential. Runtime authorization is evaluated on every call, with the resource and context of that call. The two compose: IAM decides which credentials exist; runtime authorization decides whether this use of them may run now.

Does runtime authorization stop prompt injection?

No. Injection happens in text the model reads, and Cirvix does not detect it. Runtime authorization limits what a manipulated agent can do next: the harmful tool call it attempts is still evaluated against policy and can be denied or held.

Does Cirvix see everything an agent does?

No. Every governed agent action routed through Cirvix is evaluated before execution. Calls that do not pass through the returned SDK wrappers, the MCP gateway or the local control socket, such as editor built-in tools or arbitrary subprocesses, are outside that boundary.

What does it cost to try?

The local engine is Apache-2.0 and the free tier needs no account: one governed agent and 100 policy decisions a day. npx @cirvix_ai/agent-control scan and check run locally. Paid tiers and the hosted control plane are in early access.

Start where you are

Put one agent under policy today.

Run the free local scan with no account, test a decision with check, then wrap one agent's tools.

Read the quickstart →AI agent authorization walkthrough Pricing

Originally published on cirvix.com. Cirvix is open source: try it locally with npx @cirvix_ai/agent-control scan or see github.com/CIRVIX/agent-control.

DEV Community: Umang Kumar

Hash-chained audit logs for AI agent actions, in 40 lines

The entry shape

The logger

How to verify

Two things the chain doesn't do

Where to put it

Securing MCP servers: a practical checklist for 2026

Tool-definition drift

Over-broad filesystem tools

Secrets in the environment

Egress allowlists

Audit logging

Checklist

Why approval prompts don't work as a security boundary for coding agents

Approval fatigue

Approvals that never expire

Stale pending approvals

A better shape: expiring HOLD approvals bound to the exact action hash

What changes for the agent

What doesn't change

5 permission rules every coding agent should ship with

1. Deny reads of .env and credential files

2. HOLD destructive shell in production

3. Deny force-push

4. Keep writes inside the workspace

5. Make approvals expire

Try it

Stop the read-then-exfiltrate chain: session taint for AI agents

Why per-call rules are not enough

Session taint: one bit, set once

What the agent sees

Secret handles do not taint

Honest limits

Try it

MCP Security: Where to Put the Authorization Boundary

Five places you could enforce. One that works.

What a gateway at the seam can do that nothing else can.

Evaluate before forwarding

Keep servers apart

Pin tool definitions

Return denials the agent can read

Record one chain for every server

The artifact: a gateway in front of two servers.

Four calls through the gateway.

What the gateway does not cover.

Calls that don't route through it

General network egress

Authentication

Prompt injection itself

Live policy reload

Putting an MCP security gateway in front of your servers.

Inventory your MCP servers

Move upstreams into their own file

Install the CLI globally

Make the gateway the only server the client launches

Write rules per server and per tool

Hold the writes that matter

Validate and test before restarting

Prove routing with real calls

Keep HTTP mode on loopback

Cover what the gateway can't see

MCP security gateways, asked directly.

What is an MCP security gateway?

Is an MCP gateway the same as MCP authentication or OAuth?

Can I just use an HTTP proxy for MCP security?

Does the gateway protect editor built-in tools?

How do I know my client is actually using the gateway?

Put one MCP server behind the gateway.

AI Agent Authorization: Control What Agents Can Do

Credentials grant reach. Nobody is deciding use.

Four inputs, three verdicts.

Agent

Action

Resource

Context

Six requests, one policy, every verdict explained.

Reproduce the walkthrough yourself.

What the agent experiences.

A deny is a structured error

1. Deny reads of `.env` and credential files