ranwhat GitHub

Part of the AI coding agent security checklist

A secure-by-default AI coding agent setup

Secure by default means the safe behaviour is the one you get without doing anything, and the risky one needs a deliberate step. Coding agents do not start that way. This guide lists the settings and habits that move them closer.

$ uvx ranwhat check
Install

Checked against Claude Code's documentation under Sources and ranwhat's source. Published .

01 / Meaning

What secure by default means for an agent

An agent starts with whatever your account can do: your files, your shell, your tokens. Nothing in that is wrong by itself. The risk is that the agent reads text you did not write and acts on it. OWASP's advice for that is to give the model least privilege, require human approval for high-risk actions, and treat the model as an untrusted user. Secure by default is those three, set up once, so you are not relying on a prompt.

Fail closed Network reach starts empty and you add the few hosts the work needs, rather than starting open and removing the bad ones.
Hold less The agent gets tokens scoped to its task. What it never holds, a hijacked session cannot use.
Look afterwards Prevention fails sometimes, so keep a record that you can read back.
02 / File

The settings to start from

This is one ~/.claude/settings.json that combines the deny rules and the sandbox from the prompt injection guide. Adjust the hosts and paths to your own work.

~/.claude/settings.json
{
  "permissions": {
    "deny": ["Bash(curl *)", "Bash(wget *)", "Read(./.env)", "Read(~/.aws/**)"],
    "disableBypassPermissionsMode": "disable"
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "strictAllowlist": true
    }
  }
}
Deny rules Rules run deny, then ask, then allow, and the first match wins. A deny cannot be undone by a broader allow. A Bash rule matches the command text Claude writes and is not a boundary around the program, so it complements the sandbox and does not replace it.
The sandbox Enforced by the operating system, on macOS, Linux and WSL2. It limits which files shell commands can reach and routes their network traffic through a proxy that checks each host against network.allowedDomains, which starts empty. Native Windows runs commands unsandboxed, so use WSL2.
What it does not cover The built-in Read, Edit and Write tools follow permission rules and not the sandbox. Hooks and local MCP servers run with your full access.
Bypass mode disableBypassPermissionsMode stops the prompt-skipping mode. Use that mode only inside a container or VM that holds nothing you care about.

The reasoning behind each line is in prompt injection in coding agents and blocking .env reads.

03 / Credentials

Give it less to steal

A command the agent runs can use every token in its environment and on disk. Make that set small.

Its own token Create one for the agent, with only the scopes the task needs and an expiry date, instead of lending it your admin key. See token scopes for AI agents.
Keep secrets out of reach Keep .env files and cloud credentials out of the project the agent works in where you can, and deny the reads you cannot move.
Assume exposure A secret that entered the agent's context counts as exposed. Rotate it. The rotation guide goes provider by provider.
04 / Tools

Review what you plug in

Every MCP server and every hook is a program that runs for the agent, and neither one is limited by the sandbox.

MCP servers Claude Code's security page says Anthropic does not security-audit or manage MCP servers. Read the configuration, approve only the servers you know, and scope their tokens. See MCP server security.
Hooks A hook is the one place you can block a call before it runs, and it is also code with your full access. Write them yourself or read them first. See Claude Code hooks for security.
Cloned repositories A repository can carry its own settings and hooks. Look at .claude/ in a repository you have just cloned before you open it with an agent.
05 / Record

Keep a record you can read

The transcripts your agent writes are already an audit trail, and they expire. Claude Code's are removed after 30 days by default.

Run the check on a schedule that suits you, so that a risky action or a leaked secret is something you find in days and not never. The audit log guide covers a hook or OpenTelemetry for a record from now on, and where each agent keeps its history covers the others.

$ uvx ranwhat check
Install

ranwhat reads the history locally and flags risky actions and secrets left on disk. It does not enforce any of the settings above, and it blocks nothing unless you install its Claude Code hook. It tells you what already happened.

06 / Next

Where to go from here

The AI coding agent security checklist puts these steps in order. To check what an agent wrote, read how to check that AI-written code is secure. All guides are on the guides page.

Sources