mirror of
https://github.com/P-Aimon-Pen/ROFMAD
synced 2026-06-21 13:45:02 +00:00
paimon
332 lines
21 KiB
Markdown
Executable File
332 lines
21 KiB
Markdown
Executable File
# ROFMAD
|
|
**Rust Orchestrator For Modular Automated Discovery**
|
|
|
|
## Overview
|
|
|
|
ROFMAD is a comprehensive network reconnaissance and enumeration framework designed for security professionals conducting authorized penetration testing and vulnerability assessments. Built in Rust for performance and reliability, it provides automated discovery workflows with intelligent targeting and real-time monitoring.
|
|
|
|
ROFMAD is designed to run inside [Exegol](https://exegol.com) containers, which provide the consistent, pre-tooled penetration testing environment it assumes (nmap, masscan, arp-scan, tcpdump, chromium, etc.). But it can also be used in any security oriented linux distribution, only Windows is explicitely not supported.
|
|
|
|
## Philosophy
|
|
|
|
ROFMAD does not embed any LLM or AI component. There is no model deciding what to scan, what to exploit, or how to interpret results. It's simply an orchestration and automation layer built around the operator's own enumeration methodology and judgment. It surfaces data and runs the actions the pentester defines, but it never reasons or decides on their behalf.
|
|
|
|
The goal of the tool is to enumerate internal environments to find initial access. Its workflow design is inspired by the [Orange Cyberdefense internal pentest mindmap](https://orange-cyberdefense.github.io/ocd-mindmaps/).
|
|
|
|
Under the hood, ROFMAD is a single Rust binary built on the Tokio async runtime, with Axum serving the web interface, Askama rendering its templates, and SQLite (through sqlx) holding all project state.
|
|
|
|
The whole pipeline is driven by an internal hook system rather than a fixed script: each scan stage finishes by firing an event such as a host being added, a port scan completing, or a service scan completing, and a polling loop picks those events up every 2 seconds, checks each one against a deduplication set so nothing fires twice, and dispatches whatever stage comes next.
|
|
|
|
That same hook system is what lets your own workflow actions slot in once a host's reconnaissance is complete, without ROFMAD needing to know about them ahead of time. A set of semaphores, one per scan type such as Nmap, Subnet, Nuclei, and Screenshot, caps how many of each task can run at once, and that's exactly what the Dashboard and Queue's Concurrency Status grids are showing you in real time.
|
|
|
|
This is also where the YAML workflow system fits in. A workflow action is nothing more than a condition describing which hosts qualify and a command line to run against them, with the output checked against your own regex patterns to apply tags. ROFMAD has no built-in notion of nxc, nuclei, or any other specific tool, it just runs whatever command you give it once a host's reconnaissance is complete, and substitutes placeholders like `{{IP}}` and `{{HTTP_URL}}` along the way. That's what makes it future proof: bringing in a brand new tool, including ones that don't exist yet, never requires touching ROFMAD's code. You write a `specific_actions` entry pointing at the new binary, and the engine calls it exactly the same way it calls anything else.
|
|
|
|
### Key Features
|
|
|
|
- **Multi-Phase Reconnaissance**: Automated host discovery, port scanning, service detection, and HTTP enumeration
|
|
- **Intelligent Targeting**: YAML-based workflow system with condition-driven actions
|
|
- **Real-time Web Interface**: Modern dashboard for monitoring progress and analyzing results
|
|
- **Vulnerability Scanning**: Integrated Nuclei scanning (per-host and bulk, with tag/IP-CIDR filtering) with a severity-broken-down findings dashboard
|
|
- **Visual Recon**: Automated screenshots of discovered HTTP services
|
|
- **Database-Driven**: SQLite backend with full project state management and resume capability
|
|
- **High Performance**: Configurable concurrency with intelligent resource management
|
|
- **Safety Controls**: Built-in blacklisting and interface protection for safe scanning
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Discovery │────│ Enumeration │────│ HTTP Probing │
|
|
│ • DNS Search │ │ • Port Scanning│ │ • Service ID │
|
|
│ • ARP Scanning │ │ • Service Enum │ │ • Screenshots │
|
|
│ • Passive Mon │ │ • Target Valid │ │ • Deep Enum │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
└───────────────────────┼───────────────────────┘
|
|
│
|
|
┌─────────────────┐
|
|
│ Workflow Engine│
|
|
│ • YAML Actions │
|
|
│ • Tagging │
|
|
│ • Conditions │
|
|
└─────────────────┘
|
|
│
|
|
┌─────────────────┐
|
|
│ Web Interface │
|
|
│ • Dashboard │
|
|
│ • Host Analysis│
|
|
│ • Task Monitor │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
```bash
|
|
# Required tools
|
|
sudo apt install nmap masscan arp-scan tcpdump nuclei
|
|
```
|
|
|
|
### Installation
|
|
|
|
You can use the provided `install.sh` script or follow the short guide below.
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/P-Aimon-Pen/ROFMAD.git
|
|
cd ROFMAD
|
|
|
|
# Adding MUSL target
|
|
rustup target add x86_64-unknown-linux-musl
|
|
|
|
# Build for Exegol (x86_64 Linux, statically linked via musl)
|
|
cargo build --release --target x86_64-unknown-linux-musl
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
#### 1. Create a New Project
|
|
```bash
|
|
./ROFMAD create-project myproject ./projects/ \
|
|
--interface eth0 \
|
|
--workflow workflow.yaml
|
|
```
|
|
|
|
#### 2. Resume Existing Project
|
|
```bash
|
|
./ROFMAD resume-project ./projects/myproject.db \
|
|
--interface eth0 \
|
|
--workflow workflow.yaml
|
|
```
|
|
|
|
#### 3. Web Interface Only
|
|
```bash
|
|
./ROFMAD web-only ./projects/myproject.db
|
|
```
|
|
|
|
### Web Interface
|
|
|
|
Access the dashboard at `http://your-ip:8443`. On your first visit you'll be redirected to a one-time setup page where you choose your own admin password. See [How to Use](#how-to-use) below for the full walkthrough.
|
|
|
|
- **Dashboard**: Real-time reconnaissance progress and host analysis queue
|
|
- **Hosts**: Comprehensive host listing with filtering and status tracking
|
|
- **Scanners**: Launch discovery tools and add targets
|
|
- **Actions**: Build and execute custom reconnaissance actions
|
|
- **Logs**: Monitor system activity and task execution
|
|
|
|
## How to Use
|
|
|
|
### First Launch and Admin Setup
|
|
|
|
Launch ROFMAD using `create-project`, `resume-project`, or `web-only` (see Quick Start above), then open `http://<interface-ip>:8443` in your browser. If there's no admin account yet, every route redirects you to a one-time setup page where you choose and confirm your own password (at least 8 characters). Nothing is auto-generated or printed to the terminal for the admin account. Once you submit the form, the account is created and you're sent to the login page.
|
|
|
|
|
|
|
|
### Settings: Blacklists and Player Accounts
|
|
|
|
The admin-only Settings page includes a Blacklist Configuration form. Any IPs or CIDRs you add there are excluded from all scanning, passed to masscan as `--exclude` and checked before any task spawns. It's a runtime setting stored in the database, not a CLI flag.
|
|
|
|
|
|
|
|
The same page has a Create Player User form for multiplayer use. Pick a username, then either auto-generate a secure password or set a custom one. The generated password is shown only once, so make sure to relay it to the player before navigating away. Player accounts can view all authenticated pages, but not admin-only ones like Settings, Scanners, Action Builder, or user management.
|
|
|
|
|
|
|
|
### Dashboard
|
|
|
|
This is the home page, and it refreshes every 2 seconds. You'll see top-level stat cards for hosts, subnets, and active and queued tasks, a Discovery Statistics panel covering open ports, HTTP services, and screenshots captured, an Active Tasks table, System Performance cards, and the Concurrency Status grid (Global, Nmap, Subnet, HTTP Discovery, Nuclei, and Screenshot).
|
|
|
|
|
|
|
|
### How the Pipeline Works
|
|
|
|
The workflow engine polls every 2 seconds. On each tick it pulls a fresh snapshot of every host, checks each one's open ports, tags, and completion flags against a fixed chain of stages, and fires the next stage for any host that's ready and hasn't already fired it (a function tracks which stage has run for which IP, so nothing repeats). Every host goes through the same chain, no matter how it entered the project:
|
|
|
|
1. **Full TCP port scan.** As soon as a host is added, `nmap -p- -Pn --open -T4 --min-parallelism 50 --max-retries 2` scans all 65535 TCP ports, capped at 900 seconds.
|
|
2. **Service and version scan.** Once the open ports are known, `nmap -sC -sV -Pn -T4 --script-timeout 60s --max-retries 2 -p <discovered ports>` runs against exactly those ports, not the full range again, capped at 1800 seconds.
|
|
3. **HTTP discovery.** Every open port is probed concurrently for HTTP and HTTPS, and the status code, headers, title, body, and response time are saved for anything that answers.
|
|
4. **Automated tagging.** Service names, product strings, and HTTP fingerprints get turned into the automated and refined tags covered in Search and the Tag System below.
|
|
5. **Screenshots.** Once tagging is done, headless Chrome captures a screenshot of every HTTP service. Only 5 Chrome instances run at once across the whole project, so a host with many services doesn't crowd out everyone else.
|
|
6. **Reconnaissance complete.** Once all of the above are finished for a host, it becomes eligible for your custom workflow actions and shows up in the Dashboard's Hosts Ready for Analysis grid.
|
|
|
|
Subnet scans add a funnel in front of that same per-host chain. Masscan sweeps the whole CIDR first, checking just six common ports (21, 22, 80, 139, 443, 445) at 10,000 packets per second, and every host it finds is fed straight into the per-host chain above. Once masscan finishes, a quick nmap pass (Phase 1) checks the rest of the subnet for 14 more common ports, skipping whatever masscan already caught, and anything it finds also enters the per-host chain. Finally, Phase 2 runs a full `-p-` nmap scan against whatever's still left, skipping everything Phase 1 already covered. The idea is to get the easy, common-service hosts into deep enumeration fast, while still eventually covering the entire subnet.
|
|
|
|
### Starting a Run (Scanners Page)
|
|
|
|
This is where you bring targets into the project once it's running, and none of it needs the CLI.
|
|
|
|
- **Add a single target**: enter an IP or hostname and it's inserted directly, starting the full per-host chain above at the full TCP port scan.
|
|
- **Upload a target list**: the same thing, one target per line in a text file.
|
|
- **Scan a subnet by CIDR**: launches the masscan sweep described above, which feeds straight into the Phase 1 and Phase 2 nmap passes over the rest of the subnet.
|
|
- **ARP Discovery**: runs `arp-scan --interface <iface> --localnet`, an ARP sweep of the local subnet that can find hosts that stay quiet otherwise.
|
|
- **DNS Intelligence**: reads nameserver IPs from `/etc/resolv.conf` and `/run/systemd/resolve/resolv.conf`, falls back to the default gateway from `ip route show default`, and derives likely /24 subnets from whatever it finds.
|
|
- **Interface Explorer**: runs a few `ip` commands to enumerate every address, secondary IP, and on-link route visible from the chosen interface.
|
|
- **Passive Listener**: runs `tcpdump` on mDNS, LLMNR, NetBIOS, SSDP, DNS, and DHCP ports and pulls IPs and hostnames out of whatever it overhears, without sending a single packet itself. It keeps running until you cancel it, since it's purely passive.
|
|
|
|
DNS Intelligence and Interface Explorer return their results right away. ARP Discovery, Passive Listener, and subnet scans register as background tasks you can watch from the Queue.
|
|
|
|
|
|
|
|
### Hosts Ready for Analysis
|
|
|
|
As a host finishes the pipeline above, it shows up in the Dashboard's Hosts Ready for Analysis grid. Each card shows the IP and hostname, port count, HTTP service count, action count, and tags, and clicking it takes you straight to that host's detail page.
|
|
|
|
|
|
### Queue and Task Monitoring
|
|
|
|
The Queue page mirrors the Dashboard's concurrency grid, plus full Active and Queued task tables. Each task has a Detail link that opens its live output stream, and a Kill button if you need to stop it.
|
|
|
|
### Host List
|
|
|
|
This is a sortable table of every discovered host, with columns for IP, hostname, AD domain, ports, tags, HTTP services, scan-status flags, and analyzed, nuclei-reviewed, and bookmark state. Filter pills let you narrow it down to All, Bookmarked, Not Bookmarked, Ready to Analyze, or Analyzed, and a live search bar matches IP, hostname, or tag text as you type.
|
|
|
|
|
|
|
|
### Host Detail
|
|
|
|
This is the per-host deep dive. At the top you get a status and progress header, then a stats grid, a form to add or remove manual tags, a bookmark toggle, and host management actions like resetting the host's state, forcing a retag, retaking a screenshot, or running nuclei on every HTTP service at once. Below that you'll find the Open Ports table, HTTP Services cards (each with its own Run or Redo Nuclei button), the Screenshots gallery, Nuclei Findings, the workflow's Action Outputs, and the raw nmap output.
|
|
|
|
|
|
|
|
### Running Nuclei and Finding Results
|
|
|
|
You can trigger Nuclei from either a single HTTP service's Run Nuclei button on Host Detail, or from the bulk Run Nuclei on All HTTP Services modal on the Scanners page. The bulk modal lets you include or exclude by tag and by IP or CIDR, and shows a live preview of the matched hosts before you launch it. Once a scan finishes, the results show up in two places: the host's own Nuclei Findings section on Host Detail, grouped by port and labeled with severity, and the Dashboard's Nuclei Findings panel, which gives you a per-host breakdown by severity (critical, high, medium, low, info, and unknown).
|
|
|
|
|
|
|
|
|
|
|
|
### Search and the Tag System
|
|
|
|
There isn't a separate global search page. Search is tag based and lives on the Tags page, where a search bar filters by tag name, and every tag shown elsewhere in the UI links straight to the matching host list. The page offers two views: Manual & Refined Tags, which is the default, and All Tags (Including Automated), which also breaks out tags that came from workflow actions. Each tag is badged by where it came from: MANUAL for tags you added yourself on Host Detail, AUTO for ones nmap or a service probe picked up, REFINED for tags the system cleaned up afterward, and WORKFLOW for tags applied by an action's output pattern.
|
|
|
|
|
|
|
|
### Building Custom Actions
|
|
|
|
Customizing what ROFMAD runs is just editing `workflow.yaml` directly, or building entries through the Action Builder page described below, whichever you find easier. Start from an existing entry, for example one of the SMB or MSSQL actions already in `workflow.yaml`, and change its command to whatever tool and arguments you actually want to run, adjust the condition so it only fires on the hosts you care about, and add tag patterns to capture whatever in the output matters to you. Since the engine just runs your command line as-is and fills in placeholders like `{{IP}}` and `{{HTTP_URL}}`, you're not limited to the tools shown in the examples; anything you have installed can be wired in the same way. See Workflow System below for the full condition and placeholder reference.
|
|
|
|
The Action Builder page is a form based alternative to hand-editing workflow YAML. You fill in a name, a command using the same placeholders as `workflow-example.yaml`, a timeout, and port, tag, and service conditions (there's a visual tag browser modal to help with that), plus as many output-tag-pattern rows as you need. Clicking Refresh Preview shows exactly which current hosts would match before you run anything. If you check "Save to workflow file after execution," the action gets written into the workflow YAML for future runs. Leave it unchecked and it just runs once, in memory only.
|
|
|
|
|
|
|
|
### Exporting Results
|
|
|
|
On the Tags page, select one or more tags to build a Selected Tags set, then click Export Selected Tags to download every matching host as plain text, CSV, or JSON. For example, you could export every host tagged `interesting` as a target list to hand off to someone else.
|
|
## Workflow System
|
|
|
|
ROFMAD uses YAML workflows to define custom reconnaissance actions:
|
|
|
|
```yaml
|
|
specific_actions:
|
|
- name: "smb_enumeration"
|
|
condition:
|
|
contains: "445 AND 139"
|
|
has_tag: "Windows"
|
|
command: "nxc smb {{IP}} -u '' -p '' --shares"
|
|
timeout_s: 120
|
|
tags:
|
|
- pattern: "STATUS_SUCCESS"
|
|
tag: "anonymous-smb"
|
|
```
|
|
|
|
See [`workflow-example.yaml`](workflow-example.yaml) for the full, authoritative reference: every condition type (`contains`, `equals`, `has_tag`, `has_not_tag`, `has_service`, `has_http_service`), every placeholder (`{{IP}}`, `{{PORT}}`, `{{PORT:service}}`, `{{PORTS:service}}`, `{{HTTP_URL}}`, etc.), the service-name normalization table, how automated tags are derived from nmap output, and tag-pattern regex syntax. [`workflow.yaml`](workflow.yaml) is a ready-to-use default covering SMB and MSSQL enumeration.
|
|
|
|
## Configuration
|
|
|
|
### Concurrency Modes
|
|
- **Conservative**: Low resource usage, network-friendly
|
|
- **Aggressive**: High performance, faster scanning
|
|
- **Stealth**: Minimal footprint, slower but quieter
|
|
|
|
### Directory Structure
|
|
```
|
|
/opt/ROFMAD/
|
|
├── workflows/ # YAML workflow definitions
|
|
└── screenshots/ # Web application screenshots
|
|
```
|
|
|
|
## Development
|
|
|
|
### Building from Source
|
|
|
|
```bash
|
|
# Development build
|
|
cargo build
|
|
|
|
# Release build for Exegol
|
|
cargo build --release --target x86_64-unknown-linux-musl
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Check dependencies
|
|
./target/debug/ROFMAD --check-deps
|
|
```
|
|
|
|
### Architecture Overview
|
|
|
|
- **`src/main.rs`**: CLI interface and application bootstrap
|
|
- **`src/enumeration/`**: Network discovery and port scanning modules
|
|
- **`src/http/`**: Web service discovery and enumeration
|
|
- **`src/workflow/`**: YAML workflow engine and task orchestration
|
|
- **`src/web/`**: HTTP server and dashboard interface
|
|
- **`src/sql/`**: Database operations and project context
|
|
- **`src/tag/`**: Automated and manual tagging system
|
|
- **`src/config/`**: System path constants (e.g. `/opt/ROFMAD/workflows`)
|
|
- **`src/utilities/`**: Shared utilities and logging
|
|
|
|
## Security Considerations
|
|
|
|
### Safety Features
|
|
- Automatic localhost and host interface blacklisting
|
|
- Configurable IP/subnet blacklists
|
|
- Non-interactive execution (no passwords prompted)
|
|
- Resource limit enforcement
|
|
|
|
### Responsible Use
|
|
|
|
**This tool is intended for security professionals conducting authorized testing only.**
|
|
|
|
## Known Limitations
|
|
|
|
- Limited cross-platform support (Linux only)
|
|
- Minimal input validation on some user inputs
|
|
- Some error conditions may cause panics
|
|
- No comprehensive test coverage yet
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome.
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Submit a pull request
|
|
|
|
### Workflow Contributions
|
|
|
|
The workflow engine becomes more useful the more `specific_actions` it ships with. If you've built enumeration or exploitation actions on top of ROFMAD that go beyond the SMB and MSSQL coverage in [`workflow.yaml`](workflow.yaml), consider submitting them as a pull request. Bigger, more comprehensive community-contributed workflow files make the tool better for everyone. Check [`workflow-example.yaml`](workflow-example.yaml) for the schema reference before writing your own.
|
|
|
|
### Reporting Issues
|
|
|
|
Please include:
|
|
- Operating system and version
|
|
- Rust version (`rustc --version`)
|
|
- Full command line used
|
|
- Complete error output
|
|
- Network environment details (if relevant)
|
|
|
|
## License
|
|
|
|
Apache License 2.0. See the [LICENSE](LICENSE) file for details.
|
|
|
|
## Disclaimer
|
|
|
|
This tool is provided "as is" without warranty. Users are responsible for compliance with applicable laws and regulations. The authors are not liable for misuse or damage caused by this software.
|
|
|
|
---
|
|
|
|
**Remember: Always obtain proper authorization before scanning networks you do not own.**
|