Skip to main content

Tool Gate

Controls which tools your AI agent can use and monitors for suspicious usage patterns.

What It Does​

AI agents interact with the world through tools -- reading files, running commands, calling APIs, sending messages. Without guardrails, a compromised agent could use these tools to cause real damage.

Tool Gate acts like a checkpoint for every tool call your agent makes. You control which tools are allowed and which are blocked. The guard also watches for suspicious patterns -- like an agent reading sensitive data and then trying to send it somewhere, or making an unusual number of tool calls in quick succession. Think of it as a security guard at a building entrance: checking IDs, watching for unusual behavior, and stepping in when something doesn't look right.

Beyond access control, Tool Gate validates the parameters being passed to tools, catching attempts to sneak in malicious paths or target internal services that should never be reachable from an agent.

Why It Matters​

This is your primary control over what your agent can actually do in the real world. Even if an attacker gets past other guards, Tool Gate limits the damage they can cause. It's essential for any agent that can execute commands, modify files, or communicate with external services.

If your agent only answers questions and has no tool access, this guard has nothing to monitor -- but for any agent with real-world capabilities, it's a critical safety net.

What Gets Caught​

Blocked tools: The following tools are blocked by default:

ToolWhy It's Blocked
execArbitrary command execution
spawnProcess spawning
shellShell access
sessions_spawnCreating new sessions (potential lateral movement)
sessions_sendSending messages to other sessions (potential data exfiltration)
gatewayDirect gateway access
fs_deleteFile deletion
fs_moveFile moving/renaming
whatsapp_loginExternal messaging service authentication

You can adjust this list via the allowlist and denylist in the dashboard. If a skill legitimately needs one of these tools, create an exemption for that specific skill rather than removing it from the blocklist entirely.

Suspicious sequences: The guard watches for patterns that suggest data theft or misuse:

  • Reading a file then immediately executing a command
  • Reading sensitive data then sending it via a messaging tool
  • Rapid bursts of execution commands

Parameter validation: Tool parameters are checked for path traversal attempts (../) and requests targeting internal network addresses.

What won't trigger it: Normal tool usage within configured limits — reading documents, writing files in the workspace, calling approved APIs. If a legitimate skill needs access to a blocked tool, create an exemption rather than disabling the guard.

Example​

Scenario

An agent is processing a user request and attempts to call the exec tool to run a shell command. Tool Gate checks the tool against the denylist and finds exec is blocked by default. The tool call is rejected, and the agent cannot execute the command. The audit log shows a Tool Gate event with the blocked tool name, the reason (denylist match), and the skill that attempted the call. If a trusted backup skill legitimately needs exec, an administrator can create an exemption for that specific skill rather than removing exec from the denylist.

Settings​

These settings are available in the CrabShack dashboard under your agent's security configuration.

SettingWhat It Controls
ModeHow the guard responds (Block is recommended)
AllowlistOnly these tools can be used -- everything else is blocked
DenylistThese specific tools are always blocked
Rate LimitsMaximum tool calls allowed in a time window
Sequence AnalysisWhether to watch for suspicious combinations of tool calls
Destructive Action LimitsMaximum number of potentially harmful actions per session
ExemptionsAllow specific skills to use tools that are otherwise restricted

How It Responds​

In Block mode, unauthorized tool calls are rejected and logged. Rate limit violations and suspicious sequences also trigger blocks and alerts. There's a built-in list of dangerous tools that are blocked by default -- you can override this through the allowlist if your agent has a legitimate need.

If This Guard Blocks You​

  1. Check the audit log. Navigate to Security > Audit Log in the CrabShack dashboard. Filter by Tool Gate to find the relevant event. Click on the event row to see details including which skill and channel triggered it — you'll need these values if you want to create an exemption.

  2. Understand the detection. The audit log entry shows exactly which tool was blocked and why — denylist match, rate limit exceeded, or suspicious sequence detected. If the blocked tool is on the default denylist (like exec, shell, or fs_delete), the guard is working as intended for general use. If a specific skill legitimately needs a blocked tool, create an exemption for that skill rather than removing the tool from the denylist. If a rate limit was exceeded, check whether the skill is making an unusual number of tool calls, or raise the rate limit in an exemption. If a suspicious sequence was flagged, review the sequence of tool calls in the audit log to determine if the behavior is expected.

  3. Adjust if needed. Create an exemption for a specific skill that needs access to a blocked tool. Adjust rate limits if legitimate usage is being throttled. If you're not sure what's happening, switch to Warn mode temporarily to see what Tool Gate catches without blocking. See the Configuration page for details.

tip

Prefer creating a targeted exemption for a specific skill or channel over disabling the guard entirely. If you're seeing frequent false positives, a suppression lets you silence a specific detection label temporarily while you refine your settings.

Default Behavior​

The guard runs in Block mode by default. A built-in set of dangerous tools is blocked unless explicitly allowed. Rate limiting and sequence analysis are both active. During lockdown, rate limits become stricter and fewer destructive actions are permitted per session.