# projectdiscovery/interactsh architecture

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

- Interactive diagram: https://gitdiagram.com/projectdiscovery/interactsh
- Repository: https://github.com/projectdiscovery/interactsh

## Overview

##### Major Components
- Client Side:
– Interactsh Client: Found under “cmd/interactsh-client” and “pkg/client”. This component generates unique payloads, polls for interactions, displays or logs outbound event data, and supports different features (AES encryption, verbose mode, session persistence, etc.).
– Benchmark Clients: Located under “cmd/benchmark-server” demonstrating performance aspects.
– CLI Options: Various flags and configurations are implemented in “pkg/options” to tweak payload generation and session behavior.
- Server Side:
– Interactsh Server: Found under “cmd/interactsh-server” and key server logic in “pkg/server”. The server handles multiple protocols (DNS, HTTP, SMTP, LDAP, FTP, SMB, etc.), manages dynamic responses, wildcard interactions, and integrates with external DNS records.
– ACME Integration & TLS Support: Under “pkg/server/acme”, the server hosts automatic certificate generation and renewal.
– Storage & Logging: “pkg/storage” deals with storing interaction data (in-memory or disk-based), while “pkg/filewatcher” can be used for monitoring changes.
- Deployment and Integrations:
– Deployment configurations, Dockerfiles, and workflow scripts (in “.github” and “deploy”) indicate CI/CD, containerization and deployment practices.
– External Extensions: The README details integrations with tools like Burp Suite, OWASP ZAP, and Caido Proxy.

##### Architectural Relationships and Data Flow
- Separation between Frontend and Backend: Although not a full-stack web application, the separation of client (payload generator/poller) and server (interaction listener and responder) is fundamental. The client generates payloads that are then triggered externally (via DNS lookups, HTTP requests, etc.), and those events are funneled into the server.
- Multi-Protocol Support:
- Interaction Lifecycle:
– Show the client sending out requests (or simply “payload generation”) which then crosses to external targets.
– Capture how external systems’ interaction (for example, a DNS query or HTTP request) flows back to the server.
- Configuration and Extensibility:
– Include an “options/configurations” node representing the command line flags and configuration files (e.g., go.mod, YAML configs) that allow users to modify payload length, security options (authentication, token usage) and service endpoints.
– Highlight the use of dynamic response features (query-parameter driven HTTP responses) and static file hosting via “-http-directory”, emphasizing customization.

##### Key Architectural Patterns and Design Principles
- Modular Design: The strict separation between “cmd”, “internal”, and “pkg” directories shows that the project follows a modular approach. Represent each logical module (client, server, storage, options, and ACME integration) as separate blocks.
- Containerization & CI/CD: The presence of Dockerfiles in “.github/docker” and numerous GitHub workflows (build, test, release) suggests robust automation. Illustrate these as peripheral but integrated development and deployment tools ensuring quality and repeatability.

- Within the server block, subdivide into modules based on services: DNS, HTTP/HTTPS, SMTP/SMTPS, LDAP, and additional services (FTP, SMB, Responder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Zone
    subgraph "Client Zone"
        I1["Interactsh Client (cmd)"]:::client
        I2["Interactsh Client (pkg)"]:::client
        BC["Benchmark Clients"]:::client
        CO["CLI Options"]:::client
    end

    %% External Networks
    subgraph "External Networks"
        EX["External Interactions<br/>(DNS,HTTP,SMTP,LDAP,FTP,SMB)"]:::external
    end

    %% Server Zone
    subgraph "Server Zone"
        subgraph "Server Core"
            S1["Interactsh Server (cmd)"]:::server
            S2["Interactsh Server (pkg)"]:::server
        end
        subgraph "Protocol Services"
            DNS["DNS Service<br/>(TCP/UDP 53)"]:::server
            HTTP["HTTP/HTTPS Service<br/>(80/443)"]:::server
            SMTP["SMTP Service"]:::server
            LDAP["LDAP Service"]:::server
            FTP["FTP Service"]:::server
            SMB["SMB Service"]:::server
        end
        subgraph "Supporting Modules"
            ACME["ACME Integration & TLS"]:::server
            ST["Storage"]:::server
            FW["File Watcher"]:::server
        end
        subgraph "External Integrations"
            EXT["External Tools<br/>(Burp,OWASP_ZAP,Caido)"]:::integration
        end
    end

    %% Deployment & CI/CD Zone
    subgraph "Deployment & CI/CD"
        GHW["GitHub Workflows"]:::deploy
        DEP["Deploy Scripts"]:::deploy
    end

    %% Arrows from Client Zone to External Networks
    I1 --> EX
    I2 --> EX
    BC --> EX
    CO --> EX

    %% Arrows from External Networks to Protocol Services
    EX --> DNS
    EX --> HTTP
    EX --> SMTP
    EX --> LDAP
    EX --> FTP
    EX --> SMB

    %% Arrows from Protocol Services to Server Core
    DNS --> S1
    HTTP --> S1
    SMTP --> S1
    LDAP --> S1
    FTP --> S1
    SMB --> S1

    %% Arrows from Supporting Modules to Server Core
    ACME --> S1
    ST --> S1
    FW --> S1

    %% Bidirectional arrow between External Integrations and Server Core
    EXT <--> S1

    %% Arrows from Deployment & CI/CD to key components
    GHW --> I1
    GHW --> S1
    DEP --> I1
    DEP --> S1

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef server fill:#FFCCCB,stroke:#000,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef deploy fill:#DDA0DD,stroke:#000,stroke-width:2px;

    %% Click Events
    click I1 "https://github.com/projectdiscovery/interactsh/tree/main/cmd/interactsh-client"
    click I2 "https://github.com/projectdiscovery/interactsh/tree/main/pkg/client"
    click BC "https://github.com/projectdiscovery/interactsh/tree/main/cmd/benchmark-server"
    click CO "https://github.com/projectdiscovery/interactsh/tree/main/pkg/options"
    click S1 "https://github.com/projectdiscovery/interactsh/tree/main/cmd/interactsh-server"
    click S2 "https://github.com/projectdiscovery/interactsh/tree/main/pkg/server"
    click ACME "https://github.com/projectdiscovery/interactsh/tree/main/pkg/server/acme"
    click ST "https://github.com/projectdiscovery/interactsh/tree/main/pkg/storage"
    click FW "https://github.com/projectdiscovery/interactsh/tree/main/pkg/filewatcher"
    click GHW "https://github.com/projectdiscovery/interactsh/blob/main/.github"
    click DEP "https://github.com/projectdiscovery/interactsh/tree/main/deploy"
```
