Skip to main content
Version: 11.5.0

Data Classification

Data classification lets you say what each tool and connector in HYPR AgentPass™ handles. For example, this one reads payroll records, and that one reads the public product catalog. You then write policies against those labels, instead of against tool names.

That indirection is the point. A rule that says "hold anything Restricted for approval" keeps working when a connector gains forty new tools, when a tool is renamed, and when a second connector arrives carrying the same kind of data. A rule that lists tool names does not.

Labeling is also how you answer a security reviewer who asks which of your agents' tools reach regulated data, and what governs them.

Open Settings → Data classification in the console. The page has six tabs: Labels, Assignments, Detectors, Policies, Data flow and History. This page follows the first four in that order, which is the order you need them in. Data flow is covered in Session Tracking.

Any role with Data labels: View can open the page: Admin, Operator, Security analyst and Auditor, out of the box. Changing anything on it needs Data labels: Manage, which Admin holds. A role with view access only sees You can see the classification but not change it. See Who Can See and Change This.

The Vocabulary​

A label has two parts, because one part cannot express the rules you actually write.

The Labels tab: four sensitivity tiers with their ranks and stable keys, and below them the tag table with each tag's floor tier
PartShapeWhat it is for
TierOrdered and ranked. One per tool"At or above Confidential" is a comparison, so tiers are ranked, and a rule compares the rank
TagUnordered. Any number per tool"PII" and "export-controlled" are categories, not points on a scale

Tiers​

AgentPass ships with four tiers. The rank is the number, starting at 1, that a policy compares.

RankTier
1Public
2Internal
3Confidential
4Restricted

On the Labels tab, you can rename the tiers to match your organization's existing scheme, reorder them by rank and disable the ones you do not want. To add a tier of your own, use the AgentPass administration API. The names are yours, but policy reads the order. A rule written against rank keeps working after a rename. That is why every example on this page, and every policy AgentPass ships, compares tier_rank, not a tier's name.

Rank 0 means "nothing has classified this"

Rank 0 is reserved, and is never one of your tiers. It keeps "never classified" distinct from "classified as the lowest tier." Those are two different facts, and an auditor asks about the second. A call nothing classified is not reported as rank 0 either. See When Nothing Classified the Call.

Tags​

Eight tags ship with the product. A tag may carry a floor tier: the lowest tier anything carrying that tag can be. Applying a tag with a floor raises the tier if it was lower, and never lowers it.

TagFloor tier
PIIConfidential
PCIConfidential
PHIRestricted
Export controlledRestricted
CredentialsRestricted
Customer dataConfidential
FinancialConfidential
Source code(none)

Source code ships without a floor on purpose. Whether a repository is Confidential is a judgment only you can make. On the Labels tab, you can add your own tags, and set or clear a floor on any of them.

Nothing is stored until you change something

A new organization has no vocabulary rows at all. It resolves to the shipped set, and the Labels tab says so. The first change you save writes the whole set. From then on, the vocabulary is yours, and later AgentPass releases do not alter it. Upgrading AgentPass therefore never renumbers a scale you customized.

Assigning a Label​

You attach labels on the Assignments tab, one connector at a time. There are three kinds of assignment.

The Assignments tab with a connector selected, a connector-default row and a single-tool rule, showing the tier and tag pickers and the Save labels button
KindApplies toUse it for
Connector defaultEvery tool on the connectorA floor for a whole system, such as "everything on the HR connector is at least Confidential"
RuleEvery tool whose name matches a patternThe bulk case. One rule labels the forty operations on a connector whose names contain payroll
ToolOne named toolThe exception you want to state explicitly

The tab also has two guardrail columns, Sink and Source trust, which tell the Rule-of-Two breaker what a tool does with data and whether to trust its content. Left blank, the sink is inferred and the trust is inherited from the connector.

How the Three Combine​

Precedence decides which of them apply. An explicit label on a tool beats a rule, which beats the connector default.

Among those that apply, the result is combined, not chosen:

  • The effective tier is the highest rank of everything that matched. A rule that says Internal, sitting on a connector whose default is Restricted, still leaves those tools Restricted.
  • Tags are the union of every source that matched.
  • Then any tag floor raises the tier, if it is higher than what the sources gave.

Taking the maximum is deliberate. A connector default exists to be a floor. If adding a narrower rule could pull tools beneath it, the floor would be only a suggestion. "Somebody added a rule and quietly declassified the connector" is exactly the finding this feature exists to prevent.

An explicit tool label replaces, it does not combine

The one way to place a tool below its connector's default is to label that tool explicitly. An explicit tool label suppresses the rules and the default, instead of joining them. It is the intended escape hatch for a genuine exception, such as a read-only status endpoint on an otherwise Restricted system. It is also the one assignment that can reduce protection, so review those rows when you review the connector.

See a Rule's Reach Before You Save It​

A rule is how you label a connector with hundreds of operations. As you type a rule, it shows how far it reaches, such as matches 12 of 340 tools, or matches no tool on this connector when the pattern is wrong. * spans any part of a name, and ? matches one character. Matching ignores case, and covers the whole name.

Below the table, Check a tool resolves one named tool against everything currently on the screen. It shows the resulting chips, and which assignment produced them. It runs the same precedence the gateway does, so what it shows is what will be stored.

Lowering a Label Needs a Reason​

Raising a label is always safe. Saving one takes effect on the next request, with nothing to restart.

Lowering is the audited act. When a save would reduce the highest classification anywhere on that connector, AgentPass stops and asks why, with This lowers the protection on this connector. It refuses the save without an answer.

The History tab, and the change history the administration API returns, record every save, in either direction: what changed, whether it raised or lowered, who did it, when and the reason they gave.

The vocabulary is protected the same way. You can rename a tier or tag freely, because its display name is yours. You cannot remove one, or change its key, while anything still uses it: a tool's label, a rule, a connector default or data ceiling, a Purview mapping, a dictionary or a built-in detector. The save is refused, with a list of what depends on it, so a tier cannot quietly disappear from under the tools labeled with it. Relabel or remove those first.

Detecting Sensitive Content​

Everything so far labels a tool before it is ever called. That covers the tools you know about. But a connector gains tools, a tool starts returning something it did not return last quarter, and a label nobody assigned is a label nobody has. Content detection closes that gap by reading the call itself: the arguments going out, and the reply coming back.

Detection runs entirely inside the gateway. Nothing is sent anywhere, and it works on an air-gapped deployment. The one exception is semantic classification, which is a separate switch, off until you supply a credential.

A detector never sets a tier directly. It contributes a tag, and the tier follows from that tag's floor in your vocabulary, as for a tag you assign by hand. A card number found in a reply therefore means the same as a tool you labeled pci.

Turning detection on can change what your existing policies match

A rule such as "hold anything at or above Confidential" begins matching calls whose content is classified, not only tools someone labeled. That is the purpose of the feature, but it changes enforcement, so the decision is yours. Consider running the affected policies in Observe mode first, and reading what they would have caught.

To turn detection on, click the Detectors tab, and turn on the switch beside Content detection is off. The label then reads Content detection is on. Detection is off on every tenant until you do.

The Detectors tab with content detection switched on, and a table of the built-in detectors with the tag each contributes and how it avoids false positives

The Built-In Detectors​

Twelve detectors ship with the gateway. Each one names the tag it contributes.

DetectorContributesHow it avoids false positives
Payment card numberpciChecksum-verified
US Social Security numberpiiPattern match
US ITINpiiPattern match
IBANfinancialPattern match
US routing numberfinancialChecksum-verified
Email addresspiiNeeds 5 distinct matches
Phone numberpiiNeeds 5 distinct matches. Off by default, because it is the noisiest
AWS access key idcredentialsPattern match
Google API keycredentialsPattern match
Azure storage connection stringcredentialsPattern match
JSON web tokencredentialsPattern match
Private key blockcredentialsPattern match

Two ideas in the last column keep detection from classifying your whole estate:

  • Checksum-verified means the digits must also pass the arithmetic check the real identifier carries. A sixteen-digit order number is not a payment card.
  • Needs 5 distinct matches is a density gate. One email address in a reply is a signature. Five different ones are a list of people. The count is of distinct values, so the same address repeated still counts once.

Each detector has its own switch, so you can run the checksum-backed ones and leave the pattern-only ones off. While the master switch is off, none of them run, whatever their individual switches say.

Your Own Terms​

The built-in detectors find what looks the same at every organization. A dictionary finds what is sensitive only to yours, such as an export-control marking, an internal project codename, or a customer account format that follows your own scheme.

A dictionary being edited on the Detectors tab, showing its name, the tag it contributes, its terms one per line, and the number of distinct matches required

Give a dictionary a name, the tag it contributes, and its terms, one per line. Terms match whole words and ignore case. They are stored in your own tenant database, and never sent anywhere. That matters, because the terms themselves can be as sensitive as the data they find.

SettingWhat it does
TermsLiteral words or phrases, one per line. From 3 to 200 characters each, and up to 2,000 per dictionary
PatternsRegular expressions, for identifiers with a shape instead of a fixed value. Up to 400 characters each, and up to 50 per dictionary
Needs N distinct matchesThe density gate described earlier. Raise it for a term that appears casually

A pattern is checked when you save it. If it behaves pathologically on a large payload, it is abandoned instead of being allowed to stall a request. Neither check tells you a pattern matches the right things. Only your own traffic can. Add the pattern, and read what it catches in Observe mode before you write a rule on it.

How Much of a Call Is Read​

Detection reads up to a fixed number of characters of each call. By default, that is 262,144 characters of the request and 32,768 characters of the reply, both adjustable under Scan window on the Detectors tab. The response window is smaller, because a reply is scanned on a latency-sensitive path.

When a payload is larger than its window, the part beyond it is not read. The scan is reported as truncated, not clean. Policies can read that distinction as data.scan. A rule can then insist on a complete scan, instead of treating "we found nothing" and "we did not look everywhere" as the same answer.

Semantic Classification​

The detectors match patterns. Semantic classification asks a different question: what the content is. For example, whether content reads as a customer list, or as an internal plan. No regular expression reaches that judgment.

It is an optional tier. It differs from everything else on this page in one way that governs how you approach it: it sends the arguments of tool calls to a third-party classifier outside the gateway.

What it receives is limited:

  • Arguments only. It classifies a tool call's arguments before the call is forwarded. Replies are never sent to it.
  • Credentials removed by field name. Values in credential fields are removed before anything is sent.
  • Nothing, when a credential is inside a value. If content detection finds a credential inside an argument, nothing is sent for that call, and data.semantic reads withheld.
Evaluate the processor before you enable this

Nothing leaves the gateway until you save an API key, and the switch will not turn on without one. Enabling it makes that vendor a processor of whatever your agents' tool calls carry. First, review its data-protection terms, sub-processors, data residency and retention against your own obligations. Data sent cannot be recalled.

The rest of data classification does not depend on this. Leave it off, and detection still runs, entirely inside the gateway.

When you turn on the switch beside Semantic classification is off, a confirmation titled Send call content to the classifier? states what is sent, and that sent content cannot be recalled. Click Send to classifier to turn the tier on. The History tab records who enabled or disabled the tier and when, and any change to its API key or model.

Two properties keep an imperfect classifier safe to put in an enforcement path:

  • It can only raise a classification, never lower one. The deterministic result stays authoritative, and a semantic verdict that disagrees downward changes nothing. The worst a wrong verdict can do is over-classify, which costs an approval, not a disclosure.
  • A verdict that looks manipulated is discarded. Content that argues for its own classification is a known way to move a classifier of this kind. The gateway checks for it. When the check fires, it falls back to the deterministic result, and records the call as adversarial.
SettingWhat it does
API keyWrite-only. Stored encrypted, and never shown again
ModelPinned to a specific version. Thresholds tuned against one version are not guaranteed to hold for another
Calls per minuteA budget. Calls beyond it are marked unexamined, not reported clean
Act aboveA verdict at or above this confidence contributes normally
Advise aboveBetween this and Act above, a verdict still contributes but is marked advisory, so an enforcing rule can exclude it
Treat as adversarial aboveThe threshold for discarding a verdict as manipulated
Claim a tag aboveThe confidence needed before a suggested tag is applied

Tune the thresholds against your own traffic. The shipped values are a starting point, not a recommendation. If the classifier is unreachable, rate-limited or over budget, the call proceeds, and the attribute records why. Classification never fails a request.

Writing Policies Against a Label​

A classification reaches policy conditions through two namespaces, because they answer different questions.

NamespaceWhat it describesExamples
tool.*What you assigned to the tool being calledtool.tier_rank, tool.tags
data.*What this call carries, after every source is combineddata.tier_rank, data.tags, data.sources, data.scan, data.semantic
connector.data_ceiling_rankThe highest classification the destination may receiveSee A Connector's Data Ceiling
response.data.*On the Post-Response phase, the call's classification raised by anything detection found in the replyresponse.data.tier_rank

Each attribute's type, and when it is present, is listed in the Policy Attribute Reference.

tool.* is what you assigned to the tool being called. data.* is what this call is carrying: the tool's labels, the connector default, any tag floor, and the sensitivity label on any file the request brought. Write most rules against data.*. Use tool.* when you specifically mean the assignment on the tool, not the call.

Compare the Rank, Not the Name​

data.tier_rank >= 4

This matches anything at the top of a four-tier scale. It keeps working after somebody renames Restricted, while data.tier == 'restricted' does not.

'pci' in data.tags && request.method == "POST"

This is a tag rule, narrowed to writes. Reading cardholder data is one question, and sending it somewhere is another.

connector.data_ceiling_rank > 0 && data.tier_rank > connector.data_ceiling_rank

This is the flow rule. It refuses a call that would send data more sensitive than the destination may receive. The > 0 guard keeps it inert until a ceiling exists.

response.data.tier_rank >= 4

On the Post-Response phase, this matches a call that reaches the top tier once the reply is taken into account. It catches sensitivity discovered in what came back, and also matches a call that was already classified that high.

When Nothing Classified the Call​

When a classification is unknown, AgentPass omits the attribute entirely, instead of reporting a zero or an empty string. A condition that tests a missing attribute is not a match. The same rule governs every other sometimes-absent attribute. See A Rule About a Detail the Gateway Never Learned Never Acts.

Each situation leaves these attributes absent.

SituationWhat is absent
The request is not a tool callThe whole tool namespace
Nothing classified the calldata.tier, data.tier_rank, data.tags and data.sources. data.scan and data.semantic can remain
The tool is named but unlabeledtool.tier, tool.tier_rank and tool.tags. tool.name remains
The connector has no ceilingconnector.data_ceiling and connector.data_ceiling_rank
Pre-Request, or a call nothing classified whose reply was not scannedresponse.data
Content detection is off, or the call had nothing to scandata.scan
The semantic tier is offdata.semantic, data.confidence, data.advisory

The consequence is the usual one. A DENY written only on a classification blocks the labeled traffic, and lets everything unlabeled through. That is the safe direction, but the rule is only as good as your labeling. Check what a rule catches in Observe mode before you enforce it.

A request with no tool named still picks up the connector's label

A REST call, an inference call, or an MCP method other than a tool call has no tool to resolve. The connector default applies, and tool rules do not. Classification never fails a request either. If a classification cannot be resolved, the call is treated as unclassified, and proceeds.

The Starter Policies​

The Policies tab offers ten ready-made rules. They are built against your vocabulary, not the shipped one, so they read correctly whether you kept four tiers or cut them to three. Where a rule says "your highest tier" or "your second-highest tier", it means the highest enabled tiers in your vocabulary, compared by rank. With the shipped four tiers, those are Restricted and Confidential.

The Policies tab listing starter policies, each showing its CEL expression, observe-mode badge and an Add this policy button
PolicyWhen it matchesActionPhaseNeeds session tracking
approve-top-tier-tool-callsThe call is classified at your highest tierRequire approvalPre-RequestNo
approve-elevated-responsesThe call, together with anything found in its reply, is classified at or above your second-highest tierRequire approvalPost-ResponseNo
refuse-data-above-destination-ceilingThe call would send data more sensitive than the destination's ceilingDenyPre-RequestNo
hold-session-data-leaving (recommended)The session has already read data above the destination's ceilingRequire approvalPre-RequestYes
refuse-session-data-leavingThe sameDenyPre-RequestYes
refuse-session-data-leaving-preciseThe same, but only for sessions identified precisely, not a desktop client's per-person sessionDenyPre-RequestYes
guardrail-hold-untrusted-sensitive-sinkThe session read untrusted content and data at or above your second-highest tier, and calls an external-communications or state-change toolRequire approvalPre-RequestYes
guardrail-refuse-hostile-externalThe session read content judged hostile, and calls an external-communications toolDenyPre-RequestYes
guardrail-hold-untrusted-executeThe session read untrusted content, and calls a code-execution toolRequire approvalPre-RequestYes
guardrail-cut-untrusted-inference-exfilThe session read untrusted content, and a desktop agent's model then proposes a web fetch, a web search or a network commandDenyPost-ResponseYes

The first three judge each call on what it carries. The three session starters catch an agent that reads something sensitive and then sends a reworded version elsewhere. See The Session Starter Policies. The four guardrail- starters defend agents against indirect prompt injection. See The Rule-of-Two Breaker.

A starter that needs session tracking is tagged needs session tracking, and matches nothing, until you turn session tracking on. See Session Tracking.

To adopt a starter, you need Data labels: Manage.

  1. Open Settings → Data classification, and click the Policies tab.
  2. Optional: On the starter's card, click Preview matches to see how many calls it would have matched in the last seven days.
  3. Click Add this policy.

The console confirms that the policy was added in observe mode, and the card's button reads Already added, so you do not create a second copy.

Every starter is created in Observe mode, so adopting one changes no traffic. It records what would have been held or refused, and you can read weeks of that evidence before deciding. Turning a policy to Enforce is a separate, deliberate step on Policies. See How Policies Are Evaluated.

A Connector's Data Ceiling​

A ceiling is the highest classification a destination may receive. It is the other half of the picture. A tool's label says what data comes out of a system, and a ceiling says what may go into one.

Set it on the connector itself. Open the connector, and use Highest data classification this connector may receive in its settings. Changing a connector's settings needs Connectors: Edit, which Admin holds.

Leave it unset, and nothing changes. There is no default ceiling. A flow policy that compares against one never matches on a connector that has none. That makes the starter flow rule safe to adopt before you have thought about ceilings at all. It starts acting the day you set the first one.

Where a Classification Shows Up​

Once a tool is labeled, the label travels with the call.

The Request log stream with a Data column: one row badged confidential with pii and customer_data tags, rows badged internal, and rows carrying no badge because nothing classified those calls
SurfaceWhat you see
Connector → Tools, on an MCP connectorA Data labels column, with the resolved tier and tags for each tool in the catalog
People → Roles → Agent tools permissionThe classification beside each tool as you grant it, so you can see what you are handing a role
Request logA Data column beside the tool, so a reviewer scanning for Restricted traffic reads the two together. Opening a classified call shows a Data classification card, as classified when the call was made
An approvalThe classification, added to the approval a supervisor is asked to sign, both in the console and on their phone

The line on the approval matters. Without it, a supervisor signs "call export_customers on the CRM connector" with no idea whether that is a public report or a regulated extract. The classification is appended to the message you wrote, so your own wording still leads.

The classification is context, not signed content

Adding a classification to an approval does not change what the supervisor's passkey signs. The signature still covers the agent, the method, the path and the request body. The classification is context for the person, not part of the cryptographic record of the action.

To filter the Request log by tier, choose a tier from the Any classification picker among the stream's filters. The underlying API filters on classification too, with dataTier and dataTag on the request-stream endpoint. That is how a report such as "every Restricted call last week" is produced. Filtering by tag is available through the API only.

The Agent tools permission section of a role: tool chips grouped by connector, each labeled tool carrying its tier on the chip itself The same Request log stream filtered to Restricted: the classification picker reads Restricted and only restricted rows remain

Using Your Microsoft Purview Labels​

If your documents already carry Microsoft Purview sensitivity labels, you can fold them into the same vocabulary. You then avoid writing a second set of rules against a Purview-shaped attribute.

You map a Purview label onto one of your tiers, and optionally onto tags. For example: the label we call "Highly Confidential" means Restricted, tagged Customer data. Give the label's name or its GUID, whichever you have. Matching tries both, and ignores case. After that, one rule written on data.tier_rank covers a hand-labeled tool and a Purview-labeled document alike.

The mapping is opt-in, and a label you have not mapped contributes nothing. An organization that never fills in the table is in exactly the position it was before. AgentPass does not invent a classification for your documents.

Set up through the administration API

You configure the Purview mapping through the AgentPass administration API. The Data classification page does not show it. Your HYPR representative can help you populate it.

The Purview label itself is still available to policies in its original form, as request.files[].sensitivity_label, including its sub-label parent, which a tier mapping flattens away. See The Document's Sensitivity Label for when to use which. A Purview label is read at upload in the Agent Portal, and is absent on the message that sends the file onward.

Who Can See and Change This​

Data classification has its own pair of permissions, separate from those that configure a connector.

PermissionWhat it allowsOut of the box
Data labels: ViewRead the vocabulary, the assignments, the detectors, the starter policies, the data flow and the change history. Every write control on the page is disabledAdmin, Operator, Security analyst and Auditor
Data labels: ManageChange the vocabulary, assign labels, configure detection, turn session tracking on and off, and adopt a starter policyAdmin

The page and its sidebar entry are hidden from anyone with neither.

Keeping these apart from Connectors: Edit is deliberate. Someone who may reconfigure a connector's backend is not automatically the person who decides that its data is Restricted. Those are different jobs, with different audiences, and lowering a classification is the change a reviewer asks about. Grant Data labels: Manage to whoever owns data classification in your organization. See Roles and Permissions to build a role that carries it.