> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM Guard

> Prompt injection detection, PII scanning, and content safety filtering for all LLM interactions.

## What It Does

LLM Guard intercepts all `hexr_llm()` calls and scans prompts and responses for security threats using multiple detection strategies.

***

## Scanning Pipeline

<Steps>
  <Step title="Prompt Injection Detection">
    Incoming prompt is analyzed for injection attacks, jailbreak attempts, and adversarial patterns.
  </Step>

  <Step title="PII Scanner">
    Detects and optionally redacts personally identifiable information (names, emails, SSNs, etc.).
  </Step>

  <Step title="Secrets Scanner">
    Catches API keys, tokens, passwords, and other credentials before they reach the LLM.
  </Step>

  <Step title="Token Limit Check">
    Validates the prompt fits within the configured token budget for the model.
  </Step>

  <Step title="LLM Provider">
    The sanitized prompt is forwarded to the configured LLM provider.
  </Step>

  <Step title="Response Scanner">
    The LLM response is scanned for leaked secrets, hallucinated PII, and policy violations.
  </Step>

  <Step title="Topic Boundary Check">
    Ensures the response stays within the agent's configured topic boundaries.
  </Step>
</Steps>

```
Prompt → Injection Check → PII Scan → Secrets Scan → Token Check → LLM → Response Scan → Topic Check → Agent
```

***

## Scanners

| Scanner               | Direction      | What It Catches                                                 |
| --------------------- | -------------- | --------------------------------------------------------------- |
| **Prompt Injection**  | Input          | Jailbreak attempts, system prompt extraction, role-play attacks |
| **PII Detection**     | Input + Output | Email addresses, phone numbers, SSNs, credit cards              |
| **Secrets Detection** | Input + Output | API keys, passwords, tokens, private keys                       |
| **Token Limit**       | Input          | Prevents context window overflow attacks                        |
| **Topic Boundary**    | Output         | Detects off-topic responses that may indicate manipulation      |

***

## OWASP Top 10 for GenAI Coverage

| OWASP Risk                    | LLM Guard Protection       |
| ----------------------------- | -------------------------- |
| LLM01: Prompt Injection       | Prompt injection scanner   |
| LLM02: Insecure Output        | Response content scanner   |
| LLM06: Sensitive Information  | PII + secrets scanner      |
| LLM07: Insecure Plugin Design | Gateway credential scoping |
| LLM09: Overreliance           | Topic boundary check       |

***

## Integration

LLM Guard is automatically invoked by `hexr_llm()` — no code changes required:

```python theme={null}
# LLM Guard scans this prompt before it reaches OpenAI
response = hexr_llm(
    provider="openai",
    model="gpt-4o",
    prompt="Analyze this customer data: ...",
)
# LLM Guard scans the response before returning
```

To manually scan:

```python theme={null}
from hexr.guard import scan_prompt, scan_output

result = scan_prompt("user input here")
if result.flagged:
    print(f"Blocked: {result.scanner} - {result.reason}")
```

***

## Configuration

| Environment Variable        | Default    | Description                             |
| --------------------------- | ---------- | --------------------------------------- |
| `ENABLED_SCANNERS`          | `all`      | Comma-separated list of active scanners |
| `PII_DETECTION_THRESHOLD`   | `0.85`     | Confidence threshold for PII detection  |
| `INJECTION_DETECTION_MODEL` | `built-in` | Prompt injection detection model        |
| `BLOCK_ON_DETECTION`        | `true`     | Block or warn on detection              |

***

## Observability

LLM Guard is fully instrumented with OpenTelemetry. Every scan generates span attributes on the parent `hexr.llm.call` span and emits dedicated metrics.

### Span Attributes

When LLM Guard blocks a prompt or response, the following attributes are set on the `hexr.llm.call` span:

| Attribute                    | Type     | Description                                     |
| ---------------------------- | -------- | ----------------------------------------------- |
| `hexr.guard.prompt_blocked`  | `bool`   | `true` if the input prompt was blocked          |
| `hexr.guard.scanners`        | `string` | Scanner results that triggered the prompt block |
| `hexr.guard.output_blocked`  | `bool`   | `true` if the LLM response was blocked          |
| `hexr.guard.output_scanners` | `string` | Scanner results that triggered the output block |

Blocked requests set the span status to `ERROR` with a description like `"Blocked by LLM Guard"` or `"Output blocked by LLM Guard"`.

### Metrics

| Metric                             | Type      | Description                                             |
| ---------------------------------- | --------- | ------------------------------------------------------- |
| `hexr_guard_scans_total`           | Counter   | Total scans by direction (`input`/`output`) and scanner |
| `hexr_guard_blocks_total`          | Counter   | Total blocks by direction and scanner                   |
| `hexr_guard_scan_duration_seconds` | Histogram | Scan latency by direction                               |

### Grafana Dashboard

The **Security** dashboard includes an LLM Guard panel showing:

* Block rate over time (prompt vs. response)
* Top triggered scanners
* Scan latency percentiles
* Blocks by tenant and agent

See [Observability Stack](/platform/observability-stack) for the full telemetry pipeline.