ipam-toolkit

Source-of-truth IP address management and VLSM subnet planning for multi-site networks.

Describe what each network segment needs — a name and a host count — in a single YAML file. ipam-toolkit allocates the addressing with a best-fit VLSM algorithm, validates the plan for overlaps and over-subscription, and generates the artifacts a network team actually consumes: review tables, dhcpd configuration, and reverse-DNS zones. Point CI at your plan and a bad change fails the build before it reaches a switch.

Built to mirror real enterprise IPAM/DDI work — the kind of fragmented, multi-site address space you consolidate onto a clean, reviewable plan.

---

Why

Most teams plan addressing in a spreadsheet, which drifts, overlaps, and can't be diffed or reviewed. This treats the plan as code:

• Intent, not addresses, is the source of truth. You say users-data needs 500 hosts; the allocator decides it's a /23. Renumbering a site becomes a one-line edit, not a migration.
• Validation is a gate. ipam validate exits non-zero on supernet overlaps, over-subscription, and allocation collisions, so CI blocks a broken plan.
• It generates the downstream config. DHCP scopes and reverse-DNS zones fall out of the plan automatically, so they can't drift from it.
• Dependency-light. Allocation and validation use only the Python standard library (ipaddress); the single runtime dependency is PyYAML.

Features

Best-fit VLSM allocation	Packs requests largest-block-first into the smallest free block that fits, keeping remaining space contiguous for growth.
Overlap & capacity validation	Detects supernet overlaps between sites, over-subscribed supernets, and allocation collisions. Flags wasteful (<25% utilized) blocks.
Utilization reporting	Per-segment, per-site, and org-wide address utilization with the free blocks left in each supernet.
DHCP export	ISC dhcpd.conf subnet declarations with gateway and a conservative host pool.
Reverse-DNS export	The in-addr.arpa zones implied by each allocated subnet.
Markdown / CSV reports	Human review in a pull request, or a CSV for import into an IPAM/DDI system.

Architecture

flowchart LR
    Y[sites.yaml<br/>source of truth] --> M[models<br/>parse & validate schema]
    M --> A[allocator<br/>best-fit VLSM]
    A --> V[validator<br/>overlap & capacity]
    A --> R[reporter<br/>utilization]
    R --> E[exporters]
    E --> MD[Markdown / CSV]
    E --> DH[ISC dhcpd.conf]
    E --> DN[reverse DNS zones]
    V --> CI{{CI gate<br/>fail on error}}

Loading

Install

git clone https://github.com/beepingtheboops/ipam-toolkit.git
cd ipam-toolkit
pip install -e .          # adds the `ipam` command
# or, for development:
pip install -e ".[dev]"   # + pytest and ruff

Requires Python 3.10+.

Quickstart

The source of truth is a YAML file. You declare host counts; the toolkit does the math:

organization: Acme Corp
sites:
  - name: hq-losangeles
    supernet: 10.10.0.0/16
    subnets:
      - name: users-data
        hosts: 500
        vlan: 10
      - name: wireless-corp
        hosts: 1000
        vlan: 30
      - name: mgmt
        hosts: 30
        vlan: 99

Validate the plan

$ ipam validate examples/sites.yaml
OK: Acme Corp - 3 site(s), no issues found.

Catch mistakes before they ship — a supernet overlap and an over-subscribed site:

$ ipam validate examples/sites-with-errors.yaml
ERROR  supernet overlap: site-a 10.0.0.0/24 overlaps site-b 10.0.0.0/22
ERROR  [site-a] requests need 512 addresses but supernet 10.0.0.0/24 only has 256
ERROR  [site-a] site-a/too-big: needs a /23 but supernet is only /24

3 error(s), 0 warning(s).
$ echo $?
1

Allocate and view the plan

$ ipam plan examples/sites.yaml

hq-losangeles  10.10.0.0/16  (util 3.3%, free 63,360)
  segment           vlan  subnet               gateway          usable
  users-data          10  10.10.4.0/23         10.10.4.1           510
  voice               20  10.10.6.0/24         10.10.6.1           254
  wireless-corp       30  10.10.0.0/22         10.10.0.1          1022
  wireless-guest      31  10.10.7.0/24         10.10.7.1           254
  servers             40  10.10.8.0/26         10.10.8.1            62
  printers            50  10.10.8.64/27        10.10.8.65           30
  mgmt                99  10.10.8.96/27        10.10.8.97           30

Generate downstream config

$ ipam export examples/sites.yaml --type dhcp
subnet 10.10.4.0 netmask 255.255.254.0 {  # vlan 10
    option routers 10.10.4.1;
    range 10.10.4.11 10.10.5.254;
}
...

$ ipam report examples/sites.yaml --format markdown --out plan.md
$ ipam export examples/sites.yaml --type dns --out reverse-zones.txt

Command reference

Command	Purpose
ipam validate <file>	Check for overlaps, over-subscription, and collisions. Exit 1 on error.
ipam plan <file>	Allocate and print a per-site table.
ipam report <file> --format {markdown,csv} [--out FILE]	Write a review report.
ipam export <file> --type {dhcp,dns} [--out FILE]	Generate dhcpd.conf or reverse-DNS zones.

Use it in CI

The included GitHub Actions workflow lints, runs the tests, and validates the example plan on every push. To gate your address plan, add a step:

- run: pip install -e .
- run: ipam validate network/sites.yaml

Now a pull request that introduces an overlapping supernet or an over-subscribed site fails CI instead of causing an outage.

Security

The generated dhcpd.conf and reverse-DNS zones are configuration for security-relevant services, so untrusted input is not allowed to reach them unescaped. The threat model and controls:

• Input validation at load time. Organization, site, and segment names are validated when the plan is parsed. Control characters, newlines, and the metacharacters that could break out of a comment or inject a directive into the generated files ({ } ; # |) are rejected with a clear error, so no exporter can emit a poisoned config regardless of what the YAML contains.
• Safe deserialization. Plans are parsed with yaml.safe_load; the loader never constructs arbitrary Python objects.
• No code execution or network access. The toolkit does no eval/exec, spawns no subprocesses, and makes no outbound connections. It reads a YAML file and writes text.
• Minimal dependency surface. One runtime dependency (PyYAML); the allocation and validation core is standard library only.

--out writes wherever the invoking user can write (by design, as a local operator tool); run it against plan files you trust.

Development

pip install -e ".[dev]"
pytest -q          # 23 tests
ruff check .

Roadmap

• IPv6 supernet support
• Reserved / statically-pinned subnets in the source of truth
• Direct push to Infoblox / NetBox via their APIs
• plan --diff to show address changes between two versions of the plan

License

MIT — see LICENSE.