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 Actions: allow, block, mfa Use for: Authentication, connection-level access control

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, filter, mask, encrypt 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`
`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` or `block_with_custom_message`
`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.query.statement_type == "DELETE"
}

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 the query or HTTP headers before the request reaches the resource.

Parameters

Parameter	Type	Description
`limit`	Integer	The limit to apply to the query
`comment`	String	The comment to add to the query
`headers`	`Map<String, String[]>`	HTTP headers to set. Use an empty array (`[]`) to remove a header.

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.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"
}

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 (e.g., `redact.partial`, `hash.with_salt`, `fake`, `nullify`)
`sub_type`	String	Specific masking method (e.g., `email_mask_username`)
`columns`	[]Column	List of columns to mask
`redact`	String	Replacement value for redaction
`characters_count`	Integer	Number of characters to mask
`typesafe`	Boolean	Maintain column data type (default: `false`)
`typesafe_fallback`	String	`fallback_to_null` or `fallback_to_default`

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

Masking Subtypes

Email Masking

email_mask_username: ****@example.com
email_mask_domain_name: user@*****.***
email_mask_while_preserving: a****@e******.com
email_mask_with_fake: fake.email@example.com

Personal Information

person_full_name_mask_with_fake
person_first_name_mask_with_fake
person_last_name_mask_with_fake
person_ssn_mask_with_fake

Location Data

postal_address_mask_with_fake
city_mask_with_fake
state_mask_with_fake
zip_mask_with_fake
location_mask_except_state_country

Payment Data

payment_credit_card_number_mask_with_fake
payment_credit_card_cvv_mask_with_fake
payment_credit_card_exp_mask_with_fake
payment_ach_routing_with_fake
payment_bitcoin_address_with_fake

Network Data

network_url_mask_with_fake
network_ipv4_mask_with_fake
network_ipv6_mask_with_fake
network_mac_mask_with_fake

General Redaction

redact.constant_characters: Replace with custom string
redact.first_n_characters: Mask first N chars
redact.last_n_characters: Mask last N chars
mask_everything_except_last: Show only last N chars

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"] == "ssn"
  ]
  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 Desktop App 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).

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",
  "reason": "Production access requires MFA"
} if {
  input.resource.environment == "production"
}

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 and Resources

To prevent policy conflicts when using the default keyword, you can limit which Connectors or Resources 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.

​Overview

​Evaluation Stages

Session

Request

Response

​Common Action Parameters

​Block Action

​Parameters

​Example

​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

​Example

​Rule Conflicts and Precedence

​Example of Conflict Resolution

​Scoping Policies with Connectors and Resources

​Include/Exclude Connectors

​Include/Exclude Resources

Overview

Evaluation Stages

Common Action Parameters

Block Action

Parameters

Example

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

Example

Rule Conflicts and Precedence

Example of Conflict Resolution

Scoping Policies with Connectors and Resources

Include/Exclude Connectors

Include/Exclude Resources