# robertdavidgraham/masscan architecture

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

- Interactive diagram: https://gitdiagram.com/robertdavidgraham/masscan
- Repository: https://github.com/robertdavidgraham/masscan

## Overview

MASSCAN is an Internet-scale asynchronous IP/port scanner. The principal workflow is: a user supplies targets, ports, rate, and output options; configuration builds address/port ranges; the scan engine generates and throttles probes through the raw adapter; received packets are processed by the ad hoc IP/TCP stack and protocol/banner parsers; results are dispatched to selectable output formats. The tree and excerpts confirm orchestration, packet construction, TCP handling, configuration, parsing, and output components; some receive-side wiring is inferred only from documented responsibilities.

Main entry points: [`src/main.c`](https://github.com/robertdavidgraham/masscan/blob/master/src/main.c) (Scan Orchestrator), [`src/stack-tcp-core.c`](https://github.com/robertdavidgraham/masscan/blob/master/src/stack-tcp-core.c) (Ad Hoc Stack), [`src/proto-banner1.c`](https://github.com/robertdavidgraham/masscan/blob/master/src/proto-banner1.c) (Banner Engine), [`src/rawsock.c`](https://github.com/robertdavidgraham/masscan/blob/master/src/rawsock.c) (Raw Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control &amp; Configuration"]
  node_main["Scan Orchestrator<br/>[main.c]"]
  node_config["Config Parser<br/>[main-conf.c]"]
  node_targets["Target Ranges<br/>[massip-rangesv4.c]"]
end

subgraph group_scan["Scan &amp; Networking"]
  node_throttle["Rate Throttler<br/>[main-throttle.c]"]
  node_templates["Packet Templates<br/>[templ-pkt.c]"]
  node_stack["Ad Hoc Stack<br/>[stack-tcp-core.c]"]
  node_rawsock["Raw Adapter<br/>[rawsock.c]"]
  node_ring["Packet Queues<br/>[rte-ring.c]"]
end

subgraph group_protocol["Protocol Inspection"]
  node_probes["Service Probes"]
  node_banner["Banner Engine<br/>[proto-banner1.c]"]
  node_parsers["Protocol Parsers<br/>[proto-http.c]"]
  node_tcpservices["Service Naming<br/>[out-tcp-services.c]"]
  node_vuln["Vulnerability Checks<br/>[vulncheck.c]"]
end

subgraph group_results["Results &amp; Extensions"]
  node_output["Output Dispatcher<br/>[output.c]"]
  node_formats["Output Formats<br/>[out-json.c]"]
  node_scripting["Banner Scripting<br/>[scripting.c]"]
end

node_user(("Scanner User"))
node_result_sink(("Scan Result Sink"))
node_network(("Probed Network"))

node_user -->|"starts scan"| node_main
node_main -->|"parses options"| node_config
node_config -->|"builds ranges"| node_targets
node_main -->|"starts rate"| node_throttle
node_main -->|"creates probes"| node_templates
node_main -->|"flushes packets"| node_stack
node_templates -->|"formats packets"| node_stack
node_throttle -->|"limits transmission"| node_stack
node_stack -->|"queues packets"| node_ring
node_ring -->|"delivers packets"| node_rawsock
node_rawsock -->|"sends probes"| node_network
node_network -->|"returns packets"| node_rawsock
node_rawsock -->|"feeds responses"| node_stack
node_stack -->|"delivers streams"| node_banner
node_banner -->|"dispatches protocols"| node_parsers
node_probes -->|"configures probes"| node_banner
node_parsers -->|"names services"| node_tcpservices
node_banner -.->|"runs checks"| node_vuln
node_banner -.->|"runs scripts"| node_scripting
node_main -->|"dispatches results"| node_output
node_output -->|"formats records"| node_formats
node_formats -->|"writes results"| node_result_sink

click node_main "https://github.com/robertdavidgraham/masscan/blob/master/src/main.c"
click node_config "https://github.com/robertdavidgraham/masscan/blob/master/src/main-conf.c"
click node_targets "https://github.com/robertdavidgraham/masscan/blob/master/src/massip-rangesv4.c"
click node_throttle "https://github.com/robertdavidgraham/masscan/blob/master/src/main-throttle.c"
click node_templates "https://github.com/robertdavidgraham/masscan/blob/master/src/templ-pkt.c"
click node_stack "https://github.com/robertdavidgraham/masscan/blob/master/src/stack-tcp-core.c"
click node_rawsock "https://github.com/robertdavidgraham/masscan/blob/master/src/rawsock.c"
click node_ring "https://github.com/robertdavidgraham/masscan/blob/master/src/rte-ring.c"
click node_probes "https://github.com/robertdavidgraham/masscan/blob/master/src/read-service-probes.c"
click node_banner "https://github.com/robertdavidgraham/masscan/blob/master/src/proto-banner1.c"
click node_parsers "https://github.com/robertdavidgraham/masscan/blob/master/src/proto-http.c"
click node_tcpservices "https://github.com/robertdavidgraham/masscan/blob/master/src/out-tcp-services.c"
click node_vuln "https://github.com/robertdavidgraham/masscan/blob/master/src/vulncheck.c"
click node_output "https://github.com/robertdavidgraham/masscan/blob/master/src/output.c"
click node_formats "https://github.com/robertdavidgraham/masscan/blob/master/src/out-json.c"
click node_scripting "https://github.com/robertdavidgraham/masscan/blob/master/src/scripting.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_main,node_config,node_targets,node_user toneBlue
class node_throttle,node_templates,node_stack,node_rawsock,node_ring toneAmber
class node_probes,node_banner,node_parsers,node_tcpservices,node_vuln toneMint
class node_output,node_formats,node_scripting toneRose
class node_result_sink,node_network toneIndigo
```

## Components

### Control & Configuration

- [Scan Orchestrator](https://github.com/robertdavidgraham/masscan/blob/master/src/main.c): `src/main.c`
- [Config Parser](https://github.com/robertdavidgraham/masscan/blob/master/src/main-conf.c): `src/main-conf.c`
- [Target Ranges](https://github.com/robertdavidgraham/masscan/blob/master/src/massip-rangesv4.c): `src/massip-rangesv4.c`

### Scan & Networking

- [Rate Throttler](https://github.com/robertdavidgraham/masscan/blob/master/src/main-throttle.c): `src/main-throttle.c`
- [Packet Templates](https://github.com/robertdavidgraham/masscan/blob/master/src/templ-pkt.c): `src/templ-pkt.c`
- [Ad Hoc Stack](https://github.com/robertdavidgraham/masscan/blob/master/src/stack-tcp-core.c): `src/stack-tcp-core.c`
- [Raw Adapter](https://github.com/robertdavidgraham/masscan/blob/master/src/rawsock.c): `src/rawsock.c`
- [Packet Queues](https://github.com/robertdavidgraham/masscan/blob/master/src/rte-ring.c): `src/rte-ring.c`

### Protocol Inspection

- [Service Probes](https://github.com/robertdavidgraham/masscan/blob/master/src/read-service-probes.c): `src/read-service-probes.c`
- [Banner Engine](https://github.com/robertdavidgraham/masscan/blob/master/src/proto-banner1.c): `src/proto-banner1.c`
- [Protocol Parsers](https://github.com/robertdavidgraham/masscan/blob/master/src/proto-http.c): `src/proto-http.c`
- [Service Naming](https://github.com/robertdavidgraham/masscan/blob/master/src/out-tcp-services.c): `src/out-tcp-services.c`
- [Vulnerability Checks](https://github.com/robertdavidgraham/masscan/blob/master/src/vulncheck.c): `src/vulncheck.c`

### Results & Extensions

- [Output Dispatcher](https://github.com/robertdavidgraham/masscan/blob/master/src/output.c): `src/output.c`
- [Output Formats](https://github.com/robertdavidgraham/masscan/blob/master/src/out-json.c): `src/out-json.c`
- [Banner Scripting](https://github.com/robertdavidgraham/masscan/blob/master/src/scripting.c): `src/scripting.c`

### Other components

- **Scanner User**
- **Scan Result Sink**
- **Probed Network**

## Connections

- Scanner User → Scan Orchestrator: starts scan
- Scan Orchestrator → Config Parser: parses options
- Config Parser → Target Ranges: builds ranges
- Scan Orchestrator → Rate Throttler: starts rate
- Scan Orchestrator → Packet Templates: creates probes
- Scan Orchestrator → Ad Hoc Stack: flushes packets
- Packet Templates → Ad Hoc Stack: formats packets
- Rate Throttler → Ad Hoc Stack: limits transmission
- Ad Hoc Stack → Packet Queues: queues packets
- Packet Queues → Raw Adapter: delivers packets
- Raw Adapter → Probed Network: sends probes
- Probed Network → Raw Adapter: returns packets
- Raw Adapter → Ad Hoc Stack: feeds responses
- Ad Hoc Stack → Banner Engine: delivers streams
- Banner Engine → Protocol Parsers: dispatches protocols
- Service Probes → Banner Engine: configures probes
- Protocol Parsers → Service Naming: names services
- Banner Engine → Vulnerability Checks: runs checks
- Banner Engine → Banner Scripting: runs scripts
- Scan Orchestrator → Output Dispatcher: dispatches results
- Output Dispatcher → Output Formats: formats records
- Output Formats → Scan Result Sink: writes results
