Tool Policies - Unbound Security

What are Tool Policies?

Tool Policies monitor and control actions taken by AI coding tools in your organization. Create policies to track, warn on, or block terminal commands executed by AI agents or MCP tool calls made through integrated servers like GitHub, Linear, Sentry, and more. Skill policies work the other way. They don’t stop an action. They make the agent load your guidance before it acts. Every policy type has a worked example under Examples. Dashboard: Policies → Agentic Use (gateway.getunbound.ai/policies/agentic-use)

Policy Types

Create Policy asks what you want to monitor:

Terminal Commands

Monitor shell commands run by the agents Unbound governs — Claude Code, Claude Cowork, Cursor, Codex, GitHub Copilot, Augment Code and Pi (Beta). Agent Coverage has what each one supports. The file families — read_file, write_file and delete_file — also cover the agent’s own file tools, not just the shell. A policy on delete_file catches an agent deleting a path with its built-in delete tool as well as with rm, so you write the rule once rather than per route. Which of those tools are covered varies by agent:

Agent	Its own file tools that are matched
Claude Code, Claude Cowork	read, write, edit
Augment Code	read, write, edit, delete
GitHub Copilot	read, write, edit
Cursor	read, write, delete
Codex	its patch tool only
Pi (Beta)	read, write, edit, and search (`grep` / `find` / `ls`)

So a delete_file rule catches Codex deleting through the shell (rm) but not through its own tooling, and Copilot and Pi have no delete tool to catch. A rule that must hold on every agent should target the shell as well. This holds for Block, Warn and Require Slack Approval. An Audit policy on its own covers the shell route but not the agent’s own file tools — pair it with one live rule on the same family, or start the rule on Warn, if you need both routes covered.

Select a Command Family (e.g., delete_file, git_action, remote_access)
Set Match Against to the command field you want to inspect (e.g., path, branch, or Any)
Define a Pattern to match specific paths, branches, or operations
Supports exact match, glob patterns (/etc/*), and regex (.*\.env$)

Every family, and the fields each one lets you match on, is listed under Command family reference.

Unless you say which you wrote, Unbound reads your pattern as regex, glob or exact from its syntax — and the reading can surprise you. .*bastion.* comes out as a regex; prod.* as a glob in which the . is a literal dot; *prod*|*production* as a regex that isn’t valid, so it matches nothing.Settle it with a prefix — regex:, glob: or exact:. regex:prod.*, regex:prod|production and glob:*prod* all do what they look like. (A glob already matches production from *prod*, so the regex is often unnecessary.)Globs are anchored to the whole value, regexes are an unanchored substring search, and both ignore case. A plain string with no wildcards is an exact match, so prod on its own does not match production.

Ask AI: describe what you want to govern in plain English — for example, “block any command that writes to the production database” — and Unbound drafts the policies for you to review, edit and save. The saved policies are ordinary command-family rules.

MCP Actions

Monitor tool calls made through MCP (Model Context Protocol) servers.

Select an MCP Service — a canonical service such as GitHub, Linear, or Slack. This is the required first field (“Select a service…”). Picking a service applies the policy across every connected MCP server that maps to it, so you don’t name individual server instances.
Select one or more MCP Tools to monitor (e.g., create_pull_request, create_issue). A service and at least one tool are both required.

Each MCP tool call also carries an action type — read, write, or destructive. Action type, and targeting one specific raw server instance instead of the canonical service, are available only through the policy API — the create-policy modal always targets a canonical MCP Service and its tools.

If you are building an MCP server that calls back into Unbound for policy checks, manage your MCP credentials on the MCP Connections page in the dashboard.

Skills

A skill policy makes the agent load your guidance before it acts. You attach a skill, which is a SKILL.md body, and say when it applies. Unbound then has the agent invoke the skill first. A skill policy never stops work for good. Where an action must stop, use Block or Require Slack Approval on a terminal or MCP policy. Pick one trigger:

Trigger	Match on	What happens
Before the agent runs a command	A Command Family and its patterns, a Project path (regex), or both	Unbound refuses the first matching command once and tells the agent to invoke the skill. The retry goes through
When the user sends a message	A Prompt pattern (regex), a Project path (regex), or both	The message goes through. Unbound tells the agent to invoke the skill before it does anything else

Then fill in the skill:

Field	What it takes
Slug	The skill’s name after a fixed `unbound-` prefix. Lowercase letters, digits and hyphens, up to 56 characters
Skill Body	The `SKILL.md` body, up to 51,200 characters. Copy from Discovered Skill copies one that Discovery found on your fleet
Message	Optional. What the agent reads when Unbound refuses the command. Up to 500 characters, and it must include `{{skill_name}}`

MCP tool calls never trigger a skill policy.
Unbound installs the skill into each covered developer’s agent when a session starts. It removes the skill when you delete or turn off the policy.
Unbound asks for at most one skill per turn and five skills per conversation.
If Unbound can’t evaluate the policy, the command goes through.
Claude Code, Codex, GitHub Copilot and Cursor support skill policies. Augment Code and Pi don’t.

A skill policy has no Action to pick. The policy list shows it as Inject Skill. Skills appears in Create Policy only where your organization has it turned on.

Unsanctioned MCP servers

The policies above target servers you know about. Developers also connect servers you don’t — that’s where a task quietly becomes an exfiltration path. Mark the servers you approve of as sanctioned, and Unbound governs everything else as a group. You choose how, org-wide:

Mode	What happens to an unsanctioned server
Off (where a new organization starts)	Every MCP server is allowed. You can still build the sanctioned list while it is Off, and arm it later.
Warn	The tool call is allowed and recorded as warned. The agent is told the server isn’t sanctioned, and it shows up in your Unsanctioned Usage view.
Block	The tool call is denied. You can set a custom message explaining why, so the developer knows what to do next.

Set the mode from Configure → Sanction MCP Servers. Block and Warn both need at least one sanctioned server, and either mode lets you attach a message of up to 500 characters. Start on Warn to see what your developers are actually reaching for without breaking their work, then move to Block once you’ve sanctioned the servers you’re happy with. Under Warn there is one more choice, for runs with nobody to read the notice — headless Claude Code, or the Agent SDK. Pick Allow (the default — the request proceeds like any other allowed request) or Deny (the request is refused and appears under Unsanctioned Usage). While the mode is Block, Disable Blocking Temporarily — in the same dialog, admin only — suspends blocking org-wide for 24 hours or a week without dismantling the sanctioned list. Useful when an unsanctioned server turns out to be needed mid-incident. It appears only under Block.

New unsanctioned tools can be pushed to your SIEM the moment they appear — see the Shadow AI events in Webhooks. To see what’s already out there, use AI Tools Discovery.

Command family reference

A terminal policy targets one command family and matches a pattern against one or more of that family’s fields. The picker groups the families the way they are listed here, and marks the high- and medium-risk families with a coloured dot (red for high, amber for medium); a low-risk family carries no dot. Field names appear title-cased in the dashboard (query_type reads as “Query Type”); the raw names below are what the API and CLI take. Run unbound policy tool families to print the same list, with each family’s fields and risk level.

Custom

Family	Match against	What it catches
`custom`	`command`	One pattern against the whole raw command line, for every command an agent runs, whatever family it falls into. The escape hatch for a rule no field expresses — a specific script, a particular flag, an interactive root shell

System

Family	Risk	Match against	What it catches
`update_system_file`	High	`path`, `operation`	Edits to system files — in-place `sed`, `chmod`, writes under `/etc`
`package_management`	High	`package`, `manager`, `operation`	`npm`, `pip`, `brew` and friends installing, updating, auditing or removing packages
`environment_setup`	Medium	`variable`, `value_pattern`, `scope`, `method`	Changing the environment — `export`, `source`, activating a virtualenv, `gcloud config set`
`build_operation`	Medium	`target`, `environment`, `tool`, `package`	Builds, type-checks, lints and test targets run through `tsc`, webpack, gradle

Filesystem

Family	Risk	Match against	What it catches
`delete_file`	High	`path`, `operation`	Deletions — `rm`, `unlink`, `rmdir`
`write_file`	Medium	`path`, `operation`	Writes, appends and backups to a path
`read_file`	Low	`path`	Reads of a path

Process

Family	Risk	Match against	What it catches
`process_management`	High	`process`, `signal`, `pid`, `service`, `tool`	Signalling or restarting a process or service — `kill`, `pkill`, `systemctl`
`execute_script`	Medium	`script_path`, `interpreter`, `arguments`	Running a script through an interpreter — `python3`, `node`, `bash`
`update_cron`	Medium	`schedule`, `command`, `operation`	Creating, patching or suspending a scheduled job

Network

Family	Risk	Match against	What it catches
`remote_access`	High	`host`, `port`, `user`, `protocol`	Opening a session to another host — `ssh`, `scp`
`remote_execution`	High	`target_host`, `script_name`, `operation`	Running a command somewhere else — `kubectl exec`, `ssh <host> <cmd>`, an Ansible playbook
`data_transfer`	Medium	`destination`, `protocol`, `operation`	Moving data in or out — `curl`, `wget`, `scp`, `rsync`, an `s3://` target

Container

Family	Risk	Match against	What it catches
`container_operation`	High	`container`, `image`, `operation`, `resource`, `namespace`, `runtime`	Docker, Kubernetes and Podman actions on containers, images, volumes and networks — `exec`, `rm`, `stop`, `push`, `run`

Cloud

Family	Risk	Match against	What it catches
`cloud_provision`	High	`provider`, `service`, `operation`, `resource`, `environment`	Creating or changing infrastructure — `create`, `apply`, `deploy`, `scale`
`cloud_destroy`	High	`provider`, `service`, `operation`, `resource`, `environment`	Tearing infrastructure down — `delete`, `destroy`, `terminate`, `drain`
`cloud_iam`	High	`provider`, `service`, `operation`, `principal`, `environment`	Identity and access changes — creating users, attaching policies, granting and revoking
`cloud_secrets`	High	`provider`, `service`, `secret_name`, `operation`, `environment`	Reading or writing a managed secret — Secrets Manager, KMS, SSM, Vault, a Kubernetes secret
`cloud_config`	Medium	`provider`, `service`, `config_key`, `operation`, `environment`	Switching project, region, context or a ConfigMap
`cloud_read`	Low	`provider`, `service`, `query_type`, `resource`, `environment`	Inspecting cloud state — `get`, `list`, `describe`, `plan`, `logs`

Security

Family	Risk	Match against	What it catches
`access_password`	High	`target`, `credential_type`, `location`	Fetching or printing a credential — an access token, an API key, a connection string
`privilege_escalation`	High	`method`, `target_user`, `original_command`	`sudo`, `su`, `doas`, `pkexec` — and the command being elevated
`environment_exposure`	Medium	`method`, `variable_pattern`, `source`	Dumping environment variables — `env`, `printenv`, `cat .env`, `docker inspect`

Version control

Family	Risk	Match against	What it catches
`git_action`	Medium	`branch`, `remote`, `repo`, `operation`	Git operations — `push`, `pull`, `commit`, `merge`

Database

Family	Risk	Match against	What it catches
`database_admin`	High	`database`, `table`, `operation`, `environment`	DDL and grants — `CREATE`, `DROP`, `ALTER`, `TRUNCATE`, `GRANT`, migrations
`database_write`	Medium	`database`, `table`, `operation`, `environment`	`INSERT`, `UPDATE`, `DELETE`
`database_read`	Medium	`database`, `table`, `query_type`, `environment`	`SELECT`, `describe`, listing tables

Analytics shows a few further families that the policy picker does not offer. Those commands appear in your activity view, but you cannot write a rule against them. The picker is the authoritative list of what a terminal rule can target.

Matching rules

These apply to every terminal policy. Several conditions AND together. Add one condition per field and all of them must match. A field may appear only once. Any is on its own. Setting Match Against to Any tests your pattern against every field the family carries, so it cannot be combined with a named field. The same value can be written several ways, and one pattern catches all of them.

A field holding a host or URL (remote_access.host, remote_execution.target_host, data_transfer.destination) matches on the bare host only: https://user@evil.com:8443/google.com matches evil.com, and nothing in a path or query string can pose as the host.
A path matches however it is written: ~/.aws/credentials, .aws/credentials and /Users/you/.aws/credentials all match each other. A glob with no / in it matches against the file name alone, so .env* catches /srv/app/.env.local.
A kubectl short name counts as the full resource, so a service pattern of deployment also matches kubectl ... deploy.

A read_file policy also covers secret reads. Credential reads land in access_password, environment_exposure or database_admin rather than read_file, and a read_file policy fires on those families too — still gated by its own path pattern, so a read_file rule on *.ts does not start matching .pem reads. The broadening runs one way only: a secret-scoped policy stays precise. The Custom family is what holds when a command cannot be placed. A command Unbound cannot place in a family matches no family-based rule, and is allowed rather than blocked — so a family-based rule is not unconditional. A Custom rule still fires on that command, because it matches the raw command line. Custom is not unconditional either: a Custom pattern that fails to evaluate is allowed through rather than blocked. Custom also covers an agent’s own file tools — a native read, write, edit or delete matches as its shell equivalent (cat <path>, echo "..." > <path>, rm <path>), so write the pattern against that form and one rule covers both routes. Regex in a Custom pattern has to be portable. A Custom pattern is checked when you save it, and lookahead ((?=, (?!), lookbehind ((?<=, (?<!), atomic groups and backreferences (\1, \k<name>) are refused, along with other constructs that are not portable between regex engines — write a character class or an explicit escape instead. The save fails with the construct named. An ordinary field pattern has no such restriction. An empty pattern means “any value for this field”. The rule then fires whenever the field is present at all, whatever it holds. The dashboard requires a pattern, and so does the CLI’s --field, so this one is only reachable by handing the config JSON over directly — the CLI’s --config flag, or the policy API. In the dashboard, use * instead.

Actions

Each tool policy has an action that decides what happens on a match. A skill policy has no action to pick. See Skills.

Action	Behavior
Block	Reject the command or tool call entirely. The action is prevented from executing.
Warn	Ask the developer to confirm before the action runs, and record it either way. What a developer actually sees depends on the agent: it prompts on Claude Code (used interactively), Copilot, Claude Cowork and Pi; on Cursor the action runs with no Unbound prompt; on Augment Code the prompt comes from Augment’s own tool-permission settings, which the Unbound installer seeds, rather than from the policy; on Codex and OpenClaw it stops the command outright. Where Claude Code runs headless there is no prompt to show, so Warn allows the command through unless your organization has set the headless Warn action to Block. Treat Warn as a confirmation step, not a security boundary — use Block or Require Slack Approval where the action must actually be stopped.
Audit	Silently log the action for monitoring. No user-facing impact. Available for reporting and analytics.
Require Slack Approval	Hold the command in a pending state and send an interactive Slack DM to the developer who ran the command (or, if their Slack account cannot be found, to an org admin). Whoever receives it can Allow Once, Allow 1 hour or Deny Once. If it cannot be delivered to either, the command is refused. The agent retries automatically after a decision. Requires the Slack integration to be configured.

Block and Warn both carry an Enforcement Message — up to 500 characters, shown to the developer and read back by the agent when the policy fires.

Allow 1 hour is a blanket grant, not a one-command exception. For the hour that follows, every command matching the same set of policies goes through without a new Slack request.

When more than one policy matches

Every tool policy that matches is evaluated — there is no single winner and no priority ordering. The strictest action decides what happens to the command: Block → Require Slack Approval → Warn → Audit So a command caught by a Warn rule and a Block rule is blocked. For a terminal command, only the policy that actually enforced gets a match row in its history: when Block wins, the Warn rule that also matched is not credited with the match. For an MCP tool call every matched policy is recorded, so its history can show a match the rule did not enforce. An Audit policy records the command instead of acting on it, so it has no user-facing effect and never combines with the live actions above. A skill policy sits between Block and the rest. When a Block rule also matches, Unbound blocks the command and asks for no skill. Otherwise the skill request comes first. The agent loads the skill, and on the retry any matching Require Slack Approval or Warn rule applies as usual. Policy names are unique within your organization.

Applying to Users

By default, a tool policy with no user groups applies to everyone in your organization. To restrict a policy to specific teams, assign it to one or more user groups during creation or editing. When a user group is modified, policy enforcement updates automatically for all affected users.

You can manage user groups from the User Groups page. Create groups based on teams, roles, or projects to apply different policies to different sets of users.

Policy Coverage

The Policy Health view in the Tool Policies dashboard shows which command families and MCP tool categories have no active policies — coverage gaps where agent actions are completely unmonitored. Open the Policy Health tab, then switch between the Terminal and MCP sub-views to see coverage for each.

Risk-score policies

A Risk Score policy acts on MCP tool calls whose risk score meets or exceeds a configured risk_score_threshold, independent of any specific server or tool. A call’s score follows what the tool does — a read scores lower than a write, and a write lower than something destructive.

Risk Score policies apply to MCP tool calls only. Terminal commands carry a risk score of their own, which you can see and filter on in Analytics, but a Risk Score policy does not act on them — use a command-family policy for terminal rules.

risk_score_threshold is an integer from 1–10.
A lower threshold fires the action on more tool calls; a higher threshold reserves it for the highest-risk calls.

Risk Score policies are their own policy type — they don’t carry a command family or pattern — and are created through the policy API.

Risk Score policies are currently API-only — they aren’t yet exposed in the create-policy modal.

Policy Recommendations

The dashboard surfaces policy suggestions from observed agent activity. Each recommendation identifies either a complete gap (no policy covers this command or tool type at all) or a partial gap (a policy exists but doesn’t match all observed variants). Recommendations appear automatically as your agents run. You can create the suggested policy directly from the recommendation card, or dismiss it.

Examples

Each example starts from Policies → Agentic Use → Create Policy. Where the CLI can create the same policy, its command follows.

Use Preview Impact when creating a policy to see how many historical commands match your pattern before deploying. Terminal Command policies always offer it. For MCP Actions policies it is switched on per organization, so if the button is absent, contact support — the policy can still be saved without it. The other policy types do not offer it.

Terminal Commands: audit deletions of sensitive files

Select Terminal Commands
Fill in the form:
- Name: “Audit Sensitive File Deletions”
- Command Family: delete_file
- Match Against: path
- Pattern: /etc/* or *.env
Set Action to Audit
Optionally select User Groups to limit the policy to specific teams
Click Preview Impact to see historical matches
Click Create Policy

unbound policy tool create-terminal --no-ai \
  --name "Audit Sensitive File Deletions" \
  --command-family delete_file \
  --field path='*.env' \
  --action AUDIT

Terminal Commands: require approval to push to main

Two conditions on one family, both of which must match.

Select Terminal Commands
Name: “Approve pushes to main”
Command Family: git_action
Add two conditions:
- Branch = main
- Operation = push
Action: Require Slack Approval
Click Create Policy

unbound policy tool create-terminal --no-ai \
  --name "Approve pushes to main" \
  --command-family git_action \
  --field branch=main \
  --field operation=push \
  --action REQUIRE_SLACK_APPROVAL

Terminal Commands: block one exact command

The Custom family matches the whole command line, for a rule no field expresses.

Select Terminal Commands
Name: “Block the release script”
Command Family: custom
Pattern: make release-prod
Action: Block, with the Enforcement Message “Use the release pipeline instead.”
Click Create Policy

unbound policy tool create-terminal --no-ai \
  --name "Block the release script" \
  --command-family custom \
  --field command='make release-prod' \
  --action BLOCK \
  --custom-message "Use the release pipeline instead."

MCP Actions: confirm before merging a pull request

Select MCP Actions
Name: “Confirm PR merges”
MCP Service: GitHub
MCP Tools: merge_pull_request
Action: Warn, with the Enforcement Message “Merging needs a reviewer’s sign-off. Confirm one has approved.”
Click Create Policy

unbound policy tool create-mcp --no-ai \
  --name "Confirm PR merges" \
  --mcp-server GitHub \
  --mcp-tool merge_pull_request \
  --action WARN \
  --custom-message "Merging needs a reviewer's sign-off. Confirm one has approved."

To cover every write on a service rather than one tool, the CLI also takes an action type:

unbound policy tool create-mcp --no-ai \
  --name "Audit Linear writes" \
  --mcp-server Linear \
  --mcp-action-type write \
  --action AUDIT

Unsanctioned MCP servers: warn before blocking

Open Configure → Sanction MCP Servers
Mark the servers your teams may use as sanctioned
Set the mode to Warn, with a message such as “This MCP server is not approved. Request it in #it-help.”
Watch the Unsanctioned Usage view for a week, and sanction anything legitimate that shows up
Switch the mode to Block

Skills: load SQL guidance before database commands

Select Skills
Policy Name: “Secure SQL guidance”
When: Before the agent runs a command
Command Family: custom, Pattern: ^(psql|mysql)\b
Slug: secure-sql

Skill Body: paste the guidance, or click Copy from Discovered Skill to reuse one your teams already have:

---
name: unbound-secure-sql
description: Rules for running SQL against company databases.
---

- Connect to a read replica unless the task needs a write.
- Wrap every UPDATE or DELETE in a transaction, and run the matching SELECT first to show the rows it touches.
- Never run DROP or TRUNCATE. Ask the user to do it.

Leave Message empty to use the default wording
Click Create Policy

The first time the agent runs psql in a session, Unbound refuses the command once. The agent invokes unbound-secure-sql, reads the rules, and runs the same command again, which goes through.

Skills: load the release checklist when someone asks to ship

Select Skills
Policy Name: “Payments release checklist”
When: When the user sends a message
Prompt pattern (regex): deploy|release|ship it
Project path (regex): /payments-service$
Slug: payments-release, and paste the checklist as the Skill Body
Optionally select User Groups, such as the payments team
Click Create Policy

When a developer in the payments-service folder types “ship it”, the message goes through, and the agent invokes unbound-payments-release before it starts work.

Risk Score: warn on high-risk MCP calls

You create Risk Score policies through the policy API, with an admin API key. That’s the same key unbound login --api-key takes:

curl -X POST https://backend.getunbound.ai/api/v1/command-policies/ \
  -H "Authorization: Bearer $UNBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warn on high-risk MCP calls",
    "policy_type": "RISK_SCORE",
    "risk_score_threshold": 8,
    "action": "WARN",
    "custom_message": "This tool call is high risk. Confirm it is intended."
  }'

A threshold of 8 reserves the warning for the riskiest calls, such as destructive ones, and leaves ordinary reads and writes alone. The API rejects the request if it also carries a command family, a config, or an MCP server or tool. On a private deployment, use your own backend host.

Tool Policies vs Security Policies

Tool policies and security policies are managed independently:

	Tool Policies	Security Policies
Purpose	Control terminal commands and MCP tool calls, and load guidance before the agent acts	Protect sensitive data with guardrails
Covers	Terminal command families, MCP server/tool actions, skills	PII detection, secrets detection
User group scoping	Directly on the tool policy	Directly on the security policy
Actions	Block, Warn, Audit, Require Slack Approval; skill policies require a skill instead	Block, Audit

Slack Integration

Set up Slack for interactive approval workflows

CLI Policy Management

Create and manage tool policies from the terminal

​What are Tool Policies?

​Policy Types

​Terminal Commands

​MCP Actions

​Skills

​Unsanctioned MCP servers

​Command family reference

​Custom

​System

​Filesystem

​Process

​Network

​Container

​Cloud

​Security

​Version control

​Database

​Matching rules

​Actions

​When more than one policy matches

​Applying to Users

​Policy Coverage

​Risk-score policies

​Policy Recommendations

​Examples

​Terminal Commands: audit deletions of sensitive files

​Terminal Commands: require approval to push to main

​Terminal Commands: block one exact command

​MCP Actions: confirm before merging a pull request

​Unsanctioned MCP servers: warn before blocking

​Skills: load SQL guidance before database commands

​Skills: load the release checklist when someone asks to ship

​Risk Score: warn on high-risk MCP calls

​Tool Policies vs Security Policies

Slack Integration

CLI Policy Management

What are Tool Policies?

Policy Types

Terminal Commands

MCP Actions

Skills

Unsanctioned MCP servers

Command family reference

Custom

System

Filesystem

Process

Network

Container

Cloud

Security

Version control

Database

Matching rules

Actions

When more than one policy matches

Applying to Users

Policy Coverage

Risk-score policies

Policy Recommendations

Examples

Terminal Commands: audit deletions of sensitive files

Terminal Commands: require approval to push to main

Terminal Commands: block one exact command

MCP Actions: confirm before merging a pull request

Unsanctioned MCP servers: warn before blocking

Skills: load SQL guidance before database commands

Skills: load the release checklist when someone asks to ship

Risk Score: warn on high-risk MCP calls

Tool Policies vs Security Policies