How jmk-foofus/medusa works
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: ssh.c Service modules · medusa.c Input planner · configure.ac Autotools build · Makefile.am Core build rules
Components 17
Build & packaging
- Autotools build · Configures platform support and builds the executable and loadable modules.
configure.ac - Core build rules
src/Makefile.am - Module build rules · Builds independently loadable protocol .mod files.
src/modsrc/Makefile.am
Core execution
- Medusa CLI · Parses options and orchestrates audit execution.
src/medusa.c - Application contracts
src/medusa.h - Input planner · Expands hosts, users, passwords, and combinations into login work.
src/medusa.c - Thread-pool scheduler · Runs bounded parallel authentication attempts and manages workers.
src/medusa-thread-pool.c - Network layer
src/medusa-net.c - Thread TLS · Provides secure connections for protocol workers.
src/medusa-thread-ssl.c - Results & diagnostics · Records attempt outcomes and control-relevant diagnostics.
src/medusa-trace.c
Protocol modules
- Module interface · Defines the core-to-service-module authentication boundary.
src/modsrc/module.h - Service modules · Perform service-specific handshakes, authentication, and response classification.
src/modsrc/ssh.c - NTLM / SMB2 primitives
src/modsrc/ntlm.c
Other components
- Host inputs
sample/hosts.txt - User inputs
sample/users.txt - Combination inputs
sample/combo.txt - Remote endpoints · SSH, HTTP, SMB, FTP, mail, database, RDP, VNC, SNMP, and other targets.
Connections 18
- 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