cidrwalk

cidrwalk is a small Swift command-line example built on swift-cidr. It demonstrates CIDR summarization with explicit input meaning instead of guessing from loosely typed strings.

The command is intentionally narrow and teaching-oriented:

• addresses summarizes two CIDR-qualified host endpoints with /32 or /128.
• networks summarizes the envelope covering two whole CIDR network prefixes.

Both inputs must be from the same IP address family. Reversed input order is normalized at the CLI boundary before calling into swift-cidr.

IPv6 values use deterministic RFC 5952 compressed text in list, tree, and JSON output, for example 2001:db8::1/128.

CIDR Aggregation

CIDR summarization converts an inclusive address range, or the envelope around two network prefixes, into the smallest ordered set of aligned CIDR prefixes. The result may be one prefix when the inputs align cleanly, or several prefixes when the range starts or ends inside a larger boundary.

The addresses subcommand requires /32 for IPv4 and /128 for IPv6 because those prefix lengths identify exact host endpoints. The networks subcommand accepts distinct CIDR network prefixes that do not contain one another and summarizes the full envelope that covers both inputs. Adjacent or separated networks are accepted in either order.

Usage

Homebrew

Install the released command-line tool from the RouteObjects tap on macOS or Linux. Homebrew pours a prebuilt binary; no Swift toolchain or Xcode is required at install time.

brew install RouteObjects/tap/cidrwalk
cidrwalk --version

Address Endpoints

Use addresses when the inputs are host endpoints. Prefix notation is required, and only host-length prefix lengths are accepted.

cidrwalk addresses 192.168.1.1/32 192.168.1.2/32

192.168.1.1/32
192.168.1.2/32

IPv6 host endpoints use /128:

cidrwalk addresses 2001:db8::1/128 2001:db8::f/128

2001:db8::1/128
2001:db8::2/127
2001:db8::4/126
2001:db8::8/125

Network Prefixes

Use networks when the inputs are CIDR network prefixes. The output covers both complete input networks and any gap between them. The networks must use the same address family, be unequal, and neither may contain the other. Equality is checked after canonicalizing the inputs, so 10.0.0.1/24 and 10.0.0.0/24 are rejected as the same network. Validation errors are written to stderr with a nonzero exit status and no summary on stdout.

cidrwalk networks 192.0.2.0/24 192.0.3.0/24

192.0.2.0/23

JSON

JSON output is available with --output json:

cidrwalk addresses 192.168.1.1/32 192.168.1.189/32 --output json

{
  "family" : "IPv4",
  "inputs" : [
    "192.168.1.1/32",
    "192.168.1.189/32"
  ],
  "mode" : "addresses",
  "prefixes" : [
    "192.168.1.1/32",
    "192.168.1.2/31",
    "192.168.1.4/30",
    "192.168.1.8/29",
    "192.168.1.16/28",
    "192.168.1.32/27",
    "192.168.1.64/26",
    "192.168.1.128/27",
    "192.168.1.160/28",
    "192.168.1.176/29",
    "192.168.1.184/30",
    "192.168.1.188/31"
  ],
  "rangeEnd" : "192.168.1.189/32",
  "rangeStart" : "192.168.1.1/32"
}

In network mode, rangeStart is the lowest first address and rangeEnd is the highest last address across the two inputs. With swift-cidr 0.9, each JSON boundary retains the prefix length of the input network that supplies it. These fields are contextual address values; their prefix lengths may differ.

Network inputs	rangeStart	rangeEnd
10.0.0.0/24, 10.0.2.0/25	10.0.0.0/24	10.0.2.127/25
2001:db8::/126, 2001:db8::8/127	2001:db8::/126	2001:db8::9/127

This intentionally changes the network-mode JSON boundary convention from earlier releases using swift-cidr 0.5, which emitted host-length prefixes. The inputs array preserves canonical networks in command-line order. Reversing accepted inputs leaves the boundary values and summarized prefixes unchanged. Address-mode JSON continues to use its required /32 or /128 host endpoints.

Tree

Tree output is available with --output tree. Indentation is based on prefix-length depth within the summarized result; it is a teaching visualization, not a proportional address-space diagram.

cidrwalk addresses 2001:db8::1/128 2001:db8::8/128 --output tree

2001:db8::1/128
                2001:db8::2/127
                                2001:db8::4/126
2001:db8::8/128

Build From Source

Clone the repository and run the executable with SwiftPM:

git clone https://github.com/RouteObjects/cidrwalk.git
cd cidrwalk
swift run cidrwalk --help

The package accepts swift-cidr versions in the 0.9.x line (>= 0.9.0 and < 0.10.0). This protects the command's tested serialization contract from an unreviewed pre-1.0 minor update. Building requires Swift 6.2 or newer.

Release Archives

Each release provides native macOS and Linux archives for arm64 and x86-64. Every archive contains the cidrwalk executable, LICENSE, and THIRD_PARTY_NOTICES.txt. Linux executables statically include the Swift runtime and are exercised in a clean Ubuntu 22.04 container without Swift. The release also includes SHA256SUMS covering all four archives.

Testing

Use the repository test wrapper:

./scripts/test.sh

The wrapper still runs swift test. It only adds the Swift Testing framework and runtime paths needed by standalone Command Line Tools installations where plain swift test cannot locate Testing.framework.

Maintainers can validate a committed release candidate from a clean worktree:

./scripts/check-release.sh 0.3.0

The release workflow's manual dispatch builds and inspects the same four artifacts without creating a GitHub Release. A verified signed tag creates a draft Release for separate review and publication.