Skip to content

Scanning Engine v2 - Module - Portscan

Overview

The portscan scanning module performs port scans of TCP and UDP services. Unless explicitly disabled in the configuration of the bootstrap module for a job, the portscan module will be implicitly added to all jobs that contain module invocations with a non-empty ports key. The scanning engine attempts to minimize the number of port scans necessary to satisfy all module invocations.

Targeting

The ports key of any module invocation, even module invocations that are not for portscan, can cause the portscan module to scan all targets on the declared ports. More infomation can be found here.

Configuration

Only the publicly-available configuration keys that can be set in a job's module invocations will be described below. Additional configuration keys may exist, but not be shown here because they are restricted to specific users or because they are permanently set as a static value. If no keys have (required) after their names then invocations of this module need not contain a config key.

Named Keys

addresses-only

Discard hostnames once they are resolved to addresses.

  • Type: boolean

blocklist-files (required)

File of addresses, hostnames, and CIDR blocks that are blocked.

  • Type: list(string)

cooldown

How long to wait for responses after all probes have been sent, in seconds.

  • Type: integer
  • Default: 4

debug

Run module with a debugging configuration.

  • Type: boolean

max-targets

Limit the number of targets scanned, randomly chosen.

  • Type: integer

max-v4

Maximum number of resolved IPv4 addresses to use.

  • Type: integer

max-v6

Maximum number of resolved IPv6 addresses to use.

  • Type: integer

portscanner

Use the specified portscanner.

  • Type: string
  • Default: masscan

Values for this configuration key must be one the following:

  • be
  • noop
  • zmap
  • masscan

probe

Probe to send when scanning UDP ports.

  • Type: string

protocol

Protocol to scan.

  • Type: string
  • Default: TCP

Values for this configuration key must be one the following:

  • TCP
  • UDP

qsize

The scan max queue size.

  • Type: integer
  • Default: 10000

request-timeout

Maximum timeout for each DNS request. (e.g., '10m', '1h', '1s', '1h10m')

  • Type: string

resolution-timeout

Maximum timeout for DNS resolution of each target. (e.g., '10m', '1h', '1s', '1h10m')

  • Type: string

resolver-address

Custom DNS resolver address to use.

  • Type: string

resolver-concurrency

Number of concurrent goroutines to use when resolving targets.

  • Type: integer

seed (required)

uint32 that defines the traversal of targets.

  • Type: integer

shards (required)

Range is from [1,255].

  • Type: integer

single-address

Use a single address from the DNS resolution.

  • Type: boolean

targeting-timeout

Maximum duration allowed for parsing and resolving all targets. (e.g., '10m', '1h', '1s', '1h10m')

  • Type: string

Schemas

The schema for the body object of all results generated with .task.module_name equal to portscan can be found here. The schema for results is available both in standalone and bundled form.

Examples

These are examples of the .body object for results with .task.module_name equal to x11.

GitHub Single TCP Port

This example was generated with GitHub by scanning a single TCP port.

{
  "dport": 36034,
  "saddr": "140.82.114.4",
  "window": 65408
}

GitHub All TCP Ports

This example was generated with GitHub by scanning all TCP ports.

{
  "status": "open",
  "reason": "syn-ack",
  "ttl": 63
}

Google Public DNS

This example was generated with Google Public DNS by scanning a single UDP port.

{
  "address": "8.8.8.8",
  "port": 53,
  "src_port": 16808,
  "src_addr": "[REDACTED]",
  "proto": "udp",
  "status": "open",
  "reason": "udp-response",
  "timestamp": 1725904946319
}

Changelog

v2.0.0 (2025-07-02)

  • Portscan Rewrite in Go:
  • Complete rewrite from Python to Go for improved performance and maintainability.
  • Implemented modular scanner architecture supporting multiple scanning engines (zmap, masscan, beportscan).
  • Added comprehensive target indexing system for enhanced result correlation.
  • Improved error handling and result processing with structured logging.
  • Added extensive test coverage for all scanner implementations.

v1.0.0 (2025-05-05)

  • Initial release of versioning for each module. All modules are being tagged with version number 1.0.0. Going forward:
  • Major version should be changed when there are changes that impact consumers or clients of the modules.
  • Minor version should be changed when there are additions which enrich or enhance the module but shouldn't affect consumers or clients.
  • Patch version should be changed when there are bugfixes.