How 0xzdh/o365spray works
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.