The Problem

Security operations teams face alert volumes that exceed manual investigation capacity. This platform attempts to automate correlation, enrichment, and report generation, but the codebase shows significant structural debt that risks reliability in production environments.

What This Does

The repository is a collection of 7 semi-independent projects centered on an AI-driven SOC platform. Core functionality spans alert aggregation via a Module framework (DATA/MODULES/), SIEM integration through YAML configs (Docker/PostgreSQL/, Docker/RedisStack/), and AI-powered investigation reports generated by LLM (Docker/SIRP/components/investigation_report_ai.jsx). The platform provides unified multi-SIEM access (PLUGINS/SIEM/), automated threat intelligence enrichment (PLUGINS/Forwarder/), and playbook-style one-click automation (PLAYBOOKS/). Seven distinct project areas operate under one root: PLUGINS (70 code files), Lib (15), Core (11), Docker (5 code files), ASP (5), MODULES (4), and PLAYBOOKS (4).

Execution starts from several entry points. The run function in Lib/baseapi.py:123 is the primary gateway, reaching 130 other functions and serving as the root for database operations (e.g., Token.objects.create). start in Lib/moduleengine.py:14 reaches 9 functions and appears to initialize the module framework. Webhook entry points webhook_kibana (PLUGINS/Forwarder/main.py:56) and webhook_splunk (PLUGINS/Forwarder/main.py:37) handle SIEM inbound traffic. run_engine (PLUGINS/Mock/SIEM/main.py:56) orchestrates the mock SIEM loop. The _extract_source function (PLUGINS/Forwarder/main.py:25) feeds source parsing into the forwarder pipeline.

A central call graph of 533 resolved edges shows list is called from 22 places, Condition from 12, and Group from 12. The most connected module is Lib/log (21 importers, 0 exports, instability 0) — a hub where changes have blast-radius across a fifth of the codebase. PLUGINS/SIRP/sirpcoremodel (14 importers, 1 export, instability 0.07) and Lib/monitor (1 importer, 10 exports, instability 0.91) also see high traffic, with the latter’s deep export dependency suggesting fragile signal flow. The PLUGINS/MCP/llmfunc module (1 importer, 11 exports, instability 0.92) is a pronounced outflow point for LLM operations, and its single importer means any change ripples widely.

How It Is Wired

Execution flow typically begins at run (Lib/baseapi.py:123) and proceeds through the module engine (Lib/moduleengine.py:14) to case management functions. The internal call graph reveals that Condition is a frequent branching point — called from 12 places and itself invoked by get_by_identity, list_alerts, list_artifacts, and six other list-like operations. ArtifactModel is called 19 times from run, and update_playbook_status appears 8 times. Paths from run to database writes go through create (Token.objects.create), while threat intelligence lookups fan out through PLUGINS/Redis/redis_stream_api (called from 7 places) and external providers via PLUGINN/AlienVaultOTX/alienvaultotx.py (makes outbound network calls). File reads and writes are handled by Lib/api.py (runs external commands, reads/writes files) and several plugin modules.

How To Use It

Setup: No single build command exists across the 7 projects. The presence of pyproject.toml and PLUGINS/Forwarder/requirements.txt indicates pip-based Python dependency management for the forwarder plugin. Docker compose files in Docker/PostgreSQL/ and Docker/RedisStack/ define the database and cache infrastructure. No root-level Dockerfile or Makefile was detected; container builds would need to be composed from the existing docker-compose manifests.

Configuration: ASP/settings.py contains ALLOWED_HOSTS = ['*'], which must be narrowed to deployment-specific domains before production use. Environment-specific secrets or keys are not evident in the static analysis; the repository states "MIT licensed, fully on-premise deployment — your data never leaves your network," but no .env examples or secret management files were observed among the 156 files.

Running it: To start the platform, invoke the run entry point from Lib/baseapi.py:123, or use start from Lib/moduleengine.py:14 for module initialization. The webhook endpoints (webhook_kibana, webhook_splunk) accept SIEM inbound traffic. For the mock SIEM, run_engine (PLUGINS/Mock/SIEM/main.py:56) is the starting point. No CLI script or manage.py invocation was confirmed as the primary start mechanism beyond the entry points identified.

Real-World Use

A security operations center receives a new alert from a SIEM (Splunk or ELK). The forwarder plugin (PLUGINS/Forwarder/main.py) captures the inbound webhook, normalizes the event, and injects it into the module framework. The module engine (Lib/moduleengine.py:14) routes the alert through extractors (PLUGINS/SIEM/data_extractors.py, which has 27 branch points over 84 lines) that pull IOCs and correlate them against the knowledge base. When an artifact is created, PLUGINS/SIRP/sirpapi triggers automatic threat intelligence queries via PLUGINS/Redis/redis_stream_api and external providers like AlienVaultOTX. LLM-backed investigation reports are generated (Lib/analysis.py:generate_investigation_report), and the case status is updated via run (Lib/baseapi.py:123) → update_playbook_status. An analyst reviews the structured verdict and remediation advice, then closes the case, feeding extracted knowledge back into the organizational knowledge base.

Code Health & Issues

Static analysis of 114 Python and JavaScript files produced 34 findings across 7 categories:

  • Deep nesting (HIGH, 23 occurrences): Max indentation depth 18 in PLUGINS/SIRP/sirpcoremodel.py, PLUGINS/Redis/redis_stream_api.py, and PLUGINS/SIRP/sirpbasemodel.py. Control flow is hard to follow; fix with guard clauses and extraction.
  • Oversized files (MEDIUM, 3 files): PLUGINS/SIRP/sirpcoremodel.py, PLUGINS/SIRP/sirpapi.py, and PLUGINS/Mock/SIRP/mock_alert.py each exceed 845 lines. Changes ripple widely; split into cohesive units.
  • Hub modules (MEDIUM): Lib/log.py and PLUGINS/SIRP/sirpcoremodel.py are depended on by 21 and 14 modules respectively. Churn here is high-blast-radius; keep stable and small.
  • Duplicated code (HIGH): 137 repeated 6-line blocks across 12 files in Docker/SIRP/components/ (investigation_report_ai.jsx, investigation_report_ai_dark.jsx, json.jsx, json_dark.jsx). Extract shared helpers.
  • Broad exception handling (MEDIUM): Bare or Exception-wide except blocks in Core/bootstrap.py, ASP/settings.py, and MODULES/Mail-01-User-Report-Phishing-Mail.py. Swallow errors indiscriminately; catch specific exceptions.
  • High branching density (MEDIUM): PLUGINS/SIEM/data_extractors.py has 27 branch points over 84 lines. Decompose decision logic; consider table/strategy dispatch.
  • 6 TODO/FIXME markers (LOW): In PLUGINS/Splunk/CONFIG.example.py. Triage or resolve; stale markers erode signal.

Additional SDLC observations from file structure: no test files detected repository-wide, no CI/CD pipeline or .github/ configuration, and no lockfile for the PLUGINS/Forwarder/requirements.txt dependencies — builds are non-reproducible. ASP/settings.py uses ALLOWED_HOSTS = ['*'], making the application answer to any Host header. No license file was found contradicting the repository's MIT claim, but the absence of a LICENSE file in the root should be verified.

The Bottom Line

This repository delivers a functional, agent-centric SOC platform with genuine automation value — alert aggregation, LLM-powered investigation reports, and multi-SIEM unification work as described. However, the codebase carries significant structural risk: zero test coverage, no CI gate, a wildcard ALLOWED_HOSTS setting, and 845-line files that resist change without unintended consequences. Teams needing rapid deployment will find the Docker compose and Python dependencies get them running quickly, but any production hardening — security, reliability, or maintenance — will require substantial refactoring investment. Use this as a prototype or internal tooling foundation, not yet as a hardened production platform.