← All docs

AI agent security guide

Map a coding agent's permissions, enforce boundaries outside the model, and test the controls that limit mistakes.

By The agentjail team
The lower layers still work when the model makes a bad decision.
A layered AI agent security model from the prompt through policy, sandboxing, scoped access, and logs.

The lower layers still work when the model makes a bad decision.

An AI coding agent does more than generate text. It reads files, runs commands, installs packages, calls APIs, and changes systems that matter. AI agent security is the work of deciding which of those actions are possible, then enforcing that decision outside the model.

The model is part of the application. It should not also be the final security boundary for the application.

Start with the agent’s real permissions

Forget the prompt for a minute. Ask what the agent can reach from the process where it runs:

  • Which files can it read and write?
  • Which shell commands can it execute?
  • Which MCP servers and tools can it call?
  • Which hosts can it contact?
  • Which cloud, database, package, and source-control credentials are present?
  • Can it publish, deploy, delete, or transfer anything?

That list is the practical attack surface. If the agent can reach a production database, a prompt saying “never modify production” does not remove the access.

Five boundaries worth enforcing

1. Tool calls

Intercept the action before it runs. Evaluate structured details such as the tool name, command, file path, MCP server, and MCP tool.

A useful policy has three outcomes:

  • allow for routine, low-risk work;
  • ask when human context is genuinely needed;
  • deny for actions that should not happen in that environment.

This is more practical than asking for approval on everything. Constant prompts train people to click through without reading.

2. The operating system

Tool-call policy sees the action the agent requested. An OS sandbox sees what the process actually does.

That distinction catches shell expansion, encoded commands, helper scripts, and child processes that do not look like the original request. On supported systems, agentjail uses Seatbelt on macOS and Landlock on Linux so subprocesses inherit the filesystem boundary.

Read the Claude Code sandbox guide for a concrete setup, or the sandbox reference for the full platform behavior.

3. Credentials

An agent cannot leak a credential it cannot read. Keep standing credentials out of the session, then scope the remaining ones to the smallest useful role.

Good defaults include:

  • separate identities for agents;
  • short-lived tokens;
  • repository or project scope instead of organization scope;
  • read-only database users for inspection;
  • staging credentials for tests;
  • no private keys or cloud credentials inside the working tree.

Credential scope is still useful when every other control works. It becomes essential when one of them does not.

4. Network access

Most coding agents need some network access. They do not need arbitrary egress.

Allow the model provider, source host, and package registries the job requires. Add internal or deployment hosts only for tasks that need them. For unattended work, make the allowlist part of the job definition instead of a machine-wide exception.

5. MCP and external tools

An MCP tool can turn a text instruction into a repository change, database query, message, or deployment. Inventory servers, review their credentials, and set policy per tool instead of trusting an entire server at once.

See the MCP security guide for a review checklist and working configuration.

A practical baseline for coding agents

You can apply a useful baseline without designing a security program first.

Install agentjail and wire the supported agent hooks:

curl -fsSL https://agentjail.io/install.sh | sh

Check what is active:

agentjail status
agentjail policy list
agentjail mcp scan
agentjail doctor

Launch the agent through the OS sandbox:

agentjail run -- claude
agentjail run -- codex
agentjail run -- cursor

Then test the boundary with calls you expect to allow, ask about, and deny. A policy that has never been tested is still an assumption.

What to deny and what to ask about

Hard denials should cover actions whose cost is obvious and whose legitimate use is rare in the current environment. Examples include reading SSH private keys, overwriting block devices, disabling the security daemon, and deleting a repository through an MCP tool.

Use ask for actions that may be legitimate but deserve context:

  • pushing code;
  • publishing a package;
  • creating a repository;
  • writing outside the project;
  • contacting a new external host;
  • accessing a production-adjacent system.

Keep routine reads, tests, builds, and edits inside the project quiet. Security that interrupts every harmless action will eventually be bypassed.

Prompt injection changes the path, not the answer

An agent can encounter hostile instructions in source files, issues, web pages, dependency documentation, and tool output. Better prompting may reduce how often the model follows those instructions. It cannot guarantee that the model will always distinguish trusted intent from untrusted text.

The durable answer is to limit the actions available after the model makes a bad decision. Prompt controls reduce bad requests. Policy, sandboxing, credentials, and network restrictions reduce what those requests can do.

Keep an audit trail you can use

Record the requested action, final verdict, matching rule, agent session, and time. The log should let you answer:

  • What did the agent try?
  • What actually ran?
  • Which rule allowed or blocked it?
  • Who approved an ask decision?
  • Which repository and session were involved?

Audit data is useful for incident response, but it is also how you improve the policy. Repeated harmless denials point to a bad rule. Repeated approvals may belong in an allow rule. A surprising allowed action deserves a new boundary.

Security is a stack, not a feature switch

No single control handles every failure mode. A reasonable stack looks like this:

  1. Prompts steer the model away from unsafe choices.
  2. Tool policy checks the proposed action.
  3. Human approval handles ambiguous, consequential calls.
  4. The OS sandbox contains the process and its children.
  5. Credential scope limits the authority behind a successful call.
  6. Network policy limits where data and commands can travel.
  7. Logs make the result reviewable.

Start with the boundaries closest to your largest risk. If the agent works near production credentials, fix credential exposure first. If developers install MCP servers freely, inventory and gate those tools first. If agents run unattended, prioritize sandboxing, egress controls, and tested deny rules.

The useful question is not “is this agent safe?” It is “what can this agent do when it is wrong?”

Next steps