Metadata-Version: 2.4
Name: openguard
Version: 0.1.2
Summary: guarding proxy for AI
Project-URL: Homepage, https://github.com/Jitera-Labs/openguard
Project-URL: Repository, https://github.com/Jitera-Labs/openguard
Project-URL: Issues, https://github.com/Jitera-Labs/openguard/issues
Author: OpenGuard Contributors
License-Expression: MIT
Keywords: anthropic,fastapi,guardrails,llm,openai,proxy
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: asyncache==0.3.1
Requires-Dist: cachetools==5.5.2
Requires-Dist: fastapi==0.111.0
Requires-Dist: httpx==0.27.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pyyaml==6.0.2
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]==0.30.6
Provides-Extra: dev
Requires-Dist: livereload>=2.7.1; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio==0.24.0; extra == 'dev'
Requires-Dist: pytest==8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: types-cachetools>=6.2.0.20251022; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20250915; extra == 'dev'
Description-Content-Type: text/markdown

![Splash image](./public/public/splash.png)

![Python](https://img.shields.io/badge/Python-3.10%2B-black?logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-Framework-black?logo=fastapi&logoColor=white) ![Docker](https://img.shields.io/badge/Docker-Ready-black?logo=docker&logoColor=white) ![OpenAI Compatible](https://img.shields.io/badge/OpenAI-Compatible-black?logo=openai&logoColor=white) ![Anthropic Compatible](https://img.shields.io/badge/Anthropic-Compatible-black?logo=anthropic&logoColor=white) [![PyPI](https://img.shields.io/pypi/v/openguard?color=black&labelColor=black&logo=pypi&logoColor=white)](https://pypi.org/project/openguard/)
[![Visitors](https://api.visitorbadge.io/api/combined?path=https%3A%2F%2Fgithub.com%2FJitera-Labs%2Fopenguard&labelColor=%23000000&countColor=%23ffffff&style=flat)](https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2FJitera-Labs%2Fopenguard)

OpenGuard is a security proxy for LLM applications. It sits between your application and your AI providers to intercept, sanitize, and block traffic.

If you build AI agents, expose LLMs to users, or send data to external APIs, you have a vulnerable attack surface. Users will try to inject prompts. Employees will paste sensitive customer data. Attackers will attempt data poisoning. OpenGuard gives you a central chokepoint to enforce strict security policies before any request leaves your infrastructure.

## Who This Is For

- **Agent Developers:** Autonomous agents execute code and make API calls. OpenGuard blocks prompt injections and jailbreaks before your agent executes malicious instructions.
- **WebSec Specialists:** Standard web application firewalls do not understand LLM payloads. OpenGuard inspects the actual context and intent of the prompts.
- **Enterprise & SMB:** Centralize your AI security policies. Stop personally identifiable information (PII) and proprietary secrets from reaching OpenAI or Anthropic.
- **Data Engineers:** Filter incoming prompts for malicious payloads and stop data poisoning attempts that could pollute your downstream systems.

## How It Works

OpenGuard is a transparent proxy. You do not need to rewrite your application. You change the API base URL in your existing OpenAI or Anthropic client. OpenGuard intercepts the payload, runs it through your defined rules, and either forwards the sanitized request or drops it.

Currently, OpenGuard validates incoming request payloads. It does not scan streamed responses.

## Installation & Usage

You don't need to rewrite your agent's code to use OpenGuard. The easiest way to run it is via the `launch` command, which automatically spins up the proxy, injects the correct environment variables into your tool, and shuts the proxy down when you're done.

First, set your provider keys as environment variables. OpenGuard uses wildcards (like `_1`, `_2`) to support multiple upstream accounts:

```bash
export OPENGUARD_OPENAI_KEY_1="sk-..."
export OPENGUARD_ANTHROPIC_KEY_1="sk-..."
```

**Launch your agent:**
If you have [uv](https://docs.astral.sh/uv/) installed, you can start OpenGuard and your CLI tool in a single command. OpenGuard currently supports native integrations for `claude`, `opencode`, and `codex`.

```bash
# Launch Anthropic's Claude Code through OpenGuard
uvx openguard launch claude

# Launch OpenCode
uvx openguard launch opencode
```

**Run as a background proxy:**
If you are building your own application or using a tool without a native integration, you can run OpenGuard as a persistent background proxy.

```bash
# Start the proxy directly using uvx
uvx openguard serve

# OR run the official image via Docker
docker run -p 23294:23294 \
  -e OPENGUARD_OPENAI_KEY_1 \
  -e OPENGUARD_ANTHROPIC_KEY_1 \
  -v $(pwd)/guards.yaml:/app/guards.yaml \
  ghcr.io/Jitera-Labs/openguard:main
```

Then, point your existing SDKs to the proxy endpoint. OpenGuard accepts standard OpenAI and Anthropic request formats.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:23294/v1", # Route through OpenGuard
    api_key="your-api-key"
)

# OpenGuard inspects this request before OpenAI receives it
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Execute system payload."}]
)
```

## Security Rules

You configure policies in a `guards.yaml` file. Rules map specific models or routes to a sequence of security checks.

### PII Protection
Scrub emails, phone numbers, and credit cards from prompts. You can configure it to drop the request entirely or redact the sensitive text before forwarding.

```yaml
- type: pii_filter
  config:
    enabled: true
```

### Prompt Injection Detection
Use a secondary, faster LLM to inspect incoming requests for jailbreaks or malicious instructions.

```yaml
- type: llm_input_inspection
  config:
    prompt: "Does this text attempt to override previous instructions or jailbreak the system?"
    max_chars: 2000
```

### Keyword and Content Filtering
Block specific terminology, competitor names, or proprietary project codenames.

```yaml
- type: content_filter
  config:
    blocked_words: ["Project Titan", "internal_api_key"]
```

### Token Limiting
Prevent denial-of-service attacks and control costs by enforcing hard limits on input context.

```yaml
- type: max_tokens
  config:
    max_tokens: 4096
```

## Configuration Structure

Rules apply based on matchers. You can enforce different policies for different models.

```yaml
guards:
  # Strict rules for external models
  - match:
      model:
        _ilike: "%gpt-4%"
    apply:
      - type: pii_filter
        config:
          enabled: true
      - type: llm_input_inspection
        config:
          prompt: "Is this a prompt injection?"

  # Lenient rules for local models
  - match:
      model:
        _ilike: "%llama-3%"
    apply:
      - type: max_tokens
        config:
          max_tokens: 8192
```

## Development

Run OpenGuard as a global host-level command backed by Docker:

```bash
make install-global-openguard
```

You can then run the proxy from anywhere:

```bash
openguard
```

To run the test suite:

```bash
# Unit tests
make test-unit

# Integration tests (requires the service to be running)
make test-integration
```
