# falconforceteam/soaphound architecture

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

- Interactive diagram: https://gitdiagram.com/falconforceteam/soaphound
- Repository: https://github.com/falconforceteam/soaphound

## Overview

##### Project Overview and Purpose
- SOAPHound is a .NET command-line tool that collects Active Directory data over the AD Web Services (ADWS) protocol.
- It acts as an alternative to LDAP-based tools (like SharpHound) by wrapping LDAP queries in SOAP messages and communicating using NET TCP binding.
- The tool has various collection modes such as building a cache of domain objects, generating BloodHound compatible outputs (bhdump, certdump), and dumping AD integrated DNS data.
- It is essentially a collection/processing pipeline that takes command-line options and produces JSON files (and a cache) as outputs.

##### Analyzing the File Structure
- The top-level files (Program.cs, SOAPHound.sln, SOAPHound.csproj, packages.config) indicate a C# console application.
- The “ADWS” folder contains the core components to interface with Active Directory via ADWS. Files like ADWSConnector.cs represent a dedicated module for SOAP-based communications with Domain Controllers.
- The “Enums” folder holds various constants and enumerations that support the domain objects (LDAPProperties, DomainTrusts, etc).
- The “Processors” directory has separate processor modules (e.g., DomainProcessor, UserProcessor, OUProcessor, etc.) that encapsulate the business logic of extracting and processing different types of AD objects.
- The “OutputTypes” folder shows how the tool formats or structures the output data (e.g., CANodes, GPOs, etc).
- Additional utility classes and configuration files (e.g., Options.cs, FodyWeavers.xml) provide support (logging, weaving, command-line options parsing, etc).

##### Key Components and Their Roles
a. Main Application Entry (Program.cs & CLI Parser):
- Represents the starting point where command-line arguments (such as --buildcache, --bhdump, --dnsdump, --certdump, etc.) are processed.
- Routes the execution flow based on the selected mode and authentication options.

b. ADWS Communication Layer:
- Located in the ADWS folder, this includes ADWSConnector.cs and related classes.
- Manages the connection to the ADWS service on a Domain Controller.
- Encapsulates SOAP message creation, transmission, and receiving responses.
- Should be represented as an external service boundary reflecting its communication with an external ADWS server on the AD Domain Controller.

c. Processors:
- Each processor (e.g., DomainProcessor, OUProcessor, UserProcessor, GroupProcessor) handles a specific aspect of Active Directory data retrieval or cache building.
- They consume data from the ADWS Connector and process/transform it into an internal representation.
- They also potentially communicate with each other to build relationships (e.g., linking groups to users, containers to domains).

d. Output Generation Module:
- Housed under the OutputTypes folder, these modules take processed data and format it for final output (e.g., JSON for BloodHound consumption).
- They are responsible for generating cache files and various dumps (BloodHound, DNS, and ADCS data).

e. Supporting Libraries and Enumerations:
- The Enums folder along with auxiliary files like Options.cs act as internal dependencies that define properties, settings, and constants used across the application.
- They form the “glue” that standardizes data structures and configurations.

##### Relationships and Data Flows
- Based on these options, the application instantiates the ADWS Connector to establish a connection with the AD Domain Controller.
- The ADWS Connector sends SOAP-wrapped LDAP queries to retrieve data.
- Data returned from ADWS is passed into various processors (one processor per data type, such as Domain, User, OU, Group, etc.) to extract, transform, and (if needed) build caches.
- The processed data is directed into Output Modules (e.g., CANodes, GPOs) to produce JSON files or other formats for consumption by tools such as BloodHound.
- Additionally, configuration and enumerations flow into both the processors and the connection layer, ensuring that data types and settings are standardized.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        Program["Program.cs"]:::cliStyle
        Options["Options.cs"]:::cliStyle
    end

    %% ADWS Communication Layer
    subgraph "ADWS Communication Layer"
        ADWSConnector["ADWS Connector"]:::communication
        ADObject["AD Object"]:::communication
        Reference["Reference"]:::communication
    end

    %% External AD Domain Controller
    ADServer(("AD Domain Controller")):::external

    %% Processors (Business Logic)
    subgraph "Processors"
        DomainProcessor["DomainProcessor"]:::processor
        UserProcessor["UserProcessor"]:::processor
        OUProcessor["OUProcessor"]:::processor
        GroupProcessor["GroupProcessor"]:::processor
        ACLProcessor["ACLProcessor"]:::processor
        ContainerProcessor["ContainerProcessor"]:::processor
    end

    %% Output Generation Module
    subgraph "Output Generation Module"
        CANodes["CANodes"]:::output
        GPOs["GPOs"]:::output
        NodeOutput["Node"]:::output
        TypedPrincipal["TypedPrincipal"]:::output
    end

    %% Supporting Libraries and Enumerations
    subgraph "Supporting Components"
        Enums["Enums"]:::support
        FodyWeavers["FodyWeavers.xml"]:::support
    end

    %% Data Flow Arrows
    Program -->|"parses CLI args"| ADWSConnector
    Options --> ADWSConnector
    ADWSConnector -->|"SOAP Query"| ADServer
    ADWSConnector -->|"retrieves AD Data"| DomainProcessor
    ADWSConnector --> UserProcessor
    ADWSConnector --> OUProcessor
    ADWSConnector --> GroupProcessor
    ADWSConnector --> ACLProcessor
    ADWSConnector --> ContainerProcessor

    Enums -.-> ADWSConnector
    FodyWeavers -.-> ADWSConnector
    Enums -.-> DomainProcessor
    FodyWeavers -.-> DomainProcessor

    DomainProcessor -->|"processes data"| CANodes
    UserProcessor --> GPOs
    OUProcessor --> NodeOutput
    GroupProcessor --> TypedPrincipal
    ACLProcessor --> CANodes
    ContainerProcessor --> GPOs

    %% Styles
    classDef cliStyle fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef communication fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef processor fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef output fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef support fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

    %% Click Events for CLI Layer
    click Program "https://github.com/falconforceteam/soaphound/blob/main/Program.cs"
    click Options "https://github.com/falconforceteam/soaphound/blob/main/Options.cs"

    %% Click Events for ADWS Communication Layer
    click ADWSConnector "https://github.com/falconforceteam/soaphound/blob/main/ADWS/ADWSConnector.cs"
    click ADObject "https://github.com/falconforceteam/soaphound/blob/main/ADWS/ADObject.cs"
    click Reference "https://github.com/falconforceteam/soaphound/blob/main/ADWS/Reference.cs"

    %% Click Events for Processors
    click DomainProcessor "https://github.com/falconforceteam/soaphound/blob/main/Processors/DomainProcessor.cs"
    click UserProcessor "https://github.com/falconforceteam/soaphound/blob/main/Processors/UserProcessor.cs"
    click OUProcessor "https://github.com/falconforceteam/soaphound/blob/main/Processors/OUProcessor.cs"
    click GroupProcessor "https://github.com/falconforceteam/soaphound/blob/main/Processors/GroupProcessor.cs"
    click ACLProcessor "https://github.com/falconforceteam/soaphound/blob/main/Processors/ACLProcessor.cs"
    click ContainerProcessor "https://github.com/falconforceteam/soaphound/blob/main/Processors/ContainerProcessor.cs"

    %% Click Events for Output Generation Module
    click CANodes "https://github.com/falconforceteam/soaphound/blob/main/OutputTypes/CANodes.cs"
    click GPOs "https://github.com/falconforceteam/soaphound/blob/main/OutputTypes/GPOs.cs"
    click NodeOutput "https://github.com/falconforceteam/soaphound/blob/main/OutputTypes/Node.cs"
    click TypedPrincipal "https://github.com/falconforceteam/soaphound/blob/main/OutputTypes/TypedPrincipal.cs"

    %% Click Events for Supporting Components
    click Enums "https://github.com/falconforceteam/soaphound/tree/main/Enums"
    click FodyWeavers "https://github.com/falconforceteam/soaphound/blob/main/FodyWeavers.xml"
```
