Skip to content

Commit 4e651c4

Browse files
yashab-cyberyashab-cyber
committed
docs: add SOC analyst feature roadmap (SOC.md)
10 planned features across 3 tiers: - Tier 1: IOC Analyzer, Log Analyzer, Phishing Analyzer, IR Playbooks - Tier 2: Threat Hunt Mode, PCAP Analyzer, YARA Generator, Alert Enrichment - Tier 3: Shift Handoff Reports, STIX/TAXII Export Includes CLI usage examples, API keys, file structure, and implementation order.
1 parent 87d0ae7 commit 4e651c4

1 file changed

Lines changed: 386 additions & 0 deletions

File tree

‎SOC.md‎

Lines changed: 386 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,386 @@
1+
# 🛡️ HackBot SOC Analyst Features — Roadmap
2+
3+
> Planned SOC (Security Operations Center) analyst features for HackBot.
4+
> This file tracks what to build and implementation priorities.
5+
6+
---
7+
8+
## Tier 1 — Highest Impact (Daily SOC Workflow)
9+
10+
### 1. IOC Analyzer (`/ioc`)
11+
**Priority: 🔴 High — Build First**
12+
13+
Multi-source threat intelligence for IPs, domains, file hashes, and URLs.
14+
15+
**Capabilities:**
16+
- Auto-extract IOCs from pasted logs/alerts (regex-based: IPs, domains, hashes, URLs, emails)
17+
- VirusTotal lookup (file hashes, URLs, IPs, domains)
18+
- AbuseIPDB reputation check (abuse confidence score, ISP, country, reports)
19+
- Shodan host search (open ports, banners, vulns, geolocation)
20+
- GreyNoise context (classification: benign/malicious/unknown, tags, first/last seen)
21+
- AlienVault OTX pulse search (threat intel pulses, related IOCs)
22+
- IP geolocation and ASN info
23+
- Aggregate risk scoring across all sources
24+
- Bulk IOC analysis (paste multiple IOCs at once)
25+
26+
**CLI Usage:**
27+
```
28+
/ioc 185.220.101.1 # IP reputation check
29+
/ioc evil.example.com # Domain reputation
30+
/ioc 44d88612fea8a8f36de82e1278abb02f # File hash lookup
31+
/ioc https://malware.example.com/payload.exe # URL scan
32+
/ioc --extract <paste logs> # Auto-extract and analyze all IOCs
33+
/ioc --bulk ip1,ip2,ip3 # Bulk lookup
34+
```
35+
36+
**API Keys Needed:**
37+
| Service | Free Tier | Env Variable |
38+
|---------|-----------|-------------|
39+
| VirusTotal | 4 req/min, 500 req/day | `VT_API_KEY` |
40+
| AbuseIPDB | 1000 req/day | `ABUSEIPDB_API_KEY` |
41+
| Shodan | 1 req/sec, limited | `SHODAN_API_KEY` |
42+
| GreyNoise | 50 req/day (Community) | `GREYNOISE_API_KEY` |
43+
| AlienVault OTX | Unlimited (free) | `OTX_API_KEY` |
44+
45+
**Implementation Notes:**
46+
- Create `hackbot/core/ioc.py` — IOCAnalyzer class
47+
- Follow same pattern as `cve.py` (dataclasses, rate limiting, session management)
48+
- Config: add API keys to AgentConfig, env-var overrides
49+
- CLI: `/ioc` command, `/ioc-keys` to manage API keys
50+
- GUI: IOC Analyzer panel with multi-tab layout
51+
- Agent integration: auto-extract IOCs from tool output
52+
53+
---
54+
55+
### 2. Log Analyzer (`/logs`)
56+
**Priority: 🔴 High**
57+
58+
AI-powered log parsing and anomaly detection.
59+
60+
**Capabilities:**
61+
- Parse multiple log formats: syslog, auth.log, Windows Event Logs (EVTX XML), Apache/nginx access/error logs, JSON logs
62+
- Pattern detection: brute-force attempts, privilege escalation, lateral movement, data exfiltration
63+
- Timeline reconstruction — chronological event sequence with anomaly highlighting
64+
- Statistical analysis: failed login counts, top source IPs, unusual hours, spike detection
65+
- AI-powered analysis: natural language summary of what happened
66+
- MITRE ATT&CK mapping of detected patterns
67+
68+
**CLI Usage:**
69+
```
70+
/logs analyze <paste log content> # Analyze pasted logs
71+
/logs analyze --file /path/to/auth.log # Analyze a log file
72+
/logs timeline <paste> # Build event timeline
73+
/logs brute-force <paste auth.log> # Focused brute-force detection
74+
/logs summary <paste> # AI summary of log events
75+
```
76+
77+
**Implementation Notes:**
78+
- Create `hackbot/core/log_analyzer.py`
79+
- Regex-based parsers for each log format
80+
- Statistical anomaly detection (z-score, frequency analysis)
81+
- Feed parsed data to AI for natural language analysis
82+
- Output: structured findings + timeline + AI commentary
83+
84+
---
85+
86+
### 3. Phishing Analyzer (`/phish`)
87+
**Priority: 🔴 High**
88+
89+
Email header analysis and phishing indicator detection.
90+
91+
**Capabilities:**
92+
- Email header parsing (Received chain, SPF, DKIM, DMARC results)
93+
- Sender reputation check (via IOC analyzer integration)
94+
- URL extraction and deobfuscation (base64, URL encoding, redirect chains)
95+
- Attachment hash extraction and VirusTotal lookup
96+
- Homoglyph / typosquatting domain detection
97+
- AI-powered verdict: phishing confidence score with reasoning
98+
- Response suggestions: block sender, quarantine, report
99+
100+
**CLI Usage:**
101+
```
102+
/phish analyze <paste email headers> # Full header analysis
103+
/phish url https://bit.ly/xyz # Unshorten + scan URL
104+
/phish domain paypa1.com # Typosquat detection vs paypal.com
105+
/phish verdict <paste full email> # AI phishing verdict
106+
```
107+
108+
**Implementation Notes:**
109+
- Create `hackbot/core/phishing.py`
110+
- Python `email` stdlib for header parsing
111+
- SPF/DKIM/DMARC result extraction from Authentication-Results header
112+
- URL deobfuscation chain (follow redirects with `requests`, decode encodings)
113+
- Levenshtein distance for typosquat detection against top 1000 domains
114+
- Integration with IOC analyzer for sender IP/domain reputation
115+
116+
---
117+
118+
### 4. Incident Response Playbooks (`/ir`)
119+
**Priority: 🟠 High**
120+
121+
Pre-built step-by-step IR playbooks with AI guidance.
122+
123+
**Capabilities:**
124+
- Pre-built playbooks: ransomware, phishing, data breach, DDoS, insider threat, malware infection, account compromise, web defacement, supply chain attack
125+
- Each playbook has phases: Detection → Containment → Eradication → Recovery → Lessons Learned
126+
- Evidence collection checklists per incident type
127+
- Containment commands (with safe_mode guardrails)
128+
- AI-assisted triage: paste alert details, get customized response steps
129+
- Regulatory notification timelines (GDPR 72hr, HIPAA, PCI-DSS)
130+
- Post-incident report template generation
131+
132+
**CLI Usage:**
133+
```
134+
/ir list # List all playbooks
135+
/ir ransomware # Show ransomware playbook
136+
/ir phishing # Show phishing playbook
137+
/ir triage <paste alert details> # AI-assisted triage
138+
/ir checklist ransomware # Evidence collection checklist
139+
/ir report # Generate post-incident report
140+
```
141+
142+
**Implementation Notes:**
143+
- Create `hackbot/core/incident.py`
144+
- Playbooks as structured data (dict/dataclass with phases, steps, commands)
145+
- AI integration: use playbook as system prompt context for triage
146+
- PDF report generation using existing `pdf_report.py` infrastructure
147+
- No external APIs needed — mostly structured data + AI prompting
148+
149+
---
150+
151+
## Tier 2 — Advanced SOC (Threat Hunting & Forensics)
152+
153+
### 5. Threat Hunt Mode (`/hunt`)
154+
**Priority: 🟡 Medium**
155+
156+
Hypothesis-driven threat hunting with SIEM query generation.
157+
158+
**Capabilities:**
159+
- Natural language → Sigma rule generation
160+
- Sigma → SIEM query translation (Splunk SPL, Microsoft KQL, Elastic EQL, QRadar AQL)
161+
- Pre-built hunt hypotheses library (lateral movement, C2 beacons, persistence, credential access)
162+
- TTP-based hunting (input ATT&CK technique → get detection queries)
163+
- AI-assisted hypothesis refinement
164+
165+
**CLI Usage:**
166+
```
167+
/hunt "lateral movement via SMB" # Generate Sigma + SIEM queries
168+
/hunt sigma "failed login brute force" # Generate Sigma rule only
169+
/hunt splunk "DNS tunneling" # Generate Splunk SPL query
170+
/hunt kql "suspicious PowerShell" # Generate KQL for Sentinel
171+
/hunt technique T1059.001 # Hunt by ATT&CK technique
172+
/hunt list # List pre-built hypotheses
173+
```
174+
175+
**Implementation Notes:**
176+
- Create `hackbot/core/threat_hunt.py`
177+
- Sigma rule YAML generation (structured templates + AI refinement)
178+
- Sigma-to-SIEM transpiler (template-based for each SIEM backend)
179+
- Pre-built hypothesis library (JSON/YAML data)
180+
- Integration with existing ATT&CK mapper for technique-based hunting
181+
182+
---
183+
184+
### 6. PCAP Analyzer (`/pcap`)
185+
**Priority: 🟡 Medium**
186+
187+
Network traffic forensics via tshark integration.
188+
189+
**Capabilities:**
190+
- Parse pcap files using tshark (must be installed)
191+
- Protocol distribution analysis
192+
- DNS query extraction and anomaly detection (tunneling, DGA domains)
193+
- HTTP request/response extraction
194+
- C2 beacon detection (periodic timing analysis)
195+
- Data exfiltration indicators (large outbound transfers, unusual protocols)
196+
- TLS certificate analysis (self-signed, expired, suspicious issuers)
197+
- Conversation summary (top talkers, flow analysis)
198+
199+
**CLI Usage:**
200+
```
201+
/pcap analyze capture.pcap # Full analysis
202+
/pcap dns capture.pcap # DNS-focused analysis
203+
/pcap http capture.pcap # HTTP request extraction
204+
/pcap c2 capture.pcap # C2 beacon detection
205+
/pcap summary capture.pcap # Quick traffic summary
206+
```
207+
208+
**Implementation Notes:**
209+
- Create `hackbot/core/pcap.py`
210+
- Shell out to `tshark` (add to allowed_tools)
211+
- Parse tshark JSON output for structured analysis
212+
- Statistical timing analysis for beacon detection
213+
- Feed summary data to AI for natural language forensic report
214+
215+
---
216+
217+
### 7. YARA Rule Generator (`/yara`)
218+
**Priority: 🟡 Medium**
219+
220+
AI-assisted YARA rule creation and validation.
221+
222+
**Capabilities:**
223+
- Generate YARA rules from: malware family name, IOCs, file characteristics, description
224+
- Rule validation (syntax check via `yara-python` if installed)
225+
- Template library for common malware families
226+
- String extraction suggestions
227+
- Condition builder (file size, magic bytes, import table, string counts)
228+
- VirusTotal retrohunt-compatible output
229+
230+
**CLI Usage:**
231+
```
232+
/yara generate "Cobalt Strike beacon" # AI-generated rule
233+
/yara from-iocs hash1,hash2,domain1 # Rule from IOC list
234+
/yara validate <paste rule> # Syntax validation
235+
/yara templates # List templates
236+
```
237+
238+
**Implementation Notes:**
239+
- Create `hackbot/core/yara_gen.py`
240+
- AI-driven rule generation (structured prompting with YARA syntax examples)
241+
- Optional `yara-python` for validation
242+
- Template library as embedded data
243+
244+
---
245+
246+
### 8. Alert Enrichment Pipeline (`/alert`)
247+
**Priority: 🟡 Medium**
248+
249+
SIEM alert triage automation.
250+
251+
**Capabilities:**
252+
- Paste raw SIEM alert → auto-extract all observables (IPs, domains, hashes, users, hosts)
253+
- Enrich each observable via IOC analyzer
254+
- Score overall alert priority (critical/high/medium/low/false positive)
255+
- Suggest response actions based on alert type
256+
- Map to MITRE ATT&CK techniques
257+
- Generate triage notes for ticketing system
258+
259+
**CLI Usage:**
260+
```
261+
/alert triage <paste raw alert> # Full triage pipeline
262+
/alert enrich <paste alert> # Enrich observables only
263+
/alert priority <paste alert> # Quick priority scoring
264+
/alert notes <paste alert> # Generate ticket notes
265+
```
266+
267+
**Implementation Notes:**
268+
- Create `hackbot/core/alert_triage.py`
269+
- Depends on IOC analyzer (#1) — build that first
270+
- Observable extraction: regex patterns for all indicator types
271+
- Priority scoring: weighted formula based on IOC reputations + alert context
272+
- Integration with ATT&CK mapper for technique tagging
273+
274+
---
275+
276+
## Tier 3 — SOC Operations
277+
278+
### 9. Shift Handoff Reports (`/shift`)
279+
**Priority: 🟢 Low**
280+
281+
Auto-generate SOC shift summaries.
282+
283+
**Capabilities:**
284+
- Aggregate all activities from current session
285+
- List: investigations performed, IOCs analyzed, findings discovered, actions taken
286+
- Open incident summary with status and next steps
287+
- Escalation log
288+
- Export as Markdown/PDF
289+
290+
**CLI Usage:**
291+
```
292+
/shift report # Generate shift summary
293+
/shift export pdf # Export as PDF
294+
```
295+
296+
**Implementation Notes:**
297+
- Create `hackbot/core/shift_report.py`
298+
- Pull data from session memory, findings, tool history
299+
- AI-generated narrative summary
300+
- Reuse existing PDF/report infrastructure
301+
302+
---
303+
304+
### 10. STIX/TAXII Export (`/stix`)
305+
**Priority: 🟢 Low**
306+
307+
Threat intelligence sharing in standard format.
308+
309+
**Capabilities:**
310+
- Package IOCs as STIX 2.1 bundles (indicators, observables, relationships)
311+
- Package findings as STIX attack patterns
312+
- TAXII 2.1 client for pushing to threat intel platforms
313+
- TLP marking (WHITE, GREEN, AMBER, RED)
314+
315+
**CLI Usage:**
316+
```
317+
/stix export # Export session IOCs as STIX bundle
318+
/stix export --tlp amber # With TLP marking
319+
/stix push --server https://taxii.example.com # Push to TAXII server
320+
```
321+
322+
**Implementation Notes:**
323+
- Create `hackbot/core/stix_export.py`
324+
- Use `stix2` Python library
325+
- Map CVE/IOC/finding data to STIX SDOs
326+
- Optional TAXII client (`taxii2-client`)
327+
328+
---
329+
330+
## Implementation Order
331+
332+
| Phase | Features | Effort | Dependencies |
333+
|-------|----------|--------|-------------|
334+
| **Phase 1** | #1 IOC Analyzer | ~2 days | Free API keys |
335+
| **Phase 2** | #4 IR Playbooks | ~1 day | None (data + AI) |
336+
| **Phase 3** | #3 Phishing Analyzer | ~1 day | IOC Analyzer |
337+
| **Phase 4** | #2 Log Analyzer | ~2 days | None |
338+
| **Phase 5** | #8 Alert Enrichment | ~1 day | IOC Analyzer |
339+
| **Phase 6** | #5 Threat Hunt Mode | ~2 days | ATT&CK Mapper |
340+
| **Phase 7** | #7 YARA Generator | ~1 day | None |
341+
| **Phase 8** | #6 PCAP Analyzer | ~1 day | tshark |
342+
| **Phase 9** | #9 Shift Reports | ~0.5 day | Session memory |
343+
| **Phase 10** | #10 STIX/TAXII | ~1 day | stix2 library |
344+
345+
---
346+
347+
## File Structure (Planned)
348+
349+
```
350+
hackbot/
351+
core/
352+
ioc.py # IOC Analyzer (#1)
353+
log_analyzer.py # Log Analyzer (#2)
354+
phishing.py # Phishing Analyzer (#3)
355+
incident.py # IR Playbooks (#4)
356+
threat_hunt.py # Threat Hunt Mode (#5)
357+
pcap.py # PCAP Analyzer (#6)
358+
yara_gen.py # YARA Rule Generator (#7)
359+
alert_triage.py # Alert Enrichment (#8)
360+
shift_report.py # Shift Handoff Reports (#9)
361+
stix_export.py # STIX/TAXII Export (#10)
362+
manual/
363+
14-soc-features.md # SOC manual page (after implementation)
364+
```
365+
366+
---
367+
368+
## Config Keys (Planned)
369+
370+
```yaml
371+
agent:
372+
vt_api_key: "" # VirusTotal
373+
abuseipdb_api_key: "" # AbuseIPDB
374+
shodan_api_key: "" # Shodan
375+
greynoise_api_key: "" # GreyNoise
376+
otx_api_key: "" # AlienVault OTX
377+
```
378+
379+
Environment variable overrides:
380+
```
381+
VT_API_KEY, ABUSEIPDB_API_KEY, SHODAN_API_KEY, GREYNOISE_API_KEY, OTX_API_KEY
382+
```
383+
384+
---
385+
386+
> **Status**: Planning complete. Start with Phase 1 (IOC Analyzer) when ready.

0 commit comments

Comments
 (0)