How wallarm/api-firewall works
Project Type and Purpose
• This is an open‐source, high‐performance API Firewall/proxy written in Go. It validates REST (OpenAPI) and GraphQL requests & responses against provided schemas, enforces a positive‐security model, and can run in PROXY, API, or GRAPHQL modes.
File Structure Analysis
• cmd/api-firewall: entrypoint (main.go) + HTTP(GraphQL) handlers + proxy and updater subcommands + benchmarks/tests.
• internal/: core implementation broken into layers:
• config (app settings, servers, schemas)
• mid (HTTP middleware: logging, ModSecurity, allow/deny lists)
• platform (ports/adapters): storage (databases for schemas, tokens, lists), proxy (fasthttp-based HTTP & WebSocket forwarding, DNS cache), oauth2 introspection, metrics (Prometheus), router (Chi mux), validator (OpenAPI/GraphQL decoder/encoder).
• web (HTTP server adaptor/tracing/response helpers).
• version.
• pkg/APIMode: standalone API‐mode library.
• demo/: Docker Compose & Kubernetes examples showing real backends (httpbin, vulnerable GraphQL app), volumes, manifests, scripts.
• helm/: Helm chart for Kubernetes deployment.
• docs/: guides & configuration references.
• Root: Dockerfile, Makefile, GitHub workflows for CI/CD, mkdocs, license.
Key Architecture Insights from README
• Reverse proxy with built‐in schema validator.
• Supports multiple Content‐Types & protocols (REST, GraphQL HTTP & WS).
• Pluggable ModSecurity rules via Coraza/OWASP CRS.
• Extensible storage for allow/deny lists, token denylist, schema loader/updater.
• Metrics exported to Prometheus.
a. Main Components
• Clients (External): REST clients, GraphQL clients, browsers (WebSocket)
• API Firewall Service (single container/pod) comprising:
1. HTTP Server Layer (fasthttp)
2. Router (Chi-based multiplexer)
3. Middleware (logging, CORS, allow/deny lists, ModSecurity)
4. Schema Loader/Updater (OpenAPI/GraphQL loader from DB or file)
5. Validator (request/response against schema)
6. Proxy Core
• HTTP Proxy (fasthttp ReverseProxy)
• WebSocket Proxy
• DNS Cache
7. OAuth2 Introspection (JWT & introspection calls)
8. Metrics Exporter (Prometheus client)
9. Storage Adapters
• SQLite/PostgreSQL for schemas, token denylist, allow/deny lists
• File‐based fallback
• Upstream Backends (configurable)
• REST API (e.g., httpbin)
• GraphQL server (e.g., demo app)
• External Services
• OAuth2 Auth Server (optional)
• Prometheus / Grafana
b. Relationships & Data Flow
1. Client → HTTP Server → Router → Middleware chain
2. Middleware calls Schema Loader on startup/updates; passes request to Validator
3. Validator approves or rejects; logs or blocks
4. On approval: Proxy Core forwards to Upstream Backend
5. Response travels back: Proxy Core → Validator → Middleware → Client
6. Metrics & logs emitted throughout
7. Updater component refreshes schema DB from file system or remote
c. Architectural Patterns & Principles
• Layered Architecture: clear separation of config, middleware, validation, proxy, storage.
• Ports & Adapters (Hexagonal): internal/platform defines interfaces; storage, proxy, oauth2 are adapters.
• Modular Handlers: separate handlers for API mode, PROXY mode, GraphQL HTTP & WS.
• Plug-able Schemas & Rules: dynamic loader/updater for OpenAPI, GraphQL, ModSecurity.
d. Key Technologies
• Go + fasthttp for ultra‐fast HTTP server & proxy
• Chi router for request routing
• Coraza (ModSecurity) for attack signature enforcement
• SQLite (via storage adapters) or file storage for local DBs
• Prometheus client library for metrics
• Docker, Docker Compose, Helm/Kubernetes for deployment