← Docs · Promptguard · Markdown · Home

PromptGuard methodology

Technical methodology for security reviewers and integrators.
This page describes how we think about prompt filtering — not the internal rule book, model weights, thresholds, or detector fingerprints.

Service guide: Promptguard · Markdown: /guide/promptguard-methodology.md

What PromptGuard is (and is not)

PromptGuard is a host-side gate for untrusted text deltas before they reach your main model or tool loop. It answers: does this slice look like an attempt to hijack the agent, exfiltrate secrets, or coerce unsafe tool use — given where the text came from?

It is not:

Design stance: detection assists policy; policy must not depend on perfect detection.

What’s live: gated secondary semantic encoder (soft)

Production (engine 0.3.43+): in addition to the primary attack neural and the discourse neural packs, PromptGuard runs a third soft sensor — a compact multilingual secondary semantic encoder.
Why Catch paraphrased / semantically shifted hijacks when keyword-heavy structural rules and the primary sensor are uncertain
When it runs Not on every request. Only when earlier layers look gray / uncertain (or related degraded conditions). Framed educational quotes and already-decisive hot hits typically skip it
What it does Soft boost / floor into the same policy merge — never clears a structural hard block
Latency ~0 when skipped; modest added cost only when the gate fires
Host contract Unchanged: still read injection first. Optional meta may note whether this encoder was invoked

In the architecture diagram this is step 5c. It is a first-class layer of the gate, not an experiment and not a replacement for host tool policy.

Also live (engine 0.3.43+): cold-score neural rescue + gray-only canary

After the soft neural merge, PromptGuard may apply a neural rescue floor when attack heads are already hot but the merged score stayed below the decision threshold (common on some tool_result / paraphrase cases). Default production mode applies the floor; operators can observe-only (shadow) or disable it. Soft rescue never clears a structural hard block.

The optional canary (tool-protocol probe) runs conditionally in production: skip clear-clean and already-decisive structural hits; run on gray / soft-uncertain bands. A failed canary is treated as injection.

Also live (engine 0.3.46): optional multi-turn sticky session risk

Crescendo-style attacks often split a live hijack across turns: early turns look like setup questions, later turns ask to extract. PromptGuard can carry aggregate suspicion forward when the host opts in:
How to enable Pass the same session_id (chat/run id, ≤128 chars) on every promptguard_check / POST /api/promptguard/check for that conversation
What is stored Only aggregate prior risk (score, suspicion, probe streak, injection flag, turn count) — not full prompt text
What it does Floors the next delta as max(own_score, suspicion). Setup probes accumulate below the injection threshold; extractive probes can cross it. Clean turns halve suspicion — the floor follows decay, it does not latch at 100
Cost Still one check per delta (+ cheap store read/write). No full-history re-score, no extra credit
Default Omit session_id → classic stateless behavior (unchanged)
New conversation, same id Set sticky_reset: true once
Tenant scope Risk state is scoped per organization + session_id

Hosts must generate and reuse session_id themselves — the platform does not invent conversation continuity from text alone. Response meta.sticky reports whether sticky was enabled/applied and the current suspicion (observability). Exact increment constants are not a public contract.

Pinned quality snapshot: /guide/promptguard-assurance.

GLC PromptGuard architecture

Dedicated host-side layout for the GLC MCP / agent stack. PromptGuard sits outside the main model: the orchestrator checks every untrusted delta, then applies deterministic tool policy before side effects.

flowchart TB
  subgraph Sources["Untrusted text sources"]
    UP["user_prompt"]
    RAG["rag_chunk"]
    TR["tool_result"]
  end

  ORCH["Host orchestrator<br/>(your agent loop)"]

  subgraph PG["PromptGuard gate — mcp.glc-rag.hu"]
    direction TB
    NORM["1. Normalization / multi-view<br/>(encode · Unicode tags · combining · coverage)"]
    STRUCT["2. Structural signals"]
    DISC["3. Discourse / framing"]
    INTENT["4. Intent classification"]

    subgraph SoftNeural["5. Additive soft neural stack (all soft)"]
      direction TB
      ATT["5a. Attack neural — primary"]
      DNEU["5b. Discourse neural — gated"]
      SEM["5c. ★ Secondary semantic encoder — gated<br/>paraphrase / gray zone (LIVE soft)"]
    end

    MERGE["6. Policy merge & floors"]
    SPOT["7. Spotlight facts vs orders"]
    CANARY["8. Canary optional"]
    STICKY["9. ★ Sticky session risk (optional)<br/>same session_id → floor prior risk"]

    NORM --> STRUCT --> DISC --> INTENT --> MERGE
    STRUCT -.-> ATT
    STRUCT -.-> DNEU
    INTENT -.-> SEM
    STRUCT -.-> SEM
    ATT -.->|"soft boost / floor"| MERGE
    DNEU -.->|"soft boost / floor"| MERGE
    SEM -.->|"★ invoke only if uncertain / gray"| MERGE
    MERGE --> STICKY
    STICKY --> SPOT
    STICKY --> CANARY
  end

  VERDICT["Result: injection · score · intent · policy<br/>+ optional spotlight.facts · meta.sticky"]

  subgraph HostPolicy["Deterministic host policy — required"]
    AL["Tool / domain allowlists"]
    CONF["Human confirm for money / destructive / comms"]
    SECRETS["Secrets never in model context"]
  end

  LLM["Main LLM"]
  TOOLS["Tools / side effects"]

  UP --> ORCH
  RAG --> ORCH
  TR --> ORCH
  ORCH -->|"delta + context"| PG
  PG --> VERDICT
  VERDICT --> ORCH
  ORCH -->|"prefer spotlight.facts on RAG/tool"| LLM
  LLM --> ORCH
  ORCH --> HostPolicy
  HostPolicy -->|"allow"| TOOLS
  HostPolicy -->|"block / quarantine"| ORCH

Reading the diagram

  1. Every new untrusted slice enters the orchestrator with the correct context.
  2. Inside the gate: normalize → structure → discourse framing → intent, then three soft neural sensors boost/floor suspicion — including 5c secondary semantic encoder (only when gray/uncertain). Policy merge may also apply neural rescue when heads are hot but the score stayed cold; optional canary runs gray-only.
  3. When the host passes a stable session_id, sticky session risk may floor the score from prior turns (step 9) — still one check per delta.
  4. Soft neural never clears a structural hard block.
  5. The main model may reason on facts / user intent; it must not be the enforcer.
  6. Allowlists and confirmations decide whether tools run — even if detection missed.

ASCII twin (same story, docs without Mermaid):

  user_prompt / rag_chunk / tool_result
                 │
                 ▼
        ┌────────────────────┐
        │  Host orchestrator │─── calls PromptGuard on each delta
        │  (optional session_id per chat/run)
        └─────────┬──────────┘
                  │
                  ▼
   ┌──────────────────────────────────────────────┐
   │            GLC PromptGuard gate              │
   │                                              │
   │  1. normalize / multi-view                   │
   │     (encode · tags · combining obfuscation · │
   │      long-text coverage, not head-only)      │
   │  2. structural signals                       │
   │  3. discourse / framing                      │
   │  4. intent classification                    │
   │  5. additive soft neural                     │
   │       5a attack neural (primary)             │
   │       5b discourse neural (gated)            │
   │       5c ★ secondary semantic encoder        │
   │          (LIVE soft — gray / paraphrase)     │
   │          └── only if gray / uncertain        │
   │  6. policy merge & floors (+ neural rescue)  │
   │  9. ★ sticky session risk (optional)         │
   │       └── same session_id → floor prior risk │
   │  7. spotlight (RAG/tool)                     │
   │  8. canary (optional, gray-only)             │
   └──────────────────┬───────────────────────────┘
                      │ injection, score, policy,
                      │ optional meta.sticky
                      │ spotlight.facts?
                      ▼
        ┌────────────────────┐
        │  Main LLM (reason) │◄── facts / safe context only
        └─────────┬──────────┘
                  │
                  ▼
   ┌──────────────────────────────────────────┐
   │  Deterministic tool policy (required)    │
   │  allowlist · confirm · secret hygiene    │
   └──────────────────┬───────────────────────┘
                      │
            allow ────┴──── block / quarantine
                      │
                      ▼
                   Tools / I/O

Core principle: intent × source × impact

Keyword blacklists alone fail against paraphrase, encoding, and “helpful” framing. PromptGuard therefore combines three questions:

  1. Intent — What is the text trying to make the agent do? (override instructions, extract hidden state, force tools, move money/data, etc.)
  2. Source — Where did the slice enter? User chat, retrieved document, or tool output carry different trust assumptions.
  3. Impact — If the intent succeeded, how bad would it be? High-impact classes (secrets, destructive/financial actions, tool hijack) escalate faster than stylistic jailbreak chatter.

The public result stays simple: primarily injection true|false, plus score, structured intent / policy hints, and optional spotlight for RAG/tool paths — so the orchestrator can decide without reverse-engineering internals.

Source-aware policy

Context Trust model (methodology)
user_prompt May contain legitimate instructions. Suspicious when it tries to rewrite system policy, harvest secrets, or skip approvals.
rag_chunk Data, not orders. Text addressed to the agent inside a document is treated as hostile by default.
tool_result Output, not authority. Tool results may provide data (including errors, quoted text, or structured payloads), but must not define new goals, permissions, or side effects.

Hard outcomes exist for especially dangerous combinations (untrusted source + exfiltration / destructive / financial coercion). Exact trigger lists are not published.

Example host flow

Retrieved document
    → PromptGuard check as rag_chunk
    → spotlight.facts extracted
    → main model receives facts (not embedded orders)
    → deterministic tool policy controls actions

The same pattern applies to tool_result (facts/data in, policy out) and user_prompt (intent scored, then host policy for any high-impact tool use).

Languages and locale

Detection is multilingual by design: structural and semantic layers examine the text itself (including mixed-language and encoded slices). Guide examples often show hu / en because those are common integrator locales — not because the service is limited to them.

The optional locale argument is a hint for audit / logging only. It does not:

Recommendation: pass locale when you already know it (helpful in forensics); omit it when you do not. Never block a check waiting for a perfect locale value.

Layered evaluation (high level)

Checks run as a pipeline of independent lenses. Each lens can raise suspicion; none alone is the whole product.

1. Normalization / multi-view reading

Text is examined in forms that attackers use to hide payloads: encoding, homoglyphs, markup/comment smuggling, compressed whitespace, invisible Unicode channels (including tag characters), and combining-mark / “zalgo-style” obfuscation (a cleaned view is scored alongside the raw slice). Long inputs are coverage-bounded (not head-only) so a payload at the end of a large RAG blob is still in scope. Depth and size stay online-safe.

2. Structural signals

Deterministic detectors for well-known attack families (instruction override patterns, embedded agent directives, tool-hijack shapes, and similar). These are category-oriented, not a public phrase list.

3. Discourse / framing awareness

The same words mean different things as a live order, a quoted example, documentation, a test fixture, or a denied/past log. Framed quotes and educational/meta surfaces should receive reduced suspicion when the surrounding evidence consistently indicates non-execution. Attackers may still disguise payloads as docs or tests — framing dampens, it does not grant a free pass. “Translate then obey” and other live wrappers stay live. Very short confirmations / micro-acknowledgements are treated carefully so soft neural layers do not escalate routine “yes / OK” turns.

4. Intent classification

A structured second pass estimates targets, scope, and execution stance (explain vs execute). It complements structure — it does not replace host policy. If this pass is unavailable (meta.degraded), structural (+ soft neural where still healthy) remains the fallback path.

5. Additive soft neural stack

Non-generative sensors. Soft mode can boost or floor suspicion. None silently clears a structural hard block. Shadow/degraded modes exist for safe rollout.

5a. Attack neural (primary soft)

Multi-label family scores (override, exfil, jailbreak, …) trained on large multilingual attack/benign corpora. Fast first-pass reinforcement of structural recall on paraphrase and mixed-language slices.

5b. Discourse neural (soft, gated)

Scores live_execution vs framed_safe / task. Production default is soft with gates (needs structural and/or attack-neural support) so it boosts live hijacks without replacing regex floors; framed/educational surfaces stay dampened when evidence is consistent.

5c. Secondary semantic encoder (soft, gated) — LIVE

This is the paraphrase / gray-zone module. A compact multilingual encoder runs only when earlier layers are uncertain or gray (not on every request). When invoked, soft merge can raise suspicion; when skipped, latency cost is near zero. Exact invoke gates and weights are not published. See also What’s live: gated secondary semantic encoder.

6. Policy merge & floors

Intent, source, impact, and soft-neural boosts are fused into a score and optional hard block. Sticky floors protect against classifier flaps on high-impact live attacks; descriptive/citation frames prevent sticky escalation when the surface is clearly non-executing. Soft neural is boost/floor only — never a silent clear of structural hard block.

7. Spotlight (RAG / tool)

When useful, the service separates facts the main model may see from embedded instructions that should never be obeyed as orders.

8. Canary (optional, secondary)

A tool-hijack probe — not the primary injection verdict.

9. Sticky session risk (optional, multi-turn) — LIVE

See Also live: optional multi-turn sticky session risk. Applied after policy merge when session_id is present; still delta-only cost.

Order and weighting evolve; publishing them would mainly help attackers tune bypasses.

What we optimize for

Goal How it shows up externally
Catch live hijacks High recall on override / exfil / forced-tool / approval-bypass families
Catch multi-turn / crescendo Optional session_id sticky risk floors follow-ups from suspicion (setup accumulates below threshold; extract can cross; clean turns decay)
Catch paraphrase / gray zone Soft neural stack (incl. gated secondary semantic encoder) reinforces when structure alone is uncertain
Multilingual Scripts and mixed-language slices are first-class; locale is optional logging only
Limit false positives Framed quotes, glossaries, unit-test fixtures, defensive pseudocode, and short acknowledgements receive reduced suspicion when evidence consistently indicates non-execution
Fail safe under outage meta.degraded=true → structural path still returns a verdict; host should treat uncertain/degraded as retry or quarantine, not auto-allow
Stay callable online Delta-only input, bounded size, orchestrator-called — never “ask the chat model to call PromptGuard first”

Result shape (integrator view)

Primary decision fields stay stable: injection, score, intent, policy, optional spotlight / canary.

Optional request fields: session_id, sticky_reset. When sticky is active, meta.sticky may include enabled, applied, held, prior_score, prior_injection, floor, turns, suspicion, probe_streak, probe — for audit; hosts still read injection first. The floor tracks suspicion (decays on clean turns); it is not a one-way latch.

Observability may also include additive soft-neural summaries (attack / discourse / gated semantic) and meta flags such as whether a secondary encoder was invoked. Neural detail is for audit and calibration, not a substitute for tool policy. Exact label schemas and thresholds are not a public contract.

Recommended host methodology

  1. Call promptguard_check (or POST /api/promptguard/check) on every new untrusted slice before the main LLM / tool step.
  2. Pass the correct context (user_prompt | rag_chunk | tool_result).
  3. For multi-turn chats, generate a stable session_id per conversation and send it on every check so sticky risk can link crescendo steps; use sticky_reset when starting a new chat that reuses an id.
  4. Prefer spotlight.facts for the main model on RAG/tool paths — never feed raw embedded instructions as orders.
  5. Enforce a deterministic tool policy in parallel: allowlists, domain allowlists, fresh confirmation for money/destructive/comms, secrets never in model context.
  6. If meta.degraded or host-facing uncertainty flags appear, do not auto-allow high-impact tool use.

PromptGuard narrows the window; your orchestrator closes it.

Assurance without a public rule dump

We continuously evaluate against large internal regression packs spanning direct and indirect injection, multilingual paraphrase, social-engineering wrappers, and benign controls. As of 2026-08, the sensor training/eval corpus alone covers several hundred thousand multilingual attack and benign cases. Public docs intentionally omit:

Reviewers who need deeper assurance should contact the platform operator for a private security briefing under NDA — not scrape this page for fingerprints.

Related