Skip to content

nicholashoule/subnet-splitter

BranchesTags

Repository files navigation

CIDR Subnet Calculator

A modern web application for calculating subnet details, splitting CIDR ranges recursively, and planning network configurations.

Features

Frontend Application

  • Subnet Calculation: Enter any CIDR notation to get detailed network information
  • Recursive Splitting: Split networks into smaller subnets down to /32 (single host)
  • Interactive Table: Expand/collapse subnet hierarchies with visual indentation
  • Copy to Clipboard: Click to copy any field value (network address, broadcast, hosts, etc.)
  • CSV Export: Select rows and export subnet details to CSV for use in Excel or other tools
  • Dark/Light Mode: Theme support with elegant UI
  • Responsive Design: Works on desktop and mobile devices

Backend API (Production-Ready)

  • Kubernetes Network Planning: Generate optimized network plans for EKS, GKE, AKS, and generic Kubernetes
  • Multi-Cloud Support: Battle-tested configurations for all major cloud providers (see compliance audits)
  • Deployment Tiers: Pre-configured subnet allocations (Micro → Hyperscale)
  • Provider Flexibility: Same API works with AWS, Google Cloud, Azure, and self-hosted Kubernetes
  • Compliance Documentation: Full compliance audits for EKS, GKE, and AKS

Network Information Provided

  • CIDR notation and prefix length
  • Network address and broadcast address
  • First and last usable host addresses
  • Total addresses and usable hosts count
  • Subnet mask and wildcard mask
  • Network class classification

Security

This application follows a security by design approach with multiple layers of protection:

Security Features

  • No database: No user data to protect or risk exposing
  • Stateless API: All operations are deterministic (same input = same output)
  • Client-side calculations: All subnet logic runs in the browser
  • Helmet middleware: Adds security headers for XSS, clickjacking, and MIME sniffing protection
  • Content Security Policy (CSP):
    • Strict policy in production: script-src 'self' only
    • Relaxed policy in development: allows Vite HMR and React Fast Refresh
    • Prevents inline script injection attacks
  • Rate limiting: Production SPA routes protected with rate limiting (30 requests per 15 minutes)
  • Static isolation: Only compiled assets from dist/public are served in production
  • Request validation: All API requests validated with Zod schemas
  • No vulnerabilities: npm audit reports 0 vulnerabilities

Security Best Practices

  • Environment-aware configuration for dev vs production
  • File extension checks prevent serving source files as HTML
  • Middleware ordering protects asset serving from SPA fallback interference
  • All security settings documented; core protections covered by automated tests

Tech Stack

Frontend

  • React 18 with TypeScript
  • Tailwind CSS for styling
  • shadcn/ui component library (Radix UI primitives)
  • React Hook Form with Zod validation
  • Vite for building and development

Backend

  • Express.js 5 with TypeScript
  • Node.js runtime
  • Helmet for security headers
  • express-rate-limit for DoS protection
  • In-memory storage (no database required for core functionality)

Project Structure

├── client/                 # React frontend
│   └── src/
│       ├── components/ui/  # shadcn/ui components
│       ├── hooks/          # Custom React hooks
│       ├── lib/            # Utilities (subnet-utils, kubernetes-network-generator)
│       └── pages/          # Route components
├── server/                 # Express backend
│   ├── index.ts            # Entry point with Helmet + security configuration
│   ├── routes.ts           # API route definitions (Kubernetes Network Planning)
│   ├── vite.ts             # Vite dev server setup with SPA fallback
│   └── static.ts           # Static file serving with rate limiting
├── tests/                  # Comprehensive unit and integration test suite
│   ├── unit/               # Unit tests (subnet-utils.test.ts, kubernetes-network-generator.test.ts, emoji-detection.test.ts)
│   ├── integration/        # Integration tests (styles, API, config, security)
│   ├── manual/             # Manual testing scripts (2 PowerShell, 2 TypeScript)
│   │   ├── test-api-endpoints.ps1  # Comprehensive API validation
│   │   ├── test-api.ps1            # RFC 1918 enforcement testing
│   │   ├── test-network-comparison.ts  # Network comparison utility
│   │   └── test-network-validation.ts  # Network validation utility
│   └── README.md           # Testing documentation
├── scripts/                # Build and utility tools
│   ├── build.ts            # Production build orchestration
│   └── fix-emoji.ts        # Emoji detection and auto-fix CLI tool
├── docs/                   # Reference documentation
│   ├── api.md              # Kubernetes Network Planning API reference
│   ├── test-suite-analysis.md # Test suite health analysis
│   ├── git-conventions.md  # Git commit message conventions
│   ├── test-templates.md   # Test patterns and examples
│   ├── ui-examples.md      # UI code and design system
│   ├── archive/            # Historical documentation
│   │   └── agent-reasoning.md # Development history and decisions
│   └── compliance/         # Compliance and platform-specific documentation
│       ├── kubernetes-network-reference.md # K8s network formulas
│       ├── security-reference.md # CSP and security configuration
│       ├── ip-allocation-cross-reference.md # Cross-provider IP comparison
│       ├── AKS_COMPLIANCE_AUDIT.md # Azure Kubernetes Service
│       ├── EKS_COMPLIANCE_AUDIT.md # AWS Elastic Kubernetes Service
│       └── GKE_COMPLIANCE_AUDIT.md # Google Kubernetes Engine
├── shared/                 # Shared code
│   ├── schema.ts           # TypeScript types and Zod schemas
│   └── kubernetes-schema.ts # Kubernetes API schemas
└── package.json

Getting Started

Development Setup

Prerequisites

  • Node.js v20+ (download)
  • npm v11+ (comes with Node.js)
  • Git

Installation

Clone the repository:

git clone https://github.com/nicholashoule/subnet-cidr-splitter.git
cd subnet-cidr-splitter

Install dependencies:

npm install

Security Audit (Required)

Always verify the project has no security vulnerabilities before running any code:

npm audit

If vulnerabilities are found, fix them:

npm audit fix

If issues persist, use --force (may install breaking changes):

npm audit fix --force

Note: Do not run npm run dev, npm run test, or npm run build without addressing security vulnerabilities first.

Start development server:

npm run dev

The application will be available at http://localhost:5000 or http://127.0.0.1:5000.

Access the application:

  • Web UI: Open http://127.0.0.1:5000 in your browser
  • API endpoint: POST http://127.0.0.1:5000/api/k8s/plan
  • Tier info: GET http://127.0.0.1:5000/api/k8s/tiers
  • API docs: http://127.0.0.1:5000/api/docs/ui (Swagger UI)

Windows-Specific Setup

On Windows, use npm.cmd instead of npm:

npm.cmd install
npm.cmd run dev

The development server automatically handles Windows network binding compatibility (falls back from 0.0.0.0 to 127.0.0.1 if needed).

Note: Line endings are normalized to LF via .gitattributes, so Git may show CRLF warnings on Windows. This is normal and safe.

Production Build

npm run build
npm start

The production build creates optimized assets in the dist/ directory.

Type Checking

npm run check
npm.cmd run check

Verify TypeScript compilation without emitting files.

Testing

# Run all tests
npm run test

# Run tests with interactive UI
npm run test:ui

# Run tests in watch mode (default)
npm run test
npm.cmd run test -- --run

# Run specific test file
npm run test -- tests/unit/subnet-utils.test.ts
npm run test -- tests/unit/ui-styles.test.ts

# Run API tests specifically (JSON/YAML validation)
npm run test -- tests/integration/kubernetes-network-api.test.ts --run

# Run only JSON/YAML format tests
npm run test -- tests/integration/kubernetes-network-api.test.ts -t "Output Format" --run

# Run emoji detection tests
npm run test:emoji

# Check for emoji in codebase
npm run emoji:check

# Auto-fix emoji in codebase
npm run emoji:fix

Testing the API Endpoints

Prerequisites: Start the development server first:

npm run dev

Test JSON output (default format):

curl -X POST http://127.0.0.1:5000/api/k8s/plan \
  -H "Content-Type: application/json" \
  -d '{"deploymentSize":"professional","provider":"eks","vpcCidr":"10.100.0.0/18"}'

Test YAML output (add ?format=yaml query parameter):

curl -X POST "http://127.0.0.1:5000/api/k8s/plan?format=yaml" \
  -H "Content-Type: application/json" \
  -d '{"deploymentSize":"professional","provider":"eks","vpcCidr":"10.100.0.0/18"}'

Test tier information endpoint:

# JSON format
curl http://127.0.0.1:5000/api/k8s/tiers

# YAML format
curl "http://127.0.0.1:5000/api/k8s/tiers?format=yaml"

PowerShell Testing (Windows):

# JSON output
Invoke-RestMethod -Uri "http://127.0.0.1:5000/api/k8s/plan" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"deploymentSize":"professional","provider":"eks"}' | ConvertTo-Json -Depth 10

# YAML output
Invoke-WebRequest -Uri "http://127.0.0.1:5000/api/k8s/plan?format=yaml" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"deploymentSize":"hyperscale","provider":"gke"}' | Select-Object -ExpandProperty Content

The project includes a comprehensive test suite with 406 tests (100% passing) covering:

Unit Tests (218):

  • Subnet calculations (67 tests): IP address conversion and validation, CIDR prefix/mask calculations for all prefix lengths (0-32), subnet splitting and calculations, network class identification (Classes A-E including multicast and reserved), edge cases (RFC 3021 point-to-point /31, /32 host routes, /0 all-IPv4), RFC 1918 private ranges, error handling with clear error messages, subnet tree operations
  • Kubernetes network generation (57 tests): Network plan generation, deployment tier configurations, RFC 1918 private IP enforcement, subnet allocation algorithms
  • IP calculation compliance (56 tests): IP allocation formulas, deployment tier compliance, network sizing validation
  • UI styles (19 tests): WCAG accessibility (pure math functions), HSL→RGB conversion, luminance calculations
  • Emoji detection (11 tests): Scans all markdown and source files for emoji, validates clean text-based documentation, reports violations with file/line numbers
  • Configuration (8 tests): Tailwind, PostCSS, Vite, TypeScript configuration validation

Integration Tests (188):

  • API endpoints (38 tests): API infrastructure, health checks, OpenAPI spec, Swagger UI
  • Calculator UI (52 tests): React component behavior, form validation, subnet operations, CSV export, hide parents feature, depth indicator visual hierarchy
  • Kubernetes Network Planning API (33 tests): JSON/YAML output formats, RFC 1918 enforcement, public IP rejection, all deployment tiers and providers
  • Rate limiting (23 tests): Rate limiter configuration, request throttling, DoS protection
  • Swagger UI CSP middleware (18 tests): Route-specific CSP, development vs production mode, CDN permissions
  • Swagger UI theming (12 tests): Theme toggle, persistence, dark mode CSS loading
  • CSP violation endpoint (12 tests): W3C spec compliance, rate limiting, schema validation

See tests/README.md for comprehensive testing documentation and docs/test-suite-analysis.md for detailed test suite analysis.

Windows Compatibility

This project is fully tested on Windows and includes several optimizations for cross-platform support:

  • Line Endings: Configured via .gitattributes to use LF (Unix-style) for all source files
  • npm Scripts: Uses cross-env package to handle environment variables on Windows cmd
  • Server Binding: Automatic fallback from 0.0.0.0 to 127.0.0.1 to localhost if needed
  • .gitignore: Comprehensive coverage of OS-specific files (Windows, macOS, Linux)

All development tools and commands work identically on Windows, macOS, and Linux.

Usage

Web Interface

  1. Enter a CIDR notation (e.g., 192.168.1.0/24) in the input field
  2. Click "Calculate" or use one of the example buttons
  3. View the subnet details in the Network Overview card
  4. Use the split button to divide subnets into smaller ranges
  5. Select rows with checkboxes and export to CSV

REST API - Kubernetes Network Planning

The application provides production-ready REST endpoints for generating optimized network configurations across EKS, GKE, AKS, and self-hosted Kubernetes.

WARNING Security Requirement: All VPC CIDRs must use private RFC 1918 IP ranges. Public IPs are rejected with security guidance. See full API documentation for details.

Endpoint 1: Generate Network Plan

POST /api/k8s/plan

Generate an optimized network plan with subnet allocation, pod CIDR, and service CIDR ranges.

Quick Example:

curl -X POST http://localhost:5000/api/k8s/plan \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentSize": "professional",
    "provider": "eks",
    "vpcCidr": "10.100.0.0/18"
  }'

Request Parameters:

{
  "deploymentSize": "micro|standard|professional|enterprise|hyperscale",
  "provider": "eks|gke|aks|kubernetes|k8s",
  "vpcCidr": "10.100.0.0/18",
  "deploymentName": "my-cluster"
}
  • deploymentSize (required): Deployment tier for cluster size
  • provider (optional): Cloud provider (eks, gke, aks, kubernetes, k8s). Defaults to kubernetes. Note: k8s is an alias for kubernetes
  • vpcCidr (optional): Private RFC 1918 CIDR only (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). If omitted, generates random RFC 1918 range
  • deploymentName (optional): Reference name for deployment tracking

Accepted Private IP Ranges:

  • [PASS] Class A: 10.0.0.0/8 (any /16 or larger subnet within this range)
  • [PASS] Class B: 172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
  • [PASS] Class C: 192.168.0.0/16 (any subnet within this range)

Rejected Public IPs: All non-RFC 1918 ranges are rejected (e.g., 8.8.8.0/16, 1.1.1.0/16, 200.0.0.0/16)

Example Request:

curl -X POST http://localhost:5000/api/k8s/plan \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentSize": "professional",
    "provider": "eks",
    "vpcCidr": "10.100.0.0/18",
    "deploymentName": "prod-us-east-1"
  }'

Response:

{
  "deploymentSize": "professional",
  "provider": "eks",
  "deploymentName": "prod-us-east-1",
  "vpc": {
    "cidr": "10.100.0.0/18"
  },
  "subnets": {
    "public": [
      {
        "cidr": "10.0.0.0/24",
        "name": "public-1",
        "type": "public"
      },
      {
        "cidr": "10.0.1.0/24",
        "name": "public-2",
        "type": "public"
      }
    ],
    "private": [
      {
        "cidr": "10.0.2.0/23",
        "name": "private-1",
        "type": "private"
      },
      {
        "cidr": "10.0.4.0/23",
        "name": "private-2",
        "type": "private"
      }
    ]
  },
  "pods": {
    "cidr": "10.1.0.0/16"
  },
  "services": {
    "cidr": "10.2.0.0/16"
  },
  "metadata": {
    "generatedAt": "2026-02-01T15:30:45.123Z",
    "version": "1.0"
  }
}

Endpoint 2: Get Deployment Tiers

GET /api/k8s/tiers

Retrieve information about all available deployment tiers and their configurations.

Example Request:

curl http://localhost:5000/api/k8s/tiers

Response:

{
  "micro": {
    "publicSubnets": 1,
    "privateSubnets": 1,
    "publicSubnetSize": 26,
    "privateSubnetSize": 25,
    "minVpcPrefix": 24,
    "podsPrefix": 18,
    "servicesPrefix": 16,
    "description": "Single Node: 1 node, minimal subnet allocation (proof of concept)"
  },
  "standard": {
    "publicSubnets": 1,
    "privateSubnets": 1,
    "publicSubnetSize": 25,
    "privateSubnetSize": 24,
    "minVpcPrefix": 23,
    "podsPrefix": 16,
    "servicesPrefix": 16,
    "description": "Development/Testing: 1-3 nodes, minimal subnet allocation"
  },
  "professional": {
    "publicSubnets": 2,
    "privateSubnets": 2,
    "publicSubnetSize": 25,
    "privateSubnetSize": 23,
    "minVpcPrefix": 21,
    "podsPrefix": 16,
    "servicesPrefix": 16,
    "description": "Small Production: 3-10 nodes, dual AZ ready"
  },
  "enterprise": {
    "publicSubnets": 3,
    "privateSubnets": 3,
    "publicSubnetSize": 24,
    "privateSubnetSize": 21,
    "minVpcPrefix": 18,
    "podsPrefix": 16,
    "servicesPrefix": 16,
    "description": "Large Production: 10-50 nodes, triple AZ ready with HA"
  },
  "hyperscale": {
    "publicSubnets": 3,
    "privateSubnets": 3,
    "publicSubnetSize": 23,
    "privateSubnetSize": 20,
    "minVpcPrefix": 18,
    "podsPrefix": 13,
    "servicesPrefix": 16,
    "description": "Global Scale: 50-5000 nodes, multi-region ready (EKS/GKE max)"
  }
}

API Error Responses

400 Bad Request - Invalid parameters:

{
  "error": "Invalid deployment size: unknown",
  "code": "NETWORK_GENERATION_ERROR"
}

400 Bad Request - Public IP rejected (security enforcement):

{
  "error": "VPC CIDR \"8.8.8.0/16\" uses public IP space. Kubernetes deployments MUST use private RFC 1918 ranges: 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16. Public IPs expose nodes to the internet (critical security risk). Use private subnets for Kubernetes nodes and public subnets only for load balancers/ingress controllers.",
  "code": "NETWORK_GENERATION_ERROR"
}

500 Internal Server Error - Server error:

{
  "error": "Failed to generate network plan",
  "code": "INTERNAL_ERROR"
}

Deployment Tiers Overview

Tier Nodes Public Subnets Private Subnets Public Size Private Size Pod CIDR Service CIDR Use Case
Micro 1 1 1 /26 (62 IPs) /25 (126 IPs) /20 (4K IPs) /16 (65K IPs) POC, Development
Standard 1-3 1 1 /25 (126 IPs) /24 (254 IPs) /16 (65K IPs) /16 (65K IPs) Dev/Testing
Professional 3-10 2 2 /25 (126 IPs) /23 (510 IPs) /18 (16K IPs) /16 (65K IPs) Small Production (HA-ready)
Enterprise 10-50 3 3 /24 (254 IPs) /21 (2K IPs) /16 (65K IPs) /16 (65K IPs) Large Production (Multi-AZ)
Hyperscale 50-5000 3 3 /23 (510 IPs) /20 (4K IPs) /13 (524K IPs) /16 (65K IPs) Global Scale (EKS/GKE max)

Network Sizing Notes:

  • Pod CIDR: Separate IP range for container networking (via CNI plugins like AWS VPC CNI, Calico, or Cilium)
  • Service CIDR: Kubernetes ClusterIP range for service discovery (10.2.0.0/16 by default, can be customized)
  • Public Subnets: For load balancers, NAT gateways, and bastion hosts
  • Private Subnets: For Kubernetes worker nodes (EC2 instances or node pools)
  • All networks use RFC 1918 private addressing (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)

Supported Providers

  • EKS - AWS Elastic Kubernetes Service with VPC CNI
  • GKE - Google Kubernetes Engine with Alias IP ranges
  • AKS - Azure Kubernetes Service with Azure CNI Overlay
  • Kubernetes / k8s - Generic self-hosted or alternative cloud providers

Supported Network Classes

The calculator supports all five IPv4 address classes:

Class A

  • Address Range: 1-126 (first octet)
  • Default Mask: 255.0.0.0 (/8)
  • Usable Hosts per Network: 16,777,214 (2²⁴ - 2)
  • Example: 10.0.0.0/8 - RFC 1918 private network

Class B

  • Address Range: 128-191 (first octet)
  • Default Mask: 255.255.0.0 (/16)
  • Usable Hosts per Network: 65,534 (2¹⁶ - 2)
  • Example: 172.16.0.0/12 - RFC 1918 private network

Class C

  • Address Range: 192-223 (first octet)
  • Default Mask: 255.255.255.0 (/24)
  • Usable Hosts per Network: 254 (2⁸ - 2)
  • Example: 192.168.0.0/16 - RFC 1918 private network

Class D (Multicast)

  • Address Range: 224-239 (first octet)
  • Usage: Reserved for multicast traffic
  • Example: 224.0.0.1 - All hosts multicast

Class E (Reserved)

  • Address Range: 240-255 (first octet)
  • Usage: Reserved for future use and research

RFC 1918 Private Address Ranges

The calculator includes pre-configured examples for the three RFC 1918 private address ranges:

  • 10.0.0.0/8 - Class A private (entire first octet)
  • 172.16.0.0/12 - Class B private (16.0.0.0 to 31.255.255.255)
  • 192.168.0.0/16 - Class C private (65,536 addresses)

Example CIDR Ranges

  • 10.0.0.0/8 - Class A private network (16,777,216 addresses)
  • 172.16.0.0/12 - Class B private network (1,048,576 addresses)
  • 192.168.0.0/16 - Class C private network (65,536 addresses)
  • 192.168.1.0/24 - Class C subnet (256 addresses)

Project Documentation

Comprehensive documentation is available to help developers understand and contribute to this project:

For Contributors & AI Agents

  • .github/copilot-instructions.md - Complete development guidelines including:

    • Project architecture and structure
    • Security protocols and audit requirements
    • Code style and naming conventions
    • Testing strategy and coverage requirements
    • API planning and implementation details

  • docs/archive/agent-reasoning.md - Development history and decision log (archived)

    • Note: This file captures major architectural decisions and complex problem-solving sessions
    • Historical reference for understanding the "why" behind non-obvious design choices

Testing & Quality

API & Compliance

Author

Created by nicholashoule

Contributing

We welcome contributions! Please follow these guidelines:

Before You Start

  1. Read the development guidelines: Review .github/copilot-instructions.md for:

    • Project architecture and structure
    • Code style and naming conventions
    • Robustness and hardening principles
    • Security audit requirements (mandatory)
    • API planning documentation

  2. Review development history: Check docs/archive/agent-reasoning.md to understand:

    • Major architectural decisions and rationale
    • Complex problem-solving approaches
    • Historical context for non-obvious design choices
    • Note: Only major concepts are documented here to keep the file lean and focused

  3. Understand commit conventions: Follow Conventional Commits as documented in .github/copilot-instructions.md:

    • Use feat: for new features
    • Use fix: for bug fixes
    • Use docs: for documentation
    • Use chore: for maintenance
    • Use refactor:, test:, perf:, style:, ci: as appropriate

Development Workflow

  1. Set up environment: Follow the Development Setup section above
  2. Create a feature branch: git checkout -b feat/your-feature-name
  3. Make your changes: Ensure code follows project conventions
  4. Test thoroughly:
    • Test on Windows, macOS, or Linux
    • Run npm run check for TypeScript validation
    • Test both light and dark modes
  5. Commit with clear messages: Use conventional commit format
  6. Submit changes: Create a pull request with description

Code Standards

  • TypeScript: Strict mode enabled (strict: true)
  • No any types: Always provide proper types
  • Icons: Use Lucide React only, no unicode characters
  • Styling: Tailwind CSS utilities, no inline styles
  • Components: React functional components with hooks
  • Validation: Use Zod for input validation

Testing Your Changes

# Type check
npm run check

# Build for production
npm run build

# Run development server
npm run dev

Visit http://localhost:5000 and test:

  • Subnet calculations with various CIDR notations
  • Recursive splitting and deletion
  • CSV export functionality
  • Light/dark mode switching
  • Mobile responsiveness
  • Error handling with invalid inputs

Project Structure

Before making changes, understand:

  • Client: client/src/ - React components, utilities, styles
  • Server: server/ - Express.js backend (currently static serving only)
  • Shared: shared/ - TypeScript types and Zod schemas
  • Documentation: .github/ - Developer guidelines and reasoning

Questions or Issues?

  • Review the Project Documentation section above for comprehensive guides
  • Check docs/archive/agent-reasoning.md for historical context on major decisions
  • Search existing issues for similar problems
  • When opening new issues, provide clear context and steps to reproduce

License

MIT

About

A modern web application for calculating subnet details, splitting CIDR ranges recursively, and planning network configurations.

Topics

typescript tools subnetting subnet-calculator

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages