> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/creating-an-ai-agent-security-policy.md). # Creating an AI Agent Security Policy AI Agent Security policies are configured as exfiltration policies in Nightfall. This guide walks through each step of the policy creation wizard, and how the same wizard behaves for device hooks and for Claude Inference Hooks. Checked against production on 28 September 2026. Inference Hooks still evaluate **User Prompts** only. A policy saved with content scanning off applies on scope: Block denies every covered event, and Monitor records every covered event. For recommended policies, see [Hook policy recommendations](/data-exfiltration-prevention/ai-agent-security/ai-governance/hook-policy-recommendations.md). ### Getting started 1. Navigate to Configuration > Policies > Exfiltration. 2. Click + New Policy. 3. Select AI Agent Security as the integration type. ### Step 1: Choose hook types Enable one or more hook types. Each can be independently toggled. | Hook type | What it scans | Can block on device hooks | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | User Prompts | Prompt text before it reaches the model | Yes | | Tool Calls | MCP tool calls and subagent launches: tool name and input, before execution | Yes | | Tool Responses | MCP tool output after execution, before the model reads it | Yes, on the macOS and Windows agents. Not on VS Code Copilot | | Shell Commands | Terminal commands and the agent's built-in file tools (read, write, edit), before execution. File content the agent writes is scanned here | Yes | | Model Responses | Model response after it is generated | No. Monitor only | The action is set once for the whole policy, not per hook type. Because Model Responses can only record, put it in a separate Monitor policy. ### Inference Hooks versus device hooks Use two policies. Do not put both jobs in one. | | Device hooks (Claude Code, Cursor, VS Code) | Claude Inference Hooks | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hook types that fire | The ones you select | **User Prompts** only. Tool Calls, Tool Responses, Shell Commands, and Model Responses do not arrive | | When a tool or shell is stopped | Before it runs, if that hook type is selected and the policy is set to Block | Never. The tool has already run by the time its text is in the prompt | | MCP server scope | Applies. Cursor often cannot name the server, so treat Cursor as All MCP servers | Leave on **All MCP servers**. A tool narrowing does not apply to an ordinary chat turn | | Needs the agent and MDM | Yes. [Setup and Installation](/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/setup-and-installation.md) | No. [Connect Inference Hooks](/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/setup-and-installation/connect-inference-hooks.md) | Existing device policies do not automatically cover Inference Hooks. Opt this traffic in on its own policy, with **User Prompts** selected. ### Step 2: MCP server scope Defines which MCP servers this policy is evaluated against on device hooks. This scope applies to Tool Calls and Tool Responses. It does not apply to Shell Commands or to the agent's built-in file tools. What happens when a match occurs is configured under Actions. * All MCP servers. The policy applies to every connected MCP server. * Specific MCP servers. The policy applies only to a chosen list. * All except these MCP servers. The policy applies to every server except a chosen list. When you select Specific or All except, pick MCP server collections or wildcard patterns. Nightfall identifies the server from the tool name. Clients format names differently. | AI client | Tool name format | Example | Server identified? | | -------------- | --------------------- | ---------------------- | ------------------ | | Claude Code | mcp\_\_server\_\_tool | mcp\_\_github\_\_fetch | Yes | | GitHub Copilot | mcp\_server\_tool | mcp\_github\_fetch | Usually | | Cursor | MCP:tool | MCP:fetch | No | Cursor activity under a server-specific policy is treated as All MCP servers. Pair a server-specific policy with an All MCP servers rule if you need Cursor covered. On Inference Hooks, leave scope on All MCP servers. ### Step 3: Shell command patterns When Shell Commands is enabled on a device-hook policy, you can include or exclude command patterns. Leave it empty to scan every shell command and file write. This step does nothing for Inference Hooks, because shell commands are not a separate check there. ### Step 4: Detection rules and content scanning Turn **content scanning on** and select detectors when you want the policy to fire only on sensitive data: PII, credentials, custom regex, dictionaries, or classifiers. {% hint style="warning" %} Content scanning off is enforced. It does not wait for a detector, and it is not a disabled policy. **Block** denies every event the policy covers. **Monitor** records a violation on every event and lets it through. On Inference Hooks that is every User Prompt. On device hooks it is every selected hook type. Turn content scanning on, and add at least one detection rule, unless you intend to stop or record all of that traffic. {% endhint %} A content-scanning policy still needs a detector match before it blocks. A clean prompt is allowed. Do not add the source code classifier to agent policies. Coding agents read and write code as their normal work, so it would match almost every event. ### Step 5: Actions and alerts | Action | Behavior | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Block | The action is denied. On device hooks the person sees the block message in the client. On Inference Hooks they see Nightfall's reason plus the standing message in the Claude admin. | | Monitor | The action proceeds. An incident is created. | Admin alerts: Slack, Jira, email, or webhook. End-user notification email and override with justification are not available on this policy type. The block text shown in Cursor, Claude Code, and VS Code is the custom block message on the policy. ### Example: block credentials before a coding agent acts Device hooks. Claude Code, Cursor, and VS Code. 1. Hook types: User Prompts, Tool Calls, Tool Responses, Shell Commands. 2. MCP server scope: All MCP servers. Shell command patterns: empty. 3. Content scanning on. Detection rules: credentials and API keys, passwords, private keys. 4. Action: Block. 5. Alerts: Slack and email. Record model replies in a second policy, with Model Responses selected and the action set to Monitor. ### Example: block sensitive Claude Enterprise prompts Inference Hooks. One policy, **User Prompts** only, All MCP servers, content scanning on. Start in Anthropic shadow mode. Switch the Nightfall action to Block when you turn enforcement on. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.nightfall.ai/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/creating-an-ai-agent-security-policy.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.