|
| 1 | +# PII Detection |
| 2 | +<div class='subtitle'> |
| 3 | +Detect and manage PII in traces. |
| 4 | +</div> |
| 5 | + |
| 6 | +Personally Identifiable Information (PII) refers to sensitive information — like names, emails, or credit card numbers — whether intentionally or not. If not properly handled, this data can be exposed in logs, traces, or external communications, leading to privacy violations, regulatory risks, or user harm. |
| 7 | + |
| 8 | +<div class='risks'/> |
| 9 | +> **PII Risks**<br/> |
| 10 | +> Without safeguards, agents may: |
| 11 | +
|
| 12 | +> * Log PII in traces or internal tools |
| 13 | +> * Share PII in responses or external tool calls |
| 14 | +
|
| 15 | +The `pii` function helps prevent these issues by scanning messages for PII, thus acting as a safeguard that lets you detect and block sensitive data before it’s stored, surfaced, or shared. |
| 16 | + |
| 17 | +## pii <span class="detector-badge"/> |
| 18 | +```python |
| 19 | +def pii( |
| 20 | + data: Union[str, List[str]], |
| 21 | + entities: Optional[List[str]] = None |
| 22 | +) -> List[str] |
| 23 | +``` |
| 24 | +Detector to find personally indentifaible information in text. |
| 25 | + |
| 26 | +**Parameters** |
| 27 | + |
| 28 | +| Name | Type | Description | |
| 29 | +|-------------|--------|----------------------------------------| |
| 30 | +| `data` | `Union[str, List[str]]` | A single message or a list of messages to detect PII in | |
| 31 | +| `entities` | `Optional[List[str]]` | A list of [PII entity types](https://microsoft.github.io/presidio/supported_entities/) to detect. Defaults to detecting all types. | |
| 32 | + |
| 33 | +**Returns** |
| 34 | + |
| 35 | +| Type | Description | |
| 36 | +|--------|----------------------------------------| |
| 37 | +| `List[str]` | A list of all the detected PII in `data` | |
| 38 | + |
| 39 | +### Detecting PII |
| 40 | +The simplest usage of the `pii` function is to check against any message. The following example will raise an error if any message in the trace contains PII. |
| 41 | + |
| 42 | +**Example:** Detecting any PII in any message. |
| 43 | +``` py |
| 44 | +from invariant.detectors import pii |
| 45 | + |
| 46 | +raise "Found PII in message" if: |
| 47 | + (msg: Message) |
| 48 | + any(pii(msg)) |
| 49 | +``` |
| 50 | +<div class="code-caption"> Any PII in the text of the trace will raise an error. </div> |
| 51 | + |
| 52 | + |
| 53 | +### Detecting Specific PII Types |
| 54 | +You can also specify specific types of PII that you would like to detect, such as phone numbers, emails, or credit card information. The example below demonstrates how to detect credit card numbers in Messages. |
| 55 | + |
| 56 | +**Example:** Detecting Credit Card Numbers. |
| 57 | +```guardrail |
| 58 | +from invariant.detectors import pii |
| 59 | +
|
| 60 | +raise "Found PII in message" if: |
| 61 | + (msg: Message) |
| 62 | + any(pii(msg, ["CREDIT_CARD"])) |
| 63 | +``` |
| 64 | +<div class="code-caption"> Only messages containing credit card numbers will raise an error. </div> |
| 65 | + |
| 66 | + |
| 67 | +### Preventing PII leakage |
| 68 | +It is also possible to use the `pii` function in combination with other filters to get more complex behaviour. The example below shows how you can detect when an agent attempts to send emails outside of your organisation. |
| 69 | + |
| 70 | +**Example:** Detecting PII Leakage in External Communications. |
| 71 | +```python |
| 72 | +from invariant.detectors import pii |
| 73 | + |
| 74 | +raise "Attempted to send PII in an email" if: |
| 75 | + (out: ToolOutput) -> (call: ToolCall) |
| 76 | + any(pii(out.content)) |
| 77 | + call is tool:send_email({ to: "^(?!.*@ourcompany.com$).*$" }) |
| 78 | +``` |
| 79 | +<div class="code-caption"> Explicitly prevent sending emails with PII to non-company email domains. </div> |
| 80 | + |
0 commit comments