🔭 Sentinel

AI-Powered Security Operations Center

Your tireless SOC analyst — detecting threats, correlating events, responding automatically.

---

Why Sentinel?

Traditional SIEMs are expensive, complex, and require a team to operate. Sentinel combines statistical anomaly detection, Sigma-compatible rule matching, threat intelligence feeds, and LLM-powered analysis into a single self-hosted platform that works out of the box.

Think: Splunk + CrowdStrike + an AI analyst — self-hosted, open-source, and free.

---

✨ Features

• 📥 Real-time Log Ingestion — Syslog (UDP/TCP), file watching, network capture, API collectors
• 🧠 AI-Powered Analysis — LLM interprets suspicious patterns and explains threats in plain language
• 📈 Anomaly Detection — Statistical (z-score, IQR), behavioral baselines, brute force, port scan, exfiltration, privilege escalation detection
• 📜 Rule Engine — YAML-based Sigma-compatible rules with 20+ built-in detections
• 🌐 Threat Intelligence — AbuseIPDB, AlienVault OTX feeds, IOC checking, dark web monitoring
• ⚡ Automated Response — IP blocking, process killing, host isolation, webhook/WhatsApp alerts, incident ticketing
• 🔗 Event Correlation — Links related events across configurable time windows
• 🎯 Live Dashboard — Dark-themed real-time UI with event stream, threat gauge, geographic attack map, alert timeline
• 🔌 REST API — Full Flask API for integration with existing tooling

---

🚀 Quick Start

git clone https://github.com/juliosuas/sentinel.git && cd sentinel
cp .env.example .env           # Add your API keys
docker-compose up -d           # → http://localhost:8080

Local install: pip install -r requirements.txt && make run

---

📸 Screenshots

Screenshots coming soon — live dashboard, attack map, alert timeline, incident response

---

🏗️ Architecture

               ┌──────────────────┐
               │    Collectors     │
               │ syslog │ file    │
               │ network │ api    │
               └────────┬─────────┘
                        │
                        ▼
               ┌──────────────────┐
               │  SentinelEngine  │
               │  (core/engine)   │
               └────────┬─────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
   ┌───────────┐ ┌───────────┐ ┌───────────┐
   │ Anomaly   │ │   Rules   │ │ Correlator│
   │ Detector  │ │  (Sigma)  │ │ (linking) │
   └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
          └─────────────┼─────────────┘
                        ▼
               ┌──────────────────┐
               │   AI Analyzer    │
               │  (LLM analysis)  │
               └────────┬─────────┘
                        ▼
               ┌──────────────────┐
               │    Responder     │
               │ block │ alert    │
               │ isolate │ ticket │
               └────────┬─────────┘
                        ▼
               ┌──────────────────┐
               │  Flask API +     │
               │  Live Dashboard  │
               └──────────────────┘

🔍 Built-in Detection Rules

Sentinel ships with 20+ detection rules including:

Rule	Description	MITRE ATT&CK
SSH Brute Force	Multiple failed SSH logins from same IP	T1110
Login Spray	Failed logins across multiple accounts	T1110.003
Privilege Escalation	sudo/su abuse, unauthorized root access	T1548
Port Scan	Sequential port probing detection	T1046
Data Exfiltration	Large outbound data transfers	T1041
Web Shell	Known web shell pattern detection	T1505.003
Crontab Modification	Unauthorized scheduled task changes	T1053
Suspicious DNS	DNS queries to known malicious domains	T1071.004
New User Creation	Unauthorized user account creation	T1136
Process Injection	Suspicious process execution chains	T1055

🔌 API Endpoints

Method	Endpoint	Description
GET	/api/events	List events (with filters)
GET	/api/alerts	List alerts
GET	/api/incidents	List incidents
POST	/api/incidents	Create incident
PATCH	/api/incidents/<id>	Update incident
GET	/api/stats	Dashboard statistics
GET	/api/threats	Threat intel data
POST	/api/respond	Trigger response action

⚙️ Configuration

Copy .env.example to .env and configure:

Variable	Description
ANTHROPIC_API_KEY	AI-powered analysis
ABUSEIPDB_API_KEY	IP reputation lookups
OTX_API_KEY	AlienVault OTX threat intel
WEBHOOK_URL	Alert webhook URL
WHATSAPP_API_*	WhatsApp alerting
DASHBOARD_PORT	Dashboard port (default: 8080)

🏁 Compared to Alternatives

Feature	Sentinel	Splunk	Wazuh	OSSEC
AI-powered analysis	✅ LLM	❌	❌	❌
Self-hosted	✅	✅	✅	✅
Cost	✅ Free/OSS	❌ $$$$$	✅ Free	✅ Free
Sigma rules	✅	✅ Plugin	❌	❌
Auto-response	✅	✅ SOAR $$	⚠️ Basic	⚠️ Basic
Setup time	~5 min	Days	Hours	Hours
Threat intel feeds	✅ Built-in	✅ Add-on	✅	❌

✅ AI Analysis Verification Patterns

Sentinel's AI-powered analysis includes built-in verification to ensure detection accuracy and reduce false positives.

Detection Verification Matrix

Detection Type	Verification Method	Success Criteria
Brute Force	Threshold confirmation	≥5 failed attempts from same IP within 5 minutes
Port Scan	Sequential port analysis	≥10 unique ports probed from single source within 60 seconds
Data Exfiltration	Volume anomaly check	Outbound transfer exceeds 3σ from baseline for the source
Privilege Escalation	Context chain validation	Process ancestry shows unprivileged → privileged transition
Web Shell	Signature + behavior match	File hash OR behavioral pattern (POST → command execution)
Lateral Movement	Multi-host correlation	Same credentials used across ≥2 hosts within correlation window

AI Analyzer Confidence Scoring

Every AI-generated analysis includes a confidence score and evidence chain:

Confidence Level	Score Range	AI Action	Human Action Required
🔴 High	85-100%	Auto-respond (block/isolate)	Post-incident review
🟡 Medium	50-84%	Alert with analysis	Review and decide
🟢 Low	20-49%	Log with context	Periodic batch review
⚪ Informational	0-19%	Enrich event metadata	No action needed

Verification Checklist for New Detection Rules

When adding or tuning detection rules, verify:

• Rule triggers on known-bad test data (true positive validation)
• Rule does NOT trigger on known-good traffic (false positive check)
• MITRE ATT&CK technique mapping is accurate
• Alert severity matches potential business impact
• Correlation window is appropriate for the attack type
• AI analysis provides actionable context (not just "suspicious activity detected")
• Automated response action is proportional to confidence level

---

🖥️ Platform Compatibility

Platform	Architecture	Status	Notes
Ubuntu 22.04+	x86_64, ARM64	✅ Full	Recommended for production
Debian 12+	x86_64, ARM64	✅ Full	Stable and tested
CentOS Stream 9	x86_64	✅ Full	Enterprise environments
Rocky Linux 9	x86_64	✅ Full	RHEL-compatible
macOS 13+	ARM64, x86_64	⚠️ Partial	Development/testing only — limited syslog support
Docker	Any	✅ Full	docker-compose up -d — production ready
Kubernetes	Any	✅ Full	Helm chart available
Raspberry Pi OS	ARM64	⚠️ Partial	Suitable for small network monitoring
Windows Server	x86_64 (WSL2)	⚠️ Partial	Use Docker or WSL2

Integration Compatibility

Integration	Protocol	Status	Notes
Syslog (RFC 5424)	UDP/TCP	✅ Full	Primary log ingestion
Syslog (RFC 3164)	UDP/TCP	✅ Full	Legacy format supported
File watching	inotify/kqueue	✅ Full	Log file tail monitoring
AbuseIPDB	REST API	✅ Full	IP reputation lookups
AlienVault OTX	REST API	✅ Full	Threat intelligence feeds
Slack	Webhook	✅ Full	Alert notifications
WhatsApp	API	✅ Full	Alert notifications
Generic Webhook	HTTP POST	✅ Full	Custom integrations
Sigma Rules	YAML	✅ Full	Detection rule format
MITRE ATT&CK	Framework	✅ Full	Technique mapping

LLM Provider Compatibility

Provider	Status	Notes
Anthropic Claude	✅ Recommended	Best analysis quality
OpenAI GPT-4	✅ Supported	Good analysis quality
Local LLMs (Ollama)	⚠️ Experimental	Reduced analysis depth

---

🛠️ Development

make install        # Install dependencies
make test           # Run test suite
make run            # Start full platform
make run-syslog     # Start with syslog collector
make run-filewatcher # Start with file watcher

🤝 Contributing

Contributions are welcome! Here's how to get started:

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

Check the issues tab for areas where help is needed — especially new detection rules and collector plugins.

⚖️ Legal Disclaimer

Sentinel is designed for authorized security monitoring of systems you own or have explicit permission to monitor. Unauthorized interception or monitoring of network traffic may violate local, state, and federal laws. The authors assume no liability for misuse. Ensure compliance with all applicable laws and organizational policies before deployment.

📄 License

MIT

---

Sentinel — Because threats don't sleep, and neither should your SOC. 🌙

---

🌱 Also check out

AI Garden — A living world built exclusively by AI agents. Watch it grow.

---

🧠 AI Analysis Verification

Sentinel's AI doesn't just detect — it proves its work. Every alert includes a confidence score, correlation evidence, and plain-language explanation reviewed against statistical baselines.

See docs/ai-analysis-verification.md for the full verification methodology.

Metric	Target	Method
False Positive Rate	<5%	Monthly 100-alert audit
Detection Coverage	>90% MITRE ATT&CK	Atomic red team testing
Alert-to-Action	<15 min (critical)	Automated SLA tracking
AI Explanation Accuracy	>95%	Analyst feedback loop