# punk-security/smbeagle architecture

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

- Interactive diagram: https://gitdiagram.com/punk-security/smbeagle
- Repository: https://github.com/punk-security/smbeagle

## Overview

##### Project type and purpose
- SMBeagle is a cross-platform CLI tool (written in C#/.NET Core) for auditing SMB file shares.
- It discovers networks, finds hosts, enumerates shares and files, tests permissions, and outputs results to CSV and/or Elasticsearch (with an optional Kibana dashboard).

##### File structure
Top-level organization:
- Program.cs + SMBeagle.sln/.csproj – entry point and solution.
- Enums – shared enumerations (Authors, Directory, Network, ShareType).
- NetworkDiscovery – scans local adapters and network ranges for TCP/445.
- HostDiscovery – filters alive SMB hosts on discovered networks.
- ShareDiscovery – finds shares on each host (Windows via Win32, Linux via SMBLibrary).
- FileDiscovery – crawls share directory trees, inspects file ACLs and permissions, and (optionally) fetches files.
- Output – interfaces and helpers to write results to CSV or Elasticsearch.
- Kibana – supporting Docker compose and ndjson for dashboard.
- tests – integration/unit tests in Python and Dockerfiles for CI.
- CI/CD: .github/workflows, Dockerfile, Dockerignore.

##### README for architectural insights
- There is a schematic (“Docs/schematic.png”) outlining a pipeline:
– Network candidate generation → TCP scan → SMB host detection → Share enumeration → File enumeration/permission checks → Output.
- Modules are loosely coupled, enabling easy extension.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Modules
    Program["CLI Launcher / Orchestrator\n(Program.cs)"]:::core

    %% Discovery Modules
    subgraph "Discovery Modules"
        direction TB
        ND["NetworkDiscovery\nproduces List<Network>"]:::core
        HD["HostDiscovery\nproduces List<Host>"]:::core
        SD["ShareDiscovery\nproduces List<Share>"]:::core
        FD["FileDiscovery\nproduces FilePermissionPayloads"]:::core
    end

    %% Platform Adapters
    subgraph "Platform Adapters"
        direction TB
        W32["Win32 API\n(strategy)"]:::adapter
        SMBLib["SMBLibrary\n(strategy)"]:::adapter
    end

    %% Output Modules
    subgraph "Output Modules"
        direction TB
        CSV["CSV Writer\n(writes local file)"]:::storage
        ESClient["Elasticsearch Client\n(posts to ES)"]:::storage
    end

    %% External Systems
    ESCluster["Elasticsearch Cluster"]:::external
    Kibana["Kibana Dashboard"]:::external

    %% Configuration & Enums
    Enums["Shared Enums / Config"]:::config

    %% CI/CD & Tests
    subgraph "CI/CD & Tests"
        direction TB
        GHActions["GitHub Actions\nbuild & tests"]:::ci
        DockerBuild["Docker Build / Dockerfile"]:::ci
        Tests["Tests & Scripts"]:::ci
    end

    %% Relations
    Program -->|"start"| ND
    ND -->|"List<Network>"| HD
    HD -->|"List<Host>"| SD
    SD -->|"List<Share>"| FD
    FD -->|"File ACL results"| CSV
    FD -->|"File ACL results"| ESClient
    Program -->|"invoke Output"| CSV
    Program -->|"invoke Output"| ESClient

    FD -->|"uses"| W32
    FD -->|"uses"| SMBLib

    ESClient -->|"posts"| ESCluster
    ESCluster -->|"visualize"| Kibana

    Program -->|"load enums"| Enums

    GHActions --> DockerBuild
    DockerBuild --> Tests

    %% Click Events
    click Program "https://github.com/punk-security/smbeagle/blob/main/Program.cs"
    click ND "https://github.com/punk-security/smbeagle/tree/main/NetworkDiscovery"
    click HD "https://github.com/punk-security/smbeagle/tree/main/HostDiscovery"
    click SD "https://github.com/punk-security/smbeagle/tree/main/ShareDiscovery"
    click FD "https://github.com/punk-security/smbeagle/tree/main/FileDiscovery"
    click CSV "https://github.com/punk-security/smbeagle/tree/main/Output"
    click ESClient "https://github.com/punk-security/smbeagle/tree/main/Output"
    click Enums "https://github.com/punk-security/smbeagle/tree/main/Enums"
    click Kibana "https://github.com/punk-security/smbeagle/tree/main/Kibana"
    click GHActions "https://github.com/punk-security/smbeagle/blob/main/.github/workflows/build_preview.yml"
    click GHActions "https://github.com/punk-security/smbeagle/blob/main/.github/workflows/build_release.yml"
    click DockerBuild "https://github.com/punk-security/smbeagle/tree/main/Dockerfile"
    click DockerBuild "https://github.com/punk-security/smbeagle/blob/main/.dockerignore"
    click Tests "https://github.com/punk-security/smbeagle/tree/main/tests"
    
    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef adapter fill:#FFE5B4,stroke:#d67100,color:#d67100;
    classDef storage fill:#FFF3CD,stroke:#d39e00,color:#d39e00;
    classDef external fill:#D4F8E8,stroke:#18844f,color:#18844f;
    classDef config fill:#E2E3E5,stroke:#6C757D,color:#6C757D;
    classDef ci fill:#E8D0FF,stroke:#6f42c1,color:#6f42c1;
```
