SOC Alert to Investigation Guide CLI - Transform security alerts into actionable investigation playbooks with MITRE ATT&CK mapping
npm install alert2actionbash
alert2action alert.json
`
Input: A security alert JSON file (from any SIEM, EDR, or security tool)
Output: A comprehensive investigation guide with:
- π What Happened - Plain-English summary
- π― MITRE ATT&CK Mapping - Matched techniques with confidence scores
- π Logs to Check - Relevant log sources for investigation
- β‘ Commands to Run - PowerShell & Linux commands for analysis
- π‘οΈ Containment Steps - Prioritized response actions
- π€ False Positive Hints - Common benign causes to rule out
π‘ Why This Is GOLD
- β
Helps SOC freshers - Learn investigation workflow
- β
Saves senior analyst time - Skip the basics, focus on threats
- β
No strong open-source competitor - Fills a real gap
- β
Works with any SIEM - Normalizes different alert formats
- β
Offline capable - No API keys needed
π Quick Start
$3
`bash
npm install -g alert2action
`
$3
`bash
git clone https://github.com/notsointresting/alert2action.git
cd alert2action
npm install
npm link # Makes it globally available
`
$3
`bash
alert2action examples/brute-force-alert.json
or
node bin/alert2action.js examples/brute-force-alert.json
`
π Usage
$3
`bash
alert2action
`
$3
`bash
alert2action alert.json # Colored CLI output
alert2action alert.json -o json # JSON format
alert2action alert.json -o markdown # Markdown for tickets
alert2action alert.json -v # Verbose mode
alert2action --help # Show help
`
$3
- text (default) - Colorized CLI output for terminal
- json - Raw JSON for integration with other tools
- markdown - Perfect for pasting into tickets/docs
π Supported Alert Formats
alert2action automatically normalizes alerts from various sources:
- Generic JSON - Any custom format
- Splunk - Splunk alert output
- Microsoft Sentinel - Azure Sentinel incidents
- Elastic SIEM - Elasticsearch alerts
- CrowdStrike Falcon - Falcon detection events
- Microsoft Defender - MDE/MDI alerts
- Custom SIEM - Maps common field names automatically
$3
`json
{
"title": "Multiple Failed Login Attempts",
"severity": "high",
"timestamp": "2024-01-18T10:30:00Z",
"source_ip": "185.220.101.45",
"hostname": "DC01.corp.local",
"username": "administrator",
"description": "Over 50 failed login attempts detected"
}
`
π― MITRE ATT&CK Coverage
Currently maps to 21 techniques across all major tactics:
| Tactic | Techniques |
|--------|------------|
| Reconnaissance | T1595 (Active Scanning) |
| Initial Access | T1566 (Phishing), T1190 (Exploit), T1078 (Valid Accounts) |
| Execution | T1059 (Command/Script), T1059.001 (PowerShell) |
| Persistence | T1053 (Scheduled Task), T1547 (Boot Autostart) |
| Privilege Escalation | T1548.002 (UAC Bypass), T1134 (Token Manipulation) |
| Defense Evasion | T1055 (Process Injection), T1070 (Indicator Removal) |
| Credential Access | T1003 (Credential Dumping), T1110 (Brute Force) |
| Discovery | T1087 (Account Discovery) |
| Lateral Movement | T1021 (Remote Services) |
| Command & Control | T1071 (Application Protocol) |
| Exfiltration | T1041 (Exfil Over C2) |
| Impact | T1486 (Ransomware) |
π Example Alerts Included
Try these sample alerts in the examples/ folder:
`bash
Brute force attack
node bin/alert2action.js examples/brute-force-alert.json
Malware execution (PowerShell download cradle)
node bin/alert2action.js examples/malware-alert.json
Phishing email
node bin/alert2action.js examples/phishing-alert.json
Credential dumping (LSASS access)
node bin/alert2action.js examples/credential-dump-alert.json
Lateral movement (PsExec)
node bin/alert2action.js examples/lateral-movement-alert.json
Privilege escalation (UAC Bypass)
node bin/alert2action.js examples/privesc-alert.json
Multi-stage attack (Encoded PS + C2 + Persistence)
node bin/alert2action.js examples/soc-test-alert.json
`
π οΈ Programmatic Usage
Use alert2action as a library in your own scripts:
`javascript
const { analyze, parseAlert, generateGuide } = require('alert2action');
// Quick analysis
const alertJson = require('./my-alert.json');
console.log(analyze(alertJson));
// Or step by step
const parsed = parseAlert(alertJson);
const guide = generateGuide(parsed);
console.log(guide);
``