# 0xzdh/o365spray architecture

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

- Interactive diagram: https://gitdiagram.com/0xzdh/o365spray
- Repository: https://github.com/0xzdh/o365spray

## Overview

##### Project Type and Purpose
- o365spray is an open-source, command-line Python tool for Office 365 user-enumeration and password-spraying.
- It provides three main actions: validation (validator), enumeration (enumerator), and spraying (sprayer), each with modular back-ends for different O365 endpoints or techniques.

##### High-Level File-Structure Analysis
- Top-level scripts:
- o365spray.py (entrypoint)
- o365spray/__main__.py (CLI wrapper)
- Core package (o365spray/core):
- handlers – divides into three subpackages: validator, enumerator, sprayer
– each has a generic handler class and a modules/ folder with concrete strategy implementations (e.g., oauth2.py, autodiscover.py)
- utils – shared utilities (logging, HTTP defaults, coloring, writer)
- resc/user-agents.txt – data asset for User-Agent randomization
- static – images and docs referenced by README
- setup.py, requirements.txt – packaging and dependencies

##### Key Architectural Patterns
- Strategy Pattern:
- Core handler classes load a chosen “module” at runtime based on CLI flags (`--enum-module`, `--spray-module`, etc.).
- Factory or Handler Resolver:
- Maps CLI inputs to specific module classes.
- Concurrency:
- A ThreadPoolExecutor is used to parallelize HTTP requests (controlled via `--rate` and `--poolsize`).
- HTTP Client Abstraction:
- All network calls go through helper utilities that handle timeouts, proxies (FireProx), jitter, and user-agent randomization.

##### Major System Components
A. CLI Layer
- Parses arguments (validate, enum, spray, modules, domain, files, timeouts).
B. Controller / Runner
- __main__.py instantiates the proper CoreHandler (Validator, Enumerator, or Sprayer).
- Passes config object to handler.
C. Core Handlers
- ValidatorHandler → modules/getuserrealm.py
- EnumeratorHandler → modules/{autodiscover, oauth2, office, onedrive, rst}.py
- SprayerHandler → modules/{activesync, adfs, autodiscover, autologon, oauth2, reporting, rst}.py
D. Shared Utilities
- Logger & Helper (colorized console output, debug flags)
- HTTP Request Wrapper (handles throttling, jitter, timeouts, proxies, user-agents)
- Writer (collects and writes results to disk)
E. Concurrency Engine
- ThreadPoolExecutor / rate-limiting logic
F. External Services
- Microsoft endpoints (Autodiscover, OAuth2, ActiveSync, ADFS, Office.com, OneDrive, Reporting API)
- Optional FireProx proxies (via `--proxy-url`)
G. Data Assets
- User list / Password list (files)
- User-Agent list (resc/user-agents.txt)
- Output directories and logs

##### Relationships & Data Flow
1) User invokes `o365spray` with flags →
2) CLI Layer → Controller → Core Handler selection →
3) Handler loads chosen Module class →
4) Module spins up N worker tasks in ThreadPool →
5) Each task uses HTTP Utility to issue a request to target endpoint or proxy →
6) Responses are normalized by module →
7) Results passed to Writer utility →
8) Results and logs are emitted to console and output directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI1["o365spray.py"]:::code
        CLI2["__main__.py"]:::code
    end
    CLI1 --> CLI2
    CLI2 --> Controller["Controller / Runner"]:::code

    click CLI1 "https://github.com/0xzdh/o365spray/blob/master/o365spray.py"
    click CLI2 "https://github.com/0xzdh/o365spray/blob/master/o365spray/__main__.py"
    click Controller "https://github.com/0xzdh/o365spray/blob/master/o365spray/__main__.py"

    %% Core Handlers
    subgraph "Core Handlers" 
        subgraph "ValidatorHandler" 
            VHandler["validate.py"]:::code
            subgraph "Validator Modules"
                VM_base["base.py"]:::code
                VM_get["getuserrealm.py"]:::code
            end
        end
        subgraph "EnumeratorHandler"
            EHandler["enumerate.py"]:::code
            subgraph "Enumerator Modules"
                EM_base["base.py"]:::code
                EM_auto["autodiscover.py"]:::code
                EM_alog["autologon.py"]:::code
                EM_oauth["oauth2.py"]:::code
                EM_office["office.py"]:::code
                EM_drive["onedrive.py"]:::code
                EM_rst["rst.py"]:::code
            end
        end
        subgraph "SprayerHandler"
            SHandler["spray.py"]:::code
            subgraph "Sprayer Modules"
                SM_base["base.py"]:::code
                SM_act["activesync.py"]:::code
                SM_adfs["adfs.py"]:::code
                SM_auto["autodiscover.py"]:::code
                SM_alog["autologon.py"]:::code
                SM_oauth["oauth2.py"]:::code
                SM_rep["reporting.py"]:::code
                SM_rst["rst.py"]:::code
            end
        end
    end

    click VHandler "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/validator/validate.py"
    click VM_base "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/validator/modules/base.py"
    click VM_get "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/validator/modules/getuserrealm.py"

    click EHandler "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/enumerate.py"
    click EM_base "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/base.py"
    click EM_auto "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/autodiscover.py"
    click EM_alog "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/autologon.py"
    click EM_oauth "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/oauth2.py"
    click EM_office "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/office.py"
    click EM_drive "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/onedrive.py"
    click EM_rst "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/enumerator/modules/rst.py"

    click SHandler "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/spray.py"
    click SM_base "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/base.py"
    click SM_act "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/activesync.py"
    click SM_adfs "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/adfs.py"
    click SM_auto "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/autodiscover.py"
    click SM_alog "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/autologon.py"
    click SM_oauth "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/oauth2.py"
    click SM_rep "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/reporting.py"
    click SM_rst "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/sprayer/modules/rst.py"

    Controller --> VHandler
    Controller --> EHandler
    Controller --> SHandler

    %% Handler Base & Concurrency
    subgraph "Handler Base & Concurrency" 
        Base["base.py\n(ThreadPoolExecutor & Resolver)"]:::concurrency
    end

    click Base "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/handlers/base.py"

    VHandler --> Base
    EHandler --> Base
    SHandler --> Base

    %% Shared Utilities
    subgraph "Shared Utilities"
        Logger["logger.py"]:::code
        Colors["colors.py"]:::code
        Defaults["defaults.py"]:::code
        Helper["helper.py"]:::code
        Writer["writer.py"]:::code
        UtilsInit["__init__.py"]:::code
    end

    click Logger "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/utils/logger.py"
    click Colors "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/utils/colors.py"
    click Defaults "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/utils/defaults.py"
    click Helper "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/utils/helper.py"
    click Writer "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/utils/writer.py"
    click UtilsInit "https://github.com/0xzdh/o365spray/blob/master/o365spray/core/utils/__init__.py"

    Base --> Logger
    Base --> Defaults
    Base --> Colors
    Base --> Helper
    Base --> Writer

    %% HTTP Utility Path
    Defaults --> HTTPUtil["HTTP Request Wrapper"]:::code
    Helper --> HTTPUtil

    %% Data Assets
    subgraph "Data Assets"
        UA["user-agents.txt"]:::data
        Users["users.txt"]:::data
        Passwords["passwords.txt"]:::data
    end

    click UA "https://github.com/0xzdh/o365spray/blob/master/resc/user-agents.txt"

    Users -.-> VHandler
    Users -.-> EHandler
    Users -.-> SHandler
    Passwords -.-> SHandler
    UA -.-> HTTPUtil

    %% External Services
    External["O365 Endpoints & FireProx"]:::external

    HTTPUtil -->|"HTTP request"| External
    External -->|"HTTP response"| HTTPUtil

    HTTPUtil --> ModuleRes["Module Response\n(normalized)"]:::code
    ModuleRes --> Writer

    Writer --> Output["Output Directory & Logs"]:::data

    %% Data Flow from CLI
    CLI2 -->|"flags & files"| Users
    CLI2 -->|"flags & files"| Passwords

    %% Legend
    subgraph "Legend"
        L1["Rectangle: Code Module"]:::code
        L2["Cylinder: Data Asset"]:::data
        L3["Cloud: External Service"]:::external
        L4["Purple: Concurrency"]:::concurrency
    end

    classDef code fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef data fill:#FFE5B4,stroke:#E69A00,color:#E69A00;
    classDef external fill:#D4F5D4,stroke:#28A745,color:#28A745;
    classDef concurrency fill:#E8D0FF,stroke:#6F42C1,color:#6F42C1;
```
