cidr-cli

A CLI wrapper for the cidr-tools package, specifically wrapping the containsCidr method to check if an IP address is contained within CIDR ranges.

🚀 Installation

Global Installation (Recommended)

npm install -g cidr-cli

Local Installation

npm install cidr-cli

Using npx (No Installation Required)

npx cidr-cli contains <cidr-list> <ip>

📖 Usage

cidr-cli contains <cidr-list> <ip>

Arguments

• <cidr-list>: Comma-separated list of CIDR ranges (e.g., 192.168.1.0/24,10.0.0.0/8)
• <ip>: IP address to check (IPv4 or IPv6)

Examples

# Single CIDR range
cidr-cli contains 192.168.1.0/24 192.168.1.100
# Output: true

# Multiple CIDR ranges
cidr-cli contains 10.0.0.0/8,172.16.0.0/12 10.1.2.3
# Output: true

# User's example
cidr-cli contains 1.0.0.0/24,2.0.0.0/24 1.0.0.1
# Output: true

# IPv6 support
cidr-cli contains 2001:db8::/32 2001:db8:0:0:1::1
# Output: true

# IP not in range
cidr-cli contains 1.0.0.0/24,2.0.0.0/24 3.0.0.1
# Output: false

# Help
cidr-cli --help

📋 Exit Codes

• 0: IP is contained in one of the CIDR ranges
• 1: IP is not contained in any of the CIDR ranges
• 2: Error occurred (invalid arguments, invalid CIDR format, invalid IP, etc.)

🧪 Use Cases

Shell Scripts

#!/bin/bash
if cidr-cli contains 192.168.0.0/16 $USER_IP; then
  echo "User is on local network"
else
  echo "User is on external network"
fi

CI/CD Pipelines

- name: Check if IP is in allowed range
  run: |
    if ! cidr-cli contains 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 ${{ env.SERVER_IP }}; then
      echo "Server IP not in allowed private ranges"
      exit 1
    fi

Network Security

# Check if suspicious IP is in known bad ranges
if cidr-cli contains 1.2.3.0/24,5.6.7.0/24 $SUSPICIOUS_IP; then
  echo "IP is in known malicious range - blocking"
  # Add blocking logic here
fi

🔧 Development

Requirements

• Node.js >= 14.0.0
• npm >= 6.0.0

Setup

git clone https://github.com/n-ae/cidr-cli.git
cd cidr-cli
npm install

Testing

# Run tests (Jest with ES modules)
npm test

# Run tests with coverage (c8 + Jest)
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Linting

# Check for linting issues
npm run lint

# Fix linting issues automatically
npm run lint:fix

Documentation

# Generate JSDoc documentation
npm run docs

🏗️ Project Structure

cidr-cli/
├── index.js              # Main CLI implementation (ES modules)
├── index.test.js         # Jest test suite (13 comprehensive tests)
├── package.json          # Package configuration
├── package-lock.json     # Lockfile v2 for CI compatibility
├── README.md            # This file
├── LICENSE              # MIT license
├── CHANGELOG.md         # Version history
├── PUBLISHING.md        # Publishing guide
├── WARP.md             # Claude/Warp AI development guide
├── eslint.config.js    # ESLint flat configuration (neostandard)
├── jest.config.js      # Jest configuration (ES modules)
├── .c8rc.json         # c8 coverage configuration
├── jsdoc.conf.json    # JSDoc configuration
├── .npmignore         # npm publish exclusions
├── .gitignore         # Git exclusions
├── .github/
│   └── workflows/     # GitHub Actions CI/CD (Node 14-21 matrix)
├── docs/              # Generated JSDoc documentation
├── coverage/          # c8 coverage reports (HTML + LCOV)
└── tests/             # Legacy test files (kept for reference)

🚀 Publishing

This package uses automated publishing via GitHub Actions:

1. On Push/PR: Runs full test suite across Node.js 14.x, 16.x, 18.x, 20.x, 21.x
2. On Tag: Automatically publishes to npm and creates GitHub release

Manual Publishing

npm version patch|minor|major
git push origin main --tags

📊 Test Coverage

The project maintains 100% test coverage using c8:

• 13 test cases covering all functionality and edge cases
• Integration tests: End-to-end CLI execution via child_process.spawn()
• Coverage tool: c8 (Node.js native coverage) instead of Jest built-in
• Coverage threshold: 80% minimum, currently achieving 100%
• Reports: Text, LCOV (for Codecov), and HTML formats

Test categories:

• ✅ CIDR containment checks (IPv4/IPv6)
• ✅ Multiple CIDR range support
• ✅ Help and usage information
• ✅ Error handling (invalid CIDR, invalid IP, malformed arguments)
• ✅ Exit code validation
• ✅ Whitespace handling in CIDR lists
• ✅ Process-level coverage tracking

🔗 Dependencies

Runtime Dependencies

• cidr-tools ^13.0.1 - Core CIDR functionality

Development Dependencies

• jest ^30.5.0 - Testing framework
• c8 ^12.0.0 - Native Node.js code coverage
• eslint ^9.39.5 - Code linting (flat config)
• neostandard ^0.13.0 - Standard style guide for flat config
• jsdoc ^4.0.5 - Documentation generation

Key Features

• ES Modules: Modern JavaScript module system
• Node.js 14+: Minimum Node.js version support
• CI/CD: GitHub Actions with Node.js 14.x-21.x matrix
• Coverage: 100% code coverage with c8
• Lockfile v2: Enhanced CI compatibility

📝 License

MIT © nae

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -am 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

🐛 Issues

If you find a bug, please file an issue on GitHub Issues.

📈 Roadmap

• Add support for excluding CIDR ranges
• Add JSON output format option
• Add batch processing from file input
• Add verbose mode with detailed matching information
• Add support for hostname resolution

---

Made with ❤️ for network administrators and DevOps engineers