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

# Three-Layer AI Funnel

> How Panguard processes 90% of security events in under 1ms using a cascading Rules, Local AI, and Cloud AI architecture.

# Three-Layer AI Funnel

Panguard AI uses a three-layer cascading architecture to analyze security events. 90% of events are handled by the rule engine in under 1 millisecond. Only the most complex 3% ever reach cloud AI.

## Why Three Layers?

Sending every security event to an AI model creates three problems:

1. **Too slow** -- AI inference takes seconds; attacks do not wait.
2. **Too expensive** -- Thousands of events per machine per day means runaway token costs.
3. **Unreliable** -- If the API goes down, protection stops.

The three-layer funnel is built on a simple principle: **most attacks follow known patterns. Only truly unknown threats require deep AI reasoning.**

***

## Architecture Overview

```
  Security Events
       |
       v
  +-----------+
  | Layer 1   |  ATR Rule Engine
  | 90% events|  Latency < 1ms | Cost = $0
  +-----------+
       |
    Unmatched (10%)
       |
       v
  +-----------+
  | Layer 2   |  Local AI (Ollama)
  | 7% events |  Latency < 5s  | Cost = $0 (on-device)
  +-----------+
       |
    Needs deeper analysis (3%)
       |
       v
  +-----------+
  | Layer 3   |  Cloud AI (Claude / OpenAI)
  | 3% events |  Latency < 30s | Cost ~ $0.01/event
  +-----------+
```

***

## Layer Comparison

| Property             | Layer 1: Rules        | Layer 2: Local AI    | Layer 3: Cloud AI      |
| -------------------- | --------------------- | -------------------- | ---------------------- |
| **Event share**      | \~90%                 | \~7%                 | \~3%                   |
| **Latency**          | \< 1 ms               | \< 5 s               | \< 30 s                |
| **Cost per event**   | \$0                   | \$0                  | \~\$0.01               |
| **Requires network** | No                    | No                   | Yes                    |
| **Technology**       | ATR Rules             | Ollama (llama3)      | Claude / OpenAI        |
| **Best for**         | Known attack patterns | Behavioral anomalies | Novel, complex threats |

***

<h2 id="layer-1">
  Layer 1 -- Rule Engine (90%)
</h2>

Handles all known attack patterns with zero latency and zero cost.

### ATR Rules

ATR (Agent Threat Rules) is the open standard for AI agent threat detection. Panguard Guard ships with 768 ATR rules covering common AI agent attack patterns.

```yaml ATR Rule Example theme={null}
id: ATR-2025-0001
name: Prompt Injection via Tool Response
severity: critical
detection:
  patterns:
    - 'ignore previous instructions'
    - 'system prompt override'
  context: tool_response
action: block
```

**Supported ATR features:**

* Pattern matching with regex support
* Context-aware detection (tool responses, skill manifests, agent actions)
* Multi-layer detection: regex, content fingerprinting, LLM-as-judge
* Severity levels: critical, high, medium, low
* MITRE ATT\&CK mapping for AI agent threats

***

<h2 id="layer-2">
  Layer 2 -- Local AI (7%)
</h2>

When an event does not match any known rule but exhibits suspicious behavior, it is forwarded to a local AI model for analysis.

* Runs locally via [Ollama](https://ollama.ai) -- no network required
* Zero API cost
* Inference latency approximately 3-5 seconds
* Default model: `llama3`

<Info>
  **Environment-aware routing:** On servers (VPS, cloud instances), events flow through all three
  layers. On desktops and laptops, Layer 2 is skipped to avoid competing for user resources.
  Unmatched events go directly from Layer 1 to Layer 3.
</Info>

```
Server:  Layer 1 (90%) -> Layer 2 (7%) -> Layer 3 (3%)
Desktop: Layer 1 (90%) -> Layer 3 (5-8%)  (Layer 2 skipped)
```

***

<h2 id="layer-3">
  Layer 3 -- Cloud AI (3%)
</h2>

The most complex unknown threats are analyzed by cloud AI with full dynamic reasoning.

* Complete context analysis
* Cross-event correlation
* Attack chain reasoning with MITRE ATT\&CK classification
* Remediation recommendation generation

<Note>
  Even if cloud AI is unavailable (network outage, token exhaustion), the Layer 1 rule engine
  continues operating. **Protection never stops.**
</Note>

***

## Graceful Degradation

A critical design principle of the three-layer architecture: if any layer fails, the layer above it takes over automatically.

| Scenario             | Degradation Behavior             |
| -------------------- | -------------------------------- |
| Cloud AI unavailable | Layer 2 (Local AI) takes over    |
| Ollama not installed | Layer 1 (Rule Engine) takes over |
| Rule files corrupted | Built-in default rules activate  |

**Panguard always has protection -- only the precision level changes.**

### Confidence Weighting by Available Sources

The system dynamically adjusts how much weight each evidence source carries based on what is available:

| Sources Available | Rules/Intel | Baseline | AI   | eBPF |
| ----------------- | ----------- | -------- | ---- | ---- |
| Rules only        | 0.60        | 0.40     | --   | --   |
| Rules + AI        | 0.40        | 0.30     | 0.30 | --   |
| Rules + eBPF      | 0.40        | 0.35     | --   | 0.25 |
| Rules + AI + eBPF | 0.30        | 0.20     | 0.30 | 0.20 |

***

## FunnelRouter

The `FunnelRouter` component in `@panguard-ai/core` implements the Layer 2 to Layer 3 fallback logic:

<Steps>
  <Step title="Try Local AI First">Send the event to Ollama for local analysis.</Step>

  <Step title="Evaluate Confidence">
    If Ollama returns a confident verdict, use it. If Ollama is unavailable or returns low
    confidence, escalate.
  </Step>

  <Step title="Fall Back to Cloud AI">
    Send the event to Claude or OpenAI for deep reasoning and MITRE classification.
  </Step>

  <Step title="Final Fallback">
    If no AI provider is available, the system continues with rule-based scoring only (weights shift
    to 0.6 rules + 0.4 baseline).
  </Step>
</Steps>

**Provider Auto-Detection** (at startup):

1. Check `~/.panguard/llm.enc` (encrypted local config, AES-256-GCM)
2. Check environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`
3. Probe local Ollama at `http://localhost:11434`
4. Build the appropriate adapter: FunnelRouter (both available), single provider, or null

***

## Related

<CardGroup cols={2}>
  <Card title="Learning Mode" icon="graduation-cap" href="/concepts/learning-mode">
    How Guard builds a behavioral baseline during the 7-day learning period.
  </Card>

  <Card title="Real-Time Protection" icon="shield" href="/guides/real-time-protection">
    Set up Guard for continuous monitoring and automated response.
  </Card>
</CardGroup>