|
|
--- |
|
|
title: Security Incident Analyzer |
|
|
emoji: 🛡️ |
|
|
colorFrom: blue |
|
|
colorTo: purple |
|
|
sdk: gradio |
|
|
sdk_version: 6.2.0 |
|
|
app_file: src/app.py |
|
|
pinned: false |
|
|
license: mit |
|
|
--- |
|
|
|
|
|
# Security Incident Analyzer |
|
|
|
|
|
An LLM-powered security log and incident analysis tool with a production-ready web interface. |
|
|
|
|
|
## 🎯 What It Does |
|
|
|
|
|
Paste security logs or alerts → Get immediate AI analysis explaining: |
|
|
- **What happened** — Clear incident summary |
|
|
- **Severity level** — CRITICAL, HIGH, MEDIUM, LOW, or INFO |
|
|
- **Suggested remediation** — Actionable next steps |
|
|
- **Key indicators** — IOCs and anomalies detected |
|
|
|
|
|
No training required. Director-level insights in seconds. |
|
|
|
|
|
## 🚀 Try It Now |
|
|
|
|
|
**Live Demo:** https://huggingface.co/spaces/debashis2007/SecurityIncidentAnalyzer |
|
|
|
|
|
Or run locally (5 minutes): |
|
|
|
|
|
```bash |
|
|
git clone https://github.com/Debashis2007/SecurityIncidentAnalyzer.git |
|
|
cd SecurityIncidentAnalyzer |
|
|
pip install -r requirements.txt |
|
|
cp .env.example .env |
|
|
python src/app.py # Visit http://localhost:7860 |
|
|
``` |
|
|
|
|
|
## 🏗️ Architecture |
|
|
|
|
|
``` |
|
|
src/ |
|
|
├── app.py # Gradio web UI entry point |
|
|
├── analyzer/ |
|
|
│ ├── security.py # IncidentAnalyzer: core analysis logic |
|
|
│ └── models.py # RiskLevel enum, SecurityAnalysis dataclass |
|
|
├── llm/ |
|
|
│ ├── provider.py # LLM provider abstraction |
|
|
│ │ # - OpenAIProvider (gpt-4-turbo) |
|
|
│ │ # - LocalLLMProvider (Ollama) |
|
|
│ │ # - MockLLMProvider (demo) |
|
|
│ └── prompts.py # Security analysis prompt templates |
|
|
└── utils/ |
|
|
├── config.py # Environment-driven configuration |
|
|
└── logger.py # Structured logging |
|
|
``` |
|
|
|
|
|
## ⚙️ Configuration |
|
|
|
|
|
### Option 1: Mock LLM (Default - No API Key Required) |
|
|
|
|
|
Perfect for demos and testing: |
|
|
|
|
|
```bash |
|
|
# No setup needed! Just run: |
|
|
python src/app.py |
|
|
``` |
|
|
|
|
|
The mock provider returns realistic-looking security analysis without any API calls. |
|
|
|
|
|
### Option 2: OpenAI GPT-4 Turbo |
|
|
|
|
|
For production analysis with real LLM intelligence: |
|
|
|
|
|
1. **Get an API key:** |
|
|
- Sign up: https://platform.openai.com |
|
|
- Create key: https://platform.openai.com/account/api-keys |
|
|
- Keep it safe! |
|
|
|
|
|
2. **Configure locally:** |
|
|
```bash |
|
|
cp .env.example .env |
|
|
# Edit .env: |
|
|
# LLM_PROVIDER=openai |
|
|
# OPENAI_API_KEY=sk-proj-YOUR_KEY_HERE |
|
|
python src/app.py |
|
|
``` |
|
|
|
|
|
3. **On Hugging Face Spaces:** |
|
|
- Settings → Secrets → Add: |
|
|
- `OPENAI_API_KEY` = your key |
|
|
- `LLM_PROVIDER` = openai |
|
|
|
|
|
### Option 3: Local LLM (Ollama) |
|
|
|
|
|
Run a local model without cloud API: |
|
|
|
|
|
1. **Install Ollama:** https://ollama.ai |
|
|
2. **Pull a model:** |
|
|
```bash |
|
|
ollama pull mistral:7b |
|
|
ollama serve # Keep running in another terminal |
|
|
``` |
|
|
|
|
|
3. **Configure:** |
|
|
```bash |
|
|
# .env |
|
|
LLM_PROVIDER=local |
|
|
LLM_MODEL=mistral:7b |
|
|
``` |
|
|
|
|
|
## 📋 Environment Variables |
|
|
|
|
|
Create a `.env` file (see `.env.example`): |
|
|
|
|
|
```bash |
|
|
# Provider selection (required) |
|
|
LLM_PROVIDER=mock # mock, openai, or local |
|
|
|
|
|
# OpenAI (only needed if LLM_PROVIDER=openai) |
|
|
OPENAI_API_KEY=sk-proj-... |
|
|
|
|
|
# Model override (optional, uses defaults if not set) |
|
|
LLM_MODEL=gpt-4-turbo |
|
|
|
|
|
# Debugging |
|
|
DEBUG=false |
|
|
``` |
|
|
|
|
|
**⚠️ Important:** `.env` is in `.gitignore` — secrets never get committed. |
|
|
|
|
|
### Provider Defaults |
|
|
|
|
|
| Provider | Default Model | Notes | |
|
|
|----------|---------------|-------| |
|
|
| `mock` | mock-analyzer-v1 | No API required, deterministic | |
|
|
| `openai` | gpt-4-turbo | Requires OPENAI_API_KEY | |
|
|
| `local` | mistral:7b | Requires Ollama running on localhost:11434 | |
|
|
|
|
|
## 🧪 Testing |
|
|
|
|
|
```bash |
|
|
# Run all tests |
|
|
pytest tests/ -v |
|
|
|
|
|
# With coverage report |
|
|
pytest tests/ --cov=src |
|
|
|
|
|
# Test specific module |
|
|
pytest tests/test_analyzer.py -v |
|
|
``` |
|
|
|
|
|
**Test Results:** 11/11 tests passing ✅ |
|
|
|
|
|
## 📝 Example Incidents to Test |
|
|
|
|
|
### 1. Failed Authentication |
|
|
``` |
|
|
2025-12-21 14:32:15 AUTH_FAILURE - Failed login attempt from 192.168.1.100 |
|
|
2025-12-21 14:32:18 AUTH_FAILURE - Failed login attempt from 192.168.1.100 |
|
|
2025-12-21 14:32:21 AUTH_FAILURE - Failed login attempt from 192.168.1.100 |
|
|
User: admin@company.com | Attempts: 15 in 2 minutes |
|
|
``` |
|
|
|
|
|
### 2. Ransomware Detection |
|
|
``` |
|
|
CRITICAL ALERT - File encryption detected |
|
|
Directory: /mnt/backup/production |
|
|
Files Encrypted: 500+ |
|
|
Process: unknown.exe (SYSTEM privilege) |
|
|
Time: 2025-12-21 16:20:15 UTC |
|
|
Status: ACTIVE THREAT |
|
|
``` |
|
|
|
|
|
### 3. SQL Injection Attempt |
|
|
``` |
|
|
Web Application Firewall Alert |
|
|
Rule: SQL Injection Pattern |
|
|
URL: /api/users?id=1' OR '1'='1 |
|
|
Source IP: 203.0.113.45 |
|
|
Status: BLOCKED |
|
|
Payload: ' OR '1'='1 |
|
|
``` |
|
|
|
|
|
### 4. Privilege Escalation |
|
|
``` |
|
|
Security Event: Privilege Escalation Detected |
|
|
User: john.smith@company.com |
|
|
Action: sudo su - (unauthorized) |
|
|
Target System: prod-db-server-02 |
|
|
Time: 2025-12-21 17:02:45 |
|
|
Status: No approval ticket found |
|
|
``` |
|
|
|
|
|
### 5. Suspicious Outbound Traffic |
|
|
``` |
|
|
ALERT: Unusual outbound traffic detected |
|
|
Destination: 10.0.0.1:4444 |
|
|
Source: internal-server-03 |
|
|
Data Volume: 2.3 GB in 45 minutes |
|
|
Status: ONGOING |
|
|
``` |
|
|
|
|
|
## 🚀 Deployment |
|
|
|
|
|
### Hugging Face Spaces (Recommended) |
|
|
|
|
|
Your app is live at: |
|
|
👉 https://huggingface.co/spaces/debashis2007/SecurityIncidentAnalyzer |
|
|
|
|
|
**How it works:** |
|
|
- Detects `spaces.yaml` → Gradio configuration |
|
|
- Installs `requirements.txt` → All dependencies |
|
|
- Runs `src/app.py` → Your app starts automatically |
|
|
|
|
|
**To add OpenAI:** |
|
|
1. Settings → Secrets |
|
|
2. Add `OPENAI_API_KEY=sk-proj-YOUR_KEY` |
|
|
3. Change `.env`: `LLM_PROVIDER=openai` |
|
|
4. Push to git (auto-redeploys) |
|
|
|
|
|
### Docker (Local or Cloud) |
|
|
|
|
|
```dockerfile |
|
|
FROM python:3.9-slim |
|
|
WORKDIR /app |
|
|
COPY requirements.txt . |
|
|
RUN pip install -r requirements.txt |
|
|
COPY . . |
|
|
ENV LLM_PROVIDER=mock |
|
|
CMD python src/app.py |
|
|
``` |
|
|
|
|
|
```bash |
|
|
docker build -t security-analyzer . |
|
|
docker run -p 7860:7860 security-analyzer |
|
|
``` |
|
|
|
|
|
### Traditional Server |
|
|
|
|
|
```bash |
|
|
# Production with gunicorn |
|
|
pip install gunicorn |
|
|
gunicorn -w 4 -b 0.0.0.0:7860 src.app:demo |
|
|
``` |
|
|
|
|
|
## 🔧 For AI Developers |
|
|
|
|
|
See `.github/copilot-instructions.md` for comprehensive agent onboarding: |
|
|
- **Architecture patterns** — Provider abstraction, config management, regex parsing |
|
|
- **Data flows** — How logs become analyzed incidents |
|
|
- **Extension points** — Add new LLM providers, customize analysis |
|
|
- **Testing strategy** — Unit, integration, E2E with mocks |
|
|
- **Troubleshooting** — Common issues and solutions |
|
|
|
|
|
## 📦 Requirements |
|
|
|
|
|
- **Python:** 3.9+ |
|
|
- **Core:** Gradio, Pydantic, httpx, python-dotenv |
|
|
- **Optional:** OpenAI SDK (for OpenAI provider only) |
|
|
|
|
|
See `requirements.txt` for exact versions. |
|
|
|
|
|
## 🧠 Key Design Decisions |
|
|
|
|
|
1. **Provider Abstraction** — LLM logic decoupled from analysis |
|
|
2. **Environment Config** — All settings via env vars, no hardcoding |
|
|
3. **Regex Parsing** — Flexible response extraction (works with any LLM format) |
|
|
4. **Async/Await** — Non-blocking I/O for responsive UI |
|
|
5. **Structured Types** — Pydantic models for validation and safety |
|
|
|
|
|
## ⚖️ License |
|
|
|
|
|
MIT — Use freely, modify, distribute. |
|
|
|
|
|
## 🤝 Contributing |
|
|
|
|
|
```bash |
|
|
# Fork, create a branch, make changes |
|
|
git checkout -b feature/my-improvement |
|
|
pytest tests/ -v # Ensure tests pass |
|
|
git push origin feature/my-improvement |
|
|
# Create a Pull Request |
|
|
``` |
|
|
|
|
|
## ❓ FAQ |
|
|
|
|
|
**Q: Can I use this without an API key?** |
|
|
A: Yes! The default `mock` provider needs no API key and is perfect for demos. |
|
|
|
|
|
**Q: How accurate is the analysis?** |
|
|
A: Depends on the LLM. Mock is deterministic for testing. OpenAI (GPT-4) provides production-grade analysis. |
|
|
|
|
|
**Q: Can I run this offline?** |
|
|
A: Yes! Use the `local` provider with Ollama on your own hardware. |
|
|
|
|
|
**Q: Is my data safe?** |
|
|
A: - **Mock provider:** No external calls, stays local |
|
|
- **Local provider:** Stays on your machine |
|
|
- **OpenAI provider:** Subject to OpenAI's privacy policy |
|
|
|
|
|
**Q: How do I report bugs?** |
|
|
A: Open an issue on GitHub with reproduction steps. |
|
|
|
|
|
--- |
|
|
|
|
|
**Questions?** Check `.github/copilot-instructions.md` or create an issue! |
|
|
|
|
|
## Contributing |
|
|
|
|
|
Pull requests welcome! Please ensure tests pass: |
|
|
```bash |
|
|
pytest tests/ -v |
|
|
``` |
