https://github.com/beforewire/beforewire
Local action firewall for AI agents
https://github.com/beforewire/beforewire
Last synced: 8 days ago
JSON representation
Local action firewall for AI agents
- Host: GitHub
- URL: https://github.com/beforewire/beforewire
- Owner: beforewire
- License: apache-2.0
- Created: 2026-06-07T22:58:33.000Z (9 days ago)
- Default Branch: main
- Last Pushed: 2026-06-07T22:58:53.000Z (9 days ago)
- Last Synced: 2026-06-08T02:26:47.631Z (9 days ago)
- Language: Python
- Size: 225 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# BeforeWire / beforewire
BeforeWire is a **local action firewall for AI agents**. It sits between your agent and an LLM relay/API, screens tool calls before they execute, and writes tamper-evident audit records.
- Fully local by default: no third-party cloud, no uploaded prompts or audit logs
- Works as an OpenAI-compatible / Anthropic-compatible local proxy
- Blocks obvious malicious actions with deterministic rules, not LLM-as-judge
- Default proxy mode is developer-friendly: allow normal traffic, fail-closed only on malicious findings
## Install
```bash
pip install beforewire
beforewire init
beforewire selftest
```
`beforewire init` creates local config under `~/.beforewire/` and runs a first-block self-test so you can see a poisoned action get stopped immediately.
## Use It As A Local Proxy
Point your SDK or agent tool to the local BeforeWire proxy. Your upstream key is only forwarded from your machine to your upstream provider/relay; BeforeWire does not persist it.
```bash
beforewire proxy --upstream
# OpenAI-compatible clients
export OPENAI_BASE_URL=http://127.0.0.1:8788/v1
export OPENAI_API_KEY=
# Anthropic-compatible clients
export ANTHROPIC_BASE_URL=http://127.0.0.1:8788
export ANTHROPIC_API_KEY=
```
OpenAI SDK example:
```python
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8788/v1")
print(client.chat.completions.create(
model="gpt-4.1-mini",
messages=[{"role": "user", "content": "hello"}],
).choices[0].message.content)
```
Anthropic SDK example:
```python
from anthropic import Anthropic
client = Anthropic(base_url="http://127.0.0.1:8788")
print(client.messages.create(
model="claude-3-5-sonnet-latest",
max_tokens=64,
messages=[{"role": "user", "content": "hello"}],
).content[0].text)
```
## What It Catches
BeforeWire screens action-shaped output before it reaches tools:
- `slopsquat`: hallucinated or typosquatted packages such as `pip install reqursts`
- `secret_exposure`: API keys, private keys, and canary tokens in model output
- `dangerous_code`: `curl | sh`, `rm -rf /`, `base64 | sh`, `eval/exec`
- `suspicious_url`: optional domain allowlists, direct-IP checks, and search-engine constraints
- `canary_triggered`: fake keys you plant for relay-leak attribution
A `MALICIOUS` verdict is blocked even if the default policy would otherwise allow the action. Each decision is written to a SHA-256 hash-chain audit log.
## Quick Commands
```bash
beforewire doctor # local environment and policy self-check
beforewire canary demo # simulate a relay replaying a planted canary
beforewire receipt ~/.beforewire/audit.jsonl
beforewire verify ~/.beforewire/audit.jsonl
beforewire allow --pypi mycorp-sdk # reduce false positives for known internal packages
beforewire lint-policy policies/relay-guard.yaml
```
## More Examples
- Local policy examples: `policies/relay-guard.yaml`, `policies/egress-allowlist.yaml`
- Claude Code hook example: `examples/claude-code-settings.example.json`
- MCP snapshot / approval / drift demo: `examples/mcp-risk-demo/`
- Chinese usage notes and advanced flows: `docs/usage.zh.md`
## Why This Exists
Many developers route agents through LLM relays or custom gateways. If a relay injects a malicious tool call, leaks a key, or rewrites an install command, the dangerous part is often the **action after the model response**. BeforeWire adds a local, deterministic gate before that action hits the wire.
The first focus is relay-poisoning protection; the same core also supports tool snapshot approval, drift checks, local audit receipts, and optional plugin extension points.
## Architecture
| Module | Role |
|---|---|
| `screening` | deterministic local checks for packages, secrets, URLs, canaries, and dangerous code |
| `policy` | small YAML policy engine with `default-allow` and `default-deny` modes |
| `proxy` | local OpenAI/Anthropic-compatible screening proxy |
| `audit` | SHA-256 hash-chain JSONL audit records |
| `toolscan` / `approvals` | MCP/tool config snapshots, approvals, and drift checks |
| `spi` | optional plugin protocols discovered through Python entry points |
## Contributing And Safe Reports
Small fixes, false-positive reports, and minimal repro cases are welcome. See `CONTRIBUTING.md`.
Please do not paste real API keys, private prompts, or production audit logs into public issues. For sensitive reports, email `security@beforewire.com`.
## License
Apache-2.0. See `LICENSE`.