How ad-security/ad_miner works
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.