Enforcement - Formal Documentation

Overview

Formal policies can enforce different actions at three evaluation stages: session, request, and response. Each stage has specific actions available based on when the policy is evaluated.

Evaluation Stages

Session

When: Connection establishment and, for SSH and Kubernetes exec, while the session runs Actions: allow, block, mfa, quarantine, suspend, impersonate Use for: Authentication, connection-level access control, reacting to session monitors

Request

When: Before query reaches resource Actions: allow, block, rewrite, decrypt Use for: Query validation, SQL rewriting, blocking writes, decrypting secrets for the upstream

Response

When: After data returns from resource Actions: allow, block, filter, mask, encrypt, rewrite Use for: Data masking, PII redaction, filtering results, encrypting secrets before they leave

Common Action Parameters

All actions support these parameters:

Parameter	Type	Description
`action`	String	The enforcement action: `allow`, `block`, `filter`, `mask`, `encrypt`, `decrypt`, `rewrite`, `mfa`, `quarantine`, `suspend`, `impersonate`
`reason`	String	Explanation for the action (logged for compliance and auditing)
`contextual_data`	String	Additional context that influenced the decision (e.g., “Zendesk ticket #123”)

Block Action

Deny access and terminate the connection or query.

Parameters

Parameter	Type	Description
`type`	Enum	One of `block_with_formal_message`, `block_with_custom_message`, or `mcp_suggest_alternatives`
`message`	String	Custom message to show the user

block_with_formal_message returns Formal’s default block text. That message includes the policy ID plus the session ID and request ID when they are available, so users can share those identifiers with their security team.

Example

package formal.v2

import future.keywords.if

# Block all DELETE statements in production
request := {
  "action": "block",
  "type": "block_with_custom_message",
  "message": "DELETE operations are not allowed in production",
  "reason": "Production data protection policy"
} if {
  input.resource.environment == "production"
  input.sql_query.statement_type == "DELETE"
}

Suggest approved MCP alternatives

Use mcp_suggest_alternatives to block an unapproved MCP server and tell the AI agent what to do next. The block message becomes an advisory written for the agent. It lists the MCP resources you have registered in Formal, excluding the blocked one. The advisory tells the agent to ask the user to choose one of these options:

Switch to one of the approved MCP servers.
Request the blocked server. The agent looks for a form about MCP requests with formal form list and submits it with formal form fill.
Do nothing for now.

Formal ignores message when it builds the advisory. If the advisory cannot be built, Formal returns message, or a short default text when message is empty. This policy blocks tool calls to MCP servers that have no Formal resource, such as servers the Formal Endpoint intercepts on a laptop. It is the policy that the Block unknown MCPs control on the Guardrails page generates.

package formal.v2

import future.keywords.if

request := {
  "action": "block",
  "type": "mcp_suggest_alternatives",
  "reason": "This MCP is not approved by your organization.",
} if {
  input.resource.technology == "mcp"
  input.resource.name == ""
  input.mcp.method == "tools/call"
}

Create a form with fields named name, url, and reason so agents can file requests for blocked MCP servers. Requests then reach your approval workflow.

Allow Action

Explicitly permit an operation. Use in combination with default deny policies.

Example

package formal.v2

import future.keywords.if
import future.keywords.in

# Default deny
default session := {
  "action": "block",
  "type": "block_with_formal_message"
}

# Allow admins
session := {
  "action": "allow",
  "reason": "User is in admin group"
} if {
  "admin" in input.user.groups
}

Rewrite Action

Modify a SQL query before it reaches the resource, or modify an HTTP request or response in transit.

Parameters

Parameter	Type	Applies to	Description
`limit`	Integer	SQL, request stage	Row limit to apply. Formal adds a `LIMIT` or lowers a higher one. It never raises an existing lower limit.
`comment`	String	SQL, request stage	Comment to add to the query
`headers`	`Map<String, String[]>`	HTTP-based, request and response	HTTP headers to set. Use an empty array (`[]`) to remove a header.
`path`	String	HTTP-based, request stage	Replacement URL path, such as `/v1/messages`
`body`	String	HTTP-based, request and response	Replacement for the whole body, sent as-is. `Content-Type` is unchanged.
`json`	Any JSON value	HTTP-based, request and response	Replacement body, serialized as JSON. Sets `Content-Type: application/json` unless the message already has a JSON type.
`post_form`	`Map<String, String[]>`	HTTP-based, request and response	Replacement body, URL-encoded as form fields. A field value can also be a single string. Sets `Content-Type: application/x-www-form-urlencoded` unless already set.

HTTP-based resources include HTTP, LLM, and MCP resources.

body, json, and post_form each replace the whole body. Set at most one of them in a decision. Formal rejects a decision that sets more than one and does not apply it.

When several active policies rewrite the same message, Formal applies all of their header rewrites. If more than one sets a body, only one of them takes effect. Scope policies so that body rewrites don’t overlap.

Example

package formal.v2

import future.keywords.if

# Add LIMIT clause to unbounded queries
request := {
  "action": "rewrite",
  "limit": 1000,
  "comment": "Auto-added row limit for safety",
} if {
  startswith(lower(input.sql_query.query), "select")
}

Example: Rewrite LLM request headers

package formal.v2

import future.keywords.if

rewritten_headers := object.union(input.http.headers, {
  "anthropic-allowed-org-ids": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"],
})

request := {
  "action": "rewrite",
  "headers": rewritten_headers,
} if {
  input.resource.technology == "llm"
}

For the full walkthrough, see Restrict Anthropic Sign-Ins to One Org.

Example: Redact SSNs from LLM request bodies

String-replace sensitive values in the outbound LLM body so coding agents can continue without sending SSNs upstream. Prefer body rewrites over blocking the session when the goal is redaction.

package formal.v2

import future.keywords.if
import future.keywords.in

ssn_pattern := `\b\d{3}-\d{2}-\d{4}\b`

request := {
  "action": "rewrite",
  "body": regex.replace(input.http.body, ssn_pattern, "[REDACTED-SSN]"),
  "reason": "Redact SSNs from LLM request messages",
} if {
  input.resource.technology == "llm"
  some msg in input.llm.messages
  some part in msg.content_parts
  part.type in {"text", "tool_result"}
  regex.match(ssn_pattern, part.text)
}

Filter Action

Remove rows from the result set based on conditions.

Example

package formal.v2

import future.keywords.if

# Filter rows unless user has open Zendesk ticket
default response := {
  "action": "filter",
  "reason": "No open tickets for this data"
}

response := {
  "action": "allow",
  "contextual_data": filtered_tickets,
  "reason": "User has open ticket"
} if {
  col := input.row[_]
  col["path"] == "main.public.pii.email"

  filtered_tickets := [obj |
    obj := data.zendesk_tickets[_]
    obj.requester_email == col.value
    obj.status == "open"
  ]

  count(filtered_tickets) > 0
}

Mask Action

Redact or obfuscate sensitive data in responses.

Parameters

Parameter	Type	Description
`type`	String	Masking type from Masking Types. Sets the privacy level used to resolve conflicts.
`sub_type`	String	Masking method from Masking Subtypes. Defaults to the value of `type`.
`columns`	[]Column	List of columns to mask
`redact`	String	Replacement string. Character-level subtypes repeat it once per masked character.
`characters_count`	Integer	Number of characters to mask, for `redact.first_n_characters` and `redact.last_n_characters`
`precision`	Integer	Digits to keep after the decimal point, for `reduce_decimal_precision`
`typesafe_fallback`	String	`fallback_to_null` or `fallback_to_default`. Setting it turns on type safety.

With type safety on, Formal keeps typed columns valid, such as numbers, booleans, dates, JSON, and UUIDs. nullify, redact, the hash subtypes, and reduce_decimal_precision keep their output when the column’s type can hold it. Every other mask on a typed column returns the fallback:

fallback_to_null returns NULL.
fallback_to_default returns a placeholder such as 0, {}, or an all-zero UUID. Boolean columns get NULL instead.

Text columns are masked normally.

Formal turns on type safety only when typesafe_fallback is set. A typesafe key on its own has no effect.

Masking Types

Type	Privacy Level	Description
`nullify`	4 (Highest)	Replace with NULL
`hash.with_salt`	4	Hash with random salt
`fake`	3	Generate realistic fake data
`redact.constant_characters`	3	Replace with constant string
`hash.no_salt`	2	Hash without salt (deterministic)
`redact.partial`	1	Partially redact (e.g., mask email username)
`none`	0 (Lowest)	No masking

type and sub_type do different jobs. type only sets the privacy level. sub_type picks the function that transforms the value. When you omit sub_type, Formal uses type as the subtype. That shortcut works for nullify, hash.with_salt, hash.no_salt, and redact.constant_characters. fake and redact.partial always need an explicit sub_type.

Masking fails silently when a name is wrong. Formal does not validate mask names when you save a policy, and it logs no error at query time.

An unknown sub_type leaves the value unmasked.
An unknown type has privacy level 0, so Formal drops the mask.
type: "fake" or type: "redact.partial" without a sub_type leaves the value unmasked.

Copy names from the tables on this page. Run the policy in dry-run and check query results before you activate it.

Masking Subtypes

Subtypes that end in _with_fake replace the value with a random fake value of the same kind. Pair them with type: "fake". Pair the partial subtypes, such as the email and character-level ones, with type: "redact.partial".

Redaction, hashing, and numbers

redact.constant_characters: Replace the value with redact
redact: Replace the value with redact. With type safety on, keeps redact when the column’s type can hold it, such as -1 in an integer column
replace_characters_with: Replace every character with redact. With "redact": "*", secret becomes ******
redact.first_n_characters: Replace the first characters_count characters. With "redact": "*" and a count of 3, hello becomes ***lo
redact.last_n_characters: Replace the last characters_count characters. With "redact": "*" and a count of 3, hello becomes he***
mask_everything_except_last: Replace every character except the last one. With "redact": "*", sensitive becomes ********e. This subtype ignores characters_count
nullify: Return NULL
hash.no_salt: Hash the value. The same input always gives the same output, so joins still work
hash.with_salt: Hash the value with a random salt. The output changes on every read
reduce_decimal_precision: Truncate to precision digits after the decimal point. With a precision of 2, 123.456 becomes 123.45. Non-numeric values are unchanged

email_mask_username: jane@example.com becomes ****@example.com
email_mask_domain_name: jane@example.com becomes jane@*******.com. The masked domain is always *******.com
email_mask_while_preserving: jane@example.com becomes j***@e******.com
email_mask_with_fake: Random fake email address

The first three subtypes replace every character with * when the value isn’t an email address.

Personal information

person_full_name_mask_with_fake
person_first_name_mask_with_fake
person_last_name_mask_with_fake
person_gender_mask_with_fake
person_ssn_mask_with_fake
phone_mask_with_fake

Location

postal_address_mask_with_fake
city_mask_with_fake
state_mask_with_fake
country_mask_with_fake
zip_mask_with_fake
location_mask_except_state_country: Keep only the US state and the country from a comma-separated address. 1 Main St, Springfield, IL, USA becomes IL, USA

Payment

payment_credit_card_number_mask_with_fake
payment_credit_card_cvv_mask_with_fake
payment_credit_card_exp_mask_with_fake
payment_credit_card_type_mask_with_fake
payment_currency_with_fake
payment_ach_routing_with_fake
payment_ach_account_with_fake
payment_bitcoin_address_with_fake
payment_bitcoin_private_key_with_fake

Network

network_url_mask_with_fake
network_domain_mask_with_fake
network_ipv4_mask_with_fake
network_ipv6_mask_with_fake
network_mac_mask_with_fake

Company

company_name_with_fake

Character-level subtypes repeat redact once per masked character. If redact is empty, those characters are removed instead of replaced. Always set redact, for example to "*".

Examples

Mask email usernames:

package formal.v2

import future.keywords.if

response := {
  "action": "mask",
  "type": "redact.partial",
  "sub_type": "email_mask_username",
  "columns": columns
} if {
  columns := [col |
    col := input.row[_]
    col["data_label"] == "email_address"
  ]
  count(columns) > 0
}

Replace PII with fake data:

package formal.v2

import future.keywords.if

response := {
  "action": "mask",
  "type": "fake",
  "sub_type": "person_full_name_mask_with_fake",
  "columns": columns
} if {
  columns := [col |
    col := input.row[_]
    col["data_label"] == "name"
  ]
  count(columns) > 0
}

Redact with constant value:

package formal.v2

import future.keywords.if

response := {
  "action": "mask",
  "type": "redact.constant_characters",
  "sub_type": "redact.constant_characters",
  "redact": "[REDACTED]",
  "columns": columns
} if {
  columns := [col |
    col := input.row[_]
    col["data_label"] == "social_security_number"
  ]
  count(columns) > 0
}

Encrypt & Decrypt Actions

Encrypt and decrypt sensitive HTTP values in-line, so plaintext secrets never reach places that should not see them. Formal encrypts secrets on the way out and decrypts them on the way back in, so tokens stay protected end to end.

The encrypt action on the Formal Endpoint is only available on macOS.
The encrypt action on the Connector requires configuring a cloud KMS key for token encryption. See Token Encryption for more information.

decrypt runs at the request stage. It decrypts Formal-encrypted values before the upstream receives them. If a value fails to decrypt, the request is forwarded unchanged.
encrypt runs at the response stage. It encrypts values before they leave the proxy. If encryption fails, the response is blocked.

Parameters

Parameter	Type	Description
`targets`	[]Target	The parts of the HTTP message to encrypt or decrypt

Each target is an object:

Field	Type	Description
`kind`	String	One of `header`, `json`, or `body`
`name`	String	Header name (`header`) or dot-path JSON field, e.g. `data.token` (`json`). Omit for `body`.

Example: Encrypt tokens in a response

package formal.v2
import future.keywords.if

response := {"action": "encrypt", "targets": [
    {"kind": "json", "name": "access_token"},
    {"kind": "json", "name": "refresh_token"}
]} if {
    input.resource.technology == "http"
    input.http.method == "POST"
    input.http.path == "/token"
}

Example: Decrypt a request header for the upstream

package formal.v2
import future.keywords.if

request := {"action": "decrypt", "targets": [
    {"kind": "header", "name": "Authorization"}
]} if {
    input.http.path == "/mcp"
}

For an end-to-end Notion MCP walkthrough (Endpoint Secure Enclave or Connector KMS), see Encrypt MCP OAuth Tokens.

MFA Action

The MFA action requires device-owner verification before proceeding with the connection. When a policy returns the mfa action, the Formal Endpoint prompts for device-owner verification before the connection proceeds. On macOS this is Touch ID or the device passcode. On Windows this is Windows Hello (fingerprint, facial recognition, or PIN). When a Connector evaluates the policy, it raises the challenge in the Control Plane and waits. The user’s Formal Endpoint picks up the challenge and shows the prompt. The user needs the Endpoint running to answer it.

Parameters

Parameter	Type	Description
`message`	String	Text shown in the prompt. Default: `An action via Formal requires your approval`
`timeout`	Integer	Seconds to wait for the user. Default: `60`

If verification fails or times out, Formal blocks the connection with MFA authentication failed or timed out. Please try again.

MFA on Windows requires Windows Hello. It’s the strongest form of device-owner verification available. A device with no Windows Hello method configured, or accessed over a remote desktop session where Windows Hello is unavailable, fails the challenge closed and is denied access.

Example

package formal.v2

import future.keywords.if

session := {
  "action": "mfa",
  "message": "Approve access to the production database",
  "timeout": 120,
  "reason": "Production access requires MFA"
} if {
  input.resource.environment == "production"
}

Quarantine Action

Stop a user who shows high-risk behavior. quarantine is a session-stage action for SSH and Kubernetes exec sessions. It is usually paired with session monitors, which re-evaluate session policies while the session runs. What happens depends on when the rule matches:

While a session runs: Formal ends every active session of the user and blocks the user. Blocked users can’t open SSH, Kubernetes, or RDP sessions until an admin unblocks them.
When an SSH session starts: Formal refuses that session. The user is not blocked.

Parameters

Parameter	Type	Description
`message`	String	Text sent to the client. Defaults to a Formal message with the policy ID and session ID.

To unblock a user, go to Users, open the user, and click Unblock User. Blocked users show a Blocked badge. You can also block a user manually with Block User.

Example

package formal.v2

import future.keywords.if
import future.keywords.in

session := {
  "action": "quarantine",
  "message": "Your access is paused. Contact the security team.",
  "reason": "Curl piped to bash in an SSH session"
} if {
  some monitor in input.triggered_monitors
  monitor.name == "ssh_curl_to_bash"
}

Suspend Action

End one session without blocking the user. suspend is a session-stage action for SSH and Kubernetes exec sessions.

While a session runs: Formal ends that session. The user can reconnect.
When an SSH session starts: Formal refuses that session.

Parameters

Parameter	Type	Description
`message`	String	Text sent to the client. Defaults to a Formal message with the policy ID and session ID.

Example

package formal.v2

import future.keywords.if
import future.keywords.in

session := {
  "action": "suspend",
  "message": "This session ran a destructive command and was ended.",
  "reason": "Destructive command detected"
} if {
  some monitor in input.triggered_monitors
  monitor.name == "destructive_command"
}

Impersonate Action

Run Kubernetes API requests as the end user instead of the Connector’s identity. impersonate is a session-stage action for Kubernetes resources. Formal adds the Impersonate-User and Impersonate-Group headers to each request it forwards.

Parameters

Parameter	Type	Description
`user`	String	Kubernetes user to impersonate
`groups`	[]String	Kubernetes groups to impersonate

Example

package formal.v2

import future.keywords.if

session := {
  "action": "impersonate",
  "user": input.user.username,
  "groups": input.user.groups
} if {
  input.resource.technology == "kubernetes"
}

The cluster must allow the Connector to impersonate users and groups. See Kubernetes impersonation for the RBAC setup.

Rule Conflicts and Precedence

When multiple policies apply to the same query, Formal resolves conflicts using least privilege:

Scenario	Resolution
Block vs Allow	Block wins
Multiple Filter actions	Smallest row limit wins
Multiple Mask actions	Highest privacy level wins (nullify > constant > fake > partial)
Multiple Rewrite actions	Arbitrary (avoid conflicts with scoping)

Example of Conflict Resolution

Policy A: Mask email as ***@***.com (privacy level 3)
Policy B: Nullify email (privacy level 4)

Result: Email is nullified (higher privacy)

Use included_connectors or included_resources to avoid unintended policy conflicts.

Scoping Policies with Connectors, Resources, Spaces, and Technologies

To prevent policy conflicts when using the default keyword, limit which Connectors, Resources, Spaces, or technologies a policy applies to.

Include/Exclude Connectors

Use included_connectors to apply a policy only to specific connectors:

package formal.v2

import future.keywords.if

# Only apply to these Connectors
included_connectors := ["production-connector", "staging-connector"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.resource.technology == "postgres"
}

Use excluded_connectors to exclude specific connectors:

package formal.v2

import future.keywords.if

# Exclude these Connectors
excluded_connectors := ["dev-connector"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.resource.technology == "postgres"
}

A single policy cannot use both included_connectors and excluded_connectors. Choose one or the other.

Include/Exclude Resources

Use included_resources to apply a policy only to specific resources:

package formal.v2

import future.keywords.if

# Only apply to specific resources
included_resources := ["production-postgres"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.user.type == "machine"
}

Use excluded_resources to exclude specific resources:

package formal.v2

import future.keywords.if

# Exclude specific resources
excluded_resources := ["dev-postgres", "staging-postgres"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  "engineer" in input.user.groups
}

A single policy cannot use both included_resources and excluded_resources. Choose one or the other.

Include/Exclude Spaces

Scoping by Space covers every Connector and Resource the Space contains. Use included_spaces to apply a policy only to specific Spaces:

package formal.v2

import future.keywords.if

# Only apply to these Spaces
included_spaces := ["production"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.user.type == "machine"
}

Use excluded_spaces to exclude specific Spaces:

package formal.v2

import future.keywords.if

# Exclude these Spaces
excluded_spaces := ["sandbox"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.resource.technology == "postgres"
}

A single policy cannot use both included_spaces and excluded_spaces. Choose one or the other.

Connectors that belong to no Space are never in scope for included_spaces, and are always in scope for excluded_spaces.

Include/Exclude Technologies

Use included_technologies or excluded_technologies to scope a policy by the Resource’s technology identifier, such as postgres, ssh, or llm:

package formal.v2

import future.keywords.if

# Only apply to SQL databases
included_technologies := ["postgres", "mysql", "snowflake"]

session := {
  "action": "block",
  "type": "block_with_formal_message"
} if {
  input.user.type == "machine"
}

A single policy cannot use both included_technologies and excluded_technologies. Choose one or the other.

Policy Stage Configuration

Policy evaluation can also be turned off per stage for a Resource or a Connector, without editing policies. See Policy Stage Configuration.

​Overview

​Evaluation Stages

Session

Request

Response

​Common Action Parameters

​Block Action

​Parameters

​Example

​Suggest approved MCP alternatives

​Allow Action

​Example

​Rewrite Action

​Parameters

​Example

​Example: Rewrite LLM request headers

​Example: Redact SSNs from LLM request bodies

​Filter Action

​Example

​Mask Action

​Parameters

​Masking Types

​Masking Subtypes

​Examples

​Encrypt & Decrypt Actions

​Parameters

​Example: Encrypt tokens in a response

​Example: Decrypt a request header for the upstream

​MFA Action

​Parameters

​Example

​Quarantine Action

​Parameters

​Example

​Suspend Action

​Parameters

​Example

​Impersonate Action

​Parameters

​Example

​Rule Conflicts and Precedence

​Example of Conflict Resolution

​Scoping Policies with Connectors, Resources, Spaces, and Technologies

​Include/Exclude Connectors

​Include/Exclude Resources

​Include/Exclude Spaces

​Include/Exclude Technologies

​Policy Stage Configuration

Overview

Evaluation Stages

Common Action Parameters

Block Action

Parameters

Example

Suggest approved MCP alternatives

Allow Action

Example

Rewrite Action

Parameters

Example

Example: Rewrite LLM request headers

Example: Redact SSNs from LLM request bodies

Filter Action

Example

Mask Action

Parameters

Masking Types

Masking Subtypes

Examples

Encrypt & Decrypt Actions

Parameters

Example: Encrypt tokens in a response

Example: Decrypt a request header for the upstream

MFA Action

Parameters

Example

Quarantine Action

Parameters

Example

Suspend Action

Parameters

Example

Impersonate Action

Parameters

Example

Rule Conflicts and Precedence

Example of Conflict Resolution

Scoping Policies with Connectors, Resources, Spaces, and Technologies

Include/Exclude Connectors

Include/Exclude Resources

Include/Exclude Spaces

Include/Exclude Technologies

Policy Stage Configuration