How ahmedkhlief/apt-hunter works
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.