Rules execute in order of their Order property (lower = first). Cheap regex/local checks run before expensive LLM calls.
.UseDefaults() (requires AgentGuard.Onnx package)
Wires up a solid baseline that works fully offline with no additional configuration:
using AgentGuard.Onnx;
var policy = new GuardrailPolicyBuilder()
.UseDefaults() // equivalent to the rules below
.Build();
// Expands to:
// .NormalizeInput() (order 5)
// .BlockPromptInjection() (order 10)
// .BlockPromptInjectionWithDefender() (order 11)
// .RedactPii() (order 20)
// .DetectSecrets() (order 22)
// .GuardToolCalls() (order 45)
// .GuardToolResults() (order 47)You can chain additional rules after UseDefaults() to layer on more protection (e.g. topic boundary, LLM-based rules, token limits).
.NormalizeInput(options?)
Decodes common evasion encodings before downstream rules see the text. Runs at order 5, before all other rules.
| Option | Type | Default | Description |
|---|---|---|---|
| DecodeBase64 | bool |
true | Detect and decode base64-encoded segments, in the standard or the URL-safe alphabet, with or without padding, also when joined to another word with - or _ |
| DecodeHex | bool |
true | Decode hex escape sequences (\x69\x67...) |
| DetectReversedText | bool |
true | Detect reversed text and hand it on read forwards: a message reversed as a whole, or one whose words are reversed in place, also behind a plain-text preamble (two injection keywords spelled backwards are enough) |
| NormalizeUnicode | bool |
true | Fold look-alike characters used to disguise Latin text: fullwidth letters (with the digits and punctuation in the same run), mathematical alphanumeric symbols, and circled or squared letters (the five that double as emoji, such as the parking sign, keep their emoji form when a variation selector marks them as one). Cyrillic and Greek look-alikes are folded to Latin only inside words that also contain Latin letters, so Russian or Greek text passes unchanged, as do superscripts, fractions and other compatibility characters. When full NFKC folding would reveal more injection keywords, the folded text is added as a decoded view |
| DecodeLeetspeak | bool |
true | Decode leetspeak in words that mix letters with digits or symbols (1gn0r3, a11, in$truction$). One disguised injection keyword is enough; numbers, prices and punctuation on their own are left alone |
| StripInvisibleUnicode | bool |
true | Strip the characters that render as nothing and are used to break up keywords: zero-width characters and joiners, directional marks, embeddings, overrides and isolates, soft hyphens, Hangul fillers, variation selectors placed after a letter or digit (one that selects an emoji, keycap or ideograph form stays), and Unicode tag characters (U+E0000-U+E007F, "ASCII smuggling"); text spelled in tag characters is also surfaced as a decoded view |
| MinBase64Length | int |
16 | Minimum base64 segment length to attempt decoding |
NormalizeUnicode and StripInvisibleUnicode rewrite the text itself. What the decoders decode is not added to the text - the model receives the text as written (after those two rewrites). Instead the decoded forms are handed to the pipeline as decoded views (InputNormalizationRule.DecodedViewsKey), and every later rule in the pipeline is also run on them: a block found in a decoded view blocks the text, with "(found in decoded content)" added to the reason, while a rewrite of a view is discarded. The token limit doesn't count decoded views. Running the later rules on the views means an LLM or remote rule may be called twice for a text that has them. Invalid UTF-16 (a lone surrogate) is replaced with U+FFFD rather than failing the rule.
.GuardRetrieval(options?)
Order 8, Input phase. Filters retrieved chunks before they reach the LLM context. Place the chunks in GuardrailContext.Properties["RetrievalChunks"] (any IEnumerable<RetrievedChunk>); the rule writes the surviving chunks to Properties["ApprovedChunks"] and the per-chunk evaluation to Properties["RetrievalGuardrailResult"], and leaves the user's text unchanged. EvaluateChunks(chunks) runs the same checks outside a pipeline, and RetrievalGuardrailContextProvider (AgentGuard.AgentFramework) plugs it into a MAF agent as a context provider. The provider adds the approved chunks as one User message framed as reference data (a "treat as data" header and numbered <<<chunk N>>> delimiters chunk text can't forge); ContextMessageRole and FormatContext change that, and ChatRole.System is discouraged for content you don't fully control.
Nothing puts chunks into the property bag on its own: .GuardRetrieval() in a policy used through UseAgentGuard() does nothing until the code that retrieves places its chunks there. In an agent, use RetrievalGuardrailContextProvider; elsewhere call EvaluateChunks where you retrieve.
| Option | Type | Default | Description |
|---|---|---|---|
| DetectPromptInjection | bool |
true | Flag chunks carrying an indirect injection. A chunk is checked the way a tool result is - with the tool result patterns for InjectionRiskLevel, as stored and with invisible characters removed, and inside base64, hex and percent-encoded runs. Invisible characters are also removed from the chunks handed on |
| InjectionRiskLevel | ToolRiskLevel |
Medium | Which tiers of the tool result patterns apply. Use High for stores holding text written by outsiders (inboxes, tickets, scraped pages) |
| DetectSecrets | bool |
true | Flag chunks carrying AWS access keys, GitHub tokens, private keys (PEM, PGP, SSH2), API key assignments or JWTs |
| DetectPII | bool |
false | Flag chunks carrying email addresses, US phone numbers or SSN-shaped numbers |
| MinRelevanceScore | double? |
null | Drop chunks whose Score is below this; chunks without a score are kept |
| MaxChunks | int? |
null | Keep only this many chunks, highest score first |
| Action | RetrievalFilterAction |
Remove | Remove drops a flagged chunk; Sanitize keeps it, with secrets and PII replaced where they stand and an injected instruction removed together with the rest of its paragraph |
| CustomFilters | IList<(string Name, Func<string, bool> Predicate)> |
[] | Extra checks on the chunk text; when sanitizing, a chunk a custom filter flags is replaced entirely |
| SanitizationReplacement | string |
[FILTERED] |
Replacement text when sanitizing |
With Sanitize, every filter a chunk trips is applied. A private key is replaced as a whole block - from its -----BEGIN ... PRIVATE KEY----- line (RSA, EC, DSA, OPENSSH, ENCRYPTED, PKCS#8, PGP private or secret key block, or SSH2) through the matching end line, or to the end of the chunk when that line is missing. Chunks dropped by MinRelevanceScore or MaxChunks are removed whatever the Action. A chunk that could not be scanned within the pattern time budget is removed under either action (filter scan-incomplete), and the result is then marked IsError. When chunks are removed, the result carries filteredCount, totalChunks, approvedCount and incompleteScans metadata.
.BlockPromptInjection(sensitivity)
Order 10, Input phase. Patterns informed by the Arcanum Prompt Injection Taxonomy. The builder method sets Sensitivity; for the other options add the rule directly: .AddRule(new PromptInjectionRule(new PromptInjectionOptions { ... })).
| Option | Type | Default | Description |
|---|---|---|---|
| Sensitivity | Sensitivity |
Medium | Low / Medium / High |
| CustomPatterns | IList<string> |
[] | Additional regex patterns; an invalid one throws when the rule is constructed |
| BlockSystemPromptExtraction | bool |
true | Run the system prompt extraction patterns |
| BlockRolePlayAttacks | bool |
true | Run the role/persona hijacking patterns |
| MatchTimeout | TimeSpan |
250 ms | Budget per pattern evaluation. Wall-clock; a pattern that exceeds it is tried once more before it counts as timed out |
| OnError | ErrorBehavior |
FailOpen | Outcome when a pattern timed out and no other pattern matched |
A pattern that exceeds MatchTimeout does not end the scan: the remaining patterns still run and any match blocks. The built-in patterns run in time linear in the input. The timeout is wall-clock, so on a host with no free processor it can fire for a pattern that is not slow; every regex-based rule therefore retries a timed-out pattern once before treating it as unfinished, which keeps a busy machine from skipping checks. A pattern that genuinely can't finish on an input costs two budgets instead of one.
Sensitivity tiers:
| Tier | Detects |
|---|---|
| Low (Core) | Direct instruction override, however it is worded ("ignore all of the previous instructions", "disregard your rules", "forget everything you were told"); personas without rules ("you are now DAN", "pretend you are an AI without restrictions", "developer mode enabled"); attempts to switch off the assistant's safeguards; chat-role markers followed by a directive, and forged assistant turns that start the answer; end sequence injection (chat-template tokens, fake role tags, bracketed frames, separator lines and headings that name the system or its instructions); instructions in HTML comments; variable expansion |
| Medium (+Medium) | + System prompt extraction, forged assistant turns (Assistant: at the start of a line), jailbreak keywords and personas described as having no rules, rule addition, standing orders to obey ("from now on you must comply"), anti-harm coercion, contradiction ("your real instructions are...") |
| High (+High) | + Plain role play ("pretend you are ...", "you are now a ..."), framing attacks (hypothetical/fictional contexts), inversion/double-negative extraction, link injection, bare chat-role markers (System:, User:, AI: at the start of a line), system-role JSON objects ("role": "system"), any standing order ("from now on you should ..."), bare "no restrictions" phrasing |
The Low and Medium tiers are written to leave ordinary requests alone. What a user says about their own messages ("ignore my previous instructions, I changed my mind"), about a thing ("ignore the above email"), or negated ("don't forget the previous instructions") is not an override; a filter or restriction that is not the assistant's ("disable the filter in Excel", "a plan with no restrictions") is not a bypass; "what are your rules for returns" is not prompt extraction; ### System Requirements, a PEM header and Model: ThinkPad at the start of a line are not frames or forged turns. Role play is the one deliberate trade: "pretend you are an interviewer" and "pretend you are my late grandmother" read the same to a pattern, so plain role play is only matched at High, where pasted transcripts, API payloads and standing preferences match too.
.BlockPromptInjectionWithDefender(), .BlockPromptInjectionWithDefender(mainThreshold) or .BlockPromptInjectionWithDefender(options)
Order 11, Input phase. Uses the StackOne Defender fine-tuned multi-head MiniLM-L6 ONNX model (minilm-multihead-v5, ~22 MB, int8 quantized). Fast (~8 ms), fully offline, bundled - the model ships in the Kyoto package that AgentGuard.Onnx depends on and is copied next to your app on build, so no separate download is required.
The model emits two temperature-calibrated scores: a main injection score and an aux "directed at a human reader" score. Input is blocked when main >= MainThreshold AND aux < AuxThreshold - a high aux score vetoes the block. This rescues imperative-but-benign phrasings (e.g. "show me my orders", "list all my orders") that score high on the main head.
| Option | Type | Default | Description |
|---|---|---|---|
| MainThreshold | float |
0.75 | Main-head block threshold (0.0–1.0) |
| AuxThreshold | float |
0.64 | Aux-head veto threshold (0.0–1.0); aux at or above this rescues the block |
| TemperatureT | float |
2.41 | Calibration temperature; each logit is divided by this before sigmoid |
| MaxTokenLength | int |
256 | Model input size; longer input is split into windows, not truncated |
| WindowSize | int |
64 | Tokens per window when the input doesn't fit in one; small windows keep a short injection from being diluted by surrounding text |
| WindowOverlap | int |
32 | Tokens shared by consecutive windows, so nothing that short is cut in half |
| MaxWindows | int |
512 | Input needing more windows is blocked (Medium severity, inputTooLong metadata) without running the model; 0 = no limit |
| IncludeConfidence | bool |
true | Include main/aux scores in result metadata |
| OnError | ErrorBehavior |
FailClosed | What to do when the tokenizer or the model fails on an input: FailClosed (block), Warn (pass, surfaced as a warning), FailOpen (pass quietly). The default differs from the remote and regex rules: the model is local, so a failure is caused by the input, and failing open would let a crafted input switch the classifier off |
| ModelPath | string? |
null | Custom model path (if null, bundled model is used) |
| VocabPath | string? |
null | Custom vocab path (if null, bundled vocab is used) |
When blocked, result metadata includes:
mainScore/auxScore- calibrated probabilities (0.0–1.0)model-"stackone-defender-minilm-multihead-v5"mainThreshold/auxThreshold/temperatureT- the configured decision parameters
using AgentGuard.Onnx;
// Zero-config - bundled model, no download needed
builder.BlockPromptInjectionWithDefender()
// Or with a custom main-head threshold (raise to reduce false positives further)
builder.BlockPromptInjectionWithDefender(new DefenderPromptInjectionOptions { MainThreshold = 0.93f })The options are validated when the rule is constructed: a threshold that is NaN or outside 0.0-1.0, a non-positive TemperatureT, a MaxTokenLength below 3, a WindowSize below 1, or a WindowOverlap that is negative or not smaller than WindowSize throws ArgumentOutOfRangeException. An undefined OnError value throws too. The same checks apply to the DeBERTa, PIGuard and Opir rules below. The ONNX rules are IDisposable (disposing the policy disposes them, and disposing twice is safe); evaluating a disposed rule throws ObjectDisposedException. Disposing a rule while evaluations are running is safe: they finish, and the model session is released when the last one completes.
Failures. An input the tokenizer or the model can't process is an error result decided by OnError (IsError set, exception type and message in errorDetail), not an exception out of the pipeline. Cancellation and use after disposal still throw. Unpaired UTF-16 surrogates are replaced with U+FFFD before classification, so malformed text is classified rather than failing.
Long input. Text that fits in one window is classified in a single call. Longer text is split into overlapping windows that cover all of it; the rule blocks if any window blocks, and the metadata of the worst window adds windowIndex, windowCount, windowStart and windowLength. Cost grows with length (about 5 ms per window on a laptop CPU). Because every passage is classified, long technical or instructional text (man pages, READMEs) is blocked more often than short prompts - raise WindowSize (up to MaxTokenLength - 2) to trade dilution resistance for fewer such blocks. Each window is checked against what the model session actually encodes and split further when it would not fit, so nothing is silently truncated. Defender reads line breaks and tabs as word separators, and classifies a word of more than 100 characters in pieces rather than as one unknown token (windowStart / windowLength still refer to the original text); long unbroken blobs such as base64 therefore cost more windows and can reach MaxWindows.
Limitations.
- English-centric. Trained mostly on English, the model over-fires on non-English benign input (e.g. ordinary German questions). For non-English users, raise
MainThresholdfor that segment rather than disabling the rule (see Dynamic rule enabling). Tradeoff: a higher threshold also weakens detection of native-language attacks, so pair it with a multilingual classifier for real coverage. - Text without word boundaries. An injection written with no separators at all scores lower than the same words spaced (0.64-0.77 against 0.97 measured), and a word of up to 100 characters holding a character outside the vocabulary is one unknown token. Pair Defender with
NormalizeInput()and the regex rule for obfuscated input. - Residual English imperatives. A few "show me X" phrasings (e.g. "show me my account details") still block - confidently misscored ~90% with low aux, so no threshold short of ~0.9-0.93 rescues them, and that costs recall.
The default MainThreshold is 0.75 (within the F1-optimal plateau on a held-out jailbreak set: ~4× lower false-positive rate than 0.5 for a few points of recall). Raise toward 0.9/0.93 to cut false positives further at a recall cost.
.BlockPromptInjectionWithDeberta(options) or .BlockPromptInjectionWithDeberta(modelPath, tokenizerPath, threshold)
Order 12, Input phase. Uses a fine-tuned DeBERTa v3 ONNX model (protectai/deberta-v3-base-prompt-injection-v2) for ML-based binary classification. Fully offline, ~100ms inference. Requires separate model download. For most use cases, prefer the Defender model above.
Setup: AgentGuard ships no model for this rule. Download model.onnx (~370 MB) and spm.model from the onnx/ folder of protectai/deberta-v3-base-prompt-injection-v2, or fetch them with the Kyoto bootstrap (see eng/MODELS.md):
# from a sibling checkout of the Kyoto repo
cd ../kyoto
./bootstrap-models.sh deberta # model.onnx + spm.model -> ./models/deberta-v3-prompt-injection/
source ./models/env.sh # exports AGENTGUARD_ONNX_MODEL_PATH and AGENTGUARD_ONNX_TOKENIZER_PATH| Option | Type | Default | Description |
|---|---|---|---|
| ModelPath | string |
(required) | Path to the ONNX model file |
| TokenizerPath | string |
(required) | Path to the SentencePiece model file (spm.model) |
| Threshold | float |
0.5 | Confidence threshold (0.0–1.0) for injection classification |
| MaxTokenLength | int |
512 | Model input size; longer input is split into windows, not truncated |
| WindowSize / WindowOverlap / MaxWindows | int |
510 / 128 / 32 | Window size (clamped to what the model accepts), overlap, and the cap above which input is blocked; see the Defender section |
| OnError | ErrorBehavior |
FailClosed | What to do when the tokenizer or the model fails on an input: FailClosed (block), Warn (pass, surfaced as a warning), FailOpen (pass quietly). See the Defender section |
| IncludeConfidence | bool |
true | Include confidence score in result metadata |
Multi-tier detection:
using AgentGuard.Onnx;
builder.BlockPromptInjection() // tier 1: regex (order 10)
.BlockPromptInjectionWithDefender() // tier 2: Defender ML (order 11, bundled)
.BlockPromptInjectionWithRemoteClassifier(...) // tier 3: remote ML (order 13)
.BlockPromptInjectionWithLlm(chatClient) // tier 4: LLM (order 15).BlockPromptInjectionWithPIGuard(options) or .BlockPromptInjectionWithPIGuard(modelPath, tokenizerPath, threshold)
Order 12, Input phase. Uses the PIGuard DeBERTa v3 model (ACL 2025, MIT), trained with the "Mitigating Over-defense for Free" strategy. In AgentGuard's own measurements it keeps benign false positives low (over-defense comparable to the bundled Defender) while detecting indirect / code-style injection far better than Defender (BIPIA_code recall 96% vs 34%). Fully offline. A heavier model than Defender, so best used as a standalone guard or layered after it. See the PIGuard evaluation in the Kyoto repo for the full benchmark.
Setup: Download model_fp16.onnx (~369 MB; the fp32 model.onnx is also published) and spm.model from filip-w/PIGuard-onnx, or fetch them with the Kyoto bootstrap (see eng/MODELS.md):
# from a sibling checkout of the Kyoto repo
cd ../kyoto
./bootstrap-models.sh piguard # fp16 model (saved as model.onnx) + spm.model -> ./models/piguard/
source ./models/env.sh # exports AGENTGUARD_PIGUARD_ONNX_MODEL_PATH and AGENTGUARD_PIGUARD_TOKENIZER_PATH| Option | Type | Default | Description |
|---|---|---|---|
| ModelPath | string |
(required) | Path to the PIGuard ONNX model file |
| TokenizerPath | string |
(required) | Path to the DeBERTa v3 SentencePiece model (spm.model) |
| Threshold | float |
0.9 | Confidence threshold. The argmax default (0.5) over-blocks; 0.9 is the measured operating point |
| MaxTokenLength | int |
512 | Model input size; longer input is split into windows, not truncated |
| WindowSize / WindowOverlap / MaxWindows | int |
510 / 128 / 32 | Window size (clamped to what the model accepts), overlap, and the cap above which input is blocked; see the Defender section |
| OnError | ErrorBehavior |
FailClosed | What to do when the tokenizer or the model fails on an input: FailClosed (block), Warn (pass, surfaced as a warning), FailOpen (pass quietly). See the Defender section |
| IncludeConfidence | bool |
true | Include confidence score in result metadata |
The model is an ONNX export distributed at
filip-w/PIGuard-onnx.
.BlockPromptInjectionWithRemoteClassifier(endpointUrl, apiKey?, modelName?, threshold?), .BlockPromptInjectionWithRemoteClassifier(httpClient, classifierOptions, ruleOptions?) or .BlockPromptInjectionWithRemoteClassifier(classifier, options?)
Order 13, Input phase. Calls an external model server for ML-based classification. Designed for SOTA models like Sentinel-v2 (Qwen3-0.6B, F1 ~0.957, 32K context). Requires AgentGuard.RemoteClassifier package.
EndpointUrl, ApiKey, ModelName and RequestFormat are HttpClassifierOptions (the HTTP client); the rest are RemotePromptInjectionOptions (the rule).
| Option | Type | Default | Description |
|---|---|---|---|
| EndpointUrl | string |
(required) | URL of the classification endpoint |
| ApiKey | string? |
null | Sent as a Bearer token in the Authorization header of each request; it is never set on the HttpClient, so classifiers sharing a client each send their own key |
| ModelName | string? |
null | Model name for result metadata |
| RequestFormat | HttpClassifierRequestFormat |
HuggingFace | Request/response format (HuggingFace or Simple) |
| InjectionLabels | ISet<string> |
jailbreak, injection, prompt_injection, malicious, unsafe, harmful, attack, LABEL_1 | Labels indicating injection. Labels are compared on letters and digits only, ignoring case, so prompt_injection, prompt-injection and PromptInjection are one label. Must not be empty or share a label with SafeLabels. Read once when the rule is constructed |
| SafeLabels | ISet<string> |
safe, benign, legit, legitimate, clean, normal, harmless, LABEL_0 | Labels that mean the text is clean. A predicted label in neither set is an error handled by OnError, not a pass - add your model's own labels (and swap LABEL_0 / LABEL_1 if it numbers them the other way round) |
| MaxCharactersPerRequest | int |
2000 | Longer text is classified in overlapping windows, one request each, split at whitespace; an injection in any window blocks |
| WindowOverlapCharacters | int? |
a fifth of the window | Characters consecutive windows share; at most half of MaxCharactersPerRequest |
| MaxRequests | int |
32 | Text needing more requests is an error handled by OnError (under FailClosed nothing is sent; otherwise the first windows are still checked and an injection there still blocks); 0 = no limit |
| Threshold | float |
0.5 | Confidence threshold (0.0-1.0; NaN or out of range throws when the rule is constructed) |
| IncludeConfidence | bool |
true | Include the score in result metadata |
| OnError | ErrorBehavior |
FailOpen | What to do on error: FailOpen (pass quietly), Warn (pass, surfaced as a warning), FailClosed (block) |
| Timeout | TimeSpan |
10s | Timeout of each request; must be positive or Timeout.InfiniteTimeSpan |
The rule blocks when an injection label's own score reaches the threshold - the top label's, or any injection label's when the endpoint returns a score for every label, so thresholds below 0.5 work with such endpoints. A response the classifier can't read (no entries, an entry without a label, a score outside 0-1, an unknown shape) or a predicted label the rule doesn't know is an error handled by OnError, not a pass. When the text was split, a block's metadata adds window and windowCount; windows are sent one at a time and the first failure or injection ends the evaluation.
When blocked, result metadata includes:
label- the injection label that reached the threshold (e.g. "jailbreak"; the highest-scoring one when several do)confidence- that label's score (0.0-1.0)model- model name (if configured)threshold- the configured threshold
Setting up a Sentinel-v2 endpoint: any small HTTP app wrapping transformers.pipeline("text-classification", ...) (for example FastAPI + uvicorn) works. The classifier sends POST {EndpointUrl} with {"inputs": "<text>"} (HuggingFace, the default) or {"text": "<text>"} (Simple), and reads the pipeline's output - a single {"label": "jailbreak", "score": 0.99} object, a list of them, or a nested [[...]] (every inner list is read). The highest-scoring label is the prediction, and every label's score is available as ClassificationResult.Scores.
using AgentGuard.RemoteClassifier;
var policy = new GuardrailPolicyBuilder()
.BlockPromptInjection() // tier 1: regex
.BlockPromptInjectionWithRemoteClassifier( // tier 2: remote ML
"http://localhost:8000/classify",
modelName: "sentinel-v2",
threshold: 0.7f)
.BlockPromptInjectionWithLlm(chatClient) // tier 3: LLM
.Build();.BlockPromptInjectionWithLlm(chatClient, options?)
Order 15, Input phase. Uses IChatClient as an LLM-as-judge classifier. Catches sophisticated attacks regex misses: narrative smuggling, meta-prompting, cognitive overload, multi-chain attacks.
| Option | Type | Default | Description |
|---|---|---|---|
| SystemPrompt | string? |
null | Custom system prompt override (null = built-in template) |
| IncludeClassification | bool |
true | Return structured threat classification metadata |
When IncludeClassification is true, blocked results include Metadata with:
technique- e.g.direct_override,narrative_smuggling,cognitive_overload,russian_dollintent- e.g.jailbreak,system_prompt_leak,data_extractionevasion- e.g.none,base64,hex,reversed,unicodeconfidence-high,medium, orlow
How judge replies are read (all LLM rules). The judge's reply is parsed tolerantly. These are all understood:
- markdown emphasis and code markers;
Verdict:,Answer:,Classification:,Result:,Label:,Decision:and similar prefixes, including one on a line of its own;- a reason on the same line or on the lines below, including one that starts with a negation word ("VIOLATION: no disclaimer was included");
- a positive verdict on a later line, below a preamble such as "Here is my classification:";
- reasoning in
<think>,<thinking>or<reasoning>blocks, even when the opening tag is missing; - a JSON object with a
verdict,classification,answerorresultfield.
A reply that negates or questions its own finding ("PII: none", "INJECTION - not found", "INJECTION?", "SAFE: false"), or that has no verdict at all, is unparseable and goes through the rule's errorBehavior, which fails open by default. A negative verdict is only read from the verdict line itself, never from further down: text the judge quotes from what it is judging can therefore cause a block, but not a pass. For the same reason a positive verdict on the opening line stands even when a closing reasoning tag appears later in the reply. The error detail quotes the judge's text only when content capture (AGENTGUARD_CAPTURE_CONTENT) is on.
The conversation history given to a judge includes tool calls (name and arguments) and tool results, fenced like message text and capped in size: 1,000 characters per call's arguments, 2,000 per result, and 12,000 in all, with the most recent kept first. Custom LlmGuardrailRule subclasses get the same parsing from ExtractVerdictLine/ClassifyVerdict.
.RedactPii(options?, ruleOptions?) or .RedactPii(replacement, entities...) (from AgentGuard.Pii)
Order 20, Both phases. Offline PII detection and anonymization using validated regex recognizers
with confidence scoring, overlap resolution, lemma-aware context score boosting, and configurable
anonymization operators. PiiRule is a thin adapter over the TasmanianDevil
engine, whose types (PiiOptions, PiiEntities, PiiCountries, the engines below) live in the
TasmanianDevil namespaces. The engine is inspired by the architecture of Microsoft Presidio; its
attributions are in the THIRD_PARTY_NOTICES.txt of the TasmanianDevil package.
Generic entities (always on): CREDIT_CARD (Luhn), EMAIL_ADDRESS, IBAN_CODE (mod-97),
CRYPTO (Bitcoin checksum), IP_ADDRESS, URL, MAC_ADDRESS, PHONE_NUMBER (libphonenumber).
US pack (always on): US_SSN, US_ITIN, ABA_ROUTING_NUMBER (checksum), US_BANK_NUMBER,
US_DRIVER_LICENSE, US_PASSPORT, US_NPI (Luhn), US_MBI, MEDICAL_LICENSE (DEA checksum).
Country packs (opt-in via Countries): enabling every national identifier at once inflates
false positives, so non-US packs are opt-in by ISO 3166-1 alpha-2 code:
uk(gbis accepted as an alias):UK_NINO,UK_NHS(mod-11),UK_POSTCODE,UK_PASSPORT,UK_DRIVING_LICENCE,UK_VEHICLE_REGISTRATIONde:DE_ID_DOCUMENT(ICAO checksum; the Personalausweis and Reisepass share one format and cannot be told apart by the number alone, so they are a single entity type),DE_TAX_ID(checksum),DE_PLZ,DE_SOCIAL_SECURITY(checksum),DE_VAT_ID(checksum),DE_FUEHRERSCHEIN,DE_KFZ,DE_TAX_NUMBER,DE_HANDELSREGISTERin:IN_AADHAAR(Verhoeff),IN_PAN,IN_GSTIN(structure),IN_PASSPORT,IN_VOTER,IN_VEHICLE_REGISTRATIONit:IT_FISCAL_CODE(checksum),IT_VAT_CODE(checksum),IT_DRIVER_LICENSE,IT_IDENTITY_CARD,IT_PASSPORTes:ES_NIF(mod-23),ES_NIE(mod-23),ES_PASSPORTnl:NL_BSN(11-proef),NL_POSTCODE,NL_PASSPORT- each needs a nearby context word (bsn,postcode,paspoort, ...) to clear the default threshold
By default all enabled entities are detected; pass Entities to restrict. Entity types and country
codes are open string vocabularies (custom recognizers can add their own), so the API takes string;
the PiiEntities and PiiCountries constant classes provide discoverability and typo-safety:
using AgentGuard.Pii; // RedactPii()
using TasmanianDevil; // PiiOptions, PiiEntities, PiiCountries
builder.RedactPii(new PiiOptions
{
Entities = [PiiEntities.EmailAddress, PiiEntities.PhoneNumber, PiiEntities.UsSsn],
Countries = [PiiCountries.Uk, PiiCountries.De],
});Anonymization operators: replace (default, <ENTITY_TYPE>), redact, mask, hash,
encrypt/decrypt (reversible, authenticated AES-GCM), keep, custom. Configure per-entity via Operators.
PiiOptions |
Type | Default |
|---|---|---|
| Entities | IReadOnlyList<string>? |
null (all entities) |
| Countries | IReadOnlyList<string>? |
null (generic + US only) |
| Operators | IReadOnlyDictionary<string, OperatorConfig>? |
null (replace with <ENTITY_TYPE>) |
| Replacement | string? |
null (flat replacement for every entity, e.g. [REDACTED]; ignored when Operators is set) |
| Language | string |
en |
| ScoreThreshold | double |
0.4 |
| ContextMatchingMode | Substring / WholeWord |
Substring |
| AllowList | IReadOnlyList<string>? |
null |
| AllowListMatch | Exact / Regex |
Exact (Regex treats each entry as a pattern) |
| ConflictResolution | MergeSimilarOrContained / RemoveIntersections |
MergeSimilarOrContained (RemoveIntersections also trims partially overlapping spans) |
| MergeEntitiesWithSpaces | bool |
true (adjacent same-type spans separated only by spaces become one entity; false anonymizes each span on its own) |
ContextMatchingMode controls how a recognizer's context words are matched against the
(stemmed) tokens around a candidate: Substring (default) matches card inside creditcard;
WholeWord requires an exact token match, reducing false context hits.
Guardrail-side settings live on AgentGuard's PiiRuleOptions, passed as the second argument
(.RedactPii(options, ruleOptions); RedactPiiWithNer takes it too): RedactOutput (default true)
runs the rule on input and output, false on input only; OnError (default FailOpen) decides what a
recognizer failure does - an unreachable remote or Azure detector, say. Under FailOpen and Warn the
text continues with whatever the working recognizers found redacted and the result has IsError set;
under FailClosed it is blocked.
PiiOptions.Entities is checked when the rule is built: a name no recognizer detects (a misspelling, or
a country entity whose pack is not enabled) throws ArgumentException listing the names that are
detected, instead of silently switching that detection off. Names are matched ignoring case.
// enable UK + German packs on top of the generic + US defaults
builder.RedactPii(new PiiOptions { Countries = ["uk", "de"] });
// redact user input only, leave model output alone
builder.RedactPii(new PiiOptions(), new PiiRuleOptions { RedactOutput = false });Beyond the PiiRule pipeline rule, the TasmanianDevil engine behind it can be used directly for
richer workflows. All are fully offline. PiiEngine, PiiOptions and PiiRecognizers are in the
TasmanianDevil namespace; the lower-level engines are in TasmanianDevil.Analyzer,
TasmanianDevil.Anonymizer (with OperatorConfig in TasmanianDevil.Anonymizer.Operators),
TasmanianDevil.Structured and TasmanianDevil.Batch.
The quickest entry point is the PiiEngine facade, configured once from the same PiiOptions as the
rule, with one-liners for every operation:
using TasmanianDevil;
var pii = new PiiEngine(new PiiOptions { Countries = ["de"] }); // or PiiEngine.Create("en", "de")
pii.Anonymize(text).Text; // free-text redaction
var deid = pii.Deidentify(text); // PiiDeidentificationResult (persist deid.Items)
pii.Reidentify(deid, reverseOps).Text; // restore spans anonymized with encrypt (decrypt)
pii.AnonymizeJson(json, scope); // structured JSON
pii.AnonymizeCsv(header, rows); // structured CSV
pii.AnonymizeBatch(records); // batch over keyed recordsAnalyzeAsync, AnonymizeAsync and DeidentifyAsync also run asynchronous recognizers - such as the
remote and Azure detectors in Remote PII detection, passed through the constructor's
extraRecognizers - which the synchronous methods skip. The lower-level engines below are available
directly when you need full control.
Reversible de-identification - encrypt PII spans, persist the items, restore later:
var analyzer = new AnalyzerEngine(PiiRecognizers.CreateDefaultRegistry("en"));
var anonymizer = new AnonymizerEngine();
var encryptOps = new Dictionary<string, OperatorConfig>
{
["DEFAULT"] = new("encrypt", new Dictionary<string, object> { ["key"] = "0123456789abcdef" }),
};
var encrypted = anonymizer.Anonymize(text, analyzer.Analyze(text, "en"), encryptOps);
var deid = PiiDeidentificationResult.FromEngineResult(encrypted); // .IsReversible
// later, with the same key:
var decryptOps = new Dictionary<string, OperatorConfig>
{
["DEFAULT"] = new("decrypt", new Dictionary<string, object> { ["key"] = "0123456789abcdef" }),
};
var restored = new DeanonymizerEngine().Deanonymize(deid.AnonymizedText, deid.Items, decryptOps);
// restored.Text == text (byte-for-byte)DeanonymizerEngine reverses encrypt (default decrypt) and custom spans. Lossy operators
(replace/redact/mask/hash/keep) are reported as non-reversible (IsReversible == false,
and Deanonymize throws if asked to decrypt them); a wrong or missing key throws clearly.
Structured data - redact JSON by key path or CSV by inferred column:
var structured = new StructuredEngine(analyzer);
// JSON: analyze only values under the user.email path; structure and non-string types preserved
var redactedJson = structured.AnonymizeJson(
json, new JsonRedactionScope { IncludePaths = ["user.email"] });
// CSV/TSV: per-column inference; benign columns are left untouched
var result = structured.AnonymizeCsv(header, rows); // result.ColumnEntities reports PII columnsBatch - analyze/anonymize lists or keyed records, results aligned to input:
var batchAnalyzer = new BatchAnalyzerEngine(analyzer);
var batchAnonymizer = new BatchAnonymizerEngine();
var detections = batchAnalyzer.Analyze(records); // IReadOnlyDictionary<string,string>
var anonymized = batchAnonymizer.Anonymize(records, detections); // keys preservedSee samples/AgentFrameworkPii for a runnable tour of PII in an agent, and samples/RemotePii for out-of-process detection.
.RedactPiiWithNer(nerOptions, piiOptions?, ruleOptions?) or
.RedactPiiWithNer(modelPath, tokenizerPath, configPath, threshold?, piiOptions?, ruleOptions?) (from AgentGuard.Onnx)
Order 20, same PiiRule pass. Augments the regex/checksum recognizers with an offline ONNX
named-entity recognizer that detects the span entity types regex cannot catch - PERSON,
LOCATION, ORGANIZATION, DATE_TIME - and resolves them against the regex entities in a single
analyzer -> anonymizer pass (so overlap resolution and anonymization treat them uniformly). The NER
spans flow through the same engine, so the redaction output mixes <PERSON>, <LOCATION>,
<EMAIL_ADDRESS>, etc. transparently.
Uses a GLiNER span model (mDeBERTa-v3-base
backbone, Apache-2.0) - multilingual (the reason to add it; regex and spaCy-style NER are
English-leaning) and zero-shot. The model is not bundled; download it from
filip-w/gliner-multi-pii-onnx (model, spm.model
and config.json) or with the Kyoto bootstrap - see eng/MODELS.md. Not part of UseDefaults().
GlinerNerOptions.NerThreshold (default 0.5, the micro-F1 optimum - see
the GLiNER evaluation in the Kyoto repo) is the binding gate for NER spans; the
analyzer's PiiOptions.ScoreThreshold still applies on top. NER coverage targets whitespace-segmented
scripts (Latin / Cyrillic / Arabic / Devanagari); CJK is out of practical scope for the word splitter.
GlinerNerOptions comes from the TasmanianDevil.Onnx package (using TasmanianDevil.Onnx;), which
AgentGuard.Onnx depends on.
GlinerNerOptions |
Type | Default |
|---|---|---|
| ModelPath | string |
(required) |
| TokenizerPath | string |
(required) mDeBERTa-v3 spm.model |
| ConfigPath | string |
(required) config.json (special-token ids + max span width) |
| NerThreshold | float |
0.5 |
| MaxTokenLength | int |
384 (tokens per inference call, label prompt included; longer input is split into chunks) |
| MaxSpanWidth | int |
12 (in words; must match the value the ONNX graph was exported with) |
| MaxChunkChars | int |
1200 (characters per chunk; chunks hold whole words and their spans are mapped back onto the full text) |
| EntityLabelMap | IReadOnlyDictionary<string,string> |
person→PERSON, location→LOCATION, organization→ORGANIZATION, date→DATE_TIME |
using AgentGuard.Onnx; // RedactPiiWithNer()
using TasmanianDevil; // PiiOptions
// detect names/places/orgs/dates alongside regex PII, in one order-20 pass
builder.RedactPiiWithNer(
modelPath: "models/gliner/model.onnx",
tokenizerPath: "models/gliner/spm.model",
configPath: "models/gliner/config.json",
piiOptions: new PiiOptions { Countries = ["de"] });.DetectSecrets(action?) or .DetectSecrets(options)
Order 22, Both phases. Detects API keys, tokens, connection strings, private keys and other credentials, so they are neither sent to the model nor leaked in its output.
| Option | Type | Default | Description |
|---|---|---|---|
| Categories | SecretCategory |
Default | Flags: ApiKey (API key/token assignments, bearer tokens, Slack tokens, and quoted secret fields such as "api_key": "..." or 'password': '...'), AwsCredential, ConnectionString (connection strings with a password, and any URI with a password in its user info - postgres://, mysql://, mongodb(+srv)://, redis://, amqp://, ...), PrivateKey (PEM, PGP and SSH2 blocks), JwtToken, GitHubToken (classic and fine-grained github_pat_), AzureKey (storage account and subscription keys). GenericHighEntropy is opt-in (All includes it) |
| Action | SecretAction |
Block | Block rejects the text; Redact replaces each finding (high-entropy ones included) with Replacement |
| Replacement | string |
[SECRET_REDACTED] |
Replacement text when redacting, inserted literally. Where the secret is a value - a quoted field, the password of a connection string or URI, a token assigned to a secret-like key - only the value is replaced, so a URI keeps its user name and host |
| CustomPatterns | IDictionary<string, string> |
{} | Additional patterns: label -> regex (culture-invariant). A pattern with a group named secret has only that group replaced when redacting |
| MinHighEntropyLength | int |
20 | Shortest token GenericHighEntropy considers (at least 8). A value assigned to a secret-like key name (key, secret, token, password, pwd, auth, credential, ...) is considered from 12 characters |
| OnError | ErrorBehavior |
FailOpen | Outcome when a pattern timed out and nothing else was found: FailOpen (pass, with IsError set), Warn (pass, surfaced as a warning), FailClosed (block) |
A private key matches as a whole block - from the -----BEGIN ... PRIVATE KEY----- line (RSA, EC, DSA, OPENSSH, ENCRYPTED, PKCS#8, PGP's PRIVATE KEY BLOCK and SECRET KEY BLOCK, and the SSH2 ---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ---- form) through the matching end line, or to the end of the text when that line is missing - so Redact removes the key body, not just its header. Placeholder values (${VAR}, $VAR, <password>, %PASSWORD%, ****, changeme, YOUR_API_KEY, your-api-key-here) are not reported, and neither is a value that is code rather than a key (apiKey: process.env.OPENAI_API_KEY). A value has to be a placeholder as a whole: a password that only starts like one ($uperS3cret!9, Enterprise2024!, (Tr0ub4dor&3)) is a password. In a key=value connection string the password may be quoted and may come before or after the host key; SharedAccessKey= and AccountKey= values are reported as well.
A pattern that exceeds its 200 ms match timeout twice in a row is skipped and the others still run. When nothing else was found, the result is an error decided by OnError (default FailOpen) with IsError set, not a clean pass; when Redact did replace something, the result also has IsError and IsWarning set, since the text may hold what the unfinished pattern looks for.
GenericHighEntropy flags a token when its entropy reaches 90% (85% next to a secret-like key name) of what a random string of the same length and character set - hex, single-case alphanumeric, base64 or printable ASCII - typically has. Hex strings and tokens inside URLs only count when they are assigned to a secret-like key name. Git SHAs, UUIDs, labelled and Subresource Integrity hashes, data URIs and base64 images, long words and camelCase/PascalCase identifiers, file paths, URLs without credentials and JWTs (left to the JWT pattern) are not flagged. A bare 40-character AWS secret key is only flagged when related context appears in the text (aws as a word, secret access key however it is separated, or an AKIA... access key id) and it is not forty hex digits, which is a commit id. A 32-character hex Azure subscription key is only flagged when a key is named (ocp-apim-subscription-key, subscription key, AZURE_..._KEY, api key, ...). When blocked, result metadata includes detectedCategories (e.g. aws-access-key, private-key).
.DetectPIIWithLlm(chatClient, options?)
Order 25, Both phases. Catches unstructured PII (names, addresses, contextual identifiers) that regex misses.
| Option | Type | Default |
|---|---|---|
| Action | PiiAction |
Redact |
| SystemPrompt | string? |
null (built-in templates) |
| ValidateRedaction | bool |
true |
PiiAction.Block returns a blocked result. PiiAction.Redact reads the judge's redacted version - everything after its REDACTED: marker, across all lines (the marker may also sit on its own line) - and applies it to the original rather than taking it as the new text.
The judge's version is accepted when it is the original with stretches replaced by placeholders ([REDACTED], any other bracketed label, <EMAIL_ADDRESS>, ***): the text between its placeholders has to appear in the original, in order, from its first word to its last, ignoring spacing and capitalization. The result is then the original with those stretches swapped for the placeholders, so everything that is kept is exactly what was written. A reply that changes other text, stops early, comes back unchanged, drops the data without a placeholder, or replaces more than 256 characters with one placeholder is a failed judgment: the result has IsError set and the rule's ErrorBehavior decides whether the text passes (the default) or is blocked. A message that was already redacted on an earlier turn passes.
Set ValidateRedaction = false only with a custom SystemPrompt that redacts some other way (removing the data, substituting made-up values); the judge's reply then replaces the text as it is.
.EnforceTopicBoundaryWithLlm(chatClient, topics...) or .EnforceTopicBoundaryWithLlm(chatClient, options)
Order 35, Input phase. Semantic topic classification using an LLM that understands intent and conversation context. Conversation history is included in the prompt so short follow-up replies ("yes", "tell me more") are correctly classified based on the preceding conversation.
| Option | Type | Default |
|---|---|---|
| AllowedTopics | IList<string> |
(required) |
| SystemPrompt | string? |
null (built-in template with {topics} and {history} placeholders) |
.LimitInputTokens(max, strategy) / .LimitOutputTokens(max, strategy)
Order 40, Input or Output phase.
Strategies: Reject, Truncate, Warn
Counts tokens with Microsoft.ML.Tokenizers, using the cl100k_base encoding by default. TokenLimitOptions.TokenizerModel takes an encoding name (cl100k_base, o200k_base, o200k_harmony, p50k_base, p50k_edit, r50k_base) or an OpenAI model name such as gpt-4o, matched case-insensitively; an unknown name, or a MaxTokens below 1, throws when the rule is constructed. The cl100k_base and o200k_base vocabularies ship with the package. For an encoding whose vocabulary isn't installed (p50k and r50k), the rule estimates the count per script: about 4 ASCII characters per token, one token per CJK, Kana, Hangul, fullwidth or emoji character, and 2 characters per token for other text. Truncate cuts at a token boundary and never exceeds the budget.
Text is tokenized in bounded segments, so the check stays linear in the length of the text even for one long unbroken run. Text longer than MaxTokens × TokenLimitOptions.MaxCharactersPerToken (default 16) characters - and at least 16,384 characters - is over the limit without being tokenized: Reject blocks it, Truncate cuts it to that length first, Warn reports its character count.
.BlockHarmfulContent(maxSeverity) or .BlockHarmfulContent(options) or .BlockHarmfulContent(classifier, options?)
Order 50, Both phases.
Requires an IContentSafetyClassifier. Use AgentGuard.Azure for Azure AI Content Safety integration (see Azure integration). The first two overloads attach no classifier, so the rule cannot reach a verdict: every evaluation reports a rule error, which the default OnError (FailOpen) lets through. Pass the classifier with .BlockHarmfulContent(classifier, options?).
| Option | Type | Default | Description |
|---|---|---|---|
| MaxAllowedSeverity | ContentSafetySeverity |
Low | Highest severity allowed; anything above it blocks |
| Categories | ContentSafetyCategory |
All | Which categories to check (Hate, Violence, SelfHarm, Sexual) |
| BlocklistNames | IList<string> |
[] | Server-side blocklists to check against |
| HaltOnBlocklistHit | bool |
false | Skip category analysis if blocklist matches (performance optimization) |
| OnError | ErrorBehavior |
FailOpen | What to do when there is no classifier or the classifier reports a failure: FailOpen (pass quietly), Warn (pass, surfaced as a warning), FailClosed (block) |
Blocklist matches are checked first and take precedence over category analysis. When a blocklist match is found, the result includes metadata with blocklistName, blocklistItemText, and totalMatches.
.BlockUnsafeContentWithOpir(options) or .BlockUnsafeContentWithOpir(modelPath, tokenizerPath, prefixPath, threshold)
Order 50, Input phase. Requires AgentGuard.Onnx. Uses the Opir-multilang model (GLiClass uni-encoder over mDeBERTa-v3-base, Apache-2.0) to score text against a frozen harm taxonomy - toxicity, hate speech, violence, sexual content, self-harm, harassment - in any language. Blocks when the strongest per-label probability reaches the threshold. Fully offline.
This is an offline, multilingual content-safety guard - the gap the other classifiers leave open. The bundled Defender is English-only (~0% recall off-English), and cloud content-safety APIs are per-call and PII-bound. Opir-multilang gives genuine non-English coverage locally (≈40-76% recall at 16-36% FPR across de/es/ru/ar/zh/hi on textdetox/multilingual_toxicity_dataset). Position it as complementing (not replacing) Azure Content Safety, the way Defender is positioned for English injection. See the Opir evaluation in the Kyoto repo for the full benchmark.
Setup: Download model_fp16.onnx (~561 MB; the fp32 model.onnx is also published), spm.model and prefix.json from filip-w/opir-multilang-onnx, or fetch them with the Kyoto bootstrap (see eng/MODELS.md):
# from a sibling checkout of the Kyoto repo
cd ../kyoto
./bootstrap-models.sh opir # fp16 model (saved as model.onnx) + spm.model + prefix.json -> ./models/opir-multilang/
source ./models/env.sh # exports AGENTGUARD_OPIR_ONNX_MODEL_PATH, _TOKENIZER_PATH and _PREFIX_PATH| Option | Type | Default | Description |
|---|---|---|---|
| ModelPath | string |
(required) | Path to the Opir-multilang ONNX model file |
| TokenizerPath | string |
(required) | Path to the mDeBERTa-v3 SentencePiece model (spm.model) |
| PrefixPath | string |
(required) | Path to the frozen-taxonomy label prefix (prefix.json) |
| Threshold | float |
0.5 | Block threshold on the max per-label probability. Tunable per deployment (FPR is somewhat threshold-sensitive here) |
| MaxTokenLength | int |
512 | Model input size; longer input is split into windows, not truncated |
| WindowSize / WindowOverlap / MaxWindows | int |
512 / 128 / 32 | Window size (clamped to what fits after the label prefix), overlap, and the cap above which input is blocked; see the Defender section |
| OnError | ErrorBehavior |
FailClosed | What to do when the tokenizer or the model fails on an input: FailClosed (block), Warn (pass, surfaced as a warning), FailOpen (pass quietly). See the Defender section |
| IncludeConfidence | bool |
true | Include the triggering label, score, and full per-label scores in result metadata |
When blocked, result metadata includes:
label- the harm category with the highest score (e.g. "hate speech")confidence- that label's probability (0.0-1.0)scores- per-harm-label probabilitiesmodel-opir-multilang-mdeberta-v3threshold- the configured threshold
The model is a frozen-taxonomy ONNX export distributed at
filip-w/opir-multilang-onnx. The graph also bakes asafe and benignsentinel label (excluded from the block decision) that GLiClass needs for calibration.
.GuardToolCalls(options?)
Order 45, Output phase. Inspects the arguments of the tool calls a model makes for injection aimed at the systems behind the tools.
| Option | Type | Default | Description |
|---|---|---|---|
| Categories | ToolCallInjectionCategory |
Default | Flags: SqlInjection, CodeInjection (Python/JavaScript/.NET, unsafe deserialization), PathTraversal, CommandInjection, Ssrf (localhost, private networks, cloud metadata endpoints, internal TLDs, unqualified host names). TemplateInjection and Xss are opt-in (All includes them) |
| AllowedTools | ISet<string> |
{} | Tools to skip entirely, e.g. one that legitimately takes SQL (case-insensitive) |
| AllowedArguments | ISet<string> |
{} | Argument names to skip across all tools |
| PerToolAllowedArguments | IDictionary<string, ISet<string>> |
{} | Argument names to skip for a specific tool |
Each argument is checked as written and in up to three percent-decoded layers (UTF-8 escapes, overlong forms and %uXXXX included). An argument that is a JSON object or array is also checked value by value - each string inside it, at any depth, as if it were an argument of its own (up to 512 values; a string that is JSON in turn is opened once more) - so a nested value such as {"target":{"host":"127.0.0.1"}}, or one written with \u escapes, is seen as the tool will read it:
- SSRF - hosts are parsed rather than pattern-matched. The parser handles userinfo (everything up to the last
@, sub-delimiters such as;,,and!included, however long), ports and brackets, any scheme, backslash forms and//host; a URL with ascheme://authority is also checked with the hostSystem.Uriresolves. Hosts are percent-decoded and fullwidth-folded, the characters a resolver ignores (soft hyphens, zero-width characters) are removed, and a trailing dot is dropped. Decimal, hex, octal and short IPv4 forms (2130706433,0x7f000001,0177.0.0.1,127.1) resolve to their address, and an IPv4 address embedded in IPv6 (mapped, compatible or NAT64) is judged as that IPv4 address. Loopback, private, link-local,0.0.0.0/8and100.64.0.0/10addresses are internal. So are the cloud metadata endpoints (Azure's WireServer168.63.129.16included),localhost, the.internal,.local,.corp,.lan,.intranet,.home.arpaand.svcsuffixes (kubernetes.default.svc), and, in anhttp,https,ws,wssorftpURL, any host name without a dot (http://redis:6379/), which can only be a machine on the caller's own network. App links such asslack://channelare not affected. No DNS lookups are made, so a public name that resolves to an internal address is not caught. - Path traversal - backslashes are normalized, repeated slashes collapsed,
.segments dropped (/etc/./passwdis/etc/passwd), and..;segments count as parent segments. Sensitive paths are matched aftername/..pairs are resolved:/etc/passwd,shadow,sudoersand the SSH and Kubernetes directories under/etc;/proc/<pid>/and/proc/self/;.ssh/,.aws/credentials,.azure/,.kube/config,.docker/config.json,.config/gcloud/,.gnupg/,.git-credentials,.netrc,.pgpass,.npmrc,.pypircand shell history files under any directory;/root/;/run/secrets/and/var/run/secrets/; the Docker socket; Windows system files (system32,win.ini,boot.ini, the SAM hive,NTUSER.DAT, the credential store); and an argument that is nothing but a path to a.envfile. A traversal that only appears after decoding (..%2f,%2e%2e%5c,%252e%252e%252f) is reported as encoded traversal. - Command injection - command chaining with
&&,||,;,|or&, and raw or encoded line breaks; the command may be written with its path (; /bin/rm -rf). A command name that is also an English word or a column name (rm,cat,find,id,python, ...) only counts when an option, path,$, quote or URL follows it, or when it ends the line after an operator; alone on a line onlyid,ls,envand the shells do.$(...)and backticks count when what they hold starts with a command, so$(document),$(VERSION)and "usegit statusto check" are left alone. - Code injection - calls, not words:
compile(without a space, theFunctionconstructor rather than the word "function",subprocess.check_output(,importlib.import_module(,require('child_process'). - SQL injection - quoted and unquoted tautologies (
' OR 'a'='a,1 OR 1=1,1 or true) and the same comparison afterAND(' AND '1'='1). Block comments are read the way the database reads them, soUNION/**/SELECTand/*!50000 UNION*/ SELECTcount asUNION SELECT. A--written straight onto a closing quote (admin'--) counts wherever it stands.EXECneeds a call shape (EXEC(,EXEC sp_,EXEC xp_,EXEC @), and a--or#separated from the quote by a space counts only when it ends the line. After a;the keyword has to open a statement (; UPDATE users SET,; SELECT ... FROM,; DROP TABLE), andINSERT INTO/DELETE FROMhave to be followed by a name rather than "my" or "the". Prose such as "execute the plan", "I fixed the bug; update the ticket", "delete from my calendar the 3pm meeting", a search for "C#", or an email signature is not flagged.
When blocked, result metadata includes violationCount, toolName, argumentName, category and violations.
MAF integration (UseAgentGuard()): when this rule is in the policy (gated with .When()/.Unless() or not) and the inner agent has a FunctionInvokingChatClient, a function-invocation middleware checks each call's arguments before the tool runs. A blocked call is never executed; the model receives ToolResultMiddlewareOptions.BlockedToolCallPlaceholder instead. With HardFail, the violation stops the run instead: the model is not called again, calls it made in the same turn are answered with a not-run placeholder (so the saved history has no unanswered call), and RunAsync/RunStreamingAsync throw GuardrailViolationException. The interception runs as MAF function-invocation middleware, which MAF supports only for runs whose options are null or a ChatClientAgentRunOptions. The output guardrail also evaluates the FunctionCallContent in each response, so a response that contains a blocked call is replaced with the violation message; this also covers tools that bypass FunctionInvokingChatClient (hosted tools, MCP), after the fact.
IChatClient decorator (UseAgentGuard() on IChatClient): the tool calls in each response are evaluated with its final text. Place the decorator inside a FunctionInvokingChatClient so every model turn is vetted before its tool calls run - outside it, calls can only be flagged after they have been executed:
IChatClient client = new ChatClientBuilder(innerClient)
.UseFunctionInvocation()
.Use(inner => inner.UseAgentGuard(g => g.GuardToolCalls()))
.Build();Manual usage: Place tool calls in GuardrailContext.Properties["ToolCalls"] as IReadOnlyList<AgentToolCall>. An AgentToolCall.RawContent, when set, is scanned too, unless one of the call's arguments is allow-listed. Violations are stored in Properties["ToolCallViolations"].
.GuardToolResults(options?) or .GuardToolResults(action)
Order 47, Output phase. Detects indirect prompt injection in incoming tool call results - emails, documents, API responses - before they reach the LLM. Complements ToolCallGuardrailRule (which guards outbound arguments). Inspired by StackOneHQ/defender.
| Option | Type | Default | Description |
|---|---|---|---|
| Action | ToolResultAction |
Block | Block to reject, Sanitize to remove each injection from the start of its line to the end of its paragraph |
| ToolRiskProfiles | IDictionary<string, ToolRiskLevel> |
{} | Per-tool risk overrides (Low/Medium/High) |
| SkippedTools | ISet<string> |
{} | Tool names to skip entirely |
| StripUnicodeControl | bool |
true | Strip control, zero-width, invisible-operator and Unicode tag characters from the results handed back. The patterns run on both the raw and the stripped text, so hidden characters are detected either way |
| DetectEncodedPayloads | bool |
true | Decode encoded runs - base64/base64url (24+ characters, fixed-width wrapped blocks rejoined), hex (contiguous or \x escapes) and percent-encoding - that decode to text, and run the same patterns on the decoded text. Findings carry Encoding (base64, hex or percent) and a description suffix such as "(base64-encoded)"; with Sanitize, the encoded run is replaced. JWTs are not decoded. At most 1,024 runs and 256K encoded characters are decoded per result |
| SanitizationReplacement | string |
[FILTERED] |
Replacement text when sanitizing, inserted literally |
| CustomPatterns | IReadOnlyList<(string, string, Regex)> |
[] | Additional (category, description, pattern) tuples |
| OnError | ErrorBehavior |
FailOpen | What to do when a pattern runs out of its 200 ms time budget on a result and nothing else matched. The result has IsError set under every behavior, so an unfinished scan is never reported as a clean one |
Three-tier risk-based detection:
| Tier | Risk Level | Patterns Checked |
|---|---|---|
| Core | All tools | Role markers that carry a directive (System: you must ...), instruction override however it is worded, ChatML tokens, <system> / <assistant> tags, chat message objects with a system role and JSON fields that give an order, HTML comment injection, zero-width chars, text direction overrides, Unicode tag characters, data exfiltration URLs, prompt leak instructions, attempts to switch off the assistant's safeguards, uncensored-mode requests, DAN by name, separator injection |
| Medium | Medium + High | Markdown hidden text and image payloads, [INST]/[SYS] blocks, hex content, Unicode escapes and HTML entities that spell ASCII, ROT13 instructions, words in fullwidth Latin letters |
| High | High only | Bare role markers and <user> / <instruction> tags, base64-encoded instructions, action directives (sending out everything, or something secret), command execution directives, social engineering, fake tool-output boundaries, persona and privileged-role hijacking, developer/god/sudo mode, leetspeak injection keywords |
The Core and Medium tiers run on documents, web pages and API results, so they are written to leave those alone: "role": "manager", system: ubuntu-22.04 in YAML, <user> in XML, a link with ?token= or &prompt=consent, "run the following command: npm install", "enable developer mode", escaped or entity-encoded non-English text, and right-to-left text with its embedding marks all pass. What is only suspicious when someone wrote it to the reader - a bare Assistant: line, "run the following command:", "enable developer mode" - is checked for High-risk tools, whose results are messages. There, ordinary requests between people ("please send an email to HR with your dates", "URGENT: Action required", "you are now an admin of the workspace") pass, while "forward all emails to ..." and "send your credentials to ..." do not.
A data exfiltration URL is an image whose address carries a data-bearing parameter (a client fetches it without a click), a link with a parameter named for what it carries (?data=, ?context=, ?history=), or a link whose parameter is a blank for the model to fill in (?q={conversation}).
Built-in tool risk profiles:
| Risk Level | Default Tools |
|---|---|
| High | gmail, email, send_email, read_email, outlook, slack, teams, discord, chat, message, sms |
| Medium | search, web_search, browse, read_file, get_document, github, jira, confluence |
| Low | calculator, get_weather, get_time |
Tools not in the profile default to Medium. Tool names containing "email", "mail", "message", "chat", "slack", or "sms" are heuristically classified as High.
MAF integration (UseAgentGuard()): When this rule is in the policy (gated with .When()/.Unless() or not), tool results are automatically intercepted via the MAF function-invocation middleware (requires FunctionInvokingChatClient in the inner agent). Each tool result is evaluated BEFORE being fed back to the LLM; string results from AIFunctionFactory tools are evaluated as the plain text the tool returned. The policy's output-phase rules whose order is in IncludeRuleOrders (by default PII 20, secrets 22 and LLM PII 25) run on the result first and can rewrite or block it; this rule then inspects what they produced. Blocked results are replaced with BlockedPlaceholder (or, with HardFail, a GuardrailViolationException aborts the run); sanitized results substitute the modified content. The same middleware checks tool-call arguments before the tool runs (see Tool Call Guardrails). As a safety net for tools that bypass FunctionInvokingChatClient (hosted tools, MCP), the post-hoc output guardrail also extracts FunctionCallContent and FunctionResultContent from the response messages. Configure via ToolResultMiddlewareOptions on the UseAgentGuard(policy, toolResultOptions, logger, ledger) overload (Enabled, IncludeRuleOrders, BlockedPlaceholder, BlockedToolCallPlaceholder, HardFail).
The IChatClient decorator evaluates the tool results a request carries before the model reads them (which is where they arrive when the decorator sits inside a FunctionInvokingChatClient), and those contained in each response it returns, together with the response's final text.
Manual usage: Place tool results in GuardrailContext.Properties["ToolResults"] as IReadOnlyList<ToolResultEntry>. When the rule sanitizes an injection, or strips hidden characters from a result it lets through, the cleaned results are written to Properties["SanitizedToolResults"] - use them in place of the originals. Violations are stored in Properties["ToolResultViolations"].
.ValidateOutput(predicate, message) / .ValidateInput(predicate, message)
Order 100. Simple predicate-based assertions. ValidateOutput judges answer text, so a response that is only tool calls - which has none - is not put to it.
Custom output rules do run for such a response, so that a rule of yours can inspect its tool calls: GuardrailContext.Text is then empty and GuardrailContext.Properties holds ChatMessageGuard.ToolContentOnlyKey. A rule that judges the answer should pass when that key is present.
.EnforceOutputPolicy(chatClient, policyDescription) or .EnforceOutputPolicyWithLlm(chatClient, options)
Checks whether the agent's response violates a custom policy constraint. Useful for brand safety, compliance, and operational guardrails.
| Option | Type | Default | Description |
|---|---|---|---|
| PolicyDescription | string |
(required) | Natural language description of the policy to enforce |
| Action | OutputPolicyAction |
Block | Block to reject, Warn to pass and surface the finding as a warning |
| SystemPrompt | string? |
(built-in) | Custom system prompt (use {policy} placeholder) |
- Order: 55, Phase: Output
- Response format:
COMPLIANTorVIOLATION|reason:<reason> - When
Action = Warn, the result passes withIsWarningset and a reason, so it is logged at Warning level and listed inGuardrailPipelineResult.Warnings; it includesMetadata["violation_reason"]andMetadata["policy"]
.CheckGroundedness(chatClient) or .CheckGroundednessWithLlm(chatClient, options?)
Detects hallucinated facts and claims not supported by the conversation context. Uses GuardrailContext.Messages to provide conversation history to the LLM.
| Option | Type | Default | Description |
|---|---|---|---|
| Action | GroundednessAction |
Block | Block to reject, Warn to pass and surface the finding as a warning |
| SystemPrompt | string? |
(built-in) | Custom system prompt (use {context} placeholder) |
- Order: 65, Phase: Output
- Response format:
GROUNDEDorUNGROUNDED|claim:<ungrounded claim> - Common knowledge facts are considered grounded even without conversation context
- When
Action = Warn, the result passes withIsWarningset and a reason (logged at Warning level, listed inGuardrailPipelineResult.Warnings) and includesMetadata["ungrounded_claim"]
.CheckCopyright(chatClient) or .CheckCopyrightWithLlm(chatClient, options?)
Detects verbatim or near-verbatim reproduction of copyrighted material (song lyrics, book passages, articles, restrictively-licensed code).
| Option | Type | Default | Description |
|---|---|---|---|
| Action | CopyrightAction |
Block | Block to reject, Warn to pass and surface the finding as a warning |
| SystemPrompt | string? |
(built-in) | Custom system prompt override |
- Order: 75, Phase: Output
- Response format:
CLEANorCOPYRIGHT|source:<source>|type:<lyrics|book|article|code|poem|speech|other> - Short quotes (<15 words) for commentary are acceptable and not flagged
- Public domain works and common phrases are not flagged
- When
Action = Warn, the result passes withIsWarningset and a reason (logged at Warning level, listed inGuardrailPipelineResult.Warnings) and includesMetadata["copyright_source"]andMetadata["copyright_type"]
AgentGuard.AgentFramework includes workflow guardrails that apply at MAF workflow step boundaries using the decorator pattern.
Wraps Executor<TInput> or Executor<TInput, TOutput> with a GuardedExecutor (id guarded-{innerId}) that runs guardrails before/after the inner executor. The guarded executor stands in for the inner one:
- it declares the inner executor's protocol - the message types it handles, sends and yields, its catch-all route included - so messages the inner executor sends or yields through the workflow context are accepted;
- it takes over the inner executor's options and cross-run sharing, and forwards its lifecycle hooks: initialization, message-delivery start and end, checkpoint save and restore, reset (when the inner executor supports it) and disposal;
- messages of the inner executor's other handled types are input-guarded and then passed to the inner executor, which routes them to its own handler; what that handler returns, sends and yields is output-guarded like the main handler's;
- turn and reset signals (
TurnToken,ResetChatSignal) pass through unchecked, since they carry no text.
| Executor Type | Input Guardrails | Output Guardrails | On Block |
|---|---|---|---|
Executor<TInput> (void) |
Yes | Yes - the messages it sends and yields | Throws GuardrailViolationException |
Executor<TInput, TOutput> (typed) |
Yes | Yes - its result and the messages it sends and yields | Throws GuardrailViolationException |
Output guardrails cover what an executor emits through its IWorkflowContext as well as what it returns: every SendMessageAsync and YieldOutputAsync call, from a handler or a lifecycle hook, is checked before the message reaches the workflow. A blocked message is not forwarded and the call throws GuardrailViolationException, which fails the executor unless the handler catches it. A rewritten message is forwarded rewritten; it has to be rebuilt as the type that was sent, and a rewrite that can't be applied blocks unless AllowUnappliedModifications is set. A returned value is checked once, however the executor's options forward it. Events (AddEventAsync) are not guarded: they report to whoever runs the workflow and are not delivered to other executors, so guard any model- or user-facing text you put in a custom event yourself.
// Builder overload
var guarded = executor.WithGuardrails(b => b.BlockPromptInjection().RedactPii());
// Pre-built policy overload
var guarded = executor.WithGuardrails(existingPolicy);
// With options (custom text extractor, logger, decision ledger)
var guarded = executor.WithGuardrails(b => b.RedactPii(),
new GuardedExecutorOptions { TextExtractor = myExtractor });Chat payloads are guarded message by message, the way the agent middleware guards them, without the text extractor:
ChatMessage- its text is checked and rewritten in place, keeping attachments, other contents, role, author, id, timestamp and additional properties.- Message collections on the way in (
List<ChatMessage>,ChatMessage[], or an interfaceList<ChatMessage>implements) andAgentResponse- every message is guarded as in a request, whatever its role: a blocked one is replaced with the removed-message placeholder, and a block of the newest user message blocks. - Message collections and
AgentResponseon the way out - every assistant message is guarded as in a response, including its reasoning and tool calls. - In both directions the newest message with text is also checked whatever its role, since an executor's input is often another agent's response and its output a prompt for the next one.
- The result is rebuilt as the declared type; an
AgentResponsekeeps its ids, usage, finish reason, continuation token and additional properties. A collection type that can't be rebuilt (e.g.Collection<ChatMessage>) is blocked when a rule rewrote it, with a warning logged (seeAllowUnappliedModificationsbelow).
Bridges every other workflow message type to a string for guardrail evaluation, and optionally rebuilds the message from rewritten text (TryRebuild, a default interface method that rebuilds nothing unless overridden). DefaultTextExtractor handles:
string→ the string itselfChatMessage→.TextAgentResponseandIEnumerable<ChatMessage>→ the text of every message, one per line- Objects with a public
Textproperty → reflection; when the property is settable orinit,TryRebuildrebuilds the message as a copy (a record'swithcopy, or a struct copy) with the rewrittenText - Fallback →
ToString(), for types that override it; a message with noTextand noToString()of its own has no text and passes unchecked
A guarded executor asks the extractor only for types other than the chat payloads above; the chat branches serve custom extractors that delegate to it.
Thrown when a guardrail blocks within a workflow executor. MAF surfaces this as ExecutorFailedEvent.
| Property | Type | Description |
|---|---|---|
ViolationResult |
GuardrailResult |
The blocking result (rule name, reason, severity) |
Phase |
GuardrailPhase |
Input or Output |
ExecutorId |
string |
ID of the inner executor that was guarded |
When a guardrail modifies text (e.g. PII redaction), the modification is applied to the message:
string→ replaced directly- Chat payloads → rewritten as described above, keeping everything but the changed text
- Other types → rebuilt by the extractor's
TryRebuildwhen it supports the type; otherwise the message is blocked (GuardrailViolationException) with a warning logged, so a redaction that can't be applied never lets the original through. SetGuardedExecutorOptions.AllowUnappliedModifications = trueto pass the original on unchanged instead, with the warning
.AddRule(rule) or .AddRule(name, phase, evaluate, order)
Add any IGuardrailRule implementation or a delegate-based rule.
.When(predicate) / .Unless(predicate)
Gate the most recently added rule behind a runtime predicate, evaluated per request. When the predicate returns false (.When) or true (.Unless), the rule is skipped and passes through; Name, Phase and Order are preserved so execution order and telemetry are unchanged. Both sync (Func<GuardrailContext, bool>) and async (Func<GuardrailContext, CancellationToken, ValueTask<bool>>) predicates are supported. Internally this wraps the rule in a ConditionalGuardrailRule, which you can also construct directly and pass to .AddRule(...). A gated rule otherwise behaves like the rule it wraps: it keeps its streaming mode, the MAF tool middleware recognizes a gated ToolCallGuardrailRule or ToolResultGuardrailRule, and disposing the policy disposes it. Code of your own that looks for a rule type can call rule.Unwrap() (AgentGuard.Core.Rules) to get the rule behind the gates.
The predicate can read the GuardrailContext (Properties, AgentName, Messages) and/or capture ambient services in its closure.
Recommended for the Defender English-centric limitation: raise the threshold per-segment rather than disabling. Add two gated Defender rules (both order 11; only one fires per request) - a sensitive instance for English users and a conservative one for everyone else. Non-English benign text passes the higher bar while high-confidence, language-agnostic attacks still block:
var policy = new GuardrailPolicyBuilder()
.BlockPromptInjectionWithDefender() // default threshold for English users
.When(ctx => IsEnglish(ctx))
.BlockPromptInjectionWithDefender(new DefenderPromptInjectionOptions { MainThreshold = 0.9f })
.Unless(ctx => IsEnglish(ctx)) // conservative for everyone else
.Build();Gate by a value set on the context (standalone pipeline - the caller populates Properties):
bool IsEnglish(GuardrailContext ctx) =>
!ctx.Properties.TryGetValue("language", out var l) || (string)l == "en";
// caller sets the per-request language
var ctx = new GuardrailContext
{
Text = userInput,
Phase = GuardrailPhase.Input,
Properties = { ["language"] = userProfile.Language }
};Gate by HttpContext / ClaimsPrincipal (ASP.NET - the predicate closure captures IHttpContextAccessor; it flows correctly because the pipeline runs on the request's async context, so no extra plumbing is needed):
// httpContextAccessor is resolved from DI (AddHttpContextAccessor())
bool IsEnglish(GuardrailContext _)
{
var user = httpContextAccessor.HttpContext?.User;
var lang = user?.FindFirst("locale")?.Value
?? httpContextAccessor.HttpContext?.Features
.Get<IRequestCultureFeature>()?.RequestCulture.Culture.TwoLetterISOLanguageName;
return lang is null or "en";
}The full enable/disable form (.Unless(predicate) to skip a rule entirely) is still available and gates any rule on any ambient signal - feature flags, tenant tier, A/B cohort, user role, etc. Prefer raising a threshold over fully disabling a security rule whenever a tuned threshold exists.
AgentGuard's prompt injection detection is informed by the Arcanum Prompt Injection Taxonomy (CC BY 4.0, Jason Haddix / Arcanum Information Security), which classifies attacks into:
- 12 Attack Techniques: direct instruction override, role/persona hijacking, system prompt extraction, meta-prompting, narrative smuggling, cognitive overload, russian doll/multi-chain, rule addition, framing, inversion, end sequence injection, variable expansion
- 13 Attack Intents: jailbreak, system prompt leak, data extraction, denial of service, tool enumeration, and more
- 20 Evasion Methods: base64, hex, reversed text, Unicode homoglyphs, emoji, cipher, JSON/XML wrapping, and more
The taxonomy is used at three levels:
- Regex patterns -
PromptInjectionRulecovers the techniques that can be reliably detected via pattern matching - LLM prompt templates -
LlmPromptInjectionRuleenumerates all technique families and evasion methods to give the LLM classifier precise conceptual anchors - Input normalization -
InputNormalizationRuledecodes the most common evasion encodings before any other rule evaluates the text