# 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](https://mcp.glc-rag.hu/guide/promptguard) · Markdown: [/guide/promptguard-methodology.md](https://mcp.glc-rag.hu/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**:

- a full chatbot firewall or content-moderation suite for every topic  
- a substitute for allowlists, confirmation UX, and secret hygiene  
- a claim of 100% detection — any residual miss must be **contained by deterministic host-side tool policy**

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

---

## 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.

```mermaid
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"]
    STRUCT["2. Structural signals"]
    DISC["3. Discourse / framing"]
    INTENT["4. Intent classification"]
    MERGE["5. Policy merge & floors"]
    NEURAL["6. Additive neural sensor soft"]
    SPOT["7. Spotlight facts vs orders"]
    CANARY["8. Canary optional"]
    NORM --> STRUCT --> DISC --> INTENT --> MERGE
    NEURAL -.-> MERGE
    MERGE --> SPOT
    MERGE --> CANARY
  end

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

  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. PromptGuard returns a compact verdict (and optional `spotlight.facts` for RAG/tool).  
3. The main model may reason on facts / user intent; it must **not** be the enforcer.  
4. Allowlists and confirmations decide whether tools run — even if detection missed.

ASCII twin (same story, docs without Mermaid):

```text
  user_prompt / rag_chunk / tool_result
                 │
                 ▼
        ┌────────────────────┐
        │  Host orchestrator │─── calls PromptGuard on each delta
        └─────────┬──────────┘
                  │
                  ▼
   ┌──────────────────────────────────────────┐
   │           GLC PromptGuard gate           │
   │  normalize → structure → discourse →     │
   │  intent → policy merge (+ soft neural)   │
   │  → spotlight / optional canary           │
   └──────────────────┬───────────────────────┘
                      │ injection, score, policy,
                      │ 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

```text
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**:

- select a different classifier or rule pack  
- gate accuracy (“must pass locale or miss attacks”)  
- restrict supported languages to the example set  

**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 smuggling, compressed whitespace, etc.). Depth and size are bounded so the check stays 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.

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.

5. **Policy merge & floors**  
   Intent, source, and impact 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.

6. **Additive neural sensor (soft)**  
   A non-generative multi-label neural text classifier contributes *family-level* scores. In soft mode it can boost or floor suspicion; it does not silently clear a structural hard block. Shadow/degraded modes exist for safe rollout.

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.

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 |
| Limit false positives | Framed quotes, glossaries, unit-test fixtures, defensive pseudocode, and similar meta text 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” |

---

## 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. Prefer `spotlight.facts` for the main model on RAG/tool paths — never feed raw embedded instructions as orders.  
4. Enforce a **deterministic tool policy** in parallel: allowlists, domain allowlists, fresh confirmation for money/destructive/comms, secrets never in model context.  
5. 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:

- exact pattern libraries and weights  
- numeric thresholds and floor constants  
- full training corpus inventories and label schemas beyond the API surface  
- canary challenge formats  
- detailed false-positive / recall scorecards (available under NDA for reviewers who need them)

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

---

## Related

- Tool & wiring guide: [/guide/promptguard](https://mcp.glc-rag.hu/guide/promptguard)  
- Markdown twin: [/guide/promptguard.md](https://mcp.glc-rag.hu/guide/promptguard.md)  
- Agent registration: [/guide/agent](https://mcp.glc-rag.hu/guide/agent)  
- Index: [/llms.txt](https://mcp.glc-rag.hu/llms.txt)