# bee-san/rustscan architecture

> Architecture diagram of the GitHub repository bee-san/rustscan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bee-san/rustscan
- Repository: https://github.com/bee-san/rustscan
- Video tour (about a minute): https://gitdiagram.com/bee-san/rustscan/video

## Overview

RustScan is a command-line port scanner: users supply targets and scan options, which are parsed and resolved before a configured TCP/UDP scan probes ports and reports open results. The CLI can then dispatch scripts with discovered ports, including the default Nmap command; README also documents adaptive learning, though the sampled source does not establish its implementation or wiring. Paths and relationships reflect the available tree and excerpts, so unsampled subsystem links are omitted where their callers are uncertain.

Main entry points: [`src/main.rs`](https://github.com/bee-san/rustscan/blob/master/src/main.rs) (CLI orchestration), [`src/scanner/mod.rs`](https://github.com/bee-san/rustscan/blob/master/src/scanner/mod.rs) (Scan coordinator), [`src/address.rs`](https://github.com/bee-san/rustscan/blob/master/src/address.rs) (Address resolution), [`src/port_strategy/mod.rs`](https://github.com/bee-san/rustscan/blob/master/src/port_strategy/mod.rs) (Port ordering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Inputs and targets"]
  node_cli["CLI orchestration<br/>[main.rs]"]
  node_options["Options and config<br/>[input.rs]"]
  node_addresses["Address resolution<br/>[address.rs]"]
end

subgraph group_scanning["Port scanning"]
  node_port_strategy["Port ordering<br/>[mod.rs]"]
  node_range_iterator["Random range iterator<br/>[range_iterator.rs]"]
  node_scanner["Scan coordinator<br/>[mod.rs]"]
  node_socket_iterator["Socket enumeration<br/>[socket_iterator.rs]"]
end

subgraph group_results["Results and extensions"]
  node_results_output["Scan output<br/>[main.rs]"]
  node_scripts["Script engine<br/>[mod.rs]"]
  node_adaptive["Adaptive learning"]
  node_tui["Accessible terminal UI<br/>[tui.rs]"]
end

node_user(("CLI user"))
node_dns["DNS resolver"]
node_targets(("Target hosts"))
node_script_files["User scripts"]
node_nmap["Nmap"]

node_user -->|"invokes"| node_cli
node_cli -->|"reads options"| node_options
node_options -->|"provides config"| node_cli
node_cli -->|"resolves targets"| node_addresses
node_addresses -.->|"looks up names"| node_dns
node_addresses -->|"returns addresses"| node_targets
node_cli -->|"selects ports"| node_port_strategy
node_port_strategy -->|"generates order"| node_range_iterator
node_cli -->|"runs scan"| node_scanner
node_scanner -->|"gets port order"| node_port_strategy
node_scanner -->|"enumerates sockets"| node_socket_iterator
node_scanner -->|"probes ports"| node_targets
node_scanner -->|"returns open ports"| node_cli
node_cli -->|"prints results"| node_results_output
node_cli -->|"dispatches scripts"| node_scripts
node_script_files -->|"supplies scripts"| node_scripts
node_scripts -.->|"runs command"| node_nmap
node_results_output -->|"formats output"| node_tui

click node_cli "https://github.com/bee-san/rustscan/blob/master/src/main.rs"
click node_options "https://github.com/bee-san/rustscan/blob/master/src/input.rs"
click node_addresses "https://github.com/bee-san/rustscan/blob/master/src/address.rs"
click node_port_strategy "https://github.com/bee-san/rustscan/blob/master/src/port_strategy/mod.rs"
click node_range_iterator "https://github.com/bee-san/rustscan/blob/master/src/port_strategy/range_iterator.rs"
click node_scanner "https://github.com/bee-san/rustscan/blob/master/src/scanner/mod.rs"
click node_socket_iterator "https://github.com/bee-san/rustscan/blob/master/src/scanner/socket_iterator.rs"
click node_results_output "https://github.com/bee-san/rustscan/blob/master/src/main.rs"
click node_scripts "https://github.com/bee-san/rustscan/blob/master/src/scripts/mod.rs"
click node_adaptive "https://github.com/bee-san/rustscan/tree/master/src"
click node_tui "https://github.com/bee-san/rustscan/blob/master/src/tui.rs"

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_cli,node_options,node_addresses,node_user,node_script_files toneBlue
class node_port_strategy,node_range_iterator,node_scanner,node_socket_iterator toneAmber
class node_results_output,node_scripts,node_adaptive,node_tui toneMint
class node_dns,node_targets,node_nmap toneIndigo
```

## Components

### Inputs and targets

- [CLI orchestration](https://github.com/bee-san/rustscan/blob/master/src/main.rs): `src/main.rs`
- [Options and config](https://github.com/bee-san/rustscan/blob/master/src/input.rs): `src/input.rs`
- [Address resolution](https://github.com/bee-san/rustscan/blob/master/src/address.rs): `src/address.rs`

### Port scanning

- [Port ordering](https://github.com/bee-san/rustscan/blob/master/src/port_strategy/mod.rs): `src/port_strategy/mod.rs`
- [Random range iterator](https://github.com/bee-san/rustscan/blob/master/src/port_strategy/range_iterator.rs): `src/port_strategy/range_iterator.rs`
- [Scan coordinator](https://github.com/bee-san/rustscan/blob/master/src/scanner/mod.rs): `src/scanner/mod.rs`
- [Socket enumeration](https://github.com/bee-san/rustscan/blob/master/src/scanner/socket_iterator.rs): `src/scanner/socket_iterator.rs`

### Results and extensions

- [Scan output](https://github.com/bee-san/rustscan/blob/master/src/main.rs): `src/main.rs`
- [Script engine](https://github.com/bee-san/rustscan/blob/master/src/scripts/mod.rs): `src/scripts/mod.rs`
- [Adaptive learning](https://github.com/bee-san/rustscan/tree/master/src): `src`
- [Accessible terminal UI](https://github.com/bee-san/rustscan/blob/master/src/tui.rs): `src/tui.rs`

### Other components

- **CLI user**
- **DNS resolver**
- **Target hosts**
- **User scripts**
- **Nmap**

## Connections

- CLI user → CLI orchestration: invokes
- CLI orchestration → Options and config: reads options
- Options and config → CLI orchestration: provides config
- CLI orchestration → Address resolution: resolves targets
- Address resolution → DNS resolver: looks up names
- Address resolution → Target hosts: returns addresses
- CLI orchestration → Port ordering: selects ports
- Port ordering → Random range iterator: generates order
- CLI orchestration → Scan coordinator: runs scan
- Scan coordinator → Port ordering: gets port order
- Scan coordinator → Socket enumeration: enumerates sockets
- Scan coordinator → Target hosts: probes ports
- Scan coordinator → CLI orchestration: returns open ports
- CLI orchestration → Scan output: prints results
- CLI orchestration → Script engine: dispatches scripts
- User scripts → Script engine: supplies scripts
- Script engine → Nmap: runs command
- Scan output → Accessible terminal UI: formats output
