Evaluation - Formal Documentation

Policies are evaluated at three stages: session (connection time), request (before query execution), and response (after data retrieval). Each stage provides different input data for making policy decisions.

For available enforcement actions at each stage, see Enforcement. If you have existing policies using pre_request / post_request, see Legacy Stage Names.

Policy Scope

By default, policies apply universally to all users, resources, and data locations. You can narrow the scope within each policy using conditions.

User Context Quick Reference

Access user information via input.user and input.end_user:

Field	Type	Description
`username`	String	Unique username
`email`	String	Email address (human users only)
`groups`	[]String	Group names the user belongs to
`group_ids`	[]String	Formal group IDs the user belongs to
`type`	String	`human` or `machine`
`idp.attributes`	Object	Custom SSO attributes sent by the identity provider
`idp.group_ids`	[]String	Raw IdP group IDs (e.g. Okta group IDs)

Resource Context Quick Reference

Filter by resource via input.resource:

Field	Type	Description
`id`	String	Resource ID
`name`	String	Resource name
`technology`	String	`postgres`, `mongodb`, `snowflake`, etc.
`hostname`	String	Resource hostname
`environment`	String	Environment tag

Policy stages

Session stage

Available inputs

Name	Type	Description
policy_id	STRING	ID of the policy evaluated.
session	Session Object	Formal session identity. Use `input.session.id` for the session ID.
application	STRING	Name of the application.
client_ip_address	STRING	IP address of the client.
tls	BOOLEAN	Tells if the connection between Proxy and client is encrypted with TLS.
db_name	STRING	Name of the database.
native_user	STRING	Native user making a connection to the database.
native_user_assignment	STRING	How the native user was assigned: `user-requested`, `user`, `group`, `default`, or `resource-hostname`.
user	User Object	The user making a connection to the database. User object includes name, email and groups.
end_user	User Object	If the user is a machine user, the end user is the user behind the application, otherwise the end user has the same value as the user.
device	Device Object	Device information.
agent	Agent Object	AI agent context. Populated when the connection originates from an AI coding agent via the Formal Desktop App.
resource	Resource Object	The Resource being queried.
connector	Connector Object	The current Connector.
http	HTTP Object	HTTP request details. Populated for HTTP-based resources, including LLM.
aws	AWS Object	AWS resources for SSH and Kubernetes.
kubernetes	Kubernetes Object	Kubernetes resource context for Kubernetes.
snowflake	Snowflake Object	Snowflake specific information.
space	Space Object	Space specific information.

Available actions

For this policy stage, two types of actions are possible: allow and block.

Request stage

Request rules are evaluated by the proxy when it intercepts a request (query) just before sending it to the resource. This evaluation stage is especially useful in blocking write requests.

Available inputs

Name	Type	Description
policy_id	STRING	ID of the policy evaluated.
session	Session Object	Formal session identity. Use `input.session.id` for the session ID.
request	Request Object	Formal request identity. Use `input.request.id` for the request ID.
application.name	STRING	Name of the application.
client_ip_address	STRING	IP address of the client.
sql_query	SQL Query Object	SQL query.
query	SQL Query Object	SQL query. (alias)
db_name	STRING	Name of the database.
user_type	ENUM	Underlying type used by the user to connect to the database, can be `formal` or `native`.
schema_paths	[]STRING	List of the schema paths that are accessed by a query.
table_paths	[]STRING	List of the table paths that are accessed by a query.
user	User Object	The user making a connection to the database. User object includes name, email and groups.
end_user	User Object	If the user is a machine user, the end user is the user behind the application, otherwise the end user has the same value as the user.
device	Device Object	Device information.
agent	Agent Object	AI agent context. Populated when the connection originates from an AI coding agent via the Formal Desktop App.
space	Space Object	Space information.
row	[]Column Object	Rows of data being queried.
resource	Resource Object	The Resource being queried.
connector	Connector Object	The current Connector.
http	HTTP Object	HTTP request details. Populated for HTTP-based resources, including LLM.
snowflake	Snowflake Object	Snowflake specific information.

Available actions

For this policy stage, four types of actions are possible: allow, block, rewrite, and decrypt.

Response stage

Response rules are evaluated by the proxy when it intercepts data received from the resource. This evaluation stage is particularly useful in the context of masking or filtering read requests.

Available inputs

Name	Type	Description
policy_id	STRING	ID of the policy evaluated.
session	Session Object	Formal session identity. Use `input.session.id` for the session ID.
request	Request Object	Formal request identity. Use `input.request.id` for the request ID.
application	STRING	Name of the application.
client_ip_address	STRING	IP address of the client.
sql_query	SQL Query Object	SQL query.
query	SQL Query Object	SQL query. (alias)
db_name	STRING	Name of the database.
schema_paths	[]STRING	List of the schema paths that are accessed by a query.
table_paths	[]STRING	List of the table paths that are accessed by a query.
table_names	[]STRING	List of the table names that are accessed by a query.
row	[]Column Object	Rows of data being queried.
user	User Object	The user making a connection to the database. User object includes name, email and groups.
end_user	User Object	If the user is a machine user, the end user is the user behind the application, otherwise the end user has the same value as the user.
device	Device Object	Device information.
agent	Agent Object	AI agent context. Populated when the connection originates from an AI coding agent via the Formal Desktop App.
resource	Resource Object	The Resource being queried.
connector	Connector Object	The current Connector.
http	HTTP Object	HTTP response details. Populated for HTTP-based resources, including LLM.
snowflake	Snowflake Object	Snowflake specific information.
space	Space Object	Space specific information.

Available actions

For this policy stage, four types of actions are possible: allow, filter, mask, and encrypt.

Standard input data

Policies can access various data types, including user information, resource information, SQL query information, and HTTP request information. The following sections describe the available data types.

Session object

Value	Type	Description
id	STRING	Formal session identifier

Request object

Value	Type	Description
id	NUMBER	Formal request identifier within the session. Present at request and response stages.

User object

Value	Type	Description
username	STRING	Username of the user
email	STRING	If it’s a human user, their email address
groups	[]STRING	Groups in which the user is included
type	STRING	Type of the user, can be either `human` or `machine`

Connector object

Value	Type	Description
id	STRING	ID of the Connector
name	STRING	Name of the Connector

Resource object

Value	Type	Description
id	STRING	ID of the Resource
name	STRING	Name of the Resource
technology	STRING	Technology of the Resource
hostname	STRING	Hostname of the Resource
hostname_name	STRING	Name of the Hostname of the Resource
environment	STRING	Environment of the Resource
port	STRING	Port of the Resource

Column object

Value	Type	Description
name	STRING	Name of the column
data_label	STRING	Label assigned to the column
json_path	STRING	JSON path of the column
data_type	STRING	Data type of the column
value	STRING	Value of the column
in_functions	[]Function Object	List of functions that the column is used in

input.row lists all columns extracted from your SQL query. A single returned column can come from multiple source columns (e.g. when using wildcards, joins, or unions), and thus result in several policy columns. When the Connector cannot resolve a source, the returned column itself stands in as its own policy column. This column lineage mapping is then used by the Connector’s policy engine: a response rule that masks a policy column will be able to mask every returned column whose lineage includes it. For example, in SELECT email FROM users UNION SELECT email FROM customers, the returned email column has two source columns: users.email and customers.email. Either one alone is enough to mask it for the entire result.

Function object

Value	Type	Description
name	STRING	Name of the function (e.g. `MAX`)
categories	[]STRING	Categories of the function (e.g. `["aggregate", "window"]`)

Function categories are used to group functions into different categories. The following categories are available: aggregate, bitwise, conditional, context, conversion, data_generation, date_time, differential_privacy, encryption, file, geospatial, hash, metadata, notification, numeric, scalar, semi_structured, string_and_binary, system, table, vector_similarity, window. These categories are inspired by the Snowflake documentation.

Space object

Value	Type	Description
name	STRING	Name of the space
id	STRING	ID of the space

HTTP object

Value	Type	Description
hostname	STRING	Upstream hostname (e.g. `api.anthropic.com`)
method	STRING	HTTP method
path	STRING	Request path
headers	OBJECT	HTTP headers as a map from header name to string array. Header names are normalized to lowercase in policy input.
body	STRING	Raw HTTP body, when available
json	OBJECT	Parsed JSON body, when the body is valid JSON and the content type is JSON

Native users

You can enforce policies on native users, the user used by the proxy to connect to the underlying resource. For example, here is a policy that allows the connection only if the native user is reader:

package formal.v2

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

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

session := { "action": "allow", "reason": "reader native user" } if {
	input.native_user == "reader"
}

Native user assignment

The native_user_assignment field tells you how the native user was resolved for the current session. Possible values are:

Value	Description
`user-requested`	The user explicitly specified the native user in the connection
`user`	Assigned via a user identity link
`group`	Assigned via a group membership link
`resource-hostname`	Assigned via a resource hostname link
`default`	Using the default native user for the resource

For example, the following policy blocks connections where the user explicitly overrides their native user assignment:

package formal.v2

import future.keywords.if

default session := { "action": "allow" }

session := { "action": "block", "type": "block_with_formal_message", "message": "Manual native user override is not allowed" } if {
	input.native_user_assignment == "user-requested"
}

Snowflake resources

You can enforce policies on Snowflake resources based on the role used to connect to the resource.

Snowflake object

Value	Type	Description
role	STRING	Role used to connect to the Snowflake resource

SQL resources

Formal can also enforce policies specific to SQL queries. SQL Query Object

Value	Type	Description
query	STRING	SQL query
statement_type	STRING	Type of the SQL statement
command_type	STRING	Type of the SQL command
limit	INT	Limit of the SQL query
transaction_in_progress	BOOLEAN	Whether a transaction is currently in progress. Postgres only.
transaction_history	[]STRING	List of the most recent statements executed in the current transaction (up to 15). Postgres only.

Example: Run all SQL statements in a transaction in order

You can use a workflow to create a policy suspension that ensures a sequence of SQL statements is executed in the correct order within a transaction. The workflow below accepts a list of ordered statements via its API trigger and creates a suspension that validates each statement matches the expected sequence using transaction_history.

trigger:
  type: api-request
  name: my_workflow_trigger
  args:
    allow: <allow expression here>
actions:
- type: formal-app-command
  name: create_policy_suspension
  args:
    app: Policies
    command:
      name: PolicySuspension
      type: Create
    machine_user_id: <machine user id>
    input:
      policy_id: <policy id>
      identity_type: user
      identity_id: ${{trigger.user.id}}
      input_condition: "input.sql_query.transaction_in_progress && size(input.sql_query.transaction_history) < size(${{trigger.payload.transaction}}) && lists.range(size(input.sql_query.transaction_history)).all(i, ${{trigger.payload.transaction}}[i] == input.sql_query.transaction_history[i]) && ${{trigger.payload.transaction}}[size(input.sql_query.transaction_history)] == input.sql_query.query"
      oneoff: false
      expiration_minutes: 60

AWS resources

Formal can also enforce policies on specific AWS Resources. These policies can be actively used for the SSH or Kubernetes.

AWS object

Value	Type	Description
account	Account Object	AWS account
ecs	ECS Object	Configuration details for ECS resources
ec2	EC2 Object	Configuration details for EC2 instances
eks	EKS Object	Configuration details for EKS resources

ECS object

Value	Type	Description
cluster_name	STRING	Name of the ECS cluster
service_name	STRING	Name of the ECS service
task_id	STRING	ID of the ECS task
container_name	STRING	Name of the ECS container

EC2 object

Value	Type	Description
tags	[]STRING	Tags of the EC2 instance
instance_id	STRING	Identifier of the EC2 instance

EKS object

Value	Type	Description
cluster_arn	STRING	Amazon Resource Name (ARN) of the EKS cluster
cluster_name	STRING	Name of the EKS cluster

Kubernetes resources

Formal can enforce policies on Kubernetes API requests based on the resource being accessed. The Kubernetes context is available via input.kubernetes.

Kubernetes object

Value	Type	Description
group	STRING	API group of the resource (e.g. `apps`). Empty string for core API resources.
group_version	STRING	API version of the resource (e.g. `v1`).
namespace	STRING	Namespace of the resource. Empty for cluster-scoped resources.
kind	STRING	Kind of the resource (e.g. `pods`).
name	STRING	Name of the specific resource. Empty for list or collection operations.
subresource	STRING	Subresource being accessed (e.g. `exec`).
verb	STRING	Kubernetes API verb: `get`, `list`, `watch`, `create` or the lower-cased HTTP method for non-resource requests (e.g. `get` for `/healthz`).

LLM resources

Formal can enforce policies on LLM API sessions. Use session rules to block a connection before it reaches the upstream provider, request rules to inspect and rewrite outgoing request headers or bodies, and response rules to evaluate model responses.

Tool calls are part of the model response, so policies that inspect input.llm.tool_calls should use the response rule.

LLM object

Value	Type	Description
`provider`	STRING	LLM provider name (e.g. `anthropic`, `openai`)
`model`	STRING	LLM model name
`request_format`	STRING	Wire format (e.g. `anthropic_messages`, `openai_responses`)
`system_instruction`	STRING	System prompt when present
`messages`	[]Message Object	Request messages and content parts
`tools`	[]Tool Object	Tools declared on the request
`stop_reason`	STRING	Reason the model stopped generating
`input_tokens`	INT	Number of input tokens
`output_tokens`	INT	Number of output tokens
`tool_calls`	[]Tool Call Object	Tool/function calls made by the model
`provider_session_id`	STRING	Provider’s session identifier

Message object

Value	Type	Description
`role`	STRING	Normalized role: `system`, `user`, `assistant`, `tool`
`raw_role`	STRING	Provider role before normalization
`content_parts`	[]Content Part	Text, media, and tool parts in the message

Content part object

Value	Type	Description
`type`	STRING	`text`, `image`, `audio`, `file`, `tool_call`, `tool_result`, or `unknown`
`text`	STRING	Text content when `type` is `text` or `tool_result`
`name`	STRING	Tool name or filename when applicable
`tool_call_id`	STRING	Correlates tool call and tool result parts
`input`	Object	Tool-call arguments when `type` is `tool_call`

Tool object

Value	Type	Description
`name`	STRING	Request-declared tool or function name
`type`	STRING	Request-declared tool type
`description`	STRING	Tool description when present
`input_schema`	Object	Request-declared input schema when available

Tool call object

Value	Type	Description
`name`	STRING	Name of the tool/function called
`id`	STRING	Unique identifier for the call
`input`	Object	Arguments passed to the tool

Example: Rewrite request headers

The following policy adds request headers before the LLM request is sent to the upstream provider. Header values must be arrays of strings. Set a header to an empty array to remove it.

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 request messages

Use a request-stage rewrite with regex.replace on input.http.body to strip sensitive values from prompts without blocking the session. This keeps coding agents usable when SSNs appear in the context window.

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)
}

The rewrite replaces the full HTTP body string. Keep replacements JSON-safe so the upstream request stays valid. See HTTP body rewrites.

Example: Block specific tool calls

The following policy blocks any LLM response that includes a Bash tool call with a specific command:

package formal.v2

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

response := {"action": "block", "type": "block_with_formal_message"} if {
  some tool_call in input.llm.tool_calls
  tool_call.name == "Bash"
  tool_call.input.command == "echo hi"
}

MCP resources

Formal can enforce policies on MCP tool calls. The MCP context is available via input.mcp at the request and response stages when the request is a tool call.

MCP object

Value	Type	Description
`tool_name`	STRING	Name of the MCP tool being called (e.g. `read_file`, `delete_file`)
`tool_params`	Object	Parameters passed to the tool

Example: Block a specific tool

package formal.v2

import future.keywords.if

default request := {"action": "allow"}

request := {"action": "block", "type": "block_with_formal_message"} if {
  input.mcp.tool_name == "list_pull_requests"
}

To seal OAuth Bearer tokens for MCP clients, see Encrypt MCP OAuth Tokens.

Device

Formal can also enforce policies on specific device attributes.

This feature is only available for devices using the Formal Desktop App.

Device info object

Value	Type	Description
hardware	Hardware Info Object	Hardware information of the device
software	Software Info Object	Software information of the device

Hardware info object

Value	Type	Description
model_name	STRING	Model name of the device
model_identifier	STRING	Model identifier of the device
model_number	STRING	Model number of the device
system_firmware_version	STRING	System firmware version of the device
os_loader_version	STRING	OS loader version of the device
serial_number	STRING	Serial number of the device
hardware_uuid	STRING	Hardware UUID of the device
provisioning_udid	STRING	Provisioning UDID of the device
activation_lock_status	STRING	Activation lock status of the device

Software info object

Value	Type	Description
system_version	STRING	System version of the device
kernel_version	STRING	Kernel version of the device
boot_volume	STRING	Boot volume of the device
boot_mode	STRING	Boot mode of the device
computer_name	STRING	Computer name of the device
user_name	STRING	User name of the device
secure_virtual_memory	STRING	Secure virtual memory of the device
system_integrity_protection	STRING	System integrity protection of the device
time_since_boot	STRING	Time since boot of the device

AI agents

Formal tracks connections that originate from AI coding agents running through the Formal Desktop App. When an agent is detected, input.agent is populated with context about that agent.

input.agent is only populated for connections made via the Formal Desktop App. It is empty for direct connections.

Agent object

Value	Type	Description
type	STRING	The agent type (e.g. `claude-code`, `cursor`, `codex_cli_rs`).
provider	STRING	The LLM provider used by the agent (e.g. `anthropic`, `openai`).
provider_session_id	STRING	The LLM provider’s session ID for the current conversation.
version	STRING	The version of the agent.
yolo_mode	BOOLEAN	`true` if the agent was launched with the `--dangerously-skip-permissions` flag. This flag is specific to Claude Code and bypasses its interactive permission prompts, allowing it to execute tool calls without user confirmation.

Example: block Claude Code in YOLO mode

Use input.agent.yolo_mode to block autonomous agents from accessing sensitive resources without per-action approval:

package formal.v2

import future.keywords.if

default session := {"action": "allow"}

session := {"action": "block", "type": "block_with_formal_message"} if {
    input.agent.yolo_mode == true
}

Policy Input Retention

Formal can optionally retain these inputs for policy backtesting where you can test policies on historical data.

Extending Policies with External Data

You can extend policies with custom data fetched by Policy Data Loaders. The data is accessible via the data object using the loader’s configured key. Example:

# If your Policy Data Loader has key "approved_users"
data.approved_users.user_ids

For more information, see Policy Data Loaders.

Legacy Stage Names

Prior to Connector v1.31.19, the Rego rule names for the request and response stages were pre_request and post_request. These legacy names still work and existing policies do not need to be updated. To migrate, rename pre_request to request and post_request to response in your policy code. Different policies can use different naming conventions.

​Policy Scope

​User Context Quick Reference

​Resource Context Quick Reference

​Policy stages

​Session stage

​Available inputs

​Available actions

​Request stage

​Available inputs

​Available actions

​Response stage

​Available inputs

​Available actions

​Standard input data

​Session object

​Request object

​User object

​Connector object

​Resource object

​Column object

​Function object

​Space object

​HTTP object

​Native users

​Native user assignment

​Snowflake resources

​Snowflake object

​SQL resources

​Example: Run all SQL statements in a transaction in order

​AWS resources

​AWS object

​ECS object

​EC2 object

​EKS object

​Kubernetes resources

​Kubernetes object

​LLM resources

​LLM object

​Message object

​Content part object

​Tool object

​Tool call object

​Example: Rewrite request headers

​Example: Redact SSNs from request messages

​Example: Block specific tool calls

​MCP resources

​MCP object

​Example: Block a specific tool

​Device

​Device info object

​Hardware info object

​Software info object

​AI agents

​Agent object

​Example: block Claude Code in YOLO mode

​Policy Input Retention

​Extending Policies with External Data

​Legacy Stage Names

Policy Scope

User Context Quick Reference

Resource Context Quick Reference

Policy stages

Session stage

Available inputs

Available actions

Request stage

Available inputs

Available actions

Response stage

Available inputs

Available actions

Standard input data

Session object

Request object

User object

Connector object

Resource object

Column object

Function object

Space object

HTTP object

Native users

Native user assignment

Snowflake resources

Snowflake object

SQL resources

Example: Run all SQL statements in a transaction in order

AWS resources

AWS object

ECS object

EC2 object

EKS object

Kubernetes resources

Kubernetes object

LLM resources

LLM object

Message object

Content part object

Tool object

Tool call object

Example: Rewrite request headers

Example: Redact SSNs from request messages

Example: Block specific tool calls

MCP resources

MCP object

Example: Block a specific tool

Device

Device info object

Hardware info object

Software info object

AI agents

Agent object

Example: block Claude Code in YOLO mode

Policy Input Retention

Extending Policies with External Data

Legacy Stage Names