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

***

## Layer 1 -- Rule Engine (90%)

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

***

## Layer 2 -- Local AI (7%)

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`

> [!NOTE]
>
> **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.

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

***

## Layer 3 -- Cloud AI (3%)

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

***

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

**1. Try Local AI First**

Send the event to Ollama for local analysis.

**2. Evaluate Confidence**

If Ollama returns a confident verdict, use it. If Ollama is unavailable or returns low
confidence, escalate.

**3. Fall Back to Cloud AI**

Send the event to Claude or OpenAI for deep reasoning and MITRE classification.

**4. 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).

**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

> [card] [Learning Mode](https://docs.panguard.ai/concepts/learning-mode.md)
>
> How Guard builds a behavioral baseline during the 7-day learning period.

> [card] [Real-Time Protection](https://docs.panguard.ai/guides/real-time-protection.md)
>
> Set up Guard for continuous monitoring and automated response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.