# uruc/soc-automation-lab architecture

> Architecture diagram of the GitHub repository uruc/soc-automation-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uruc/soc-automation-lab
- Repository: https://github.com/uruc/soc-automation-lab

## Overview

##### Project type and purpose
- This is a hands-on SOC Automation Lab: a full-stack security monitoring and response system built on virtual machines and open-source tools.
- Purpose: Collect Windows security events (via Sysmon), centralize and alert on them (via Wazuh), automate incident workflows (via Shuffle), manage cases (via TheHive), enrich alerts (via VirusTotal), and notify analysts.

##### File structure
- Top-level files: README.md (detailed deployment and architecture guide), LICENSE, .gitignore, .gitattributes.
- images directory: screenshots and the master SOC_Automation_Diagram.png.
- No code—this is an infrastructure lab with manual and scripted installations.

##### Extract architectural insights from the README
- Components: Windows 10 Sysmon client; Wazuh server (manager, web UI, Filebeat); TheHive server (application, Java, Cassandra, Elasticsearch); Shuffle (SOAR workflows); VirusTotal API; Email system.
- Workflows: Sysmon → Wazuh → custom alert → webhook to Shuffle → VirusTotal lookup + TheHive case creation + email notification.
- Deployment: Each major tool lives on its own VM or service endpoint.

##### Main components and their interactions
a. Windows 10 VM with Sysmon agent
b. Wazuh VM
– Wazuh Manager (ossec)
– Elasticsearch & Filebeat (for archiving & indexing)
– Wazuh Web UI
c. Shuffle SOAR (cloud or VM service)
d. TheHive VM
– TheHive application
– Cassandra (data store)
– Elasticsearch (search/index store)
e. External services
– VirusTotal API
– SMTP/Email server

1. Sysmon → Wazuh Manager (event forwarding)
2. Wazuh Manager → Filebeat → Elasticsearch (log indexing)
3. Wazuh Manager → webhook (Shuffle integration)
4. Shuffle workflow:
- extract SHA256 → VirusTotal API → parse results
- call TheHive API → create incident/case
- send email notification

##### Architectural patterns and principles
- Micro-VM/service separation: each tool lives in its own sandbox VM or container.
- Event-driven integration: Wazuh alerts trigger webhooks into Shuffle.
- Modular SOAR workflows: each step (regex extraction, API enrichment, case creation, notification) is a self-contained module.
- Data persistence: Elasticsearch indexes events; Cassandra/Elasticsearch store TheHive cases.

##### Technologies, frameworks, libraries
- Sysmon on Windows for event capture.
- Wazuh (Ossec + Filebeat + Elasticsearch + Kibana-like UI).
- Shuffle (SOAR orchestration).
- TheHive (Scala/Play application) with Cassandra and Elasticsearch.
- VirusTotal REST API.
- SMTP/email.
- Virtualization platform (VMware or cloud droplets on DigitalOcean).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation
    subgraph "Documentation"
        Doc["README.md"]:::documentation
        Diagram["SOC Automation Diagram"]:::documentation
    end

    %% Client VM
    subgraph "Windows 10 Client VM" 
        Sysmon["Sysmon Agent"]:::client
    end

    %% Wazuh VM
    subgraph "Wazuh VM"
        Manager["Wazuh Manager\n(ossec)"]:::wazuh
        Filebeat["Filebeat"]:::wazuh
        ES1["Elasticsearch\n(9200)"]:::db
        UI["Wazuh Web UI"]:::wazuh
    end

    %% SOAR Service
    Shuffle["Shuffle SOAR\nWebhook Listener"]:::soar

    %% TheHive VM
    subgraph "TheHive VM"
        THApp["TheHive Application\n(9000)"]:::thehive
        Cassandra["Cassandra"]:::db
        ES2["Elasticsearch\n(9200)"]:::db
    end

    %% External Services
    Virus["VirusTotal API"]:::external
    Email["SMTP Email Service"]:::external

    %% Data Flows
    Sysmon -->|"syslog/Winlogbeat"| Manager
    Manager -->|"log forward"| Filebeat
    Filebeat -->|"index"| ES1
    Manager -->|"HTTP webhook"| Shuffle
    Shuffle -->|"REST: VT lookup"| Virus
    Shuffle -->|"REST: Create case"| THApp
    Shuffle -->|"REST: Send email"| Email
    THApp -->|"store case"| Cassandra
    THApp -->|"index case"| ES2

    %% Click Events
    click Doc "https://github.com/uruc/soc-automation-lab/blob/main/README.md"
    click Diagram "https://github.com/uruc/soc-automation-lab/blob/main/images/SOC_Automation_Diagram.png"

    %% Styles
    classDef client fill:#CCEEFF,stroke:#333,stroke-width:1px;
    classDef wazuh fill:#CCFFCC,stroke:#333,stroke-width:1px;
    classDef thehive fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef soar fill:#FFF2CC,stroke:#333,stroke-width:1px;
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px;
    classDef db fill:#CCCCFF,stroke:#333,stroke-width:1px;
    classDef documentation fill:#EEEEEE,stroke:#333,stroke-width:1px;font-style:italic;
```
