Skip to main content
How to add a customized PII policy covers the console procedure — creating a policy and applying it. This page covers the rule content: what to write in which field so the detection engine behaves accurately, and how to design priorities so rules don’t fight each other. The examples follow the structure of the Starfort default PII policy (which ships tuned for Korean identifiers — resident registration numbers, Korean addresses and phone formats), adapted here to US data for familiarity. The writing principles are identical for any locale.

​
Policy structure and processing order

A PII policy is made of three rule arrays. The allowed top-level keys are ner, regex, and keyword, and the engine always checks them in the order Keyword → Regular Expression → NER. Text settled by an earlier stage is hidden from later stages, so an earlier stage’s decision is final for that text.
Rule typeCharacteristicsBest for
KeywordCase-sensitive exact match. Fastest, fully deterministicInternal codenames, known-safe values (allowlist)
Regular ExpressionPattern match. DeterministicFixed-format identifiers (SSNs, phone numbers, card numbers, emails)
NER EntityAI-model detection. Understands contextContext-dependent information (names, addresses), variants that patterns miss

​
Designing priorities

As rules multiply, their interactions decide the outcome. Keep three priority rules in mind.
  1. Rule-type priority: Keyword > Regular Expression > NER. Text settled by an earlier stage is never re-judged by a later one.
  2. PASSING is an allowlist. Text matched by a policy_type: "PASSING" rule is settled as safe — no masking or blocking rule can override it afterwards. When two rules of the same type match the same text, the rule with the lower id wins.
  3. Action priority: BLOCK > MASK > PASS. If any rule in the request decides BLOCK, the whole request is blocked, even when every other rule only masks.
Put these principles to work by placing PASSING test-pattern rules at lower ids than the real masking regexes, so dummy values used in docs and QA never get masked: 
{
  "id": 0,
  "rule_id": "test_data:_ssn_test_pattern",
  "regex": "(?<!\\d)(?:000-00-0000|123-45-6789|078-05-1120)(?!\\d)",
  "description": "000-00-0000, 123-45-6789, 078-05-1120 (well-known sample SSNs)",
  "policy_type": "PASSING",
  "mask_word": "TEST_DATA",
  "alert_message": "test data pattern - allowed"
}
A keyword rule can serve the same purpose — preempt John Doe, the placeholder name every sample document uses, with PASSING so the NER name rule can’t mask it. Because the Keyword stage runs before NER, the preemption is guaranteed.

​
Writing Regular Expression rules

A US Social Security number rule: 
{
  "id": 10,
  "rule_id": "ssn:_us_social_security_number",
  "regex": "(?<!\\d)(?!000|666|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0000)\\d{4}(?!\\d)",
  "description": "219-87-3456, 457-55-5462 — excludes invalid areas (000, 666, 900-999) and invalid groups (00, 0000)",
  "policy_type": "MASKING",
  "mask_word": "SSN",
  "alert_message": "social security number detected"
}
Practices this rule demonstrates:
  • Anchor digit boundaries. Without the surrounding (?<!\d) / (?!\d), a middle slice of a longer digit run (a bank account, a barcode) gets misdetected as an SSN.
  • Encode known-invalid ranges in the pattern. The lookaheads reject areas the SSA never issues (000, 666, 900–999) — false positives you can eliminate deterministically shouldn’t be left to chance.
  • Record match examples in description. The field plays no part in detection, but it saves the next reviewer from having to decode the pattern.
  • Resolve conflicts with other rules inside the pattern. A phone-number rule should carry a trailing guard (e.g. (?![-\.]?\d)) so it doesn’t claim the leading segment of a longer account-style number.
Patterns that can match empty text (\d*, secret|) detect nothing and are skipped. Leading/trailing spaces are trimmed when the policy is read — express an intentional edge space inside the pattern itself (\s, [ ]).

​
Writing NER Entity rules

Only four NER fields reach the AI model: Name, Description, Positive Examples, Negative Examples. Policy Type, Mask Word, and Alert Message decide what happens after a detection and never influence detection itself. Detection accuracy therefore lives entirely in the first four fields. A US street-address rule shows what each field does. What makes it instructive is the specificity boundary: a location mention is sensitive only when it is specific enough to find a particular person or business — general location talk is not. Read the sections below with an eye on which part of the example each one points at: 
{
  "id": 2,
  "name": "street address (US)",
  "description": "US addresses that identify the location of a specific person or business. Must contain a street number with a street name, optionally followed by unit detail (Apt/Suite/Floor). General location references — landmarks, transit stations, standalone building names, a city or neighborhood without a street number — are NOT addresses.",
  "policy_type": "MASKING",
  "mask_word": "ADDRESS",
  "alert_message": "address detected",
  "positive_examples": [
    "Our headquarters: 350 Fifth Avenue, Suite 3210, New York, NY 10118 →350 Fifth Avenue, Suite 3210",
    "I live at 1240 Maple Street, Apt 4B, Springfield, IL →1240 Maple Street, Apt 4B",
    "Please deliver the package to 77 Beacon St 2nd floor before noon →77 Beacon St 2nd floor"
  ],
  "negative_examples": [
    "Meet me at Grand Central Station",
    "See you at the Starbucks on Fifth Avenue",
    "Any good cafes in SoHo?"
  ]
}
The shipped default policy is authored for Korean traffic (Korean addresses, resident numbers, phone formats). The rule above adapts its address rule to US data — the field structure and writing principles are unchanged.

​
Description — a definition plus specificity conditions

The Description above carries four elements in order: the definition (identifies a person’s or business’s location), the required specificity (“a street number with a street name”), the allowed detail variants (Apt/Suite/Floor), and exclusions (landmarks, transit stations, standalone building names, city or neighborhood without a street number). The Description draws the sensitive/not-sensitive boundary in plain sentences — and exclusions written there genuinely work, because the model is instructed to answer NO for cases the Description rules out. Scenario 3 below shows this boundary splitting a single message.

​
Positive Examples — the arrow convention

Write every positive example as context →value. The model learns that the part after → is the exact text to detect.
  • The sentence before → teaches when to fire (recall); the value after → teaches the exact output form (precision).
  • The value also teaches the masking span. In all three examples the value covers the street number through the unit detail and drops the city/state/ZIP — the examples tell the rule where sensitive text begins and ends.
  • The value must be locatable back in the input. Writing it exactly as it appears is safest (whitespace differences are tolerated); a value reassembled in a different order — street name before the number, say — cannot be located and is discarded.
  • The three examples each teach one surface form that actually occurs: a labeled headquarters line, a residential address with an apartment unit, and an address embedded mid-sentence with no label. Give each must-catch form its own example.
  • Write examples in the language and format of the data you expect to catch.

​
Negative Examples — the false-positive shield

Add near-misses that lack the required specificity. The three negatives each close a different false-positive path: Grand Central Station (a landmark meeting spot), the Starbucks on Fifth Avenue (a business on a named street — but no street number), and SoHo (a neighborhood). All three pair with the Description’s exclusions. NER rules are screened together in small batches, so weak negatives on one rule can cause over-detection on its neighbors too.

​
Writing Keyword rules

Keyword rules are case-sensitive exact matches. They see no context, so avoid short generic words.
  • Good BLOCKING keyword: an internal codename like PROJECT-ORION — sensitive wherever it appears.
  • Good PASSING keyword: John Doe — an allowlist that preempts the placeholder name before the NER name rule can mask it.
  • Bad keyword: a generic noun like account — fires indiscriminately on every occurrence.

​
Example scenarios

Behavior of a Guardian with rules like the above assigned.

​
Scenario 1 — masking a mobile number

“My number is (212) 555-0134. You can also reach me at 212.555.0199.”
The phone regex matches both values despite the different separators. The result is "action": "MASK" with body My number is [PHONE_NUMBER_1]. You can also reach me at [PHONE_NUMBER_2]. — mask words get indexed in order of appearance.

​
Scenario 2 — test data passes, real data masks

“The test account SSN is 123-45-6789; the real one is 219-87-3456.”
123-45-6789 matches the SSN masking rule’s shape — but it is the canonical sample SSN, so the PASSING test pattern (id 0) preempts it first and it passes through unchanged. Only 219-87-3456 is masked: The test account SSN is 123-45-6789; the real one is [SSN_1]. — this is why the allowlist rules carry lower ids than the real ones.

​
Scenario 3 — only the specific address is sensitive

“Let’s meet at the coffee shop by Grand Central Station. Send the signed contract to 350 Fifth Avenue, Suite 3210, New York, NY 10118.”
One message, two location mentions, two different verdicts. Grand Central Station is a landmark-level mention, so it passes — exactly what the Description’s exclusion and the negative examples taught. Only the specific address masks, and the span starts and ends where the example values taught it to: Let's meet at the coffee shop by Grand Central Station. Send the signed contract to [ADDRESS_1], New York, NY 10118.

​
Scenario 4 — BLOCK beats everything

If ten masking rules match and one BLOCKING rule matches, the result is "action": "BLOCK" and no masked body is returned. Reserve BLOCKING for values whose very transmission must be stopped (confidential codenames); use MASKING for the rest.

​
Checklist

  • Did you anchor digit/word boundaries ((?<!\d), (?!\d)) in your regexes?
  • Did you preempt test/sample values with PASSING rules first?
  • Does each NER Description state the definition + specificity/context conditions + exclusions?
  • Are Positive Examples written as context →value, with the value marking the exact masking span?
  • Do Negative Examples contain near-misses that lack the required specificity?
  • Is BLOCKING reserved for rules that truly need to stop the request?
Starfort ships a comprehensive default PII policy (authored for Korean identifiers) that you can load through the console’s JSON editor — use it as a structural template and adapt the rules to your locale, as this page did. The TIP button on the console policy page shows a summary of this guide.
Rule count and example volume are detection cost. The full rule definitions travel with every call, so an overly verbose policy slows every request and, in the extreme, exceeds the model’s input limit and fails the request. Five to ten sharp examples per rule beat an exhaustive list.