Skip to main content

Tool Security

The tool-security policy checks the serialized input request. It blocks a local pattern, a blocked entity, or a dangerous external firewall verdict. This policy-stage check does not prove that the gateway examined each subsequent model-emitted tool action before dispatch.

Phase and verdicts​

  • Phase: input
  • Verdicts: allow or block

Configuration​

pack:
  name: tool-security-example-1
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - tool-security

policy:
  tool-security:
    analysis_mode: local
    blocked_patterns:
      - delete_message
    blocked_entity_types:
      - pan
      - ssn
      - jwt

Supported fields​

FieldTypeDefaultNotes
analysis_modestringlocallocal or external.
firewall_endpointstring—Used only when analysis_mode: external and an endpoint is configured.
secret_key_refobject—Use secret_key_ref.env for the bearer token environment variable.
fail_closedbooleantrueApplies to client, network, and response errors from the external firewall.
blocked_entity_typesstring[][]Empty means the built-in blocked-entity defaults are used.
blocked_patternsstring[][]Case-insensitive substring matches against the serialized request JSON.

Local checks​

Local mode examines the serialized request for these constant substrings:

  • ../
  • ..\
  • drop table
  • rm -rf
  • 169.254.169.254
  • file://
  • curl http://localhost

It also blocks detected entities. With an empty blocked_entity_types list, the defaults are:

  • account_number
  • aws_access_key
  • cvv
  • health_plan_beneficiary
  • jwt
  • mrn
  • pan
  • private_key
  • ssn

External mode​

When analysis_mode: external has a firewall_endpoint, the gateway sends these items in a POST request:

  • the full request payload
  • detected entities

It then interprets one or more of these as a blocking verdict:

  • verdict
  • action
  • flagged

These values block the request: deny, block, blocked, reject, rejected, flagged, and review.

Important behavior notes​

  • If analysis_mode: external has no firewall_endpoint, the policy uses local checks.
  • Local evaluation uses substrings in the serialized request JSON. It is not a structured argument validator.
  • Decision details include flagged and reason. Event details include matched entities when this data is available.
  • The policy-stage evaluator does not validate model-emitted tool arguments.
  • Use a pre-dispatch tool workflow when each actual action must have authorization and argument checks.

Minimal correct example​

policy:
  tool-security:
    analysis_mode: local

Next steps​