# jmk-foofus/medusa architecture

> Architecture diagram of the GitHub repository jmk-foofus/medusa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jmk-foofus/medusa
- Repository: https://github.com/jmk-foofus/medusa

## Overview

#### Purpose and execution model
Medusa is a native C command-line parallel network login auditor/brute-forcer. Its executable orchestrates credential attempts across hosts, users, and passwords, delegating protocol-specific authentication to dynamically selected service modules. Primary entry point: `src/medusa.c`; shared application contracts: `src/medusa.h`.

#### Build and runtime packaging
The project uses GNU Autotools to configure platform capabilities and build the core executable plus protocol `.mod` modules. Build definitions are rooted in `configure.ac`, `Makefile.am`, and `src/Makefile.am`; module build rules are in `src/modsrc/Makefile.am`. Runtime behavior depends on the executable locating the requested independently built module rather than linking every protocol implementation into core.

#### Input planning and target expansion
The core accepts individual values or files for hosts, usernames, passwords, and combination records, then transforms those inputs into login-attempt work. Sample input formats demonstrate this boundary: `sample/hosts.txt`, `sample/users.txt`, and `sample/combo.txt`. The planner must preserve the combinatorial relationship among target, credential, and selected module while enforcing configured concurrency.

#### Concurrent attempt scheduler
A thread-pool subsystem executes authentication work in parallel, enabling concurrency across hosts, accounts, or passwords. Core scheduling and worker lifecycle reside in `src/medusa-thread-pool.c` and `src/medusa-thread-pool.h`; the main control path is `src/medusa.c`. This is the central control boundary between credential/input planning and protocol network activity.

#### Protocol module boundary
Each remote service is implemented as a separate module conforming to the module interface in `src/modsrc/module.h`. Modules own protocol handshakes, authentication exchanges, response classification, and service-specific options; examples include `src/modsrc/ssh.c`, `src/modsrc/http.c`, and `src/modsrc/smbnt.c`. Supported external endpoints include SSH, HTTP, SMB, FTP, mail protocols, database servers, RDP, VNC, SNMP, and others.

#### Network, TLS, and protocol primitives
Core networking abstracts socket operations and connection handling through `src/medusa-net.c` and `src/medusa-net.h`. TLS support is isolated in `src/medusa-thread-ssl.c` and `src/medusa-thread-ssl.h`, likely allowing per-thread secure protocol connections. Protocol modules also embed or share authentication primitives where necessary, such as NTLM/SMB support in `src/modsrc/ntlm.c` and `src/modsrc/smbnt-smb2.c`.

#### Results, diagnostics, and extensibility
Attempt outcomes flow back from modules to core for reporting and control decisions (success, failure, retry/error, stop conditions). Utilities and trace/logging support this cross-cutting behavior in `src/medusa-utils.c`, `src/medusa-trace.c`, and `src/medusa-trace.h`. New services extend the system by implementing the module contract and adding the source to the module build, without changing the scheduler or input engine.

Main entry points: [`src/modsrc/ssh.c`](https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/ssh.c) (Service modules), [`src/medusa.c`](https://github.com/jmk-foofus/medusa/blob/master/src/medusa.c) (Input planner), [`configure.ac`](https://github.com/jmk-foofus/medusa/blob/master/configure.ac) (Autotools build), [`src/Makefile.am`](https://github.com/jmk-foofus/medusa/blob/master/src/Makefile.am) (Core build rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & packaging"]
  node_autotools{{"Autotools build<br/>build system<br/>[configure.ac]"}}
  node_core_build["Core build rules<br/>[Makefile.am]"]
  node_module_build["Module build rules<br/>[Makefile.am]"]
end

subgraph group_core["Core execution"]
  node_cli["Medusa CLI<br/>native executable<br/>[medusa.c]"]
  node_contracts["Application contracts<br/>core header<br/>[medusa.h]"]
  node_input_plan["Input planner<br/>attempt planning<br/>[medusa.c]"]
  node_scheduler["Thread-pool scheduler<br/>concurrent scheduler"]
  node_network["Network layer<br/>socket abstraction<br/>[medusa-net.c]"]
  node_tls["Thread TLS<br/>TLS support"]
  node_reporting["Results &amp; diagnostics<br/>reporting and tracing<br/>[medusa-trace.c]"]
end

subgraph group_modules["Protocol modules"]
  node_module_contract["Module interface<br/>plugin contract<br/>[module.h]"]
  node_service_modules["Service modules<br/>loadable protocol modules<br/>[ssh.c]"]
  node_smb_primitives["NTLM / SMB2 primitives<br/>authentication primitives<br/>[ntlm.c]"]
end

node_hosts["Host inputs<br/>sample input<br/>[hosts.txt]"]
node_users["User inputs<br/>sample input<br/>[users.txt]"]
node_combos["Combination inputs<br/>sample input<br/>[combo.txt]"]
node_remote_services(("Remote endpoints<br/>network services"))

node_autotools -->|"generates build"| node_core_build
node_autotools -->|"generates build"| node_module_build
node_core_build -->|"builds"| node_cli
node_module_build -->|"builds .mod files"| node_service_modules
node_hosts -->|"targets"| node_input_plan
node_users -->|"accounts"| node_input_plan
node_combos -->|"credential records"| node_input_plan
node_cli -->|"configures"| node_input_plan
node_contracts -.->|"shared contract"| node_cli
node_input_plan -->|"attempt work"| node_scheduler
node_scheduler -->|"selects module"| node_module_contract
node_module_contract -->|"implemented by"| node_service_modules
node_service_modules -->|"connections"| node_network
node_service_modules -.->|"secure sessions"| node_tls
node_service_modules -.->|"SMB authentication"| node_smb_primitives
node_service_modules -->|"authenticates against"| node_remote_services
node_service_modules -->|"attempt outcomes"| node_reporting
node_reporting -->|"status and control"| node_cli

click node_autotools "https://github.com/jmk-foofus/medusa/blob/master/configure.ac"
click node_core_build "https://github.com/jmk-foofus/medusa/blob/master/src/Makefile.am"
click node_module_build "https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/Makefile.am"
click node_cli "https://github.com/jmk-foofus/medusa/blob/master/src/medusa.c"
click node_contracts "https://github.com/jmk-foofus/medusa/blob/master/src/medusa.h"
click node_input_plan "https://github.com/jmk-foofus/medusa/blob/master/src/medusa.c"
click node_hosts "https://github.com/jmk-foofus/medusa/blob/master/sample/hosts.txt"
click node_users "https://github.com/jmk-foofus/medusa/blob/master/sample/users.txt"
click node_combos "https://github.com/jmk-foofus/medusa/blob/master/sample/combo.txt"
click node_scheduler "https://github.com/jmk-foofus/medusa/blob/master/src/medusa-thread-pool.c"
click node_network "https://github.com/jmk-foofus/medusa/blob/master/src/medusa-net.c"
click node_tls "https://github.com/jmk-foofus/medusa/blob/master/src/medusa-thread-ssl.c"
click node_module_contract "https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/module.h"
click node_service_modules "https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/ssh.c"
click node_smb_primitives "https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/ntlm.c"
click node_reporting "https://github.com/jmk-foofus/medusa/blob/master/src/medusa-trace.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_autotools,node_core_build,node_module_build toneBlue
class node_cli,node_contracts,node_input_plan,node_scheduler,node_network,node_tls,node_reporting toneAmber
class node_module_contract,node_service_modules,node_smb_primitives toneMint
class node_hosts,node_users,node_combos,node_remote_services toneNeutral
```

## Components

### Build & packaging

- [Autotools build](https://github.com/jmk-foofus/medusa/blob/master/configure.ac): build system · Configures platform support and builds the executable and loadable modules. · `configure.ac`
- [Core build rules](https://github.com/jmk-foofus/medusa/blob/master/src/Makefile.am): build rules · `src/Makefile.am`
- [Module build rules](https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/Makefile.am): build rules · Builds independently loadable protocol .mod files. · `src/modsrc/Makefile.am`

### Core execution

- [Medusa CLI](https://github.com/jmk-foofus/medusa/blob/master/src/medusa.c): native executable · Parses options and orchestrates audit execution. · `src/medusa.c`
- [Application contracts](https://github.com/jmk-foofus/medusa/blob/master/src/medusa.h): core header · `src/medusa.h`
- [Input planner](https://github.com/jmk-foofus/medusa/blob/master/src/medusa.c): attempt planning · Expands hosts, users, passwords, and combinations into login work. · `src/medusa.c`
- [Thread-pool scheduler](https://github.com/jmk-foofus/medusa/blob/master/src/medusa-thread-pool.c): concurrent scheduler · Runs bounded parallel authentication attempts and manages workers. · `src/medusa-thread-pool.c`
- [Network layer](https://github.com/jmk-foofus/medusa/blob/master/src/medusa-net.c): socket abstraction · `src/medusa-net.c`
- [Thread TLS](https://github.com/jmk-foofus/medusa/blob/master/src/medusa-thread-ssl.c): TLS support · Provides secure connections for protocol workers. · `src/medusa-thread-ssl.c`
- [Results & diagnostics](https://github.com/jmk-foofus/medusa/blob/master/src/medusa-trace.c): reporting and tracing · Records attempt outcomes and control-relevant diagnostics. · `src/medusa-trace.c`

### Protocol modules

- [Module interface](https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/module.h): plugin contract · Defines the core-to-service-module authentication boundary. · `src/modsrc/module.h`
- [Service modules](https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/ssh.c): loadable protocol modules · Perform service-specific handshakes, authentication, and response classification. · `src/modsrc/ssh.c`
- [NTLM / SMB2 primitives](https://github.com/jmk-foofus/medusa/blob/master/src/modsrc/ntlm.c): authentication primitives · `src/modsrc/ntlm.c`

### Other components

- [Host inputs](https://github.com/jmk-foofus/medusa/blob/master/sample/hosts.txt): sample input · `sample/hosts.txt`
- [User inputs](https://github.com/jmk-foofus/medusa/blob/master/sample/users.txt): sample input · `sample/users.txt`
- [Combination inputs](https://github.com/jmk-foofus/medusa/blob/master/sample/combo.txt): sample input · `sample/combo.txt`
- **Remote endpoints**: network services · SSH, HTTP, SMB, FTP, mail, database, RDP, VNC, SNMP, and other targets.

## Connections

- Autotools build → Core build rules: generates build
- Autotools build → Module build rules: generates build
- Core build rules → Medusa CLI: builds
- Module build rules → Service modules: builds .mod files
- Host inputs → Input planner: targets
- User inputs → Input planner: accounts
- Combination inputs → Input planner: credential records
- Medusa CLI → Input planner: configures
- Application contracts → Medusa CLI: shared contract
- Input planner → Thread-pool scheduler: attempt work
- Thread-pool scheduler → Module interface: selects module
- Module interface → Service modules: implemented by
- Service modules → Network layer: connections
- Service modules → Thread TLS: secure sessions
- Service modules → NTLM / SMB2 primitives: SMB authentication
- Service modules → Remote endpoints: authenticates against
- Service modules → Results & diagnostics: attempt outcomes
- Results & diagnostics → Medusa CLI: status and control