# ahmedkhlief/apt-hunter architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedkhlief/apt-hunter
- Repository: https://github.com/ahmedkhlief/apt-hunter

## Overview

##### Project Type & Purpose
- Identification: APT-Hunter is a specialized, command-line threat-hunting tool targeted at analyzing Windows event logs. Its purpose is to scan, detect, and report suspicious events using prebuilt detection modules (including heuristics and Sigma rule-based detection) with an emphasis on statistical analysis.
- Core Use Cases: It supports filtering via time frames, searching using strings or regex, and applying Sigma rules for threat detection.

##### File Structure
- Key Files & Directories:
- Top-level Python scripts: APT-Hunter.py (main entry point) and APT-Hunter_old.py.
- The lib directory houses detection modules (e.g., CSVDetection.py, EvtxDetection.py, EvtxHunt.py, O365Hunter.py, SigmaHunter.py, Banner.py), alongside a configuration subfolder (with sigma-converter rules config).
- Shell scripts (Custom-Sigma-Convertor.sh, Get_Latest_Sigma_Rules.sh) and PowerShell scripts (windows-log-collector-full-v3-CSV.ps1, windows-log-collector-full-v3-EVTX.ps1) indicate external support for log collection and rule conversion.
- A set of sample reports in the Samples folder shows various output formats.
- The rules.json file holds detection rules, possibly used by the SigmaHunter module.

##### Review the README for Additional Insights
- Architecture hints: The README emphasizes using command-line parameters for different modes (e.g., basic analysis, time-framed search, regex or file pattern hunting, and Sigma rule application).
- Multiprocessing in V3.0: Indicates that the newer version leverages multiple processes—an important architectural detail.
- Data flow: Input logs are parsed then processed by several modules that extract specific events (logon events, process execution, object access, etc.), with outputs formatted as timeline-friendly CSV/Excel reports.

a. Components:
- User Interface & Input Handler:
- Command-line interface (CLI) via APT-Hunter.py, handles parameters (log file path, options like “-allreport”, “-start”, “-end”, “-hunt” etc.).
- Configuration Manager:
- Loads settings from requirements.txt, sigma-converter configuration (in lib/config), and rule definitions (rules.json).
- Core Processing Engine:
- Responsible for coordinating detection modules.
- Multiprocessing Manager: Oversees concurrent tasks (v3.0 focuses on multiprocessing to improve performance).
- Detection Modules (found in lib/):
- CSVDetection, EvtxDetection, and EvtxHunt: Parse and analyze different log formats.
- O365Hunter: Specialized module to examine Office 365 detection rules.
- SigmaHunter: Applies Sigma rules against logs.
- Banner: Likely used to display the tool’s title/info (UI/UX oriented).
- Rule Conversion & Updates:
- Shell scripts (Get_Latest_Sigma_Rules.sh, Custom-Sigma-Convertor.sh) interface with external Sigma repositories to convert/update detection rules.
- Data Output Generator:
- Formats output reports (CSV, Excel, XLS) for timeline tools. This module organizes data for direct visualization in third-party applications.
- External Log Collection:
- PowerShell scripts for collecting windows logs (CSV and EVTX) which feed data into the system.

b. Relationships & Interactions:
- The user invokes APT-Hunter.py, providing input paths and parameters.
- Configuration Manager initializes the environment, loading rule files and settings.
- Control hands off to the Processing Engine, which, using multiprocessing, dispatches the appropriate Detection Module based on input file type (CSV vs. EVTX).
- Detection Modules scan logs, apply both heuristic/regex and Sigma-based rule checks.
- Output Generator gathers findings from each module and produces formatted reports.
- Shell scripts and PowerShell scripts provide auxiliary functions (e.g., updating Sigma rules or collecting logs).

c. Architectural Patterns & Design Principles:
- Modular Design: Each detection capability is implemented as an independent module (e.g., CSVDetection, EvtxHunt), allowing easier updates and maintenance.
- Separation of Concerns: Input handling, rule management, detection processing, and reporting are clearly separated.
- Extensibility: The ability to add new detection modules or update Sigma rules externally indicates an extensible architecture.
- Multiprocessing: For performance improvement, especially when processing large log datasets.

d. Technologies & Frameworks:
- Python3: The primary programming language.
- Multiprocessing library: For concurrent processing of log files.
- YAML configuration: For sigma converter rules configuration.
- Shell/PowerShell Scripting: For external log collection and rule updating.
- Excel/CSV file formats: For output report generation.

##### Elements
- From user input to the CLI.
- From CLI to Configuration Manager.
- From Configuration Manager into the Processing Engine.
- From Processing Engine to each specialized detection module.
- From detection modules merging results into the Output Generator.
- A different style for scripts/auxiliary utilities.
- Another styling for external services (e.g., PowerShell log collectors or Sigma conversions).

##### Final Advice
- Avoid overcomplicating—modularizing the overall flow into input/configuration, processing (with detection modules), and output will clearly communicate the system architecture.
- Review the README outputs (screenshot samples) to understand the output process which is important for linking the detection stage to the report generation stage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Initialization
    CLI["User Input (APT-Hunter.py)"]:::core

    %% Configuration Layer
    CONFIG["Configuration Manager"]:::core
    CLI -->|"invokes"| CONFIG

    %% Processing Engine
    PROC["Core Processing Engine (Multiprocessing)"]:::core
    CONFIG -->|"loads_settings"| PROC

    %% Detection Modules
    subgraph "Detection Modules"
        direction TB
        CSV["CSVDetection Module"]:::core
        EVTX["EvtxDetection Module"]:::core
        EVTXH["EvtxHunt Module"]:::core
        O365["O365Hunter Module"]:::core
        SIGMA["SigmaHunter Module"]:::core
        BANNER["Banner (UI/UX)"]:::core

        PROC -->|"dispatches"| CSV
        PROC -->|"dispatches"| EVTX
        PROC -->|"dispatches"| EVTXH
        PROC -->|"dispatches"| O365
        PROC -->|"dispatches"| SIGMA
        PROC -->|"displays"| BANNER
    end

    %% Output Generation
    OUTPUT["Data Output Generator (Reports)"]:::core
    CSV -->|"produces_report"| OUTPUT
    EVTX -->|"produces_report"| OUTPUT
    EVTXH -->|"produces_report"| OUTPUT
    O365 -->|"produces_report"| OUTPUT
    SIGMA -->|"produces_report"| OUTPUT

    %% Auxiliary Utilities
    subgraph "Auxiliary Utilities"
        RULES["Rule Conversion & Updates"]:::script
        LOGCOLL["External Log Collection"]:::external

        RULES1["Custom-Sigma-Convertor.sh"]:::script
        RULES2["Get_Latest_Sigma_Rules.sh"]:::script
        LOGCSV["windows-log-collector-full-v3-CSV.ps1"]:::external
        LOGEVTX["windows-log-collector-full-v3-EVTX.ps1"]:::external

        RULES --> RULES1
        RULES --> RULES2
        LOGCOLL --> LOGCSV
        LOGCOLL --> LOGEVTX

        PROC -->|"integrates_rules"| RULES
        CLI -->|"triggers_collection"| LOGCOLL
    end

    %% Click Events
    click CLI "https://github.com/ahmedkhlief/apt-hunter/blob/main/APT-Hunter.py"
    click CONFIG "https://github.com/ahmedkhlief/apt-hunter/blob/main/requirements.txt"
    click CONFIG "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/config/sigma-converter-rules-config.yml"
    click CONFIG "https://github.com/ahmedkhlief/apt-hunter/blob/main/rules.json"
    click CSV "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/CSVDetection.py"
    click EVTX "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/EvtxDetection.py"
    click EVTXH "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/EvtxHunt.py"
    click O365 "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/O365Hunter.py"
    click SIGMA "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/SigmaHunter.py"
    click BANNER "https://github.com/ahmedkhlief/apt-hunter/blob/main/lib/Banner.py"
    click RULES1 "https://github.com/ahmedkhlief/apt-hunter/blob/main/Custom-Sigma-Convertor.sh"
    click RULES2 "https://github.com/ahmedkhlief/apt-hunter/blob/main/Get_Latest_Sigma_Rules.sh"
    click OUTPUT "https://github.com/ahmedkhlief/apt-hunter/tree/main/Samples"
    click LOGCSV "https://github.com/ahmedkhlief/apt-hunter/blob/main/windows-log-collector-full-v3-CSV.ps1"
    click LOGEVTX "https://github.com/ahmedkhlief/apt-hunter/blob/main/windows-log-collector-full-v3-EVTX.ps1"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef script fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
```
