# AI agent security guide

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

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](/docs/guides/claude-code-sandbox) for a
concrete setup, or the [sandbox reference](/docs/concepts/sandbox) 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](/docs/guides/mcp-security) 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:

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

Check what is active:

```sh
agentjail status
agentjail policy list
agentjail mcp scan
agentjail doctor
```

Launch the agent through the OS sandbox:

```sh
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

- [How agentjail works](/docs/concepts/how-it-works): the request, policy, and
  decision path.
- [Writing your first rule](/docs/policies/first-rule): add a boundary for your
  own environment.