🐕‍🦺 Cerbère — The Three-Headed Guardian of AI Agents

Runtime Security & Observability for AI Agents

No agent passes unseen.

Cerbère is a runtime security control plane for autonomous AI agents. It intercepts every LLM call and tool invocation, applies multi-layered security policies, and blocks threats in real-time.

🏛️ The Three Heads

One SDK. One Collector. Three detection layers.

⸻

Why Cerbère -- AgentGuard?

AI agents can call LLMs, APIs, databases, browsers, email systems, code interpreters, and other tools.

Traditional application security does not fully understand these interactions.

AgentGuard provides a runtime security layer designed specifically for agentic workflows:

                     ┌──────────────────────┐
                     │       AI AGENT       │
                     └──────────┬───────────┘
                                │
                     ┌──────────▼───────────┐
                     │    AgentGuard SDK    │
                     │                      │
                     │  Policy Enforcement  │
                     │  Security Checks     │
                     │  Budget Controls     │
                     │  Tool Controls       │
                     └──────────┬───────────┘
                                │
                     ┌──────────▼───────────┐
                     │   3-Layer Detection  │
                     │                      │
                     │  1. Regex / Rules    │
                     │  2. ML Classifier    │
                     │  3. LLM Judge        │
                     └──────────┬───────────┘
                                │
                     ┌──────────▼───────────┐
                     │  ✅ ALLOW   /  🚫 BLOCK │
                     └──────────┬───────────┘
                                │
                     ┌──────────▼───────────┐
                     │    Collector         │
                     │                      │
                     │ Traces               │
                     │ Metrics              │
                     │ Security Events      │
                     │ Cost / Usage         │
                     └──────────┬───────────┘
                                │
                     ┌──────────▼───────────┐
                     │      📊 Dashboard    │
                     └──────────────────────┘

⸻

✨ Core Capabilities

🔍 AI Observability

• Real-time agent traces
• LLM calls and tool calls
• Latency monitoring
• Token / cost tracking
• Session information
• Security events
• Detection statistics

🛡️ Runtime Security

• Prompt injection detection
• PII detection and redaction
• Tool-use policy enforcement
• Tool allowlists
• Budget enforcement
• Suspicious behavior detection
• Runtime blocking
• Risk scoring

🧠 Multi-Layer Detection

Cerbère -- AgentGuard combines three detection mechanisms:

1. Rules / Regex — fast deterministic checks
2. ML Classifier — semantic threat detection
3. LLM Judge — analysis of ambiguous cases

This allows the system to use inexpensive deterministic checks first and reserve more expensive analysis for uncertain cases.

⸻

🛡️ Three-Layer Security Engine

flowchart TD
    A[Incoming Prompt / Tool Call] --> B{Layer 1<br/>Rules + Regex}
    B -->|Strong malicious pattern| X[BLOCK]
    B -->|Clean / uncertain| C{Layer 2<br/>ML Classifier}
    C -->|High risk| X
    C -->|Low risk| P[PASS]
    C -->|Ambiguous| D{Layer 3<br/>LLM Judge}
    D -->|High risk| X
    D -->|Moderate risk| R[ALERT / REVIEW]
    D -->|Low risk| P

Detection flow

The exact thresholds are configurable.

⸻

🚨 Threat Coverage

Cerbère -- AgentGuard is intended to provide defense in depth, not a guarantee that every attack will be detected.

⸻

🚀 Quick Start

Requirements

• Python 3.11+
• pip

Option 1 — Install the SDK only (recommended if you already have a Collector)

pip install cerbere-ag

from agentguard import AgentGuard

guard = AgentGuard(
    collector_url="https://YOUR_AGENTGUARD_HOST",
    api_key="ag-your-key",
    agent_id="my-agent",
)

Optional extras:

pip install "cerbere-ag[signing]"   # verify signed policy decisions (Ed25519)
pip install "cerbere-ag[pii]"       # advanced PII detection via Presidio
pip install "cerbere-ag[redis]"     # distributed rate limiting / LLM Judge cache
pip install "cerbere-ag[ml]"        # local ML classifier (torch + transformers)

Option 2 — Run your own Collector (self-hosted)

1. Clone

git clone https://github.com/chrismsmr-celcom/cerbere-AG.git
cd cerbere-AG

2. Install

pip install -r requirements.txt

Optional ML dependencies:

pip install -r requirements-ml.txt

3. Start the Collector

gunicorn wsgi:app --bind 0.0.0.0:8080

The default collector runs on:

http://localhost:8080

4. Run the example agent

python example_agent.py

5. Check the API

curl http://localhost:8080/api/metrics

⸻

🧩 MCP Server (for agents built with Claude, Cursor, etc.)

If your agent is built on top of an LLM client that supports the Model Context Protocol, install the MCP server instead of wiring the SDK by hand:

pip install cerbere-ag-mcp

See README_MCP.md for the Claude Desktop / Cursor configuration snippets and the full list of exposed tools.

⸻

🐳 Docker

Docker Compose provides a convenient deployment environment.

cp env.example .env

Generate an API key:

python -c "import secrets; print('ag-' + secrets.token_urlsafe(32))"

Set the key in .env, then:

docker compose up -d

Services can include:

• AgentGuard Collector
• PostgreSQL
• Redis
• Gunicorn
• Health checks
• Persistent storage

⸻

🔌 SDK Integration

AgentGuard can wrap LLM and tool execution.

from agentguard import AgentGuard
guard = AgentGuard(
    collector_url="http://localhost:8080",
    api_key="ag-your-key",
    max_budget=10.0,
    block_on_high=True,
    use_ml=True,
    use_llm_judge=True,
)

Protect an LLM call

@guard.guard_llm_call
def call_openai(messages):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )

Protect a tool

@guard.guard_tool_call
def send_email(to, subject, body):
    return email_service.send(to, subject, body)

⸻

🔗 Integrations

Current examples include:

The SDK is designed to sit at the execution boundary rather than requiring changes to the underlying model.

⸻

🔧 Configuration

Example configuration:

# Authentication
AGENTGUARD_API_KEY=ag-your-key
# Database
AGENTGUARD_DB_TYPE=sqlite
# sqlite | postgres
DATABASE_URL=postgresql://user:pass@localhost:5432/agentguard
# ML
AGENTGUARD_USE_ML=true
AGENTGUARD_MODEL_PATH=./models/agentguard-injection-v1
AGENTGUARD_ML_THRESHOLD=0.80
# LLM Judge
AGENTGUARD_USE_LLM_JUDGE=true
DEEPSEEK_API_KEY=your-key
AGENTGUARD_JUDGE_MODEL=deepseek-chat
AGENTGUARD_BLOCK_ON_AMBIGUOUS=true
# Runtime
AGENTGUARD_RATE_LIMIT=300 per minute
AGENTGUARD_SPAN_RATE_LIMIT=150 per minute
AGENTGUARD_LOG_LEVEL=INFO

⸻

🧠 ML Detection

AgentGuard includes an optional ML detection pipeline.

Generate a dataset

python scripts/generate_dataset.py \
    --samples 50000 \
    --output dataset.csv

Train

python scripts/train_detector.py \
    --dataset dataset.csv \
    --output models/agentguard-injection-v1

Evaluate

python scripts/evaluate_detection.py \
    --model models/agentguard-injection-v1

Performance

The following are engineering targets, not guaranteed results:

Actual performance must be established through reproducible benchmarks on an independent test set.

⸻

🎯 LLM Judge

The LLM Judge is designed for cases where deterministic rules and the ML classifier cannot confidently determine whether an interaction is malicious.

Example:

{
  "score": 88,
  "reason": "Potential attempt to bypass agent restrictions through contextual manipulation.",
  "is_attack": true
}

LLM Judge support is configurable and can be disabled when low latency or deterministic behavior is preferred.

⸻

📊 Observability Dashboard

AgentGuard includes a web dashboard for runtime monitoring.

Dashboard

http://localhost:8080/

Depending on the deployment configuration, the dashboard provides:

• Real-time traces
• Security alerts
• Risk distribution
• Activity metrics
• Cost monitoring
• Session information
• ML detection statistics
• LLM Judge statistics
• JSON log export

API endpoints

GET  /api/metrics
GET  /api/traces
GET  /api/detection/stats
GET  /api/llm/stats
GET  /trace/<trace-id>
POST /span

Authentication is required according to the configured security policy.

⸻

📁 Project Structure

agentguard/
├── agentguard_sdk.py
├── agentguard_ml.py
├── collector.py
├── example_agent.py
│
├── integrations/
│   ├── langchain_example.py
│   └── crewai_example.py
│
├── tests/
│   ├── test_security.py
│   └── test_detection.py
│
├── scripts/
│   ├── generate_dataset.py
│   ├── train_detector.py
│   └── evaluate_detection.py
│
├── requirements.txt
├── requirements-ml.txt
├── env.example
├── Dockerfile
├── docker-compose.yml
├── wsgi.py
├── LICENSE
└── README.md

⸻

🧪 Testing

Run the complete test suite:

pytest -q

Security-specific tests:

pytest tests/test_security.py -vv

Detection tests:

pytest tests/test_detection.py -vv

Security testing and independent evaluation are an ongoing part of the project.

⸻

🗺️ Roadmap

v4.x — Runtime Security Foundation

• Three-layer detection architecture
• Runtime telemetry
• Security events
• Dashboard
• PostgreSQL support
• Redis rate limiting
• Docker deployment
• ML detection pipeline
• LLM Judge integration

v5.x — Platform

• Multi-tenant architecture
• OpenTelemetry integration
• Alerting
• Slack / Email / PagerDuty integrations
• Dedicated CLI
• React dashboard
• Policy management
• Advanced RBAC

v6.x — AI Security Infrastructure

• High-performance collector
• Distributed detection
• Continuous model evaluation
• Automated threat intelligence
• Advanced agent behavior analysis
• Enterprise policy engine
• Security analytics

Roadmap items are subject to change.

⸻

🤝 Contributing

Contributions are welcome for permitted non-commercial development.

Typical workflow:

git clone <repository>
git checkout -b feature/my-feature

Make your changes, run the tests:

pytest -q

Then submit a Pull Request.

Before contributing, please read:

• LICENSE
• AUTHORS.md
• NOTICE.md
• CONTRIBUTING.md (if present)

⸻

📜 License

Cerbère / AgentGuard uses an open-core model:

• SDK & MCP server (agentguard/, agentguard_sdk.py, mcp/) → Apache License 2.0 — free for commercial and non-commercial use. See LICENSE.

• Collector, Dashboard & multi-tenant platform (collector/, dashboard/) → Commercial license required for production/commercial use. See LICENSE-COMMERCIAL.md.

For commercial licensing, contact: contact@cerbereag.site

Copyright © 2026 Christopher Dikesa

⸻

🧾 Attribution

If you use or reference AgentGuard in research, documentation, presentations, or derivative non-commercial projects, please credit:

AgentGuard — created by Christopher Dikesa

Original project repository:

chrismsmr-celcom/cerbere-AG

⸻

⚠️ Security Disclaimer

AgentGuard is a security layer designed to reduce risk in AI agent systems.

It does not guarantee complete protection against prompt injection, data leakage, tool abuse, model vulnerabilities, or other attacks.

Do not rely on AgentGuard as the sole security control for critical infrastructure.

If you discover a security vulnerability, please report it responsibly rather than publicly exposing exploitable details.

⸻

🙏 Acknowledgements

AgentGuard builds upon ideas, research, and tooling from the broader AI security ecosystem, including:

• OWASP LLM / GenAI security research
• Hugging Face
• DeepSeek
• Open-source Python ecosystem

⸻