One Allowlist for Tool Calls and File Reads

Most teams end up with two artifacts: a JSON file listing MCP servers and tools, and a separate ignore or allowlist of paths. The two drift apart, because nothing forces a new tool to state which directories it needs. The failure modes are well catalogued. A tool approved today can change tomorrow, so a sound policy hashes each server's tool manifest and forces re approval when definitions change per this tool and plugin security guide. A trusted server can still expose a destructive tool, which is why policy objects need to sit at the individual tool level rather than only at the server or agent level as Backslash Security's allowlist guidance sets out.

Putting both lists in one document does three things:

1. Every tool entry must state the scopes it needs, so a bash tool that wants the repository root cannot be added without that fact being visible in a diff.
2. One validator reads one file, so a path rule cannot be bypassed by reaching the filesystem through a tool that was never wired to the path checker.
3. Review becomes a single file to read, which matters more than it sounds: reviewers approve what they can hold in their head.

The pattern is not novel in the broader security world. Policy engines such as Open Policy Agent let you write authorization as a separate, reviewable artifact that can be tested in CI with opa test, and tool approval callbacks in agent SDKs already map a policy decision to allow, deny or requires approval as the AI SDK documentation describes. You do not need a full policy engine to start, but you do want the decision to live in a file rather than inside a function.

Below is a YAML policy that names tools, their arguments, the scopes they need, and the paths the agent may touch. It is plain data: no expressions, no templating, so a reviewer can read it without knowing the validator's internals.

policy: repo-agent
version: 1

paths:
  allow:
    - "/workspace/app/**"
    - "/workspace/docs/**"
  deny:
    - "/workspace/app/config/prod/**"
    - "**/.env"
    - "**/*.pem"
  follow_symlinks: false

tools:
  read_file:
    class: read
    args:
      - name: path
        type: path
        must_match: paths.allow
    scopes: [filesystem.read]

  list_dir:
    class: read
    args:
      - name: path
        type: path
        must_match: paths.allow
    scopes: [filesystem.read]

  write_file:
    class: write
    args:
      - name: path
        type: path
        must_match: paths.allow
    scopes: [filesystem.write]

  bash:
    class: execute
    args:
      - name: command
        type: command
        grammar: allowlist
        allow: ["git status", "git diff", "pytest", "npm test", "ls"]
    scopes: [process.execute]
    path_args: extract
    require_path_check: true

  web_fetch:
    class: network
    args:
      - name: url
        type: url
        allow_hosts: ["docs.internal.example"]
    scopes: [network.read]

Two properties are doing the heavy lifting. First, deny beats allow: a path that matches both sections is refused, which is how you keep prod config out even though it sits under an allowed directory. Second, bash declares require_path_check: true, which is the line that closes the hole most teams leave open. A shell tool can read any file the process can read; declaring that its arguments must be extracted and re checked against the path policy is what makes the shell governed by the same declaration as read_file.

The type: path versus type: command distinction is also worth guarding. Treating a free form command string as a path, or a path as a command, is exactly the sort of mismatch that lets a crafted argument slip past one checker because it was meant for the other.

The validator's job is to answer a fixed set of questions in a fixed order, and to fail closed when it cannot answer. This table is the specification you can hand to whoever writes the code.

Read the last row carefully: a tool that is absent from the document is denied, not ignored. That is the difference between an allowlist and a blocklist. A blocklist can only name components that have already been published and judged bad, and a renamed copy of a tool is on nobody's block list per Backslash Security's analysis. Default deny closes that gap by making silence mean no.

The validator has to run after the agent has decided what to call and before the system executes it. That timing is not a detail. A ban written in a system prompt only works when the model happens to read it, whereas a deny rule in the hook that fires before execution works in every mode as this write up of action class matrices argues. The two questions the hook answers are separate: is this command on the approved list (the allowlist, and the primary boundary), and does this specific invocation do something dangerous regardless of its name (the deny patterns, as defense in depth) per this pre tool hook guide.

A minimal Python validator below implements the table above. It normalizes paths with os.path.realpath so that .. segments and (when follow_symlinks is false) resolved symlinks are evaluated on the real target, then matches against the compiled globs.

import fnmatch, os, shlex

class Denied(Exception):
    pass

def norm(p, base="/workspace"):
    full = p if os.path.isabs(p) else os.path.join(base, p)
    return os.path.realpath(full)

def path_allowed(policy, raw):
    target = norm(raw)
    deny = policy["paths"]["deny"]
    allow = policy["paths"]["allow"]
    if any(fnmatch.fnmatch(target, pattern) for pattern in deny):
        return False
    return any(fnmatch.fnmatch(target, pattern) for pattern in allow)

def command_paths(command):
    tokens = shlex.split(command)
    return [t.split("=", 1)[1] for t in tokens
            if "=" in t and ("/" in t.split("=", 1)[1])]

def check(policy, tool_name, args, grant):
    tool = policy["tools"].get(tool_name)
    if tool is None:
        raise Denied(f"tool {tool_name} not declared")
    if not set(tool["scopes"]).issubset(grant):
        raise Denied(f"missing scope for {tool_name}")

    for spec in tool["args"]:
        value = args.get(spec["name"])
        if spec["type"] == "path" and not path_allowed(policy, value):
            raise Denied(f"path {value} not allowed")
        if spec["type"] == "command":
            verb = " ".join(shlex.split(value)[:2])
            if not any(verb.startswith(a) for a in spec["allow"]):
                raise Denied(f"command not allowed: {verb}")

    if tool.get("require_path_check"):
        for candidate in command_paths(args["command"]):
            if not path_allowed(policy, candidate):
                raise Denied(f"command touches {candidate}")
    return True

Two notes before you ship this. realpath resolves symlinks even when you have set follow_symlinks: false, so if you truly want to refuse symlinked paths you must compare the raw and resolved values and deny when they differ. Symlink handling is not academic: a sandbox escape was reported in which an agent inside a sandbox planted a symlink that produced read write access to an arbitrary host directory it was never given per Endor Labs' write up. Second, extracting paths from a shell command with a regular expression is a losing game. If your commands are complex, parse them with a grammar instead of a pattern, because a regex that matches git diff will miss git diff --output=... and everything after a pipe.

Suppose a monorepo agent has four declared tools and a path policy with two allowed roots. During one task it attempts 40 tool calls. Here is what an honest audit looks like.

Twenty two percent of calls were refused, and every refusal carries a reason string that names the rule. That log is the artifact your security reviewer actually wants, because it answers "was this invocation authorized for this agent, and does it deviate from baseline" rather than only "which credential acted" as this analysis of tool call visibility argues. Compare that to the alternative: 40 calls, no policy, and a review after the fact of what the agent chose to do.

The comparison also tells you where to spend effort. Three of the twenty two refusals were undeclared tools, which is a declaration hygiene problem, not an attack. Two were commands outside the grammar, which is either a missing legitimate entry or an agent improvising. Only four were genuine path violations, and those are the ones that justify the whole exercise.

That last row has a direct precedent. BeyondTrust's workflow runs a new policy in audit first, replays recorded activity to see what it would have matched, publishes it as a draft, attaches it to a test endpoint, and only then switches to block, confirming that the agent's attempt is recorded while the user's is not per their documentation. That sequence exists because policy that is not enforced inline, before execution, is documentation rather than control as Backslash Security puts it.

Drift is the quiet failure after launch. Configurations move away from the approved baseline through human error, emergency hotfixes and scripts that cannot keep up, so detection needs codified policy, runtime checks, version control and regular review per this guide to policy drift detection. For an agent policy, drift usually looks like one extra line in the file that nobody discussed. A required reviewer on that file is cheaper than any runtime product.

The validator sits between your agent and the outside world, but the model behind the agent still needs a route to every surface it uses: text for planning, image models for screenshots of a failing UI, embedding models for retrieval over docs. Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI compatible key, which means the policy file can name model scopes alongside tool scopes without a second vendor relationship.

For teams that would rather have the whole harness written than assemble it, Quanta Experts reads your repository context and returns finished work, and the skill library behind it can be installed into an existing coding agent, so the policy you just wrote can travel with the capability rather than being rewritten per tool.