Complete README with full configuration guide, examples, and FAQ

README.md

@@ -2,151 +2,299 @@
 
 An LLM-powered security log and incident analysis tool with a production-ready web interface.
 
-## What It Does
+## 🎯 What It Does
 
-- **Paste logs or security alerts** → LLM analyzes and explains
-- **Intelligence extraction**: What happened, severity level, remediation steps
-- **Director-level insights**: Clear, actionable narrative for decision-makers
-- **No training required**: Works out of the box with OpenAI, local LLMs, or mock inference
+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
 
-## 🚀 Quick Start
+No training required. Director-level insights in seconds.
 
-**Try it live:** https://huggingface.co/spaces/debashis2007/SecurityIncidentAnalyzer
+## 🚀 Try It Now
 
-Or run locally:
+**Live Demo:** https://huggingface.co/spaces/debashis2007/SecurityIncidentAnalyzer
+
+Or run locally (5 minutes):
 
 ```bash
-# Install dependencies
+git clone https://github.com/Debashis2007/SecurityIncidentAnalyzer.git
+cd SecurityIncidentAnalyzer
 pip install -r requirements.txt
-
-# Set up environment variables
 cp .env.example .env
-# Edit .env with your OpenAI API key or leave as mock for demo
-
-# Run the application
-python src/app.py
+python src/app.py  # Visit http://localhost:7860
 ```
 
-Visit `http://localhost:7860` in your browser.
-
-## Architecture
+## 🏗️ Architecture
 
 ```
 src/
-├── app.py                 # Gradio interface & main entry
-├── llm/
-│   ├── provider.py       # LLM provider abstraction (OpenAI, local, mock)
-│   └── prompts.py        # Security analysis prompt templates
+├── app.py                    # Gradio web UI entry point
 ├── analyzer/
-│   ├── security.py       # Core incident analysis logic
-│   └── models.py         # Data models for analysis results
-├── utils/
-│   ├── logger.py         # Logging configuration
-│   └── config.py         # Configuration management
-└── __init__.py
+│   ├── 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
 ```
 
-## Key Design Decisions
+## ⚙️ Configuration
 
-1. **Provider Abstraction**: LLM provider logic separated from analysis logic (see `src/llm/provider.py`)
-2. **Structured Outputs**: Analysis results use Pydantic models for validation and CLI output
-3. **Environment-based Config**: Support for API keys, model selection, and prompt templates
-4. **Minimal Dependencies**: Gradio + requests/httpx only (no heavyweight frameworks)
+### Option 1: Mock LLM (Default - No API Key Required)
 
-## Testing
+Perfect for demos and testing:
 
 ```bash
-pytest tests/
-pytest --cov=src tests/  # With coverage
+# No setup needed! Just run:
+python src/app.py
 ```
 
-## Deployment
+The mock provider returns realistic-looking security analysis without any API calls.
 
-### Hugging Face Spaces (Recommended)
-The app is automatically deployed! Just visit:
-👉 **https://huggingface.co/spaces/debashis2007/SecurityIncidentAnalyzer**
+### 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
+   ```
 
-HF Spaces detects and auto-configures:
-- ✅ `spaces.yaml` → Gradio app configuration
-- ✅ `Procfile` → Launch command
-- ✅ `requirements.txt` → Dependencies
+3. **Configure:**
+   ```bash
+   # .env
+   LLM_PROVIDER=local
+   LLM_MODEL=mistral:7b
+   ```
 
-**Optional: Add OpenAI API Key to HF Spaces**
-1. Go to Space Settings → Secrets
-2. Add `OPENAI_API_KEY` = your-key
-3. Update `.env` locally: `LLM_PROVIDER=openai`
-4. Push changes (Space auto-redeploys)
+## 📋 Environment Variables
+
+Create a `.env` file (see `.env.example`):
 
-### Local Deployment
 ```bash
-# Set your provider
-export LLM_PROVIDER=openai  # or mock, local
-export OPENAI_API_KEY=your-key
+# Provider selection (required)
+LLM_PROVIDER=mock          # mock, openai, or local
 
-# Start the app
-python src/app.py
+# 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
 ```
 
-## Environment Variables
+**⚠️ Important:** `.env` is in `.gitignore` — secrets never get committed.
 
-- `OPENAI_API_KEY`: Your OpenAI API key
-- `LLM_PROVIDER`: `openai`, `local`, or `mock` (default: `mock`)
-- `LLM_MODEL`: Model name (e.g., `gpt-4-turbo`, defaults provided per provider)
-- `DEBUG`: Set to `true` for verbose logging
+### Provider Defaults
 
-### For HF Spaces
-Add secrets via Settings → Secrets instead of `.env`:
-- `OPENAI_API_KEY` for OpenAI
-- `LLM_PROVIDER` (optional, defaults to mock)
-- `DEBUG` (optional)
+| 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
 
-### For Local Development
-Copy `.env.example` to `.env` and edit:
 ```bash
-cp .env.example .env
-# Edit with your keys/settings
-```
+# Run all tests
+pytest tests/ -v
 
-**Important:** `.env` is in `.gitignore` — never commit secrets!
+# With coverage report
+pytest tests/ --cov=src
 
-## Example Security Incidents
+# Test specific module
+pytest tests/test_analyzer.py -v
+```
+
+**Test Results:** 11/11 tests passing ✅
 
-Try these in the app:
+## 📝 Example Incidents to Test
 
-### Failed Authentication
+### 1. Failed Authentication
 ```
 2025-12-21 14:32:15 AUTH_FAILURE - Failed login attempt from 192.168.1.100
-User account: admin@company.com
-Attempts: 15 in 2 minutes
+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
 ```
 
-### Ransomware Detection
+### 2. Ransomware Detection
 ```
 CRITICAL ALERT - File encryption detected
-Files Encrypted: 500+ files
-Process: unknown.exe running as SYSTEM
+Directory: /mnt/backup/production
+Files Encrypted: 500+
+Process: unknown.exe (SYSTEM privilege)
+Time: 2025-12-21 16:20:15 UTC
 Status: ACTIVE THREAT
 ```
 
-### SQL Injection
+### 3. SQL Injection Attempt
 ```
 Web Application Firewall Alert
-Rule Triggered: SQL Injection Pattern
-Payload: ' OR '1'='1'
-Status: Blocked
+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.
 
-## Architecture for AI Developers
+**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
 
-See `.github/copilot-instructions.md` for comprehensive AI agent onboarding—covers:
-- Component architecture and data flows
-- Critical patterns (provider abstraction, config management, regex parsing)
-- Extension points for new providers and features
-- Testing strategy and troubleshooting
+**Q: How do I report bugs?**
+A: Open an issue on GitHub with reproduction steps.
 
-## License
+---
 
-MIT
+**Questions?** Check `.github/copilot-instructions.md` or create an issue!
 
 ## Contributing