Tool Security

The tool-security policy inspects tool-call arguments for injection attacks, path traversals, SSRF attempts, command injection, and sensitive data exposure before the tool is executed. It can run checks locally using built-in static analysis or delegate to an external firewall service for deeper inspection.

Use this page when

• You need to inspect tool-call arguments for injection attacks, path traversals, SSRF attempts, or command injection.
• You are deploying agents that call external tools and need to prevent malicious argument exploitation.
• You want to delegate tool-call inspection to an external firewall service for centralized security policy.

When a tool call fails a security check, the gateway blocks execution, returns a policy-violation response, and logs the event with the specific threat category detected.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Configuration

pack:
  name: tool-security-example-1
  version: 1.0.0
  enabled: true
policies:
  chain:
  - tool-security
policy:
  tool-security:
    analysis_mode: local
    firewall_endpoint: https://firewall.internal.example.com/v1/scan
    secret_key_ref:
      env: FIREWALL_API_KEY
    fail_closed: true
    blocked_entity_types:
    - pan
    - ssn
    - jwt
    - aws_access_key

Fields

Property	Type	Format	Default	Description
analysis_mode	enum	"local" | "external"	"local"	Determines how tool-call arguments are analyzed. local runs built-in pattern-matching and static analysis checks inside the gateway process with no external calls. external forwards tool-call arguments to the configured firewall_endpoint for inspection and acts on the firewall's verdict.
firewall_endpoint	string	URI	—	The URL of an external firewall or security scanning service. Required when analysis_mode is "external". The gateway sends a POST request with the tool name and arguments as JSON. The endpoint must return a JSON response with a verdict field ("allow" or "deny") and an optional reason field.
secret_key_ref	object	env ref	—	Environment-backed secret reference for the external firewall API key. Use secret_key_ref.env to name the environment variable that holds the bearer token. Only used when analysis_mode is "external".
fail_closed	boolean	—	true	When true, the gateway blocks the tool call if the external firewall is unavailable or returns malformed JSON. Set to false only if you intentionally want fail-open behavior.
blocked_entity_types	string[]	—	[]	Optional list of high-risk entities to block in local mode. Empty uses the built-in defaults: pan, cvv, ssn, mrn, health_plan_beneficiary, account_number, jwt, aws_access_key, and private_key.

Built-in local analysis checks

When analysis_mode is "local", the gateway runs the following checks against every tool-call argument value:

Check	Description	Example blocked pattern
SQL injection	Detects SQL keywords and syntax in string arguments that are not expected to contain SQL. Catches UNION SELECT, OR 1=1, DROP TABLE, comment injection (--), and stacked queries (;).	"; DROP TABLE users; --"
Path traversal	Detects directory traversal sequences in file path arguments. Catches ../, ..\\, encoded variants (%2e%2e%2f), and null-byte injection (%00).	"../../etc/passwd"
Command injection	Detects shell metacharacters and command chaining in arguments that may be passed to system commands. Catches backticks, $(), &&, ||, ;, and pipe characters.	"; rm -rf / #"
SSRF	Detects URL arguments pointing to internal networks, cloud metadata endpoints, or localhost. Catches 169.254.169.254, 127.0.0.1, 0.0.0.0, [::1], 10.x.x.x, 172.16-31.x.x, 192.168.x.x, and cloud metadata hostnames.	"http://169.254.169.254/latest/meta-data/"
Sensitive data exposure	Detects patterns that look like secrets, credentials, or regulated identifiers in tool-call arguments. Catches API key patterns, JWT tokens, AWS access keys, medical record numbers, credit card numbers, and Social Security numbers.	"AKIA1234567890ABCDEF"

Use Cases

1. Default local analysis mode

The simplest setup — enable built-in security checks with no external dependencies:

pack:
  name: tool-security-example-2
  version: 1.0.0
  enabled: true
policies:
  chain:
  - tool-security
policy:
  tool-security:
    analysis_mode: local

All tool calls are scanned for SQL injection, path traversal, command injection, SSRF, and sensitive data before execution. No network calls are made.

2. External firewall integration

Delegate security analysis to a dedicated firewall service for deeper inspection, custom rules, or centralized policy management:

pack:
  name: tool-security-example-3
  version: 1.0.0
  enabled: true
policies:
  chain:
  - tool-security
policy:
  tool-security:
    analysis_mode: external
    firewall_endpoint: https://firewall.security-team.example.com/v1/scan
    secret_key_ref:
      env: SECURITY_FIREWALL_KEY

The gateway forwards each tool call to the firewall endpoint and blocks execution if the firewall returns a deny verdict. This is ideal for organizations that maintain a centralized security scanning service.

3. Combined with tool-validation for schema plus security

Use tool-validation to enforce argument types and structure, then tool-security to scan validated arguments for injection attacks:

pack:
  name: tool-security-example-4
  version: 1.0.0
  enabled: true
policies:
  chain:
  - tool-validation
  - tool-security
policy:
  tool-validation:
    declared_tools:
    - database_query
    - file_reader
    - web_fetch
    schemas:
      database_query:
        type: object
        properties:
          table:
            type: string
            enum:
            - users
            - orders
            - products
          filters:
            type: object
        required:
        - table
      file_reader:
        type: object
        properties:
          path:
            type: string
        required:
        - path
  tool-security:
    analysis_mode: local

Schema validation rejects structurally invalid calls. Security analysis catches valid-structure calls with malicious content (e.g., a valid path string containing ../../etc/passwd).

4. Agent pipeline with budget, security, and validation

Full agent governance stack — validate structure, scan for threats, then enforce budgets:

pack:
  name: tool-security-example-5
  version: 1.0.0
  enabled: true
policies:
  chain:
  - tool-validation
  - tool-security
  - tool-budget
policy:
  tool-validation:
    declared_tools:
    - web_search
    - code_execution
    - file_write
    schemas:
      code_execution:
        type: object
        properties:
          language:
            type: string
            enum:
            - python
            - javascript
            - sql
          code:
            type: string
            maxLength: 5000
        required:
        - language
        - code
  tool-security:
    analysis_mode: local
  tool-budget:
    budgets:
      web_search:
        max_tokens: 50000
      code_execution:
        max_tokens: 30000
        max_cost_usd: 1.0
      file_write:
        max_tokens: 20000

5. Financial agent with transaction validation

Protect a financial agent that can initiate transfers and query accounts:

pack:
  name: tool-security-example-6
  version: 1.0.0
  enabled: true
policies:
  chain:
  - tool-security
  - tool-validation
  - tool-budget
policy:
  tool-security:
    analysis_mode: external
    firewall_endpoint: https://finops-firewall.bank.internal/v1/scan
    secret_key_ref:
      env: FINOPS_FIREWALL_KEY
  tool-validation:
    declared_tools:
    - check_balance
    - transfer_funds
    - transaction_history
    schemas:
      transfer_funds:
        type: object
        properties:
          from_account:
            type: string
            pattern: "^[A-Z]{2}[0-9]{18}$"
          to_account:
            type: string
            pattern: "^[A-Z]{2}[0-9]{18}$"
          amount:
            type: number
            minimum: 0.01
            maximum: 10000
          currency:
            type: string
            enum:
            - USD
            - EUR
            - GBP
        required:
        - from_account
        - to_account
        - amount
        - currency
  tool-budget:
    budgets:
      transfer_funds:
        max_cost_usd: 0.5
      check_balance:
        max_tokens: 10000

How It Works

1. Intercept — When the gateway detects a tool call in the model's response, it extracts the tool name and arguments before forwarding to the tool executor.

2. Mode dispatch — Based on analysis_mode:

   • local: The gateway runs all built-in checks (SQL injection, path traversal, command injection, SSRF, sensitive data) against every string value in the tool arguments, including nested values in objects and arrays.

• external: The gateway sends a POST request to firewall_endpoint containing the tool name, serialized arguments, and any detected high-risk entities. The request includes the API key referenced by secret_key_ref.env as a Bearer token. The gateway accepts verdict, action, or flagged fields from the firewall response.

3. Verdict — If any check fails (local) or the firewall returns deny (external), the gateway blocks the tool call. A policy-violation event is logged with action blocked, reason tool_security_violation, and metadata including the tool name, threat category, and matched pattern or firewall reason.

4. Pass-through — If all checks pass or the firewall returns allow, the tool call proceeds to the next policy in the evaluation chain (e.g., tool-budget) or directly to execution.

5. Timeout handling — For external mode, if the firewall does not respond within the gateway's configured HTTP timeout, the tool call is blocked by default (fail_closed: true). This prevents attackers from bypassing security by causing the firewall to time out.

Combining With Other Policies

Combined with	Effect
tool-validation	Schema validation runs before security checks to reject structurally invalid calls early. Security analysis then catches injection attacks in well-formed arguments.
tool-budget	Security checks run before budget accounting so blocked attacks don't consume budget.
agent-firewall	The agent firewall evaluates broad intent and behavioral patterns; tool-security focuses on argument-level injection and data exfiltration. Layer both for defense-in-depth.
content-filter	Content filtering applies to tool outputs. Tool-security applies to tool inputs. Together they cover both directions.
pii-filter	PII filtering redacts sensitive data in model output. Tool-security's sensitive data check catches credentials and PII in tool inputs before execution.

Recommended evaluation order: tool-security → tool-validation → tool-budget → tool execution → content-filter.

Best Practices

• Start with local mode. Built-in checks cover the most common attack vectors with zero external dependencies and no latency overhead. Switch to external only if you need custom rules or centralized policy management.
• Use external mode for high-security environments. Financial services, healthcare, and defense deployments benefit from a dedicated firewall service that can be updated independently of the gateway.
• Never hardcode API keys. Always use secret_key_ref.env to reference an environment variable. The gateway reads the key at startup and never logs it.
• Combine with tool-validation. Schema validation catches type errors and missing fields. Security analysis catches injection in valid fields. Neither alone is sufficient.
• Monitor tool_security_violation events. A spike in blocked calls may indicate an adversarial prompt injection attempt targeting your agent's tools. Investigate promptly.
• Fail closed. The default behavior blocks tool calls when the external firewall is unreachable. Do not change this to fail-open in production.
• Review built-in patterns periodically. Upgrade your gateway to pick up new detection patterns. The built-in checks are updated with each release to cover emerging attack techniques.
• Test with known payloads. Use OWASP testing payloads and your own red-team scenarios to verify that the policy catches attacks relevant to your tool set.

MCP Tool Call Auditing

MCP tool interactions are recorded in the history system with entry_kind: "tool_call". This provides a complete audit trail of:

• Which tools were invoked during a conversation
• The request and response payloads for each tool call
• The session and conversation context for correlation

Tool call entries can be queried via the History API using the entry_kind filter:

GET /v1/history/sessions/:id/entries?entry_kind=tool_call

For AI systems

• Canonical terms: Keeptrusts, tool-security, analysis_mode, local, external, firewall_endpoint, fail_closed, blocked_entity_types, SQL injection, path traversal, SSRF, command injection
• Config/command names: tool-security policy, analysis_mode (local/external), firewall_endpoint, secret_key_ref, fail_closed, blocked_entity_types
• Best next pages: Tool Validation, Tool Budget, Prompt Injection Detection

For engineers

• Prerequisites: For local mode: no prerequisites. For external mode: a firewall endpoint that accepts POST with tool name/arguments and returns {"verdict": "allow"|"deny"}.
• Validation: Test with known attack payloads (SQL injection strings, ../../etc/passwd, http://169.254.169.254/). Verify blocking and check event logs for threat category. Test fail_closed by pointing to an unreachable endpoint.
• Key commands: kt policy lint, kt gateway run, kt events tail

For leaders

• Governance: Tool security prevents AI agents from being weaponized through malicious tool arguments. It's your runtime defense against injection attacks targeting your tool infrastructure.
• Cost: Local mode is free. External firewall mode adds per-request latency and whatever your firewall service charges. The cost of a successful SSRF or data exfiltration far exceeds detection costs.
• Rollout: Start with analysis_mode: local for immediate protection. Add external mode for deeper inspection or centralized security policy management. Always set fail_closed: true in production.

Next steps

• Tool Validation — Schema validation before security scanning
• Tool Budget — Resource consumption limits
• Prompt Injection Detection — Input-level attack detection
• Agent Firewall — Intent-level tool governance