Azure Prompt Shields: REST Detection and Policy Boundaries

Azure Prompt Shields accepts a user prompt and document text, then returns separate attack findings for each input surface. The standalone Azure AI Content Safety endpoint answers a narrow detection question. Application code still decides if a flagged prompt gets blocked or sent for review. It separately decides when to allow it. It also decides if the authenticated caller may use the requested model and data.

I want to keep those decisions separate because a green attack result can look reassuring in a console while the request still violates enterprise policy.

TL;DR

• Azure Prompt Shields detects user prompt attacks and document attacks in text supplied by the application.
• The standalone REST route is POST <endpoint>/contentsafety/text:shieldPrompt?api-version=2024-09-01, authenticated with the Content Safety subscription key in Ocp-Apim-Subscription-Key.
• The response has a Boolean for the user prompt and each submitted document. Direct API integrations own allow, block, review, or exclusion logic.
• Foundry guardrail configuration can filter detected attacks before model processing. User prompt attack detection is enabled by default, while document attack detection starts disabled.
• Attack detection remains separate from identity-aware request policy, which evaluates the caller, role, data class, model destination, and active policy version.

Prompt Shields has two detection inputs

Microsoft's Prompt Shields concept documentation defines user prompt attacks as attempts to bypass system instructions or safety training. Examples include instructions to replace system rules, adopt an unrestricted persona, imitate prior conversation turns, or use encoding to evade controls.

Document attacks place hostile instructions inside content such as retrieved pages, emails, uploaded files, model-generated text, or tool responses. The application submits that material through the documents array. Microsoft leaves provenance to the customer integration. Your code determines which bytes came from a user and which came from an external document.

Preserve that split through prompt assembly. If retrieval code concatenates five sources into the userPrompt string, Prompt Shields runs the user-prompt analysis against the combined text. It loses the document boundary your application discarded. Keep source identity while normalizing the text. Send untrusted source material in documents.

Prompt Shields detects attack patterns. Microsoft explicitly separates that job from harmful-content classification, factual accuracy, groundedness, policy compliance, and task alignment. Assign those questions to their named controls.

The standalone REST request is explicit

The current Microsoft Prompt Shields REST quickstart uses this request boundary:

• Method and route: POST <endpoint>/contentsafety/text:shieldPrompt?api-version=2024-09-01
• Authentication header: Ocp-Apim-Subscription-Key: <your_subscription_key>
• Media type: Content-Type: application/json
• User input field: userPrompt, containing the text selected for user prompt attack analysis
• External-content field: documents, containing an array of strings selected for document attack analysis

Keep the endpoint and subscription key in a secret store rather than source control. Build the JSON with a serializer. A prompt containing quotation marks or line breaks should remain data, rather than breaking a hand-built request body. Set a request timeout. Define the failure action before production traffic reaches this path.

The whiteboard version should show the application calling the Content Safety endpoint before the model endpoint. Draw the Prompt Shields call before the model call, then write the timeout action beside that arrow. A blank space there usually means the first outage will define the security policy.

The standalone endpoint accepts up to five documents according to Microsoft's current concept page. An application with more sources needs a documented strategy. It can select the highest-risk sources or combine text while preserving source markers. Additional checks are another option. Record which documents were assessed so an incident review can distinguish scanned context from omitted context.

Response handling belongs in application policy

The REST response places attackDetected under userPromptAnalysis. It returns a documentsAnalysis array with an attackDetected Boolean for each submitted document. Preserve document order or attach your own correlation map outside the API payload. A log entry saying documentsAnalysis[2] = true has little investigative value unless an operator can map index 2 to the retrieved URL or file identifier. A content hash can provide another mapping.

Define actions by input surface. A detected user prompt attack may produce a deny response and a security event. A detected document attack may exclude that source or rerun retrieval. It may instead stop the request. Human review can fit high-value workflows, but the queue needs a timeout and an owner. The standalone API supplies the signal. Your application owns blocking and routing.

A false result carries the same narrow meaning. A clean result leaves benign intent and document trust unresolved. Continue applying data policy, destination policy, output controls, and authorization after a negative result.

Log the API version, resource, latency, request correlation identifier, and action taken. Store document identifiers and hashes where possible. Raw prompts can contain credentials, source code, PHI, or privileged text, so copying every payload into a general SIEM creates a second exposure.

Foundry configuration changes the enforcement point

Prompt Shields can also run as a Foundry guardrail assigned to model deployments or agents. In that path, configured blocking can stop classified input before the model processes it. The annotation contains separate detected and filtered values, so an attack may be detected while configuration permits it.

Microsoft documents user prompt attack detection as enabled by default in Foundry. Document attack detection is disabled by default and requires configuration. For model API calls, document scanning runs at the user-input intervention point. Supported Foundry Agent Service tools can also scan document attacks at the tool-response intervention point in preview.

Treat direct Content Safety calls and Foundry filtering as different deployment modes. A direct call gives application code a Boolean result. A Foundry control can annotate or filter according to its assigned action. Save test evidence with the guardrail assignment and action. Otherwise, a screenshot of the control in a project proves configuration exists, while leaving its deployment attachment uncertain.

Microsoft also documents Spotlighting as an optional document transformation in preview. That feature changes how document content reaches the model and can increase token usage. The spotlighting implementation guide covers source marking and encoding. This guide stays with Prompt Shields detection and response handling. It also covers request policy.

Regression tests need attacks and clean controls

Start with paired fixtures. Put the same hostile instruction in userPrompt, then place it inside one document. The expected result should move to the corresponding analysis field. Add a clean document containing security terms and quoted attack text. Include ordinary role-play content as another clean control to expose false positives.

Run the set against the standalone API and every Foundry guardrail assignment used in production. Include five-document requests and source-order changes. Exercise malformed JSON, a missing secret, HTTP timeouts, rate limits, and service errors. The prompt injection test cases guide adds retrieval and tool-use cases for the surrounding application.

Microsoft says the models have multilingual capabilities but are primarily trained and evaluated on English content. Build a separate set for each production language. Measure attack detection and clean-task acceptance independently. A deployment that catches every English fixture but blocks ordinary French support tickets still fails its production requirement.

I would reject a launch review that shows only red-team hits. Clean controls and timeout behavior are what keep the detector enabled after the first noisy week. Document-to-result correlation matters as well.

Detection and identity-aware request policy answer different questions

Prompt Shields analyzes supplied text for attack patterns. Identity-aware request policy evaluates a different record: the authenticated person or agent, their role, the prompt's data classification, the requested model destination, and the policy version in force. One result can inform the other without replacing it.

Consider an engineer sending clean source code to an unapproved public model. Prompt Shields may correctly report no attack. Enterprise policy can still deny the route because the classified code falls outside that role's approved destinations. Reverse the case and a permitted user may submit an injected document to an approved model. The detector should catch the content while authorization still confirms the route.

Keep separate fields for the attack result and authorization decision. Preserve separate policy versions and reasons as well. The AI gateway architecture guide shows where an HTTP policy point can evaluate the complete request context. This separation prevents a probabilistic classifier result from becoming an accidental entitlement decision.

DeepInspect

DeepInspect applies identity-aware policy to authenticated HTTP traffic deliberately routed between users or agents and LLM endpoints. The calling application supplies verified identity and role context. DeepInspect evaluates that context with the data classification, model destination, route, and active policy before forwarding an allowed model request. Each decision produces a separate audit record.

Prompt Shields remains responsible for its attack signal. DeepInspect can use a detection result as one input without treating it as proof of identity or permission. Its exact boundary is the authenticated HTTP model request and response that passes through the proxy. Retrieval, local file parsing, STDIO tools, local inference, and tool execution outside that route remain with application, endpoint, and runtime controls.

Book a technical deep dive at deepinspect.ai.