SENTINAL — AI-Powered WAF & Intrusion Detection System

Traditional Web Application Firewalls rely entirely on static rule sets — a list of banned patterns and keywords. This approach generates massive false positives, misses zero-day variants (slightly mutated payloads that evade pattern matching), and provides no intelligence about why a request was blocked. Security teams have no visibility into attack patterns, no forensic depth per incident, and no way to correlate related attacks. For high-stakes applications, there is also no safe mechanism for "human review before blocking" — either everything is auto-blocked (breaking legitimate traffic) or nothing is (leaving the app exposed).

Built a 5-microservice security platform from scratch in 36 hours. Every incoming HTTP request passes through a Node.js/Express gateway that checks a MongoDB blocklist (30s in-memory cache), logs the raw request, and forwards suspicious traffic to a Python FastAPI detection engine running a trained XGBoost classifier that returns { attackType, severity, confidence }. Confirmed attacks are passed to the Nexus Policy Engine — a Python AI agent powered by Google Gemini 1.5 Pro — which evaluates PolicyGuard-v1 rules: low-risk actions (rate_limit_ip, send_alert) are auto-executed, while high-risk irreversible actions (permanent_ban_ip, shutdown_endpoint) are queued for human approval via the dashboard. A React + Vite security operations center displays all of this in real time via Socket.IO with 17 pages including an AI Copilot, forensic reports, geo threat maps, and a PCAP analyzer.

├── .env.example               # All 20+ env vars documented
├── ecosystem.config.js        # PM2 config for all 5 processes
├── deploy.sh                  # One-command Ubuntu VPS deploy (37KB)
├── start.sh / stop.sh         # Local lifecycle scripts
├── status.sh                  # Health check script
│
├── Readme/                    # 4 complete documentation files
│   ├── ARCHITECTURE.md        # System design + full data flow
│   ├── API_REFERENCE.md       # Every endpoint with req/res examples
│   ├── LOCAL_SETUP.md         # Step-by-step local dev guide
│   └── CODEBASE_GUIDE.md      # Key files explained
│
├── backend/src/               # Node.js Gateway (Entry: server.js)
│   ├── middleware/
│   │   ├── blocklistMiddleware.js   # IP check, 30s in-memory cache
│   │   └── requestLogger.js         # Logs every HTTP request
│   ├── models/
│   │   ├── BlockedIP.js       # TTL-indexed MongoDB schema
│   │   ├── ActionQueue.js     # Pending Nexus proposals
│   │   ├── AttackEvent.js     # Confirmed attack records
│   │   ├── Alert.js           # High/critical notifications
│   │   ├── AuditLog.js        # Immutable action trail
│   │   └── SystemLog.js       # Raw HTTP request log
│   ├── routes/
│   │   ├── attacks.js         # GET /api/attacks
│   │   ├── blocklist.js       # CRUD /api/blocklist
│   │   ├── actions.js         # /api/actions approve/reject
│   │   ├── gemini.js          # All 4 Gemini AI endpoints
│   │   └── armoriq.js         # /api/nexus/trigger (demo)
│   ├── services/
│   │   ├── attackService.js   # Save + broadcast attack events
│   │   └── geminiService.js   # Gemini API wrapper
│   ├── sockets/               # Socket.IO event broadcast layer
│   ├── validators/            # Input validation
│   └── tests/                 # Backend unit tests
│
├── services/
│   ├── detection-engine/      # Python FastAPI :8002
│   │   ├── app/               # FastAPI routes + scoring pipeline
│   │   └── models/            # Trained XGBoost .joblib files
│   ├── nexus-agent/           # Python FastAPI :8004
│   │   └── PolicyGuard-v1 rules + Gemini 1.5 Pro decisions
│   ├── pcap-processor/        # Python FastAPI :8003
│   │   └── scapy/pyshark + anomaly extraction
│   └── sentinal-response-engine/  # Extended response layer
│
├── frontend/src/              # React 18 + Vite :5173
│   │                          # (Tailwind CSS — team contribution)
│   ├── pages/                 # 17 route-level page components
│   ├── components/            # Shared UI components
│   ├── hooks/                 # useSocket + custom hooks
│   ├── services/api.js        # All Axios API calls
│   ├── styles/                # Global CSS
│   └── utils/                 # Helper functions
│
├── sentinal-middleware/       # Standalone npm package (team contribution)
│   ├── src/
│   │   ├── rateLimiter.js     # ingestLimiter (100 req/min) + globalLimiter (300 req/min)
│   │   └── validate.js        # Joi schema-based request validator
│   ├── index.js               # Package entry point
│   └── package.json           # MIT, peer dep: express >=4.0.0
│
├── demo-target/               # Intentionally vulnerable Express app
│   └── (SQLi, XSS, traversal endpoints — for live demo)
├── postman/
│   └── SENTINAL_API.postman_collection.json
├── assests/                   # Screenshots + demo media
└── config/                    # PM2 + Nginx config files```

blocklistMiddleware uses a 30-second in-memory cache of the MongoDB blockedips collection — zero DB hit on 99% of requests after warm-up

Nexus is fire-and-forget — called asynchronously after attack is confirmed, so it never adds latency to the Gateway's response path

Detection Engine (FastAPI + uvicorn + uvloop) runs on async I/O — handles concurrent scoring requests without blocking

Socket.IO broadcasts are event-driven — the dashboard receives updates in real time without polling

MongoDB TTL index on blockedips.expiresAt — expired blocks are automatically cleaned by MongoDB, no cron job needed

sentinal-middleware npm package — extracted rate limiter uses express-rate-limit v7 which stores state in memory with O(1) lookup per request

Each service is independently scalable and in its own language/runtime best suited for the task More operational complexity — 5 processes to manage, PM2 required Trains fast (minutes not hours), interpretable confidence scores, tiny model file, runs on CPU Less accurate on highly obfuscated/novel attack variants

Microservice orchestration in a hackathon is risky: Managing 5 processes across different runtimes (Node.js + Python ×3) in 36 hours meant a lot of time debugging inter-service communication. PM2 with ecosystem.config.js was the right call to manage this centrally — but the lesson was: establish the service-to-service contract (request/response shape) on paper before writing any code.

Rate limiting is trivially extractable: The sentinal-middleware npm package proved that generic security primitives (rate limiting, validation) don't need to be buried inside application code — they can be published as zero-dependency, reusable packages for any Express app. The whole thing was 3 files.

ML models need a fallback path: If the Detection Engine is down, the Gateway must still serve requests. We implemented a graceful degradation mode — if the Python service is unreachable, requests are logged and flagged, but not blocked, to avoid taking the protected app offline.

WebSocket event design matters early: Initially the dashboard was polling every 5 seconds. Switching to Socket.IO real-time events mid-hackathon required refactoring the entire frontend data layer. The lesson: decide on push vs. pull architecture before writing frontend pages.

Human-in-the-loop UX is underrated: The /action-queue page — where a human approves or rejects AI-proposed bans — was the feature judges found most compelling. A security tool that shows its reasoning and asks for permission before doing something irreversible is fundamentally more trustworthy than a black-box auto-blocker.

Webhook integrations: Slack / PagerDuty / Discord alerts when severity = critical — currently only visible in the dashboard

Multi-tenant support: Each protected application gets its own namespace, blocklist, and dashboard view

Model retraining pipeline: Collect confirmed attack events from MongoDB as ground truth → retrain XGBoost weekly → hot-swap model file without restarting the service

HTTPS / TLS termination: Currently runs on HTTP — Nginx config exists but TLS cert automation (Let's Encrypt via Certbot) not yet wired in

sentinal-middleware npm publish: The package is fully structured for npm publish — next step is to push to registry so any Express app can npm install sentinal-middleware and get rate limiting + validation in one line

Geo-blocking rules: AbuseIPDB integration is wired (ABUSEIPDB_API_KEY in .env) but UI-level geo-blocking rules (block entire countries) not yet implemented

Attack replay: Record + replay a captured attack sequence against a sandbox to test if a patch actually fixes the vulnerability

blocklistMiddleware on every request: No route in the Gateway is exempt — IP check runs before any route handler executes, ensuring blocked IPs never reach application logic

PolicyGuard-v1 rules enforce human authorization for irreversible actions: permanent_ban_ip and shutdown_endpoint are always queued, never auto-executed — this is a hard constraint in the Nexus engine, not a toggle

AuditLog is append-only: Every approve/reject/block action writes an audit entry — there is no delete or update route for audit_log in the API

GEMINI_API_KEY + MONGO_URI are server-side only: Never sent to the frontend; all Gemini calls proxy through the Gateway

JWT_SECRET + API_SECRET: Two separate secrets — one for user session tokens, one for internal API-to-API calls between microservices

Demo target is intentionally vulnerable: demo-target/ is a separate Express app with deliberately exploitable endpoints (SQLi, XSS, path traversal) — it must never be deployed on the same port as a real application

sentinal-middleware rate limits: ingestLimiter caps at 100 req/min per IP on data ingest routes; globalLimiter caps at 300 req/min per IP globally — both use sliding window algorithm from express-rate-limit v7