# sbousseaden/evtx-attack-samples architecture

> Architecture diagram of the GitHub repository sbousseaden/evtx-attack-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sbousseaden/evtx-attack-samples
- Repository: https://github.com/sbousseaden/evtx-attack-samples

## Overview

##### Main Components

- EVTX Sample Repository – The heart of the project consists of many directories (e.g., AutomatedTestingTools, Command and Control, Credential Access, Defense Evasion, Discovery, Lateral Movement, Persistence, Privilege Escalation, and Other). Each directory represents a category of attack or a group of related event log samples mapped to MITRE ATT&CK techniques.

- EVTX Metadata Module – The “EVTX_ATT&CK_Metadata” directory includes scripts (Python scripts such as BinaryParser.py, Evtx.py, etc.) and a Jupyter Notebook that likely help parse and analyze EVTX logs, providing metadata extraction and possibly transformation.

- External Tools/Services – Refer to Winlogbeat (an external tool by Elastic) indicated in the README. This tool is used to parse the EVTX files and forward events to a destination, such as an ELK stack or another output file (.json). Represent this external dependency as part of the system.

##### Relationships and Interactions

- The EVTX event log files are stored in the neat, categorized folder structure. These files are “fed” into the Winlogbeat-Bulk-Read script.

- Winlogbeat, as configured by the winlogbeat_example.yml (or winlogbeat.yml if present) in the directory, then forwards data to a destination. That destination might be an ELK stack (Elasticsearch, Logstash, Kibana) or a local file (./winlogbeat/events.json). Represent this as an output component.

- Optionally, if the EVTX-to-Xml.ps1 or EVTX metadata processing is used, highlight an alternate data transformation path that converts binary EVTX logs into XML or enriched metadata for further analysis.

##### Important Architectural Patterns and Design Principles

- Modular Organization – The clear directory segmentation by attack technique shows a modular design where each “module” (or directory) encapsulates specific types of events.

- Pipeline/Dataflow Pattern – The design follows a data ingestion pipeline: Event Log Repository → Bulk Read Ingestion Script → Winlogbeat Parser → Output Destination.

- Separation of Concerns – The repository cleanly separates storage (files categorized by technique) from processing (PowerShell script and winlogbeat configuration) and metadata extraction (Python scripts in EVTX_ATT&CK_Metadata).

##### Final Reminders

- Every component is clearly labeled with its function (e.g., “EVTX Repository – Categorized Attack Logs”, “Bulk Log Parser – Winlogbeat-Bulk-Read.ps1”, “Log Forwarder – winlogbeat”, “Destination – events.json / ELK”).

- Be as detailed as possible, even if that means breaking down the repository into several logical modules. The goal is to capture all essential parts of the pipeline—from EVTX collection, through processing, to eventual log aggregation/output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% EVTX Sample Repository Subgraph
    subgraph "EVTX Sample Repository - Categorized Logs"
        Repo["Data Repository\n(EVTX Files)"]:::repo
        at["AutomatedTestingTools"]:::repo
        cc["Command and Control"]:::repo
        ca["Credential Access"]:::repo
        de["Defense Evasion"]:::repo
        di["Discovery"]:::repo
        ex["Execution"]:::repo
        lm["Lateral Movement"]:::repo
        pe["Persistence"]:::repo
        pr["Privilege Escalation"]:::repo
        oth["Other"]:::repo

        at --> Repo
        cc --> Repo
        ca --> Repo
        de --> Repo
        di --> Repo
        ex --> Repo
        lm --> Repo
        pe --> Repo
        pr --> Repo
        oth --> Repo
    end

    %% EVTX Metadata Module
    meta["EVTX Metadata Module"]:::meta

    %% Bulk Log Parser Component
    bulk["Bulk Log Parser\n(Winlogbeat-Bulk-Read.ps1)"]:::ing

    %% Winlogbeat Configuration Node
    config["Configuration\n(winlogbeat_example.yml)"]:::ing

    %% External Winlogbeat Service
    wb["Winlogbeat Parser\n(winlogbeat.exe)"]:::external

    %% Output Destination
    out["Output Destination\n(ELK Stack / events.json)"]:::output

    %% Data Flow
    Repo -->|"ReadEVTX"| bulk
    Repo -->|"OptionalMetadataExtraction"| meta
    meta -->|"TransformEnrich"| bulk
    bulk -->|"UsesConfig"| config
    bulk -->|"PassEventData"| wb
    wb -->|"ForwardEventData"| out

    %% Click Events for EVTX Sample Repository Directories
    click at "https://github.com/sbousseaden/evtx-attack-samples/tree/master/AutomatedTestingTools"
    click cc "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Command and Control"
    click ca "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Credential Access"
    click de "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Defense Evasion"
    click di "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Discovery"
    click ex "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Execution"
    click lm "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Lateral Movement"
    click pe "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Persistence"
    click pr "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Privilege Escalation"
    click oth "https://github.com/sbousseaden/evtx-attack-samples/tree/master/Other"

    %% Click Events for Other Components
    click meta "https://github.com/sbousseaden/evtx-attack-samples/tree/master/EVTX_ATT&CK_Metadata"
    click bulk "https://github.com/sbousseaden/evtx-attack-samples/blob/master/Winlogbeat-Bulk-Read.ps1"
    click config "https://github.com/sbousseaden/evtx-attack-samples/blob/master/winlogbeat_example.yml"

    %% Styles
    classDef repo fill:#D1E8FF,stroke:#1E88E5,stroke-width:2px;
    classDef meta fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef ing fill:#E8FFD1,stroke:#43A047,stroke-width:2px;
    classDef external fill:#FFE8D1,stroke:#FB8C00,stroke-width:2px;
    classDef output fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
```
