# ad-security/ad_miner architecture

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

- Interactive diagram: https://gitdiagram.com/ad-security/ad_miner
- Repository: https://github.com/ad-security/ad_miner

## Overview

##### Project Type and Purpose
- AD Miner is an auditing tool focused on analyzing Active Directory (on-premise and Entra ID) environments.
- It leverages Neo4j (unified with BloodHound data) and uses Cypher queries to detect weaknesses in directory configurations.
- The tool produces static, web-based reports with dynamic graphs and historical indicators to track AD risks and mitigation paths.
- It also supports advanced features – multi-threading, cluster queries, caching and integration with neo4j’s Graph Data Science plugin for “smartest paths.”

##### Analyzing the File Structure
- The top-level directory contains support files like CONTRIBUTING, license documents, CI/CD configurations (GitHub workflows), and hooks.
- The main code is contained in the “ad_miner” directory that includes the __main__.py file for launching the tool.
- The “ad_miner/scripts” directory contains helper scripts (like anon_graphdb.py for anonymizing Neo4j graph data).
- “ad_miner/sources” is divided into HTML and JS folders containing front-end assets (Bootstrap, CSS, JavaScript, templates, and UI components) so that auditing reports are rendered in a dynamic, web-based format.
- The “ad_miner/sources/modules” folder holds most of the core business logic, consisting of classes (cache_class, card_class, graph_class, etc.), various controls in the "controls" subdirectory, and utility functions. These implement the actual data processing and analysis (querying Neo4j, formatting results, etc.).
- Other files (requirements, pyproject.toml, poetry.toml) show how the project is packaged, which is common for command-line Python applications.

##### Components and Architectural Overview
- Input/External Data Source:
– Neo4j Database running BloodHound data (accessed using a bolt protocol, default on port 7687).
– Optionally, data extracted via third-party tools (SharpHound, AzureHound, etc.) prior to reporting.
- Data Connector / API Layer:
– The main AD Miner script (ad_miner/__main__.py) serves as the entry point.
– Modules in “sources/modules” (e.g., neo4j_class, path_neo4j) handle the actual connection to the Neo4j database, control query execution (via Cypher queries), and incorporate the Graph Data Science plugin.
- Business Logic Layer:
– Several specialized “controls” (in sources/modules/controls) implement the auditing checks for Kerberos, Passwords, and Permissions.
– Utility modules (e.g., logger.py, utils.py, config.json) which manage configuration, logging, cache handling, and multi-threading support.
– Support for smart path computation – determining exploitability using additional logic that selects between shortest and “smartest” paths.
- Presentation/Reporting Layer:
– Web-based Report Generation:
- The “sources/html” directory (with its assets, templates, Bootstrap CSS/JS, components, and cards) provides the dynamic presentation.
- JavaScript files (such as graph.js, main_circle.js, search_bar.js) add interactivity to the report.
– The report integrates graphs, cards, tables, and evolution views over time with interactive elements.
- Caching & Parallel Processing:
– Cache mechanisms (cache_class and cache files generated during runs) allow storing results of expensive Neo4j queries.
– Support for multi-threading and clustering (allowing use of multiple neo4j nodes with parameters like –nb_chunks and –nb_cores).
- Deployment & CI/CD:
– Files such as GitHub workflows and configuration files are there for continuous integration and packaging.
– Packaging details support various Linux distributions and pipx installation.

##### Architectural Patterns and Design Principles
- Layer Separation: Clear separation between data extraction (Neo4j connection and queries), business logic (controls, processing, caching), and presentation (HTML/JS web interface).
- Modularity: Each control is implemented as a separate module, promoting single-responsibility.
- Extensibility: The file structure (especially under “controls”) exhibits how new auditing checks can be added.
- Scalability: Use of multi-threading and cluster support indicates that the system is built to handle large datasets and parallel processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources"
        extNeo["Neo4j Database (BloodHound Data)"]:::database
        extThird["Third-Party Tools (SharpHound,AzureHound)"]:::external
    end

    %% Data Connector & API Layer
    subgraph "Data Connector & API Layer"
        launcher["AD Miner Launcher (__main__.py)"]:::connector
        neoClass["Neo4j Class"]:::connector
        pathNeo["Path Neo4j"]:::connector
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        controls["Controls Modules"]:::business
        logger["Logger"]:::business
        utils["Utils"]:::business
        cache["Cache Manager"]:::business
        gds["Graph Data Science Plugin"]:::business
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        html["Web Report Generator (HTML Templates & Assets)"]:::presentation
        js["JS Interactivity"]:::presentation
    end

    %% Auxiliary Scripts (Support Tools)
    aux["Auxiliary Scripts"]:::aux

    %% Connections from External Data to Data Connector
    extNeo -->|"Bolt/Cypher"| neoClass
    extNeo -->|"Bolt/Cypher"| pathNeo
    extThird -->|"DataExtraction"| neoClass

    %% Connections inside Data Connector & API Layer
    launcher --> neoClass
    launcher --> pathNeo

    %% Connections from Data Connector to Business Logic
    neoClass --> controls
    pathNeo --> controls
    neoClass -->|"GDSintegration"| gds
    gds --> controls

    %% Business Logic internal interactions
    controls --> logger
    controls --> utils
    controls --> cache

    %% Connections from Business Logic to Presentation Layer
    controls --> html
    controls --> js

    %% Auxiliary Scripts support Business Logic
    aux --> controls

    %% Click Events
    click launcher "https://github.com/ad-security/ad_miner/blob/main/ad_miner/__main__.py"
    click neoClass "https://github.com/ad-security/ad_miner/blob/main/ad_miner/sources/modules/neo4j_class.py"
    click pathNeo "https://github.com/ad-security/ad_miner/blob/main/ad_miner/sources/modules/path_neo4j.py"
    click controls "https://github.com/ad-security/ad_miner/tree/main/ad_miner/sources/modules/controls"
    click logger "https://github.com/ad-security/ad_miner/blob/main/ad_miner/sources/modules/logger.py"
    click utils "https://github.com/ad-security/ad_miner/blob/main/ad_miner/sources/modules/utils.py"
    click cache "https://github.com/ad-security/ad_miner/blob/main/ad_miner/sources/modules/cache_class.py"
    click html "https://github.com/ad-security/ad_miner/tree/main/ad_miner/sources/html"
    click js "https://github.com/ad-security/ad_miner/tree/main/ad_miner/sources/js"
    click aux "https://github.com/ad-security/ad_miner/tree/main/ad_miner/scripts"

    %% Styles
    classDef external fill:#bbd1ff,stroke:#000,stroke-width:2px;
    classDef connector fill:#c3f9c3,stroke:#000,stroke-width:2px;
    classDef business fill:#ffe4b5,stroke:#000,stroke-width:2px;
    classDef presentation fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef aux fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef database fill:#add8e6,stroke:#000,stroke-width:2px;
```
