Built for MSSPs, enterprise security teams, and managed detection & response providers
Quick Start · Features · Architecture · Connectors · Deploy · Contributing
NeuraShield is a production-grade, multi-tenant SOC platform that ingests security events from your existing tools, normalizes and correlates them in real-time, and gives your analysts an AI-assisted workspace to triage, investigate, and respond — all from a single dashboard.
Every layer is built for multi-tenancy: data, rate limits, API keys, playbooks, and RBAC are fully isolated per tenant, making NeuraShield suitable for MSSPs managing many client environments or enterprises with multiple independent business units.
Wazuh · Suricata · MS Defender · Syslog
│
▼ POST /api/v1/connectors/{source}/ingest
┌────────────────────────────────────────────────────┐
│ INGEST → NORMALIZE → CORRELATE → DETECT │
│ │
│ Alerts → Investigations → Playbooks → Notify│
└────────────────────────┬───────────────────────────┘
│ REST + WebSocket
┌───────────▼───────────┐
│ React Dashboard │
│ + AI Copilot (LLM) │
└───────────────────────┘
- Multi-source ingestion — Wazuh, Suricata IDS, Microsoft Defender ATP, syslog, and custom webhooks out of the box
- Normalization engine — maps raw events to a unified schema regardless of source format
- Real-time correlation — groups related events into incidents using configurable time windows and co-occurrence rules
- Sigma rule support — write detections in the open Sigma format; bulk-import from SigmaHQ
- Custom detection rules — threshold, pattern-match, and behavioral rules with severity scoring and MITRE ATT&CK tagging
- UEBA — user & entity behavior analytics; statistical baselines surface anomaly alerts automatically
- Attack chain visualization — interactive DAG graph showing how low-level events chain into multi-stage attacks
- MITRE ATT&CK browser — map every detection to the ATT&CK matrix; visualize your detection coverage as a heatmap
- Suppression rules — silence known-good noise with field-matching expressions; time-bounded or permanent
- Investigation tickets — create, assign, tag, prioritize, and close investigations with a full audit trail
- AI Copilot — ask natural-language questions about any alert; the LLM receives scoped, tenant-isolated SOC context
- Playbooks — define automated response runbooks (block IP, isolate host, send Slack alert, create ticket, etc.)
- Threat intelligence enrichment — AbuseIPDB, AlienVault OTX, and VirusTotal lookups per indicator, per alert
- IOC management — import, search, tag, and correlate indicators of compromise across all ingested events
- Complete tenant isolation — database rows, Redis namespaces, rate limits, API keys, and settings are separated per tenant
- RBAC — Owner / Admin / Analyst / Viewer roles with per-tenant membership management
- MSSP super-admin portal — manage all client tenants from a single elevated view
- Per-tenant ingest rate limiting — noisy tenants are throttled without impacting neighbours
- Email invitations — onboard teammates with role assignment; no admin required for self-registration
- MFA / TOTP — time-based one-time passwords with QR code provisioning and backup codes
- Tamper-evident audit log — SHA-256 hash chaining on every audit entry; the chain breaks if any row is altered
- JWT + Argon2 — short-lived access tokens (15 min), rotating refresh tokens (7 days), Argon2id password hashing
- HMAC agent tokens — agents authenticate with fast HMAC-SHA256 tokens; legacy Argon2 still accepted during migration
- API key management — scoped keys for connector integrations; keys are hashed at rest
- Rate limiting on every auth endpoint (login, register, MFA, password reset, demo)
- Content-length middleware — 10 MiB cap on all inbound requests
- Strict security headers — CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
- Prometheus metrics — HTTP request latency, event throughput, queue depth, active alerts (bearer-token gated)
- Sentry APM — distributed traces, performance profiling, and session replay for both backend and frontend
- Structured JSON logging — structlog with request-ID propagation through the entire async call chain
- Health endpoints —
/api/v1/health(unauthenticated) and/api/v1/health/metrics-info(auth-gated)
- SOC Agent — lightweight Python agent for Windows/Linux endpoints; phone-home heartbeat, log forwarding
- Fleet dashboard — real-time agent heartbeat, version tracking, and remote status monitoring
- One-command bootstrap — PowerShell (
bootstrap.ps1) for Windows; Python installer for Linux/macOS
- PDF report generation — executive summaries, alert timelines, KPIs, and analyst workload stats
- Scheduled reports — generate and email reports automatically on a cron schedule
- SOC metrics dashboard — MTTD, MTTR, alert volume trends, false-positive rates, team throughput
Data flow summary:
- Security tools push raw events to
/api/v1/connectors/{source}/ingestwith a per-tenant API key - The ingestion pipeline normalizes each event, enriches it with GeoIP and threat-intel lookups, and appends it to a Redis stream
- Background workers consume the stream and run correlation and detection rule evaluation
- Detections create alerts; high-severity alerts trigger configured playbook actions (notify, escalate, block)
- Analysts triage alerts in the React dashboard and ask the AI Copilot for context
- Every privileged action is written to the tamper-evident, hash-chained audit log
| Layer | Technology |
|---|---|
| API | Python 3.12+, FastAPI 0.115+, Uvicorn (ASGI) |
| ORM / Migrations | SQLAlchemy 2.0 (async + typed), Alembic |
| Database | PostgreSQL 16, pgvector (RAG embeddings) |
| Cache / Queues | Redis 7 (Hiredis) — streams, pub/sub, distributed locks |
| Frontend | React 18, TypeScript 5.6, Vite 8, Tailwind CSS 3 |
| UI Components | Radix UI, TanStack Table/Query, XyFlow, Recharts, Framer Motion, dnd-kit |
| State Management | Zustand (client state), TanStack Query (server state) |
| AI / LLM | Groq (Llama models), Google Gemini — switchable per tenant |
| Auth | PyJWT 2.9+, Argon2-cffi, pyotp (TOTP), HMAC-SHA256 |
| Observability | Prometheus client, Sentry SDK 2.0+ (FastAPI + React integrations) |
| Logging | structlog (async-safe, JSON output) |
| Brevo (primary), Resend (secondary), SMTP fallback | |
| Threat Intel | AbuseIPDB, AlienVault OTX, VirusTotal, MaxMind GeoLite2 |
| Deployment | Docker Compose (local / self-hosted), Railway (cloud PaaS) |
| CI/CD | GitHub Actions — lint, type-check, unit tests, integration tests, Docker build, deploy |
- Docker Desktop 24+ with Docker Compose
- Git
git clone https://github.com/ai-soc-analyst/soc-saas-v2.git
cd soc-saas-v2
cp backend/.env.example backend/.envEdit backend/.env — at minimum, set the JWT secrets:
# Generate strong secrets (run these, paste the output into .env)
openssl rand -hex 64 # → JWT_SECRET
openssl rand -hex 64 # → JWT_REFRESH_SECRETdocker compose up --buildAll five services start with health-check ordering (db → redis → backend → worker → frontend).
| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:8000/api/v1 |
| Swagger UI | http://localhost:8000/docs |
| Health check | http://localhost:8000/api/v1/health |
Visit http://localhost:5173 → Get Started → complete the setup wizard.
Or via API:
curl -X POST http://localhost:8000/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "admin@example.com",
"password": "YourStr0ng!Pass",
"tenant_name": "Acme SOC"
}'All settings live in backend/.env. Copy backend/.env.example for the full reference with inline docs.
Core settings
ENVIRONMENT=production
LOG_LEVEL=INFO
DATABASE_URL=postgresql://user:pass@host:5432/soc_saas
REDIS_URL=redis://host:6379/0
JWT_SECRET=<openssl rand -hex 64>
JWT_REFRESH_SECRET=<openssl rand -hex 64>
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7AI / LLM (optional — AI Copilot features)
# Free tier at console.groq.com
GROQ_API_KEY=gsk_...
# Free at aistudio.google.com/app/apikey
GEMINI_API_KEY=...Threat intelligence (optional — free tiers available)
ABUSEIPDB_API_KEY=... # abuseipdb.com — 1 000 lookups/day free
ALIENVAULT_API_KEY=... # otx.alienvault.com — free
VIRUSTOTAL_API_KEY=... # virustotal.com — 4 lookups/min free
# Offline GeoIP (recommended — no rate limit, no external calls)
# Register free at dev.maxmind.com, download GeoLite2-City.mmdb
MAXMIND_DB_PATH=/data/GeoLite2-City.mmdbEmail (optional — pick one provider)
# Brevo — recommended; no domain verification needed for dev
BREVO_API_KEY=...
BREVO_FROM_EMAIL=noreply@yourdomain.com
# Resend — alternative; requires verified domain
RESEND_API_KEY=...
RESEND_FROM_EMAIL=noreply@yourdomain.comObservability (optional)
# Sentry — leave empty in dev to disable
SENTRY_DSN=https://...@sentry.io/...
# Prometheus /metrics auth — leave empty to open-access in dev
METRICS_SECRET_TOKEN=<openssl rand -hex 32>Point your existing security tools at the ingest API. All connectors share the same pattern:
POST https://<your-backend>/api/v1/connectors/{source}/ingest
X-API-Key: <tenant-api-key>
Content-Type: application/json
Generate an API key under Dashboard → Settings → API Keys → Create Key.
| Source | {source} |
Guide |
|---|---|---|
| Wazuh | wazuh |
docs/connectors.md → Wazuh |
| Suricata IDS | suricata |
docs/connectors.md → Suricata |
| Microsoft Defender ATP | defender |
docs/connectors.md → Defender |
| Syslog (rsyslog / syslog-ng) | syslog |
docs/connectors.md → Syslog |
| Custom / Generic Webhook | generic |
docs/connectors.md → Generic |
See docs/connectors.md for copy-paste config snippets for each source.
NeuraShield is pre-wired for Railway's managed Postgres and Redis.
- Fork this repository
- In Railway, create a new project → Deploy from GitHub repo → select your fork
- Add a PostgreSQL service and a Redis service to the project
- Set all required environment variables (copy from
backend/.env.example) - Railway auto-detects the
Dockerfile, builds on every push tomain, and runsalembic upgrade headon deploy
# Build and start all services
docker compose -f docker-compose.yml up -d --build
# Apply database migrations
docker compose exec backend alembic upgrade headProduction environment variables:
ENVIRONMENT=production
ALLOWED_ORIGINS=["https://app.yourdomain.com"]
FRONTEND_URL=https://app.yourdomain.com
DATABASE_URL=postgresql://... # managed Postgres (TLS recommended)
REDIS_URL=rediss://... # managed Redis (TLS)cd backend
pip install -e ".[dev]" # install with dev extras
alembic upgrade head # apply migrations
uvicorn app.main:app --reload # start with hot reloadcd frontend
npm install
npm run dev # Vite dev server on :5173cd backend
# Unit tests — no infrastructure required
pytest tests/unit/ -v
# Integration tests — requires running Postgres + Redis
pytest tests/integration/ -v
# With coverage
pytest tests/ --cov=app --cov-report=html# Backend
ruff check app/ # lint
ruff format app/ # format
mypy app/ # type check (strict)
# Frontend
npm run lint # ESLint — 0 warnings enforced
npm run type-check # tsc --noEmit
npm run format:check # PrettierSecurity is a first-class concern in NeuraShield. The platform has completed multiple security audit passes covering:
- Authentication & session management (JWT, MFA, HMAC agent tokens)
- Multi-tenant data isolation (database, Redis, rate limits)
- Input validation & content limits at every boundary
- SSRF prevention on outbound webhook calls
- Tamper-evident audit logging with SHA-256 hash chaining
- Dependency vulnerability management (PyJWT migration, npm audit)
Found a vulnerability? Please do not open a public issue.
Read our Security Policy and report privately.
Contributions are welcome — bug fixes, new connectors, detection rules, UI improvements.
Please read CONTRIBUTING.md before opening a pull request.
Quick guide:
- Fork the repo and create a branch from
main - Make your changes (include tests where relevant)
- Ensure
ruff,mypy,eslint, andtscall pass - Open a PR — the CI pipeline runs automatically
MIT © 2025 NeuraShield Contributors