Metadata-Version: 2.4
Name: cerbere-ag
Version: 0.5.0
Summary: Runtime security & observability guard for AI agents — intercepts LLM calls and tool calls before execution.
Author: Christopher Dikesa
License-Expression: Apache-2.0
Project-URL: Homepage, https://app.cerbereag.site
Project-URL: Repository, https://github.com/chrismsmr-celcom/cerbere-AG
Keywords: ai,agents,security,llm,guardrails,observability,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.31.0
Requires-Dist: structlog<25.0.0,>=23.2.0
Requires-Dist: tiktoken<1.0.0,>=0.7.0
Requires-Dist: pydantic<3.0.0,>=2.7.0
Provides-Extra: signing
Requires-Dist: cryptography<45.0.0,>=41.0.0; extra == "signing"
Provides-Extra: pii
Requires-Dist: presidio-analyzer<3.0.0,>=2.2.350; extra == "pii"
Requires-Dist: presidio-anonymizer<3.0.0,>=2.2.350; extra == "pii"
Provides-Extra: redis
Requires-Dist: redis<6.0.0,>=5.0.0; extra == "redis"
Provides-Extra: ml
Requires-Dist: torch==2.1.2; extra == "ml"
Requires-Dist: transformers==4.36.2; extra == "ml"
Requires-Dist: scikit-learn==1.3.2; extra == "ml"
Dynamic: license-file

# 🐕‍🦺 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

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

| Layer | Technology | Purpose |
|-------|-----------|---------|
| 1 | Rules / Regex | Fast deterministic detection |
| 2 | ML | Semantic classification |
| 3 | LLM Judge | Ambiguous or complex cases |

The exact thresholds are configurable.

⸻

## 🚨 Threat Coverage

| Threat | Rules | ML | LLM Judge | Possible Action |
|--------|-------|----|-----------|-----------------|
| Prompt Injection | ✅ | ✅ | ✅ | Block |
| PII Leakage | ✅ | ✅ | ✅ | Redact / Block |
| Tool Misuse | ✅ | ✅ | ✅ | Block |
| Unauthorized Tools | ✅ | — | — | Block |
| Budget Overflow | ✅ | — | — | Block |
| Suspicious Input | ✅ | ✅ | ✅ | Alert |
| Ambiguous Behavior | — | ⚠️ | ✅ | Review |

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)

```bash
pip install cerbere-ag
```

```python
from agentguard import AgentGuard

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

Optional extras:

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

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

2. Install

```bash
pip install -r requirements.txt
```

Optional ML dependencies:

```bash
pip install -r requirements-ml.txt
```

3. Start the Collector

```bash
gunicorn wsgi:app --bind 0.0.0.0:8080
```

The default collector runs on:

```
http://localhost:8080
```

4. Run the example agent

```bash
python example_agent.py
```

5. Check the API

```bash
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:

```bash
pip install cerbere-ag-mcp
```

See [README_MCP.md](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.

```bash
cp env.example .env
```

Generate an API key:

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

Set the key in .env, then:

```bash
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.

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

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

Protect a tool

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

⸻

## 🔗 Integrations

Current examples include:

| Integration | Support |
|-------------|---------|
| LangChain | ✅ |
| CrewAI | ✅ |
| OpenAI | ✅ |
| DeepSeek | ✅ |
| Anthropic | ✅ |

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

⸻

## 🔧 Configuration

Example configuration:

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

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

Train

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

Evaluate

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

Performance

The following are engineering targets, not guaranteed results:

| Metric | Target |
|--------|--------|
| Recall | > 99% |
| Precision | > 98% |
| False Positive Rate | < 1% |
| Detection latency | < 50 ms |

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:

```json
{
  "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:

```bash
pytest -q
```

Security-specific tests:

```bash
pytest tests/test_security.py -vv
```

Detection tests:

```bash
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:

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

Make your changes, run the tests:

```bash
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](LICENSE).

- **Collector, Dashboard & multi-tenant platform** (`collector/`, `dashboard/`)
  → **Commercial license required** for production/commercial use.
  See [LICENSE-COMMERCIAL.md](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

⸻

<div align="center">

🛡️ AgentGuard

Observe. Detect. Enforce.

Runtime security infrastructure for agentic AI.

Copyright © 2026 Christopher Dikesa

</div>
