# cravaterouge/bloodyad architecture

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

- Interactive diagram: https://gitdiagram.com/cravaterouge/bloodyad
- Repository: https://github.com/cravaterouge/bloodyad

## Overview

##### Project Type and Purpose
- bloodyAD is a specialized security tool focused on Active Directory privilege escalation via LDAP calls. It is essentially a command-line engine that leverages multiple authentication methods (cleartext, pass-the-hash, pass-the-ticket, and certificate-based authentication) to interact with domain controllers.
- The tool also includes features such as a SOCKS proxy support and various formatting modules to output AD-related information (like DNS, LDAP types, winerror, etc.).
- Given its focus and structure, the project fits into the category of a security/penetration testing tool for AD environments rather than a full-stack web application.

##### Analysis of File Structure
- The top-level directories and files include:
- Directories like .github (for CI/CD workflows and funding information) and tests (for different testing levels).
- The main application package is "bloodyAD", containing key sub-directories:
▪ asciitree – Likely in charge of creating ASCII representations of hierarchical data (perhaps for visualizing directory structure within AD).
▪ cli_modules – Contains modules for specific CLI commands (add, get, remove, set) which are used to perform AD operations.
▪ formatters – Houses various modules for formatting output related to access controls, AD schema, DNS, cryptography, etc.
▪ network – Contains network configuration and LDAP interactions (e.g. connecting to the domain controller).
▪ Additionally, files such as main.py act as the entry point of the application, whereas exceptions.py and utils.py are helper modules.
- Configuration files (pyproject.toml, requirements.txt) indicate dependency management and project configuration.
- The tests directory shows that comprehensive unit, functional, and integration tests are provided, suggesting modular design and clear separation of concerns.

a. CLI Interface:
- Representing the command parsing layer that directs which CLI module (add, get, remove, set) gets executed.
b. Core Engine:
- Coordinates high-level operations by calling handler functions within respective modules.
c. Network Layer:
- Manages LDAP connections, authentication (including different strategies: cleartext, pass-the-hash, ticket, certificates) and possibly integration with SOCKS proxies.
- Implement the LDAP communication logic (found in the "network" directory).
d. Formatting Modules:
- This collection converts raw data (from Active Directory responses) into human-readable output (using different formatters like for DNS, access controls, etc.).
e. AsciiTree:
- Visualizes hierarchical or tree-structured data extracted from Active Directory.
f. Error Handling:
- Modules like exceptions.py which capture and handle application-specific errors.
g. Utility Functions:
- Reusable functions and helpers defined in utils.py.
h. External Dependencies & Third-party Libraries:
- Although not all external libraries are directly visible in the tree, the README mentions dependencies on libraries like MSLDAP and impacket. These should be represented as external services or libraries the system integrates with.

##### Relationships and Interactions
- The CLI Interface receives a user's command and parameters, then triggers the matching module in cli_modules.
- Each CLI module then invokes functions in the Core Engine that, depending on the function, use the Network Layer to interact with a Domain Controller over LDAP.
- The Network Layer is responsible for utilizing the specified authentication methods (driven by configurations or command-line parameters) and establishing communication with AD domain controllers.
- Retrieved data is processed by Formatting Modules to output results (e.g., structured AD data, DNS information, access control lists) in a user-friendly format.
- The AsciiTree component might come into play when the output requires visualizing the AD structure.
- Utility and exception handling modules support all these interactions by providing shared logic and error management.
- External libraries (like MSLDAP and impacket) are integrated within the network functionality to perform low-level LDAP operations and AD-specific attacks.

##### Architectural Patterns and Design Principles
- Modular Design: The separation into multiple directories (cli_modules, formatters, network, asciitree) indicates that each component encapsulates a specific responsibility.
- Layered Architecture: There is a clear separation between the user interface (CLI), business logic (core engine/cli_modules), network communication, and output formatting.
- Extendibility: Clear extension points exist within the CLI and formatting modules, making it easier to introduce additional AD operations.
- Error Handling and Testing: A robust error handling mechanism with dedicated exception modules and a suite of tests suggests emphasis on reliability.

## Diagram (Mermaid)

```mermaid
graph TD
    CLI["CLI Interface"]:::core
    Engine["Core Engine"]:::core
    Network["Network Layer<br/>(LDAP, Authentication, SOCKS)"]:::core
    Formatters["Formatting Modules<br/>(Output Formatting)"]:::core
    Ascii["AsciiTree<br/>(AD Structure Visualization)"]:::core
    External["External Dependencies<br/>(impacket, MSLDAP)"]:::external
    ErrorHandler["Error Handling<br/>(exceptions.py)"]:::utility
    Utility["Utility Functions<br/>(utils.py)"]:::utility

    CLI -->|"parsesCommand"| Engine
    Engine -->|"callsLDAP"| Network
    Engine -->|"formatsOutput"| Formatters
    Engine -->|"generatesTree"| Ascii
    Network -->|"integratesWith"| External
    Utility ---|"supports"| Engine
    ErrorHandler ---|"managesErrors"| Engine
    Utility ---|"supports"| CLI
    ErrorHandler ---|"handlesErrors"| CLI

    click CLI "https://github.com/cravaterouge/bloodyad/tree/main/bloodyAD/cli_modules"
    click Engine "https://github.com/cravaterouge/bloodyad/blob/main/bloodyAD/main.py"
    click Network "https://github.com/cravaterouge/bloodyad/tree/main/bloodyAD/network"
    click Formatters "https://github.com/cravaterouge/bloodyad/tree/main/bloodyAD/formatters"
    click Ascii "https://github.com/cravaterouge/bloodyad/tree/main/bloodyAD/asciitree"
    click ErrorHandler "https://github.com/cravaterouge/bloodyad/blob/main/bloodyAD/exceptions.py"
    click Utility "https://github.com/cravaterouge/bloodyad/blob/main/bloodyAD/utils.py"

    classDef core fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef external fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef utility fill:#FFECB3,stroke:#F57C00,stroke-width:2px;
```
