Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

Investigating a Policy Decision

A policy can block a request, hold it for approval, or, in Observe mode, record what it would have done. Each time, HYPR AgentPass™ keeps the decision together with the request that caused it. Each connector's Policies tab lists those decisions. Opening one answers four questions in one place:

  • Which policy decided?
  • What traffic caused it?
  • What else did that request set off?
  • Why did the rule match?
note

Investigating decisions is an administrator task. Reading decisions needs the View permission on Policies. The request behind a decision is shown only to a role that can also view the Request Log. See Who Sees What.

When a User Reports a Block​

Most investigations start with someone saying their agent was stopped. What they saw already names the policy. A blocked agent receives the policy's name and its message. A held request appears on the Approvals page with the policy that raised it.

  1. Find the connector. It is the provider or tool server the agent was calling. If you are not sure, find the request in the Request Log, which shows the connector that served it.
  2. Open its decisions. Go to Connectors, open the connector, and click the Policies tab.
  3. Narrow to the report. Set the time window to cover when it happened, Policy to the name they were given, and Disposition to Blocked or Approval. Match the row to the agent in the Agent › Tool column.
  4. Open the row to see why the rule matched and what the request carried. See Open a Decision.

If the rule caught something it should not have, set it back to Observe while you narrow it. See Roll Back.

Find the Decisions​

Open Connectors, pick the connector, and click the Policies tab. The tab's count includes every policy that governs this connector: those scoped to it, and the global ones that apply to every connector. The Scope column tells them apart, as this connector or global.

Below the policy list, the Decisions card lists what those policies did to this connector's traffic, newest first.

A connector's Policies tab, with the Scope column showing global and this-connector policies, and the Decisions card below filtered to Observe matches

Each row has these columns, from left to right.

ColumnWhat it shows
ModeENFORCE when the policy acted on the traffic, OBSERVE when it only recorded a match. Rows that are not policy decisions, such as an approval being raised, show SYSTEM
DispositionWhat happened to the request. See the following table
Agent › ToolThe agent that made the call, and the tool it called. Hover over either for the full value
PolicyThe policy that decided
Time · TxnWhen it happened, and the start of the request's correlation ID. Hover for the full timestamp and ID

Read the disposition first.

DispositionMeaning
BlockedThe request was refused
Would blockAn Observe policy matched. Nothing was changed. This is what the policy would have done once enforced
ApprovalThe request was held for a supervisor
ResolvedA held request was approved, denied, answered or expired
AllowedAn Enforce ALLOW policy matched, and the request went through
InfoAnything else worth recording

Consecutive rows that are identical except for time collapse into one row, with a count such as 3×. The row shows the time range they span.

The connector's Connections tab carries the same rows from the last 24 hours, in its Events card, alongside the connector's other operational events. Clicking a row there opens the same detail.

Narrow the List​

The bar above the decisions filters them.

FilterOptions
Time windowLast hour, Last 24 hours (the default), Last 7 days, Last 30 days
ModeENFORCE, OBSERVE
DispositionAny of the dispositions listed earlier
PolicyThe policies that govern this connector
ToolThe tools in the decisions shown
Policy or tool nameA search on either name

Clear filters returns to the last 24 hours, with nothing else set. The list loads 50 decisions at a time. Load more, at the bottom, fetches the next set.

To follow one thread through the list, right-click a row's Agent › Tool cell, and choose Decisions for this agent, Decisions for this policy or Decisions for this tool.

When nothing is listed, the card tells you why:

  • If no enabled policy governs the connector, nothing is being evaluated at all.
  • If policies are in scope but none fired in the window, the card says how many are in scope and in which mode, and offers Widen to 7 days.
  • If your filters exclude everything, it offers Clear filters.
A quiet list is not proof of a working rule

An Observe policy that never appears here has not matched anything in the window. Before you promote it to Enforce, send the traffic you meant it to catch, and confirm a Would block row appears.

Open a Decision​

Click any row. A panel opens on the right, headed with the policy name and the request's full correlation ID, which you can copy. Beneath the mode, disposition and time, it has four sections.

The decision panel for an Observe match, showing the request's agent and supervisor, why the rule matched, the traffic sizes and the events the request caused

Who, What, Where​

This section describes the request behind the decision.

FieldWhat it shows
AgentThe agent's name, or Unattributed when the request carried no agent identity
SupervisorThe supervisor responsible for the agent
CallThe method, and the tool called
ClientThe client software and its version
SessionThe session the call belonged to
ResultThe status the call returned, and how long it took

The request may not be available. It may be older than the Request Log keeps, or belong to a supervisor whose requests you may not see. The panel then says so, and leaves this section out. The rest of the decision is still shown. For an older event with no linked request, the panel says that the traffic behind it cannot be identified.

Why It Matched​

This section shows the policy's name, mode and priority, and whether it is global. A tag says whether the rule has changed since the decision: rule changed since this decision, rule unchanged since this decision or rule version not recorded. Beneath that, the rule is broken into its clauses, the parts joined by &&. Each clause is shown as written, with:

  • ✓ if the clause held, ✗ if it did not, or ? if it could not be judged on its own
  • The value each attribute in the clause resolved to at the moment of the decision

This is the evidence for a decision: not what the rule says today, but what the gateway actually saw. When a clause reads request.method == "DELETE" and the value shown is DELETE, you know exactly which part of the request the rule caught.

The Why it matched section, showing the rule as written, a check mark for the clause that held, and the value it resolved to

A few cases display differently:

  • A rule written with || is shown as one clause.
  • A very long value is shortened, and a rule with many clauses records only the first ones. The panel notes when that happened.
  • For decisions made before clause values were recorded, the panel shows the rule as written instead.
  • Rule changed since this decision means the values were judged against an earlier version of the rule than the one in your policy list now.
  • When the policy has since been deleted, the panel says that its rule cannot be shown.
Values are shown as the gateway saw them

Clause values are recorded as they were, so anyone who can view decisions can read them. A rule that tests a header or tool argument carrying a secret would show that secret to everyone with that permission. Test for the presence or shape of such a value, with has(…) or .startsWith(…), instead of comparing it to a literal secret. By default, clause values are not sent to your external event destinations. An administrator can change how the evidence attribute leaves the gateway on the Data Management page.

The Traffic​

This section shows the size of the request and the response. When the payload was kept, each line links to that request in the Request Log, where the detail panel opens on it and shows the body. When it was not kept, the line says why: the body was empty, or payloads are not retained for that tool. When there is no request record, the line says there is no payload to show.

Everything This Request Caused​

This section lists every event the same request produced, oldest first, with the one you opened marked this one. A block, the approval it raised, and any other policy that also matched line up here in order. An event that raised an approval carries Open the approval, which takes you to that approval on the Approvals page.

Who Sees What​

Each part of an investigation needs its own permission.

To seeA role needs
The connector and its tabsView on Connectors
The decisions list and the decision panelView on Policies
The request behind a decisionView on Request Log

Where a permission is limited to your own records, the list shows only decisions made by policies you authored. The panel then shows only requests from agents you supervise. The built-in AgentPassAdmin and AgentPassOperator roles see everything. You set permissions in Roles and Permissions.