Defensive runtime security kernel for cross-chain bridge systems.
BridgeGuard v2 is a local-first operator console and API for simulating bridge events, checking runtime invariants, scoring risk, and producing explainable decisions. It keeps the original v1 simulation endpoints intact while adding authentication, project isolation, event listeners, alerts, policy calibration, connector discovery, and signed compliance reports.
- Authenticated FastAPI v2 API with JWT login/register and
/api/v2/auth/me. - Project-scoped multi-tenancy for simulations, decisions, alerts, listeners, policy configs, and reports.
- Project dashboard with recent decisions, alert status, listener status, and v2 simulation flow.
- Multi-chain connector framework with EVM, Solana, and Cosmos connector types.
- EVM auto-discovery endpoint for verified ABI method mapping suggestions.
- Celery/Redis listener foundation for polling or websocket connector events.
- Slack, email, and webhook alert rules for risky decisions.
- Policy calibration with risk weights and custom expression rules.
- PDF decision reports with digital signature verification.
- TailwindCSS/shadcn-style frontend components.
- Docker Compose stack for PostgreSQL, Redis, backend, Celery worker, and Nginx frontend.
- GitHub Actions workflow for backend pytest and frontend type-check/build.
The original v1 API is intentionally preserved:
- Root v1 endpoints still work, including
/health,/simulate,/simulate-attack/{name},/decisions,/metrics,/reason-codes, and/connectors. - The same v1 routes are also available under
/api/v1. - v2 routes live under
/api/v2and require auth for project-scoped operations. - The frontend keeps a v1 Tools section for historical replay, risk metrics, old connector storage, recent v1 decisions, and reason-code reference.
- Existing local
backend/connectors.jsonfiles continue to work with old connector endpoints.
The fastest path is Docker:
docker compose up --buildOpen:
- Frontend:
http://localhost:3000 - Backend health:
http://localhost:8000/health - API docs:
http://localhost:8000/docs
The Alembic seed migration creates a demo account:
Email: demo@bridgeguard.local
Password: bridgeguard-demo
Project: Demo Bridge Operations
For a guided walkthrough, see QUICKSTART.md.
The Compose stack includes:
db: PostgreSQL 16redis: Redis 7backend: FastAPI with Alembic migrations on startupcelery: BridgeGuard worker for listener and alert tasksfrontend: Nginx serving the production React build and proxying API routes
Useful commands:
docker compose up --build
docker compose ps
docker compose logs -f backend
docker compose downTo reset the database volume:
docker compose down -v
docker compose up --buildBackend:
cd backend
python -m pip install -r requirements.txt
alembic upgrade head
python -m pytest tests
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000Frontend:
cd frontend
npm install
npm.cmd exec tsc -- --noEmit
npm.cmd run build
npm startOptional local services for v2 listener/alert workflows:
redis-server
cd backend
celery -A app.tasks.celery_app worker --loglevel=infoEnvironment variables:
DATABASE_URL=sqlite:///./bridgeguard.db
DATABASE_URL=postgresql://bridgeguard:bridgeguard@localhost:5432/bridgeguard
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
SECRET_KEY=change-this-in-real-deployments
v1 examples:
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/attacks
curl -X POST "http://127.0.0.1:8000/simulate-attack/Ronin%20Bridge"v2 auth:
curl -X POST http://127.0.0.1:8000/api/v2/auth/register `
-H "Content-Type: application/json" `
-d "{\"email\":\"operator@example.com\",\"password\":\"bridgeguard-demo\",\"project_name\":\"Ops\"}"
curl -X POST http://127.0.0.1:8000/api/v2/auth/login `
-H "Content-Type: application/x-www-form-urlencoded" `
-d "username=operator@example.com&password=bridgeguard-demo"v2 project-scoped requests use:
Authorization: Bearer <token>
X-Project-ID: <project_id>
BridgeGuard supports a connector registry with:
- EVM connector
- Solana connector mock
- Cosmos connector mock
- Config-file discovery
- Etherscan ABI discovery through
POST /api/v2/connectors/discover
Default demo connector configs are stored in:
backend/app/sample_data/default_connectors.json
User-created legacy connectors are stored in:
backend/connectors.json
Backend:
cd backend
python -m pytest testsFrontend:
cd frontend
npm.cmd exec tsc -- --noEmit
npm.cmd run buildCI runs the same backend and frontend checks on push and pull request.
BridgeGuard is open for bridge operators, auditors, insurers, and DeFi security researchers evaluating runtime bridge monitoring.
Using BridgeGuard in a pilot, audit workflow, research project, or insurance risk process? Open an issue or discussion to be listed here.
BridgeGuard is defensive-only:
- no private keys
- no transaction signing
- no exploit payloads
- no live fund movement
- no guarantee of absolute security
- no proprietary internal bridge logic exposed
See SECURITY.md for reporting guidance and safe-use notice.
The risk model is deterministic and explainable. v2 adds project-level weight calibration and custom expression rules, but operators must calibrate with real operational data before any production use.
See RISK_MODEL.md.
For managed hosting, enterprise features, or custom integrations, contact us at [email/website].
The historical incident library is used only for defensive simulation and product demonstration.
BridgeGuard v2.0.0 is a stable open-source defensive release for demonstrations, internal review, prototype operator workflows, and commercial evaluation. It is not a substitute for independent audits, bridge-specific threat modeling, or production incident response controls.
This project is licensed under the MIT License – see LICENSE file for details.