// project

SOAR Suite

A Python-based Security Orchestration, Automation and Response platform built for SOC environments. Ingests alerts from any source, runs automated enrichment playbooks, derives weighted verdicts, and generates full audit-trail reports backed by MySQL.

Python SOAR SOC Automation MITRE ATT&CK VirusTotal API Flask MySQL
View on GitHub
What It Does

When an alert arrives from any source (SIEM, EDR, firewall, email gateway, or manual submission) the engine parses and normalises it, auto-classifies the type and severity if not provided, creates an incident record in MySQL, routes it to the matching playbook, and runs a chain of enrichment steps against VirusTotal, a local IOC database, and GeoIP/ASN lookups.

Every enrichment result feeds a weighted verdict scoring system. Signals are classified as low, medium, high, or critical, and the engine derives a final verdict of benign, suspicious, malicious, or unknown based on signal combinations. The incident is then auto-closed or escalated depending on playbook rules. Every action is written to a full audit trail in MySQL, and HTML and JSON reports are generated for each incident.

The REST API means alerts can be submitted from any tool via a single HTTP call. The CLI works for manual investigation and bulk testing.

Playbooks
BruteForcePlaybook
T1110
Handles brute force alerts. Enriches source IP via VirusTotal and GeoIP, checks IOC database, scores velocity and geography signals.
MalwarePlaybook
T1204, T1059
Enriches file hashes and IPs. Checks VT detection ratio, process ancestry, and known malware family associations.
PhishingPlaybook
T1566, T1598
Analyses sender domains and URLs. Runs domain reputation via VirusTotal and checks for lookalike indicators in the IOC database.
SuspiciousIPPlaybook
T1071, T1090
Full IP reputation chain: VirusTotal, GeoIP/ASN, IOC lookup. Flags Tor exit nodes, VPN infrastructure, and known C2 ranges.
LateralMovementPlaybook
T1021, T1550, T1075
Correlates source and destination host context. Checks for credential abuse patterns and unusual internal authentication sequences.
DataExfilPlaybook
T1048, T1567, T1071.004
Analyses destination IPs and domains for exfiltration indicators. Checks volume anomalies and known cloud upload services used for data theft.
Verdict Logic
MALICIOUS
Any critical signal, or 2 or more high signals.
SUSPICIOUS
1 high signal plus any medium, or medium signals only.
BENIGN
No signals raised across all enrichment steps.
UNKNOWN
Enrichment returned no usable data. Requires manual review.

Every signal is written to the action_log table with a timestamp, action name, status, and the full raw enrichment result stored as JSON.

Architecture
soar-suite/
engine/
alert_ingestor.py # parse, classify, persist incoming alerts
dispatcher.py # route to playbook, manage incident lifecycle
playbooks/ # 6 playbooks + abstract base class
enrichment/
virustotal.py # VT v3 API: IP, domain, file hash
ioc_lookup.py # local MySQL IOC database queries
geoip.py # GeoIP and ASN via ip-api.com
db/
schema.sql # full schema with seed data
api/
app.py # Flask REST API
reports/
generator.py # HTML and JSON report renderer
scripts/
run_alert.py # CLI: single alert
run_bulk.py # CLI: all sample alerts at once
REST API
# Submit a single alert
POST /api/v1/alerts
{
"alert_type": "brute_force",
"src_ip": "185.220.101.1",
"username": "administrator",
"severity": "high",
"source": "firewall"
}

# List incidents filtered by verdict
GET /api/v1/incidents?verdict=malicious

# Full incident detail with audit trail
GET /api/v1/incidents/INC-XXXXXXXXXX

# Add analyst notes
PATCH /api/v1/incidents/INC-XXXXXXXXXX
{ "analyst_notes": "Confirmed true positive. Host isolated." }

# IOC lookup
GET /api/v1/ioc/lookup?type=ip&value=185.220.101.1
Alert Payload Schema
{
"alert_id": "ALT-OPTIONAL-CUSTOM-ID", // auto-generated if omitted
"source": "crowdstrike | siem | firewall | manual | ...",
"alert_type": "brute_force | malware | phishing | suspicious_ip | lateral_movement | data_exfil",
"severity": "low | medium | high | critical", // auto-classified if omitted
"src_ip": "1.2.3.4",
"hostname": "WORKSTATION-01",
"username": "jdoe",
"raw_log": "raw log string or event description"
}
Database Tables
alerts
All ingested alerts with full original payload.
incidents
One incident per alert, linked to a playbook run and final verdict.
action_log
Full audit trail of every enrichment step with timestamps and raw results.
ioc_db
Local threat intelligence store queried during enrichment.
playbook_rules
Maps alert types to playbooks with auto-close and escalation thresholds.
Why I Built It

Commercial SOAR platforms like Palo Alto XSOAR or Splunk SOAR are powerful but completely opaque. You configure playbooks through a GUI without ever understanding what the orchestration engine is actually doing underneath. Building one from scratch forced me to understand every layer: how alerts get normalised from different source formats, how enrichment results translate into actionable signals, how verdict scoring needs to balance false positive rate against detection sensitivity, and how an audit trail needs to be structured to be actually useful during an investigation or post-incident review.

The REST API design reflects how SOAR actually integrates in production. Any tool that can make an HTTP call can submit an alert, which means the platform is source-agnostic from the start. The analyst notes endpoint reflects the real workflow where a human reviews an automated verdict and adds context before closing or escalating the incident.

This is the top of the stack across the entire portfolio. The IOC database feeds the enrichment layer. The VT Bulk Enricher uses the same API patterns as the enrichment module. The Python SIEM generates the kind of alerts this platform is designed to receive. The SOC Triage Lab represents the manual investigation process that SOAR is built to automate. Every project connects.