# 0xcgz/project-mursad architecture

> Architecture diagram of the GitHub repository 0xcgz/project-mursad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xcgz/project-mursad
- Repository: https://github.com/0xcgz/project-mursad

## Overview

##### Project type & purpose (what you’re diagramming)
**Project Mursad** is not a typical “codebase application” architecture; it’s an **enterprise security lab / SOC telemetry environment** implemented as **virtualized infrastructure on Proxmox**, with:
- **Network perimeter & segmentation** via **pfSense** (VLANs/bridges, DMZ vs LAN isolation)
- **Enterprise identity** via **Active Directory Domain Services (DC/DNS)**
- **Telemetry + detection** via **Wazuh SIEM** (manager/indexer/dashboard + agents + syslog ingestion)
- **Adversary simulation / validation** via **Kali Linux**
- Later-stage **endpoint protection / EDR** (Kaspersky Security Center, antivirus integration)
- IDS/IPS as a dedicated control plane (often Suricata/Snort on pfSense or a separate sensor VM)

##### Where components live (Proxmox nodes, VMs, VLANs, NICs/bridges)
2) **How signals flow** (logs/telemetry to SIEM, management traffic, user traffic crossing zones)

The file tree is documentation-oriented (no app source code):
- `docs/` → where phase-by-phase build docs/architecture notes should live (even if empty now)
- `configs/` → intended to store pfSense exports, Wazuh configs, AD/GPO notes, IDS rules, syslog configs
- `scripts/` → automation (Proxmox provisioning, agent rollout, hardening scripts, benchmark scripts)

##### Main components to include (break the system into as many components as possible)
Based on README phases, your canonical component list should include at least:

##### Infrastructure
- Bare-metal server
- **Proxmox** hypervisor
- Virtual networking (bridges, VLAN trunk)
- VM templates / images (if used)

##### Perimeter & segmentation
- **pfSense firewall/router**
- WAN interface
- LAN interface
- DMZ interface
- VLAN interfaces
- NAT, firewall rules, static routes

##### Identity / core services
- **Windows Server Domain Controller**
- AD DS
- DNS (and possibly DHCP)
- Internal DNS resolution path(s) (LAN vs DMZ)

##### SOC / telemetry
- **Wazuh** components (explicitly split them):
- Wazuh Manager
- Indexer (OpenSearch/Elastic)
- Dashboard
- Syslog forwarders / collectors (if separate)
- Time sync (NTP) source (important for SOC accuracy)

##### Detection / prevention
- IDS/IPS engine (Suricata/Snort)
- Sensor placement (on pfSense vs dedicated VM “tap” / SPAN-like approach)

##### Endpoints & validation
- Windows clients/servers in LAN
- DMZ servers (intentionally vulnerable services)
- **Kaspersky Security Center** + endpoint agents (Phase 4)

##### External dependencies
- ISP/Internet
- External DNS (if used)
- Threat intel feeds (if Wazuh/IDS pulls any)
- Update repos (Windows Update, Linux repos)

##### Architectural patterns to explicitly show
This lab implies several key patterns—make them visually obvious:

- **Defense-in-depth**: perimeter firewall + segmentation + IDS + SIEM + EDR
- **Network zoning / trust boundaries**: WAN vs LAN vs DMZ (and optionally MGMT/SOC)
- **Centralized telemetry**: many-to-one log aggregation into Wazuh
- **Control plane vs data plane separation**: management access should not traverse DMZ casually
- **Phased build-out**: matches the README phases; components appear over time

##### Phase roadmap view

Store exported images in `assets/`, and cross-link them from `docs/` as the build progresses.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram Pack: Project Mursad SOC Lab
  %% =========================

  subgraph "Repository (documentation-oriented)"
    RepoReadme["README (Phases 1–4 roadmap reference)"]:::repo
    RepoDocs["docs (phase-by-phase build notes)"]:::repo
    RepoAssets["assets (diagrams/screenshots/exports)"]:::repo
    RepoConfigs["configs (pfSense/Wazuh/AD/IDS/syslog/GPO/rules exports)"]:::repo
    RepoScripts["scripts (automation/provisioning/hardening/agent rollout)"]:::repo
  end

  subgraph "A) Physical / Virtualization Deployment (Proxmox-centric)"
    BareMetal["Bare-metal Server"]:::infra
    Proxmox["Proxmox Hypervisor"]:::infra

    subgraph "Proxmox Virtual Networking"
      NICTrunk["Physical NIC (VLAN trunk/uplink)"]:::infra
      vmbr0["vmbr0 (WAN/Upstream Bridge)"]:::bridge
      vmbrLAN["vmbrLAN (LAN Bridge)"]:::bridge
      vmbrDMZ["vmbrDMZ (DMZ Bridge)"]:::bridge
      vmbrMGMT["vmbrMGMT (MGMT/SOC Bridge - optional)"]:::bridge
    end

    subgraph "VM Inventory"
      pfSense["pfSense VM (Firewall/Router)"]:::pfsense
      DC["Windows Server VM (Domain Controller)"]:::server
      WazuhMgr["Wazuh Manager VM/Service"]:::soc
      WazuhIdx[("Wazuh Indexer Storage (OpenSearch/Elastic)")]:::db
      WazuhDash["Wazuh Dashboard (UI)"]:::socui
      IDSSensor["IDS/IPS Sensor (Suricata/Snort)"]:::ids
      Kali["Kali Linux VM (Adversary Simulation)"]:::attacker
      WinEndpoints["Windows Clients/Servers (LAN endpoints)"]:::endpoint
      DMZServers["DMZ Servers (intentionally exposed/vulnerable services)"]:::dmz
      KSC["Kaspersky Security Center (later-phase)"]:::edr
      EDRagents["Endpoint AV/EDR Agents (later-phase)"]:::edr
      NTP["NTP/Time Source (for correlation)"]:::infra
      AdminWS["Admin Workstation / Jump Access (recommended)"]:::admin
    end

    BareMetal -->|"hosts"| Proxmox
    Proxmox -->|"uplink"| NICTrunk
    NICTrunk -->|"bridge"| vmbr0
    NICTrunk -->|"bridge"| vmbrLAN
    NICTrunk -->|"bridge"| vmbrDMZ
    NICTrunk -->|"bridge"| vmbrMGMT

    vmbr0 -->|"connects"| pfSense
    vmbrLAN -->|"connects"| pfSense
    vmbrDMZ -->|"connects"| pfSense
    vmbrMGMT -->|"connects"| pfSense

    vmbrLAN -->|"connects"| DC
    vmbrLAN -->|"connects"| WinEndpoints
    vmbrDMZ -->|"connects"| DMZServers
    vmbrLAN -->|"connects"| WazuhMgr
    vmbrLAN -->|"connects"| WazuhDash
    vmbrLAN -->|"connects"| IDSSensor
    vmbrLAN -->|"connects"| KSC
    vmbrLAN -->|"connects"| Kali
    vmbrMGMT -->|"connects"| AdminWS
    vmbrLAN -->|"time-sync"| NTP
  end

  subgraph "B) Network Segmentation / Topology (pfSense-centric)"
    Internet["ISP / Internet (Untrusted)"]:::wan
    WAN["WAN Zone"]:::wan
    LAN["LAN Zone (Internal)"]:::lan
    DMZ["DMZ Zone (Semi-trusted)"]:::dmz
    MGMT["MGMT/SOC Zone (Control Plane - optional)"]:::mgmt

    WANlbl["Label: VLAN?/Public IP via ISP\nKey: NAT + perimeter rules"]:::note
    LANlbl["Label: VLAN ID + Subnet/CIDR\nKey: AD/DNS, endpoints, SOC tooling"]:::note
    DMZlbl["Label: VLAN ID + Subnet/CIDR\nKey: exposed services, strict allow-list"]:::note
    MGMTlbl["Label: VLAN ID + Subnet/CIDR\nKey: admin-only access paths"]:::note

    Internet -->|"upstream"| WAN
    WAN -->|"pfSense WAN interface"| pfSense
    pfSense -->|"pfSense LAN interface"| LAN
    pfSense -->|"pfSense DMZ interface"| DMZ
    pfSense -->|"pfSense MGMT interface (optional)"| MGMT

    WANlbl -.-> WAN
    LANlbl -.-> LAN
    DMZlbl -.-> DMZ
    MGMTlbl -.-> MGMT

    %% Data plane (solid)
    LAN -->|"client-egress"| pfSense
    pfSense -->|"NAT+egress"| WAN
    pfSense -->|"NAT+egress"| Internet

    %% Restricted inter-zone flows (solid, high-level)
    LAN -->|"restricted-allowlist"| DMZ
    DMZ -->|"restricted-allowlist"| LAN

    %% Attack simulation paths (solid)
    Kali -->|"attack-traffic"| DMZServers
    Kali -->|"attack-traffic (if permitted)"| WinEndpoints
  end

  subgraph "C) SOC Telemetry & Detection Data-Flow (Wazuh-centric)"
    subgraph "Telemetry Sources"
      SrcWin["Windows Endpoints (Security events, optional Sysmon)"]:::endpoint
      SrcDC["Domain Controller Logs (AD DS/DNS/Security)"]:::server
      Srcpf["pfSense Logs (firewall/DHCP/DNS resolver)"]:::pfsense
      SrcIDS["IDS/IPS Alerts (Suricata/Snort)"]:::ids
      SrcLinux["Linux Servers (agent or syslog)"]:::server
    end

    subgraph "Collection & Analytics Pipeline"
      AgentChan["Wazuh Agent Channel"]:::pipe
      Syslog514["Syslog (UDP/TCP 514)"]:::pipe
      WazuhManager["Wazuh Manager"]:::soc
      Indexer["Indexer (OpenSearch/Elastic)"]:::db
      Dashboard["Wazuh Dashboard (Analyst UI)"]:::socui
    end

    subgraph "Outputs"
      Alerts["Alerts/Detections/Correlation Rules"]:::socout
      Dashboards["Dashboards/Visualizations"]:::socout
      Notify["Notifications (email/Slack/ticketing - optional)"]:::socout
    end

    %% Telemetry plane (dashed)
    SrcWin -.->|"agent-events"| AgentChan
    SrcDC -.->|"agent-events"| AgentChan
    SrcLinux -.->|"agent-or-syslog"| AgentChan

    Srcpf -.->|"push-logs"| Syslog514
    SrcIDS -.->|"push-alerts"| Syslog514

    AgentChan -.->|"ingest"| WazuhManager
    Syslog514 -.->|"ingest"| WazuhManager
    WazuhManager -.->|"index"| Indexer
    Indexer -.->|"query"| Dashboard

    Dashboard -.->|"drives"| Alerts
    Dashboard -.->|"renders"| Dashboards
    Alerts -.->|"optional"| Notify
  end

  subgraph "D) Identity & Management Plane (AD-centric)"
    ADDS["AD DS (Domain Services)"]:::id
    ADDNS["AD DNS (Internal resolution)"]:::id
    DHCP["DHCP (pfSense or Windows - choose one)"]:::id
    GPO["GPO / Centralized Policy"]:::id
    AgentRollout["Wazuh Agent Rollout (GPO/script)"]:::pipe

    %% Identity dependencies (solid)
    DC -->|"hosts"| ADDS
    DC -->|"hosts"| ADDNS

    %% Control plane (dotted)
    AdminWS -.->|"HTTPS/SSH/RDP"| Proxmox
    AdminWS -.->|"HTTPS"| pfSense
    AdminWS -.->|"HTTPS"| WazuhDash
    AdminWS -.->|"RSAT/RDP"| DC

    %% Identity services (solid)
    ADDNS -->|"DNS 53"| WinEndpoints
    ADDS -->|"Kerberos/LDAP"| WinEndpoints

    %% DHCP ownership (dotted since it's a design choice)
    pfSense -.->|"or"| DHCP
    DC -.->|"or"| DHCP
    DHCP -->|"leases"| WinEndpoints
    DHCP -->|"leases"| DMZServers

    %% Agent rollout (dotted admin/control)
    GPO -.->|"deploys"| AgentRollout
    AgentRollout -.->|"installs"| WinEndpoints
    AgentRollout -.->|"enrolls"| WazuhMgr
  end

  subgraph "E) Phase Roadmap (Phases 1–4 lifecycle)"
    P1["Phase 1: Proxmox + pfSense + base networking"]:::phase
    P2["Phase 2: AD DS/DNS + segmentation hardening + secure DNS mapping"]:::phase
    P3["Phase 3: Wazuh SIEM + agents + syslog + IDS/IPS integration"]:::phase
    P4["Phase 4: Endpoint Protection/EDR (Kaspersky) + validation"]:::phase

    P1 --> P2 --> P3 --> P4
  end

  %% Cross-diagram conceptual links (keep vertical)
  RepoReadme -->|"defines"| P1
  RepoReadme -->|"defines"| P2
  RepoReadme -->|"defines"| P3
  RepoReadme -->|"defines"| P4

  RepoDocs -->|"documents"| P1
  RepoDocs -->|"documents"| P2
  RepoDocs -->|"documents"| P3
  RepoDocs -->|"documents"| P4

  RepoConfigs -->|"stores-exports-for"| pfSense
  RepoConfigs -->|"stores-exports-for"| WazuhMgr
  RepoConfigs -->|"stores-exports-for"| DC
  RepoConfigs -->|"stores-exports-for"| IDSSensor

  RepoScripts -->|"automates"| Proxmox
  RepoScripts -->|"rollout"| AgentRollout

  RepoAssets -->|"diagram-pack-output"| Proxmox
  RepoAssets -->|"diagram-pack-output"| pfSense
  RepoAssets -->|"diagram-pack-output"| WazuhDash
  RepoAssets -->|"diagram-pack-output"| DC

  %% Later-stage EDR integration (dashed telemetry + dotted management)
  KSC -.->|"manages"| EDRagents
  EDRagents -.->|"security-events (optional)"| WazuhMgr

  %% Click Events (from component mapping)
  click RepoReadme "https://github.com/0xcgz/project-mursad/blob/main/README.md"
  click RepoDocs "https://github.com/0xcgz/project-mursad/tree/main/docs/"
  click RepoAssets "https://github.com/0xcgz/project-mursad/tree/main/assets/"
  click RepoConfigs "https://github.com/0xcgz/project-mursad/tree/main/configs/"
  click RepoScripts "https://github.com/0xcgz/project-mursad/tree/main/scripts/"

  %% =========================
  %% Styles (color + shapes)
  %% =========================
  classDef repo fill:#0B3A53,stroke:#7DD3FC,stroke-width:2px,color:#E6F6FF
  classDef infra fill:#2B2F36,stroke:#9CA3AF,stroke-width:2px,color:#F9FAFB
  classDef bridge fill:#374151,stroke:#A3A3A3,stroke-width:2px,color:#F9FAFB
  classDef wan fill:#3B0A0A,stroke:#EF4444,stroke-width:2px,color:#FFECEC
  classDef lan fill:#062E1F,stroke:#22C55E,stroke-width:2px,color:#EFFFF7
  classDef dmz fill:#3A1F00,stroke:#F59E0B,stroke-width:2px,color:#FFF7E6
  classDef mgmt fill:#1F2937,stroke:#60A5FA,stroke-width:2px,color:#EAF2FF
  classDef pfsense fill:#111827,stroke:#F97316,stroke-width:3px,color:#FFF7ED
  classDef server fill:#0F172A,stroke:#93C5FD,stroke-width:2px,color:#EEF2FF
  classDef endpoint fill:#052F3A,stroke:#22D3EE,stroke-width:2px,color:#ECFEFF
  classDef attacker fill:#2A0F1E,stroke:#F43F5E,stroke-width:2px,color:#FFF1F2
  classDef soc fill:#2D1B4E,stroke:#A78BFA,stroke-width:2px,color:#F5F3FF
  classDef socui fill:#3B1D6A,stroke:#C4B5FD,stroke-width:2px,color:#F5F3FF
  classDef db fill:#1F2A44,stroke:#818CF8,stroke-width:2px,color:#EEF2FF
  classDef ids fill:#2A2410,stroke:#FBBF24,stroke-width:2px,color:#FFFBEB
  classDef edr fill:#123018,stroke:#34D399,stroke-width:2px,color:#ECFDF5
  classDef id fill:#0B2447,stroke:#60A5FA,stroke-width:2px,color:#EAF2FF
  classDef pipe fill:#1F2937,stroke:#E5E7EB,stroke-width:2px,color:#F9FAFB
  classDef socout fill:#312E81,stroke:#A5B4FC,stroke-width:2px,color:#EEF2FF
  classDef admin fill:#111827,stroke:#FDE68A,stroke-width:2px,color:#FFFBEB
  classDef phase fill:#0F2E2E,stroke:#5EEAD4,stroke-width:2px,color:#E6FFFB
  classDef note fill:#111827,stroke:#D1D5DB,stroke-dasharray: 4 3,stroke-width:1.5px,color:#F9FAFB
```
