# zmap/zgrab2 architecture

> Architecture diagram of the GitHub repository zmap/zgrab2, 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/zmap/zgrab2
- Repository: https://github.com/zmap/zgrab2

## Overview

- Core Scanning Engine: This is the heart of the application, likely started from the main command in cmd/zgrab2. It processes input (via CSV/STDIN), parses configuration files, and dispatches scan jobs.
- Module Framework: Show a dedicated component for “Modules” (located in the modules/ directory) which plug into the engine. Emphasize that new protocols are added as modules by satisfying the Scanner, ScanModule, and ScanFlags interfaces.
- Input Processing: Represent the CSV/STDIN input parser (see input.go and related tests) that transforms target lines (IP, DOMAIN, TAG, PORT) into scan tasks. Add support for expanding CIDR blocks.
- Output Processing: Illustrate the pipeline that gathers detailed handshake transcripts and outputs JSON or structured files. Indicate usage of the lib/output section for processing and exporting results.
- Schema and Post-Processing: Include the “zgrab2_schemas” component which provides schemas for various modules and feeds into offline analysis.
- CLI and Configuration: Add a component for the command-line interface that supports “single module usage” and “multiple module usage” (via configuration .ini files) along with flag processing.
- External Tools/Dependencies: Note integration with ZMap (which identifies L4 responsive hosts) and Docker for containerized operation, as well as Python for integration test validations.

##### Relationships and Data Flow
- Inputs (CSV/STDIN) → Input Parser → Core Scanning Engine.
- Core Engine: Routes targets based on either direct CLI parameters or section-based configuration (for the multiple modules use case) to the corresponding scanning modules.
- Each module (HTTP, SSH, FTP, etc.) takes targets, performs protocol-specific handshakes, and then returns detailed transcripts.
- Handshake Data → Output Processing → File/JSON Output → Validation/Offline Analysis (using schemas).
- Additionally, command-line parameters and configuration files feed into the module initialization process (note the modules’ init() calls registering themselves with the world).

##### Architectural Patterns and Design Principles
- Modularity and Extensibility: The design clearly separates protocol-specific logic into discrete modules.
- Plugin-like registration: New protocols are added using a registration mechanism in Go’s init() functions.
- Separation of Concerns: Distinct components for input parsing, scan execution, output processing, and integration testing.
- Containerized testing approach: Use of Docker and integration_tests for reliable end-to-end validation.
- Consistent CLI and configuration-driven execution enabling both simple one-off scans and complex multi-module scans.

##### Technologies, Frameworks, and Libraries
- Language/Toolchain: Go (version 1.23 required; auto-downloading support from Go 1.21+).
- Docker: For containerized execution and integration testing (see Dockerfile, docker-runner, integration_tests).
- Python: For running integration tests (requirements.txt, use of zschema, and integration_tests/test.py).
- External dependency: ZMap for preliminary host discovery.
- Logging and Error Handling: Modules like errors.go are used to manage scanning errors.

##### Be Detailed
- You illustrate every major directory or file group that has architectural significance. For example, indicate that the “integration_tests” folder supports automated testing and that “zgrab2_schemas” provides output schema functionality.
- That relationships (such as dependency injection of configuration, the use of environment variables, and external orchestration via Docker) are clearly shown.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scan Core Subgraph
    subgraph "Scan Core"
        CLIConfig["CLI and Configuration"]:::cli
        InputProcessing["Input Processing (CSV/STDIN Parser)"]:::input
        CoreEngine["Core Scanning Engine"]:::engine
        ModuleFramework["Module Framework"]:::module
        OutputProcessing["Output Processing"]:::output
        SchemaPost["Schema and Post-Processing"]:::schema
    end

    %% Testing Infrastructure Subgraph
    subgraph "Testing Infrastructure"
        IntegrationTest["Integration Test Harness"]:::test
        DockerRunner["Docker Runner"]:::external
        PythonRequirements["Python Integration (requirements.txt)"]:::external
    end

    %% External Dependency (ZMap)
    ZMap["ZMap"]:::external

    %% Connections within Scan Core
    CLIConfig -->|"feeds"| CoreEngine
    InputProcessing -->|"parses input"| CoreEngine
    CoreEngine -->|"dispatches scan jobs"| ModuleFramework
    ModuleFramework -->|"returns handshake transcripts"| OutputProcessing
    OutputProcessing -->|"formats output"| SchemaPost

    %% External dependency connection
    ZMap -->|"pre-scan host discovery"| CoreEngine

    %% Connections within Testing Infrastructure
    DockerRunner -->|"provides container environment"| IntegrationTest
    PythonRequirements -->|"runs integration tests"| IntegrationTest
    IntegrationTest -->|"triggers scan routines"| CoreEngine
    IntegrationTest -->|"validates output"| SchemaPost

    %% Styles
    classDef engine fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef input fill:#cce5ff,stroke:#004080,stroke-width:2px;
    classDef output fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef schema fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef cli fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef test fill:#d9d9d9,stroke:#666666,stroke-width:2px;
    classDef external fill:#f0e68c,stroke:#b8860b,stroke-width:2px;

    %% Click Events
    click CLIConfig "https://github.com/zmap/zgrab2/tree/master/cmd/zgrab2/"
    click InputProcessing "https://github.com/zmap/zgrab2/blob/master/input.go"
    click CoreEngine "https://github.com/zmap/zgrab2/blob/master/cmd/zgrab2/main.go"
    click ModuleFramework "https://github.com/zmap/zgrab2/tree/master/modules/"
    click OutputProcessing "https://github.com/zmap/zgrab2/blob/master/lib/output/process.go"
    click SchemaPost "https://github.com/zmap/zgrab2/tree/master/zgrab2_schemas/"
    click IntegrationTest "https://github.com/zmap/zgrab2/tree/master/integration_tests/"
    click DockerRunner "https://github.com/zmap/zgrab2/tree/master/docker-runner/"
    click PythonRequirements "https://github.com/zmap/zgrab2/blob/master/requirements.txt"
```
