🛡️ SPIR

Security Posture & Incident Response Platform

The all-in-one cybersecurity command center for German SMEs

     

---

SPIR monitors your infrastructure 24/7, detects threats with AI-powered rules, automates incident response through pre-built playbooks, and tracks compliance against the frameworks that matter in Germany and the EU — all from a single platform.

✨ Key Features

	Feature	Description
🛡️	Security Score	Real-time health score (0–100) across 5 weighted dimensions with letter grades
📡	Log Collection	Syslog (UDP/TCP), iptables/pfSense/Fortinet/Sophos, Windows Event Log, AWS CloudTrail, Azure Activity Log, endpoint agents
🚨	Smart Alerts	16+ SIGMA-compatible detection rules, sliding-window correlation, ML anomaly detection (Isolation Forest), false-positive filter with analyst feedback loop
🔥	Incident Response	6 pre-built playbooks (ransomware, phishing, data breach, DDoS, insider threat, brute force) with automated account actions
✅	Compliance Tracker	NIS2, BSI IT-Grundschutz, ISO 27001, GDPR — gap analysis, effort estimation, text/JSON/HTML reports
👤	Identity & Access	MFA coverage analysis, dormant account detection, over-privilege review, service account audit
🔗	Integrations	VAPT scanner import, Jira ticket creation, SIEM export (CEF/LEEF), Slack, Teams, email, webhooks

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose (optional, for full-stack deployment)

1. Clone & Install

git clone https://github.com/aryanajit24/SPIR.git
cd SPIR
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. Configure

cp .env.example .env
# Edit .env with your database, SMTP, Slack/Teams webhooks, etc.

3. Run the Interactive Demo

No external services needed — everything runs in-memory:

python scripts/demo.py

This walks through log collection, alert detection, playbook execution, compliance tracking, identity auditing, and security score calculation with rich terminal output.

4. Start the API Server

python -m api.app

• API: http://localhost:8000
• Swagger Docs: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

5. Full Stack with Docker Compose

docker-compose up -d

Service	Port	Description
spir-api	8000	FastAPI backend
spir-dashboard	3000	React frontend
postgres	5432	PostgreSQL 16 database
opensearch	9200	OpenSearch 2.12 log storage
redis	6379	Cache & pub/sub

6. Run Tests

pytest tests/ -v                          # All 124+ tests
pytest tests/test_alert_engine.py -v      # Specific module
pytest tests/ --cov=. --cov-report=html   # With coverage report

---

📁 Project Structure

SPIR/
├── api/                    # FastAPI REST API
│   ├── app.py              #   Application entry point & lifespan
│   ├── middleware/          #   API key authentication
│   └── routes/             #   dashboard, alerts, incidents, compliance, identity, vapt, settings
├── alert_engine/           # Threat detection engine
│   ├── engine.py           #   Core rule evaluator with 12 operators & correlation
│   ├── models.py           #   DetectionRule & Alert dataclasses
│   ├── rules/              #   16 pre-built rules + SIGMA format loader
│   ├── ml/                 #   Isolation Forest anomaly detector, FP filter
│   └── dispatchers/        #   Email (HTML), Slack, Teams, generic webhook
├── collector/              # Log collectors
│   ├── collector_manager.py#   Event queue (10K buffer) & handler dispatch
│   ├── syslog_collector.py #   RFC 3164 / 5424 UDP listener
│   ├── firewall_collector.py#  iptables, pfSense, Fortinet, Sophos parser
│   ├── windows_event_collector.py # WEF polling (25+ Event IDs)
│   ├── cloud_collector.py  #   AWS CloudTrail & Azure Activity Log
│   └── endpoint_collector.py#  HTTP receiver for endpoint agents
├── incident_response/      # Automated incident response
│   ├── engine.py           #   Playbook executor & ticket manager
│   ├── actions/            #   disable_account, force_password_reset, revoke_sessions, etc.
│   └── playbooks/          #   ransomware, phishing, data_breach, ddos, insider_threat, brute_force
├── compliance/             # Regulatory compliance tracking
│   ├── tracker.py          #   Framework registry, scoring, reporting
│   ├── gap_analyzer.py     #   Gap analysis & effort estimation
│   ├── report_generator.py #   Text / JSON / HTML report output
│   └── frameworks/         #   NIS2, BSI Grundschutz, ISO 27001, GDPR definitions
├── identity/               # Identity & access management auditing
│   ├── auditor.py          #   Main audit orchestrator
│   ├── mfa_checker.py      #   MFA coverage & risk scoring
│   ├── dormant_detector.py #   30/60/90-day inactivity detection
│   └── privilege_reviewer.py#  Over-privileged & service account review
├── security_score/         # Security health score (0-100)
│   ├── calculator.py       #   Weighted 5-dimension aggregator
│   └── dimensions.py       #   Vuln mgmt, access control, monitoring, compliance, IR readiness
├── integrations/           # External tool connectors
│   ├── vapt_connector.py   #   VAPT scan import & remediation tracking
│   ├── jira_connector.py   #   Auto-create Jira tickets from alerts
│   └── siem_exporter.py    #   CEF & LEEF format export
├── dashboard/              # React 18 frontend (dark theme)
├── config/                 # Settings (pydantic-settings) & logging
├── scripts/                # demo.py, generate_test_data.py, setup.sh
├── tests/                  # 124+ pytest tests across all modules
├── docs/                   # 8 detailed guides (setup, API, architecture, compliance, …)
├── docker-compose.yml      # Full-stack orchestration (5 services)
├── Dockerfile              # Python 3.11 production image
└── requirements.txt        # 30+ pinned dependencies

---

🔧 Configuration

All settings are loaded from environment variables or a .env file via pydantic-settings:

Variable	Default	Description
SPIR_ENV	development	development / staging / production
SPIR_API_KEY	change-me	API authentication key (X-API-Key header)
SPIR_SECRET_KEY	change-me	Application secret key
POSTGRES_HOST	localhost	PostgreSQL host
OPENSEARCH_HOST	localhost	OpenSearch host
REDIS_HOST	localhost	Redis host
SMTP_HOST / SMTP_PORT	localhost / 587	Email alert delivery
SLACK_WEBHOOK_URL	—	Slack incoming webhook
TEAMS_WEBHOOK_URL	—	Microsoft Teams webhook
VAPT_API_URL	http://localhost:8001	VAPT scanner API
AWS_REGION	eu-central-1	AWS region for CloudTrail

See .env.example for the full list including LDAP, Jira, and Azure settings.

---

📊 API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/dashboard	Consolidated security overview
GET	/api/alerts	List alerts (filter by status/severity)
PUT	/api/alerts/{id}/acknowledge	Acknowledge an alert
PUT	/api/alerts/{id}/resolve	Resolve an alert
GET	/api/incidents	List incident tickets
POST	/api/incidents/trigger	Trigger a playbook
GET	/api/compliance/frameworks	All compliance frameworks with scores
GET	/api/compliance/frameworks/{id}/gaps	Gap analysis for a framework
GET	/api/identity	Identity & access audit report
POST	/api/vapt/import	Import VAPT scan results
GET	/api/collectors/status	Collector health status
GET	/api/settings	Platform configuration

Interactive API documentation is available at /api/docs (Swagger UI) and /api/redoc.

---

🛡️ Security Score

The platform calculates a real-time security health score (0–100) from 5 weighted dimensions:

Overall Score = Σ (dimension_score × weight)

┌──────────────────────────────┬────────┬─────────────────────────────────────┐
│ Dimension                    │ Weight │ What it measures                    │
├──────────────────────────────┼────────┼─────────────────────────────────────┤
│ Vulnerability Management     │ 25%    │ Open vulns, patch velocity, scan    │
│                              │        │ freshness                           │
│ Access Control               │ 25%    │ MFA coverage, dormant accounts,     │
│                              │        │ privilege hygiene                   │
│ Monitoring & Detection       │ 20%    │ Collector coverage, alert response  │
│                              │        │ time, event flow                    │
│ Compliance                   │ 20%    │ NIS2/BSI/ISO/GDPR completion %     │
│ Incident Readiness           │ 10%    │ Playbook coverage, drill recency   │
└──────────────────────────────┴────────┴─────────────────────────────────────┘

Grades:  🟢 A (81-100)  ·  🟡 B (61-80)  ·  🟠 C (41-60)  ·  🔴 D/F (0-40)

---

📋 Compliance Frameworks

Framework	Standard	Coverage
NIS2	EU Directive 2022/2555	All 10 Article 21(2) risk management measures
BSI IT-Grundschutz	German federal standard	10 key Bausteine (DER.1, DER.2.1, CON.3, …)
ISO/IEC 27001:2022	International ISMS	18 Annex A controls (5.x – 8.x)
GDPR Article 32	EU data protection	10 technical & organisational measures

Each framework includes: control tracking, gap analysis, effort estimation (days/weeks), quick-win identification, and exportable reports (text/JSON/HTML).

---

🚨 Detection Rules

16 pre-built rules covering key MITRE ATT&CK tactics:

Rule	Tactic	Technique
SSH Brute Force	Credential Access	T1110.001
Windows Failed Login Burst	Credential Access	T1110
Ransomware Indicators	Impact	T1486
Port Scan	Discovery	T1046
Data Exfiltration (100MB+)	Exfiltration	T1041
Off-Hours Login	Initial Access	T1078
Admin Account Created	Persistence	T1136
Malware (mimikatz, cobalt strike)	Execution	T1059
DNS Tunneling	Command & Control	T1071.004
Privilege Escalation (sudo/su)	Privilege Escalation	T1548.003
VAPT Unpatched Critical	Initial Access	T1190
Firewall Rule Modification	Defense Evasion	T1562.004
Malicious IP Connection	Command & Control	T1571
Audit Log Cleared	Defense Evasion	T1070.001
AWS Root Console Login	Privilege Escalation	T1078.004
Insider Threat — Bulk Download	Collection	T1213

Additional rules can be loaded from SIGMA YAML files.

---

📚 Documentation

Guide	Description
Setup Guide	Step-by-step installation for dev and production
Architecture	System design, data flow, component interactions
API Reference	Full endpoint documentation with curl examples
User Guide	How to use every feature in the platform
Testing Guide	Running unit tests, integration tests, and the demo
Deployment	Production deployment guide (Hetzner Cloud)
Compliance Guide	Preparing for NIS2/BSI/ISO audits with SPIR

---

🏗️ Tech Stack

Layer	Technology
Backend	Python 3.11, FastAPI, Pydantic v2, SQLAlchemy 2.0, Celery
Frontend	React 18, Recharts
Database	PostgreSQL 16
Search / Logs	OpenSearch 2.12
Cache	Redis 7
ML	scikit-learn (Isolation Forest)
Container	Docker, Docker Compose
Auth	API key (X-API-Key) + JWT (extensible)

---

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create your feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m 'Add your feature'
4. Push to the branch: git push origin feature/your-feature
5. Open a Pull Request

Please make sure all tests pass (pytest tests/ -v) before submitting.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

SPIR — Schützen Sie Ihr Unternehmen. Heute.

Protect your business. Today.