Skip to main content
Version: 11.5.0

Creating a Policy

Every HYPR AgentPass™ policy is created in the New policy wizard. The wizard walks through the same steps whichever way you start:

  • Start from scratch, and write the condition yourself.
  • Start from a common guardrail, a ready-made rule you can adjust.
  • Describe it in your own words, and let AI write the condition. See Authoring a Policy with AI.

Each way ends with the same condition in the same editor, which you can read and change before you publish.

Before you start, read How Policies Are Evaluated once. Knowing what each setting does to a live request is what makes the rule right.

note

You need Policies: Add to create a policy, Policies: Edit to change one and Policies: Delete to delete one. Admin holds all three for every policy. Operator and Supervisor hold them for the policies they own. When your permission covers only your own policies, AgentPass makes you the owner when you save. What Your Role Lets You Do lists which permission each action needs.

Open the Wizard​

Open the wizard in any of these ways:

  • On Policies, click New policy.
  • On a connector's detail page, open the Policies tab, and click New policy. The wizard starts with that connector already chosen.
  • On the Suggested tab of Policies, click Create policy on a suggestion. See Suggested Policies.
  • On Session watch, focus an entity in the findings graph, and click Draft a policy. The wizard opens on Describe it in your own words, with the connector and the goal filled in. See Drafting a Policy from an Entity.

The wizard's steps are Start, Details, Logic, Back test and Review & publish. A rail lists them, each with a short summary of what you chose. Click Continue to move on, or click a step you already reached to go back to it.

Cancel leaves the wizard. If you changed anything, the wizard first asks whether to discard it: click Yes, discard changes to leave, or No, keep editing to stay.

Start step of the New policy wizard with Describe it in your own words, two common guardrails and Start from scratch

Choose a Starting Point​

The Start step asks What kind of policy do you need?

  • Describe it in your own words lets AI write the condition from a goal in plain English. The option is offered when AI drafting is set up. See Authoring a Policy with AI.
  • Or start from a common guardrail offers ready-made rules. The first two are shown. Show all N templates lists the rest.
  • Or write the expression yourself, with Start from scratch, opens an empty condition.

The Common Guardrails​

A template fills in a complete policy: its name, description, what it checks, its action, its message and its condition. The condition is the template's own fixed rule. No AI is involved. You can change any of it in the following steps.

TemplateWhat it stopsChecks
Block destructive shell commandsrm -rf, mkfs and dd writing to a deviceThe reply
Block reads of credential filesOpening .env, ~/.aws/credentials, private keys and keychainsThe reply
Block writes outside the projectWrites and edits under /etc, /usr or an .ssh directoryThe reply
Block secrets pasted into a promptPrivate keys, AWS access keys and bearer tokens in the newest messageThe request
Block personal data in promptsNational ID and payment card numbers in the newest messageThe request
Block production system accessConnections to production hosts, databases or a production Kubernetes contextThe reply

Every template denies, and reads the conversation on an inference connector. Policy Examples gives each one's condition, and why a command is caught in the reply.

Set the Details​

The Details step starts with the connector, because the connector decides what the policy can see. Then it holds every setting except the condition.

FieldWhat it does
ConnectorThe connectors the policy watches. Left empty, the policy is evaluated on every connector, including any connected later
Apply toShown for a single MCP connector. Let the AI choose, offered when AI drafting is set up, has the AI author read every tool description and pick the tools that match your goal. All tools on this connector covers every tool, now and later. Specific tools covers the tools you name. A tool added later is not covered
NameShown wherever the policy is listed. It cannot be changed once the policy exists
DescriptionOne sentence, shown under the name in the policy list
OwnerWho answers for the policy when it blocks something. It defaults to you. Where your permission is limited to your own records, it is always you
ChecksThe reply — before it returns or The request — before it is sent. Decides which half of the exchange the condition looks at. The default is the reply
PriorityA whole number of 1 or more. Lower runs first. The default is 1000
ActionDeny, Require approval or Allow. The default is Deny. When AI drafting is set up, a new policy also offers Let the AI choose from the goal: the author picks the action from what you describe, and you can change it on the Logic step. See Authoring a Policy with AI
Enforcement modeObserve — evaluate and log, do not enforce, the default, or Enforce — apply the action to every match
EnabledOn by default. A disabled policy is skipped at evaluation: nothing is logged and nothing is enforced. Turn it off to park a policy without deleting it
Message to the agentWhat the agent is told when the policy acts. Required for Deny and Require approval

Under the connector, a note says what the policy can see:

  • An inference connector carries a conversation, not a tool catalog. The policy reads what was sent and what the model replied.
  • An MCP connector exposes tools, so the policy can cover every tool or only the ones that matter.
  • No connector chosen means the policy is written against what every connector has. Only request.* attributes exist on every connector.
Details step on an MCP connector, with the Apply to choices Let the AI choose, All tools on this connector and Specific tools

Write the Condition​

The Logic step asks How should this policy decide? Its expression editor holds the condition the gateway runs.

Conditions are written in Common Expression Language (CEL), a small expression language with syntax close to most programming languages. A condition is true or false for each request. When it is true, the policy applies. As you type, the editor suggests attribute names, operators and functions.

A condition can use these operators.

WriteTo mean
request.method == "DELETE"Equal to. != means not equal. >, >=, < and <= compare numbers
a && b, a || b, !aBoth, either, not
request.path.startsWith("/v1/admin")Starts with. Also .endsWith(…), .contains(…), and .matches(…) for a regular expression
has(request.body.max_tokens)Whether a field is present in a parsed body. Test presence before comparing a value that might be missing
"write" in request.agent.scopesWhether a list contains a value
request.files.exists(f, f.size_bytes > 10485760)Whether any element of a list passes a test. .all(f, …) tests every element

Everything a condition can refer to is listed in the Attribute Reference.

Check the Condition as You Write​

The wizard checks the condition while you type, and reports the result in the In plain language card:

BadgeMeaning
Valid expressionThe condition compiles. The card reads it back to you in plain English
Cannot be readThe condition does not compile. The error is shown under the editor
Never matchesThe condition compiles, but can never be true
Nothing yetThe editor is empty

Continue is available once the condition is valid and the policy has an action.

When the condition reads an attribute that some of the chosen connectors never have, a warning says so, such as This policy cannot match on 2 of 3 connectors. For example, inference.* exists only on inference connectors. Remove those connectors under Connector in Details, or change the condition.

Start From an Example​

Under Examples, the step offers eleven example conditions:

  • Block DELETEs, Large token requests, Specific path, Error responses, Specific agent and Slow responses
  • Bedrock: unattributed caller and Bedrock: no MFA
  • M365: Copilot Studio agents only
  • Files: confidential attachment and Files: over 10 MB

Click one to replace the expression in the editor with it, then adjust it. Policy Examples explains each one.

Change one thing at a time

Starting from an example and changing one thing at a time is the fastest way to a correct condition. The examples also show the habit worth copying: a rule that says which traffic it is about, such as connector.template == "AWS_BEDROCK" && ….

Look Up an Attribute​

Click Available attributes to open the attribute panel beside the editor. It lists what the chosen connectors give you to write against, by group, with each attribute's type and meaning. Search it by name, and click an attribute to insert it into the editor.

GroupWhere it exists
request.*On every connector
response.*On every connector, once the reply exists
tool.*, data.*MCP connectors only
inference.*Inference connectors only
connector.*On every connector. Some fields exist only on their own kind of connector

The panel carries the same warnings as the Attribute Reference about attributes that are present only when resolved.

Logic step with the Available attributes panel open beside the expression editor

Say Which Traffic the Rule Is About​

Lead the condition with an attribute that is always present on the traffic you mean:

  • connector.template or connector.name, on any connector
  • connector.aws.bedrock.identity_source, on Bedrock
  • connector.m365.copilot.surface, on Copilot
  • request.file_count, for files

A condition on a missing attribute is never true. See How Policies Are Evaluated.

A Reply-Side Rule on a Model Connector​

A condition can read the model's reply, through inference.tool_uses or inference.completion.*, when the policy checks the reply. Enforcing such a rule stops the model's reply at the tool call. Write its message for the person waiting on that reply, and keep it in Observe first. Governing Inference Traffic describes the behavior.

Back-Test It​

The Back test step asks What would this have caught? It replays the policy against the requests the connectors in scope carried over the last 7 days. It runs as the step opens. Nothing is blocked or held. It only shows what would have been.

The result shows:

  • Examined: how many requests were replayed
  • Matched: how many the policy would have caught
  • To review: how many matches you marked as looking wrong

Under What it matched, mark each sample Correct or Looks wrong. Your marks count toward To review while you are in the wizard. They are not saved with the policy. Click Run again after you change the condition.

Read the result as evidence, not a verdict:

  • No matches can mean the rule is too narrow, or that nothing in the period did what the rule is about. Spot-check a few recent requests before you decide.
  • Some recorded requests carry only a summary, not the full body. The step says what share of the replay used a summary, so matches that depend on argument detail may be missing.
  • The back test reads the request examples the gateway retains. Once those examples age past the Activity retention window set in Data Management, nothing is left to replay.

With no traffic in the period, the step reads No traffic to test against. You can still publish. The policy then starts in Observe, and you review it once traffic arrives.

Every back test is kept on the policy's History tab. See Understanding Your Policies.

Review and Publish​

The Review & publish step reads Ready to publish. It states what the policy does in plain language, then lists every setting. Click Change beside a setting to go back to its step.

The step warns you when:

  • The policy was not tested on real traffic. Leave it in Observe, and look at its matches before you enforce it.
  • The policy looks like one you already have. The warning names the existing policy, and Open it opens that policy in a new tab. You can still create yours. Whichever has the lower priority number runs first.

Click Create policy. The policy is published in the enforcement mode you chose in Details.

When you chose Enforce and the policy was not back-tested on any traffic, the wizard asks Turn on enforcement without testing it? Click Publish in Observe to publish it observing, or Publish in Enforce to enforce it straight away.

The wizard returns you to where you started, with a Policy created banner. View policy opens the new policy's page.

When the gateway refuses the policy, the reason is shown on the Review & publish step. A name already in use reads A policy named “…” already exists. Change the name in Details.

Approval on inference rules

The gateway refuses to enforce REQUIRE_APPROVAL on a condition that reads inference.*. You can publish such a rule in Observe, to record where approval would have been required, but not in Enforce. See Where Require Approval Applies.

Watch, Then Promote​

A new policy is evaluated from the next request. In Observe, it changes nothing:

  1. Watch. Send the traffic you mean to govern. Each match is recorded as a Would deny or Would wait decision. Read them on the policy's Decisions tab, or on Activity → Policy decisions. See Policy Decisions.
  2. Promote. On the policy list, click the policy's State badge, and choose Enforcing. See Promoting a Policy to Enforce.
  3. Adjust. Edit any setting except the name. See Edit a Policy.
Nothing matched in Observe?

A rule that matches nothing in Observe mode does nothing in Enforce mode either. Check that the attribute you tested is actually present on that traffic. The Request log detail panel shows what the gateway resolved for a request. Also check that the connector is in the policy's scope.

Edit a Policy​

On Policies, open the policy's row menu, and click Edit. On the policy's own page, click Edit.

The wizard opens on Details, titled Edit policy. Every step is open from the rail, and Save changes is available from any of them. The name cannot be changed.

Editing an enforcing policy takes effect on the next request. If you change its condition, its connectors, its tools or what it checks, the back test must run again before you can click Save changes. Until it has, Save as observing saves your changes with the policy observing.

Every change is recorded on the policy's History tab, with who made it and what changed.

Delete a Policy​

  1. On Policies, open the policy's row menu, and click Delete policy.
  2. Read the Delete …? confirmation. When the policy matched requests in the last 7 days, it says how many, and that they would then fall through to the next policy in priority order.
  3. Click Yes, delete policy. To keep it, click No, keep policy.

Deleting cannot be undone. A policy can be deleted only from Policies, not from a connector's Policies tab.

The Connector's Policies Tab​

Every connector's detail page has a Policies tab listing every policy that governs it, with the count in the tab's name. Use it when your question is about one connector: what governs this provider's traffic, and what has it caught?

  • New policy opens the wizard with this connector already chosen.
  • The Scope column shows whether each policy covers This connector, several connectors, or All connectors.
  • Each row has the same State badge as the main list, and a row menu with Edit and All decisions.

Under the list, Recent decisions on this connector shows what those policies most recently caught, grouped by condition and outcome. Each row names the policy that caught it. See Policy Decisions.

A connector's Policies tab, listing the policies that govern it with their scope and state, and the connector's recent decisions