A
Docs
Back to Builder

Security Guidelines

Best practices for secure agent configuration and operation.

Security is critical when building AI agents that interact with your systems. This guide covers best practices for safe agent configuration and operation.

Permission Levels

Choose the appropriate permission level for your use case:

Restrictive

Read-only access. Best for:

  • Code review and analysis
  • Research and information gathering
  • Auditing and compliance checks
  • Untrusted environments

Balanced

Read and controlled write access. Best for:

  • Development assistance
  • Documentation generation
  • Report creation
  • Most production use cases

Permissive

Full access including command execution. Best for:

  • Trusted development environments
  • Automated testing
  • Local development only

Avoid permissive in production

The permissive level enables run-command which can execute arbitrary shell commands. Use with extreme caution.

Tool Selection

Principle of Least Privilege

Only enable tools your agent actually needs:

  • Start with the minimum set of tools
  • Add tools as specific needs arise
  • Regularly audit enabled tools
  • Disable unused tools

High-Risk Tools

These tools require extra consideration:

ToolRiskConsideration
run-commandHighCan execute any shell command
write-fileMediumCan overwrite files
edit-fileMediumCan modify existing files
database-queryMediumCan execute SQL queries
api-clientMediumCan make external requests

Path Restrictions

Configure path restrictions in the permission system:

1// src/permissions.ts
2const restrictedPaths = [
3  // System directories
4  '/etc',
5  '/usr',
6  '/bin',
7  '/sbin',
8
9  // User sensitive directories
10  process.env.HOME + '/.ssh',
11  process.env.HOME + '/.aws',
12  process.env.HOME + '/.config',
13
14  // Application sensitive
15  '.env',
16  'credentials.json',
17  'secrets/',
18];

Command Restrictions

If run-command is enabled, restrict dangerous commands:

1// src/permissions.ts
2const blockedCommands = [
3  // Destructive commands
4  'rm -rf',
5  'rmdir',
6  'mkfs',
7
8  // Privilege escalation
9  'sudo',
10  'su',
11  'chmod 777',
12
13  // Network exposure
14  'nc -l',
15  'ssh-keygen',
16
17  // Sensitive data access
18  'cat /etc/passwd',
19  'cat /etc/shadow',
20];

Environment Variables

Never Commit Secrets

  • Use .env files (gitignored)
  • Use .env.example as template
  • Never hardcode API keys

Validate Environment

1// Validate required environment variables
2const requiredEnvVars = [
3  'ANTHROPIC_API_KEY', // or OPENAI_API_KEY
4];
5
6for (const envVar of requiredEnvVars) {
7  if (!process.env[envVar]) {
8    throw new Error(`Missing required environment variable: ${envVar}`);
9  }
10}

Hooks for Security

Use hooks to enforce security policies:

Block Secrets in Commits

1{
2  "name": "block-secrets",
3  "event": "PreToolUse",
4  "matcher": "Bash",
5  "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'git (commit|push)'; then git diff --cached | grep -qE '(API_KEY|SECRET|PASSWORD|TOKEN)=' && exit 1; fi",
6  "timeout": 10000
7}

Validate File Types

1{
2  "name": "validate-write",
3  "event": "PreToolUse",
4  "matcher": "Write",
5  "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(env|pem|key)$'; then exit 1; fi",
6  "timeout": 5000
7}

MCP Server Security

Use Environment Variables

Never hardcode credentials in MCP configurations:

1{
2  "env": {
3    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
4    "DATABASE_URL": "${DATABASE_URL}"
5  }
6}

Audit Server Permissions

MCP servers may have their own permissions. Verify:

  • What data the server can access
  • What actions it can perform
  • Whether it requires network access

Audit and Monitoring

Log Tool Usage

Track what tools are being used and with what parameters:

1// Add logging to tool execution
2const originalExecute = tool.execute;
3tool.execute = async (params) => {
4  console.log(`[AUDIT] Tool: ${tool.name}, Params: ${JSON.stringify(params)}`);
5  const result = await originalExecute(params);
6  console.log(`[AUDIT] Result: ${tool.name} completed`);
7  return result;
8};

Review Conversations

Periodically review agent conversations for:

  • Unexpected tool usage patterns
  • Access to sensitive areas
  • Prompt injection attempts

Security Checklist

Before deployment

Verify the following:

  • Permission level matches use case
  • Only necessary tools are enabled
  • Path restrictions are configured
  • Command restrictions are in place
  • Secrets are in environment variables
  • .env is gitignored
  • MCP servers use env vars for credentials
  • Hooks validate sensitive operations