# withsecurelabs/drozer architecture

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

- Interactive diagram: https://gitdiagram.com/withsecurelabs/drozer
- Repository: https://github.com/withsecurelabs/drozer

## Overview

##### Main components of the system
- Console/Client: Represented by the drozer CLI (found in src/drozer/cli and related modules) that the security tester uses.
- Agent (Server-side on Android): The drozer Agent runs on the Android device and provides the “Embedded Server” functionality. Note that installation instructions (using adb) refer directly to installing the drozer Agent.
- API and Communication Infrastructure: There are robust API components defined for handling system requests/responses (src/drozer/api and similar paths in pysolar/api) plus protobuf interfaces (common/protobuf.proto) used for communication between parts.
- Exploits & Modules: There is a vast suite of modules (e.g., src/drozer/modules, subdirectories for app, auxiliary, exploit, scanner, etc.) where each module encapsulates a security test or exploit.
- Build and Packaging Infrastructure: The presence of Docker, Debian and RPM packaging scripts, and build instructions in README indicate that the build and deployment pipelines are also important.
- Supporting Libraries: There are common utilities (e.g., src/WithSecure/common) and additional helper libraries such as for reflection (pysolar/reflection) and payloads.

##### Relationships and interactions
- The drozer Console (CLI) initiates connections (over network or via adb port-forwarding) to the Agent running on the Android device.
- Once connected, the Console sends commands that are handled by the Agent’s server component. The Agent then uses the API handlers (from src/drozer/api/handlers) to process requests and return responses.
- Many modules lie in between – they encapsulate specific functionalities (e.g., scanning, exploiting, payload delivery). The Console can call these modules, which in turn might use common libraries and modules to perform their operations.
- Additionally, build and packaging components (Dockerfile, build scripts in “scripts”) wrap the code to enable deployment and distribution on multiple systems.

##### Architectural patterns and principles
- Modularity: The repository is split into many independent modules (for exploits, scanners, and payloads) to allow extensibility.
- Client–Server Interaction: The separation between the drozer Console (client) and the Agent (server) defines clear boundaries with network-based communication.
- Abstraction via APIs: The clear API endpoints (system request/response, reflection APIs) abstract the underlying Android interactions.
- Layer separation: Notice how core utilities (common directory) support both the drozer and pysolar functionalities, meaning shared libraries are abstracted for reuse.
- Extensibility: With directories for module installers (repoman), payload generation, and even for additional tests (test folder), the design supports extensibility and testing.

##### Relevant external technologies
- Python3 (source code written in Python)
- Java libraries (for components like agent.jar, android-support libraries)
- Protobuf for structured messaging (seen in common/protobuf.proto and in pysolar/api)
- Twisted (asynchronous networking framework used by some parts)
- Docker (containerization setup for deployment)
- Dependencies such as PyOpenSSL, Distro, and Java SDK are also essential.

- A “Communication Layer” component that shows network channels (TCP port 31415) or USB (adb port forwarding).
- API Handlers (system_request_handler, etc.)
- Module Execution Engine (modules folder)
- Connector Components (server/protocols, server/receivers)
- Built-in Web Server functionality (web_root, uploader)
- A “Common Libraries and Utilities” segment that supports both parts (common, pysolar, modules/common).
- A “Build & Packaging” area showing Docker, deb & rpm scripts, and packaging routines that wrap the overall application.
- Optionally, a “Testing” component showing where tests exist to validate functionality (test folder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        C1["drozer Console (Client)"]:::client
    end

    %% Communication Layer
    subgraph "Communication Layer"
        COM["Communication Layer (TCP/adb)"]:::communication
    end

    %% Agent/Server Layer
    subgraph "Agent/Server Layer"
        subgraph "Agent Subcomponents"
            A1["Agent Manager"]:::server
            A2["API Handlers"]:::server
            A3["Exploit Modules"]:::server
            A4["Connectors"]:::server
            S1["Server Functionality"]:::server
        end
    end

    %% API & Communication Infrastructure
    subgraph "API & Communication Infrastructure"
        API_COMPONENTS["API Components"]:::api
        APIB["API Builders (pysolar)"]:::api
        PROTO["Protobuf Interfaces"]:::api
    end

    %% Supporting Libraries & Utilities
    subgraph "Supporting Libraries & Utilities"
        CLIB["Common Utilities"]:::common
        HLIB["Helper Libraries"]:::common
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        DOCK["Docker Build"]:::build
        DEB["Debian Packaging"]:::build
        RPM["RPM Packaging"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EXT1["Python3"]:::external
        EXT2["Java SDK & Libraries"]:::external
        EXT3["Twisted"]:::external
        EXT4["Docker"]:::external
    end

    %% Connections
    C1 -->|"initiates"| COM
    COM -->|"establishes"| A1

    A1 -->|"delegates"| A2
    A1 -->|"executes"| A3
    A1 -->|"uses"| A4
    A1 -->|"invokes"| S1
    A1 -->|"accesses"| CLIB
    A1 -->|"uses"| HLIB

    A2 -->|"calls"| API_COMPONENTS
    A2 -->|"interfaces"| APIB
    A2 -->|"formats"| PROTO
    A2 -->|"accesses"| CLIB

    A3 -->|"utilizes"| CLIB

    HLIB -->|"supports"| APIB

    %% Build & Packaging interactions (illustrative; not runtime interactions)
    DOCK -.-> A1
    DEB -.-> A1
    RPM -.-> A1

    %% External Dependencies connections
    EXT1 --> C1
    EXT2 --> A1
    EXT3 --> A2
    EXT4 --> DOCK

    %% Click Events
    click C1 "https://github.com/withsecurelabs/drozer/blob/develop/src/drozer/cli/console.py"
    click A1 "https://github.com/withsecurelabs/drozer/blob/develop/src/drozer/agent/manager.py"
    click S1 "https://github.com/withsecurelabs/drozer/blob/develop/src/drozer/server/dz.py"
    click A4 "https://github.com/withsecurelabs/drozer/blob/develop/src/drozer/connector/server_connector.py"
    click API_COMPONENTS "https://github.com/withsecurelabs/drozer/tree/develop/src/drozer/api"
    click PROTO "https://github.com/withsecurelabs/drozer/blob/develop/common/protobuf.proto"
    click APIB "https://github.com/withsecurelabs/drozer/tree/develop/src/pysolar/api"
    click A3 "https://github.com/withsecurelabs/drozer/tree/develop/src/drozer/modules"
    click DOCK "https://github.com/withsecurelabs/drozer/tree/develop/docker/Dockerfile"
    click DEB "https://github.com/withsecurelabs/drozer/blob/develop/scripts/deb/control.template"
    click RPM "https://github.com/withsecurelabs/drozer/blob/develop/scripts/rpm/drozer.spec"
    click CLIB "https://github.com/withsecurelabs/drozer/tree/develop/src/WithSecure/common"
    click HLIB "https://github.com/withsecurelabs/drozer/tree/develop/src/drozer/lib"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef communication fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef api fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef common fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef build fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
