Protections & Firewall

Prevent confidential data leaks and unauthorized tool calls

Introduction

Each server has its own protections and rules. Manage them in the tool server's Security tab.

  • Protections are built-in checks that can find sensitive content.
  • Rules are manual controls that you can add. They allow for more specific targeting.

Protections

ModeEffect
OffSkip scans, unless a protection rule applies to the tool
AuditRecord matches without changing tool arguments or responses
OnApply the configured Request and Response actions and record matches

The Secrets, Personal data and Prompt injection protections are available.

Directions

A protection can scan two directions:

  • Request: the arguments that the client sends. In the API, the name is arguments.
  • Response: the result, upstream error messages and progress messages. In the API, the name is result.

Each direction has an action for On mode. Open the protection's mode menu, then select Request or Response under Actions.

ActionEffect
OffSkip scans in this direction
AuditRecord matches and pass the content unchanged
RedactReplace matches with a marker, such as [REDACTED:github-pat]
BlockRefuse a matching request before the tool runs, or withhold a matching result or upstream error message after the tool runs

For progress messages, Block replaces matches with a marker. It does not stop the tool.

The built-in actions are:

ProtectionRequestResponse
SecretsBlockRedact
Personal dataAuditRedact
Prompt injectionNot scannedRedact

In Audit mode, Gatana scans the same directions as On mode, but only records matches. A direction set to Off is not scanned in either mode unless a protection rule applies.

Select Default (...) to remove a server action and use the organization default or built-in value. The menu shows where the current value comes from. An asterisk (*) beside the mode shows that a server action or option differs from its default.

With Request Off, this protection does not scan the arguments. Audit and trace logs can contain them as sent. With Response Off, this protection passes results and messages unchanged. Protection rules can still enable scans for selected tools.

Defaults for your organization

Each action and setting comes from the first level that sets it:

  1. The server.
  2. The organization default.
  3. The built-in value.

A server without its own value follows the organization default, including later changes. A list replaces the list from the next level; the lists are not combined.

Users with permission to manage the organization set defaults on the Protections & Firewall page:

  1. Select Edit defaults.
  2. Change the values.
  3. Select Save.

The defaults apply as follows:

  • Mode for new servers sets the initial mode. Later changes do not change existing server modes. Without an organization default, a new server has Secrets On and the other protections Off.
  • Request and Response apply to all servers without their own action, including existing servers.
  • Settings set through the API also apply to all servers without their own value.

You can change modes for existing servers on the Protections & Firewall page. Select the servers, then use the bulk actions.

API

Set protections in a server API request. For example:

{
  "protections": {
    "secrets": {
      "mode": "on",
      "actions": {
        "arguments": "block",
        "result": "redact"
      },
      "settings": {
        "includeGeneric": false
      }
    }
  }
}

Broad detection (includeGeneric) also finds generic key=value secrets. It is off by default. Set it through the API, on a server or as an organization default.

Phrase detection (phrases) enables injection phrase rules. It is on by default. Set it to false to scan only for hidden characters. Change it in the protection's mode menu, through the API, or as an organization default.

Missing actions and settings use organization defaults or built-in values. Each server stores its own mode. A missing protection on an existing server is Off.

The read-only field resolvedProtections in server responses shows:

  • Each direction's action for On mode, regardless of the current mode.
  • Each setting's value.
  • The source of each value: server, organization or builtin.
  • The inherited value that applies if the server removes its own value.

The tenant field protectionDefaults stores organization defaults in the same format. An update to this field replaces all organization protection defaults. Omitted values use built-in defaults.

To remove a server action or setting, send the complete protections object without that key in a PUT request. Omitted keys in a PATCH request keep their current values.

Personal data

The Personal data protection is off by default. It uses patterns and checksums, without a model or an external service. The rules accept missed values to reduce false matches, because redaction changes tool results.

TypeWhen it matches
Email addressAnywhere. It does not match service addresses such as noreply@..., or clone URLs such as [email protected]:...
Phone numberAnywhere, if it starts with + and is valid. Other forms require a label such as phone
IBANAnywhere, with a correct checksum
Card numberAnywhere, with a correct checksum and a known issuer. Numbers without separators are excluded from ID fields, such as id or order_id
National ID numberWith a correct checksum. Formats that are easy to identify match anywhere. Other forms require a label such as ssn or personnummer
Name, birth date, street address, passport numberOnly in a field that identifies the type, such as first_name, date_of_birth or street_address. These types do not match in sentences or fields named only name or address

A field name can serve as the label for its value.

National ID numbers are supported for Australia, Austria, Belgium, Canada, Croatia, Czechia, Denmark, Estonia, Finland, France, Germany, Greece, Iceland, India, Ireland, Italy, the Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, the United Kingdom and the United States.

The redaction marker identifies the type, such as [REDACTED:email-address] or [REDACTED:se-personnummer].

With Request Audit, the tool and the audit record receive the arguments unchanged, including personal data. Set Request to Redact to remove personal data before the arguments reach the tool and the audit record.

Prompt injection

The Prompt injection protection is off by default. It scans tool responses for hidden characters and injection phrases. It uses patterns without a model or an external service.

GroupWhat it findsWhat Redact does
Hidden charactersUnicode tag characters that carry invisible text, four or more zero-width characters in a row, also when spaces separate them, zero-width characters next to other hidden characters, a zero-width character inside a Latin word, bidirectional overrides (U+202D, U+202E) and other invisible charactersDeletes the characters. The visible text stays
PhrasesSentences that override instructions, address an AI, assign the AI a new role, ask the AI to hide something from the user, chat template markers such as <|im_start|>, and tags such as <INFORMATION>Replaces the whole text block, string value or message with a marker such as [REDACTED:instruction-override], because the sentence around the phrase carries the instruction

The phrase rules cover English and German. Hidden-character rules apply to all languages. Before the phrase scan, Gatana removes hidden characters, converts typographic apostrophes, no-break spaces and fullwidth letters to plain text, and joins wrapped lines. A blank line ends a sentence.

Emoji keep their joiners, and the flags of England, Scotland and Wales keep their tag characters. Bidirectional embeddings and isolates, which right-to-left text uses, are not changed.

The protection does not find instructions that read like a normal task, such as "translate this into French", requests that do not address an AI, encoded text such as base64, look-alike letters, phrases in other languages, text hidden with CSS, or image links that carry data. Use Audit first to see what it finds in your tool results.

With Phrase detection off, the protection finds hidden characters only. Use this on servers that return email threads, documents or web pages, where people also write "ignore my previous instructions".

The audit record names each matched rule, such as unicode-tags or instruction-override. It does not include the matched text.

See gatana.ai/measurements for detection rates, false matches, the method and the data.

What is scanned

Gatana scans the following content when the direction is enabled:

  • string values in arguments and structured results
  • result text
  • text resources
  • upstream error and progress messages.

If result text, a text resource or a message is valid JSON, Gatana decodes and scans each string separately. Its key serves as the label. Gatana also scans keys and numbers with 7 or more digits. Matched keys and numbers become string markers. Spacing and other values stay unchanged.

Keys and numbers in arguments and structured results are not scanned, because a marker can break the schema.

If JSON is only part of a text, Gatana scans the whole text as one part.

It does not scan images, audio, other binary content or resource links. It does not decode base64 or other encodings inside text.

Redaction can make a value fail schema validation. Prompt injection deletes hidden characters without a marker. This can avoid failures caused by markers. The changed value can still fail validation.

Rules

A rule applies to All tool calls or Specific tools. It uses either a condition or a protection check.

Condition rules

A condition rule uses these actions:

ActionEffect
DenyStop the call before the tool runs
AuditRecord the match and continue to the remaining rules and protections
AllowMake protections record matches without blocking or redacting. Deny rules still apply

Rules run in order from top to bottom. Deny stops evaluation. Audit and Allow continue, so a later Deny still blocks a call.

A missing argument makes a condition such as args.confirm != true not match. Other evaluation errors, such as comparing text with a number, block the call.

Use args in an Allow condition only for trusted callers. Callers control the arguments and can make the rule match to avoid blocking and redaction.

Protection rules

A protection rule selects a protection and a direction, such as Secret in request. It uses Block, Redact or Audit with the effects described above.

For each protection and direction, the first rule that applies to the tool selects the action. It takes priority over the protection mode and direction action, even when either is Off. A matching Allow condition rule still changes the selected action to Audit.

Configuration

  1. Open a tool server under Servers, then select Security.
  2. Open each protection's mode menu to set its mode and Request and Response actions.
  3. Select Add rule, choose the tools, condition or protection check, and action, then Save. For conditions, use the expression builder or the CEL tab.
  4. Use each rule's menu to move, duplicate or delete it.

Changes are saved immediately and take effect within 30 seconds.

Test a call checks rules and argument protections without running the tool or writing audit records.

Condition fields

FieldValue
tool, args.*Tool name and arguments
user.id, user.email, user.name, user.roleCaller details
user.isServiceAccount, user.isDisabledCaller flags
teams, profilesCaller team IDs and active profile IDs
claims.*, authMethodToken claims and authentication method

For example, deny writes outside a directory:

tool == "write_file" && !args.path.startsWith("/workspace/")

Auditing

See the server's Audit Logs tab or use SIEM Streaming. Deny and Audit condition rules write firewall_deny and firewall_log events.

Protection matches appear in protectionChecks, without matched text. For Allow, wouldHaveAction shows the action replaced by Audit. Older records use the action log for Audit.

Last updated on

On this page