From 11eb16ae4e896e8bc9099274603f8b97d11ed0a2 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:33:38 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) โ€” AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc => README.md | 254 ++++++++++++++++++++++----------------- 1 file changed, 142 insertions(+), 112 deletions(-) rename README.adoc => README.md (53%) diff --git a/README.adoc b/README.md similarity index 53% rename from README.adoc rename to README.md index 392adc0..9f90e0b 100644 --- a/README.adoc +++ b/README.md @@ -1,44 +1,58 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= IPv6-Only Tools -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/ipv6-only"] + +A comprehensive toolkit for IPv6-only networking, featuring utilities +for address manipulation, network analysis, diagnostics, and testing. -A comprehensive toolkit for IPv6-only networking, featuring utilities for address manipulation, network analysis, diagnostics, and testing. +# ๐ŸŒŸ Features -== ๐ŸŒŸ Features +## Python Library -=== Python Library -- *IPv6 Address Manipulation*: Validation, compression, expansion, and format conversion -- *Network Calculator*: Subnet planning, CIDR calculations, and network analysis -- *Address Generation*: Link-local, ULA, random addresses, and MAC-to-IPv6 (EUI-64) -- *Utilities*: Reverse DNS, subnet masks, address type detection +- **IPv6 Address Manipulation**: Validation, compression, expansion, and + format conversion + +- **Network Calculator**: Subnet planning, CIDR calculations, and + network analysis + +- **Address Generation**: Link-local, ULA, random addresses, and + MAC-to-IPv6 (EUI-64) + +- **Utilities**: Reverse DNS, subnet masks, address type detection + +## Command-Line Tools -=== Command-Line Tools - `ipv6-calc` - Network subnet calculator + - `ipv6-validate` - Address and network validator + - `ipv6-gen` - Address generator (link-local, ULA, random, from MAC) -- `ipv6-convert` - Format converter (compress, expand, binary, hex, reverse DNS) -=== Shell Scripts +- `ipv6-convert` - Format converter (compress, expand, binary, hex, + reverse DNS) + +## Shell Scripts + - `ipv6-diag.sh` - Comprehensive IPv6 diagnostics tool + - `ipv6-config.sh` - IPv6 configuration helper -=== Web Application -Modern, responsive web interface featuring: -- Address validator with type detection -- Network calculator with CIDR analysis -- Format converter -- Address generator -- Subnet planner +## Web Application + +Modern, responsive web interface featuring: - Address validator with +type detection - Network calculator with CIDR analysis - Format +converter - Address generator - Subnet planner + +## Go Tools -=== Go Tools - `ipv6-ping` - High-performance IPv6 ping utility + - `ipv6-scan` - Fast IPv6 network scanner -== ๐Ÿ“ฆ Installation +# ๐Ÿ“ฆ Installation -=== Python Package +## Python Package ```bash = Clone the repository @@ -52,7 +66,7 @@ pip install -e . pip install -e ".[dev]" ``` -=== Go Tools +## Go Tools ```bash cd src/go @@ -64,7 +78,7 @@ go build -o ../../bin/ipv6-ping ./cmd/ipv6-ping go build -o ../../bin/ipv6-scan ./cmd/ipv6-scan ``` -=== Shell Scripts +## Shell Scripts ```bash = Scripts are in src/scripts/ @@ -75,9 +89,9 @@ chmod +x src/scripts/*.sh ./src/scripts/ipv6-diag.sh ``` -== ๐Ÿš€ Quick Start +# ๐Ÿš€ Quick Start -=== Python Library +## Python Library ```python from ipv6tools import IPv6Address, IPv6Network, IPv6SubnetCalculator @@ -99,7 +113,7 @@ for subnet in subnets: print(subnet.network) ``` -=== Command-Line Tools +## Command-Line Tools ```bash = Validate an address @@ -121,7 +135,7 @@ ipv6-gen from-mac 00:11:22:33:44:55 ipv6-convert 2001:0db8:0000:0000:0000:0000:0000:0001 --compress ``` -=== Shell Scripts +## Shell Scripts ```bash = Run diagnostics @@ -140,7 +154,7 @@ sudo ./src/scripts/ipv6-config.sh enable-privacy sudo ./src/scripts/ipv6-config.sh static eth0 2001:db8::10 64 ``` -=== Go Tools +## Go Tools ```bash = Ping an IPv6 address @@ -153,25 +167,26 @@ sudo ./src/scripts/ipv6-config.sh static eth0 2001:db8::10 64 ./bin/ipv6-scan -n 2001:db8::/64 -w 200 -v ``` -=== Web Application +## Web Application + +Simply open `src/web/index.html` in your browser. All tools run locally +with no server required. -Simply open `src/web/index.html` in your browser. All tools run locally with no server required. +# ๐Ÿ“š Documentation -== ๐Ÿ“š Documentation +## Address Types -=== Address Types +The library recognizes these IPv6 address types: - **Loopback** +(`::1`) - Local loopback - **Unspecified** (`::`) - Unspecified +address - **Link-Local** (`fe80::/10`) - Local network communication - +**Unique Local** (`fc00::/7`) - Private addresses - **Multicast** +(`ff00::/8`) - Group communication - **Global Unicast** (`2000::/3`) - +Public routable addresses -The library recognizes these IPv6 address types: -- *Loopback* (`::1`) - Local loopback -- *Unspecified* (`::`) - Unspecified address -- *Link-Local* (`fe80::/10`) - Local network communication -- *Unique Local* (`fc00::/7`) - Private addresses -- *Multicast* (`ff00::/8`) - Group communication -- *Global Unicast* (`2000::/3`) - Public routable addresses +## Network Operations -=== Network Operations +### Subnet Division -==== Subnet Division ```python calc = IPv6SubnetCalculator("2001:db8::/32") @@ -182,22 +197,25 @@ subnets = calc.divide_into_subnets(4) subnets = calc.divide_by_prefix(34) ``` -==== Supernet Calculation +### Supernet Calculation + ```python calc = IPv6SubnetCalculator("2001:db8::/32") supernet = calc.get_supernet(24) ``` -==== Address Testing +### Address Testing + ```python net = IPv6Network("2001:db8::/32") print(net.contains("2001:db8::1")) # True print(net.overlaps(IPv6Network("2001:db8:1::/48"))) # True ``` -=== Address Generation +## Address Generation + +### Link-Local Addresses -==== Link-Local Addresses ```python from ipv6tools.utils import generate_link_local @@ -208,7 +226,8 @@ addr = generate_link_local() addr = generate_link_local("0000000000000001") ``` -==== Unique Local Addresses (ULA) +### Unique Local Addresses (ULA) + ```python from ipv6tools.utils import generate_unique_local @@ -223,7 +242,8 @@ addr = generate_unique_local( ) ``` -==== MAC to IPv6 (EUI-64) +### MAC to IPv6 (EUI-64) + ```python from ipv6tools.utils import mac_to_ipv6_link_local @@ -231,9 +251,9 @@ addr = mac_to_ipv6_link_local("00:11:22:33:44:55") = Returns: fe80::211:22ff:fe33:4455 ``` -== ๐Ÿงช Testing +# ๐Ÿงช Testing -=== Run Python Tests +## Run Python Tests ```bash = Install test dependencies @@ -249,16 +269,14 @@ pytest --cov=ipv6tools tests/ pytest tests/python/test_address.py -v ``` -=== Test Web Tools +## Test Web Tools -Open `src/web/index.html` in a browser and test each tab: -1. Validator - Try various IPv6 addresses -2. Calculator - Calculate network information -3. Converter - Convert between formats -4. Generator - Generate different address types -5. Subnet Planner - Plan subnet allocations +Open `src/web/index.html` in a browser and test each tab: 1. Validator - +Try various IPv6 addresses 2. Calculator - Calculate network information +3. Converter - Convert between formats 4. Generator - Generate different +address types 5. Subnet Planner - Plan subnet allocations -== ๐Ÿณ Docker +# ๐Ÿณ Docker Build and run in Docker: @@ -273,9 +291,9 @@ docker run -it --rm ipv6-only docker run --rm ipv6-only ipv6-validate 2001:db8::1 ``` -== ๐Ÿ”ง Development +# ๐Ÿ”ง Development -=== Setup Development Environment +## Setup Development Environment ```bash = Clone repository @@ -295,77 +313,89 @@ black src/python/ipv6tools/ flake8 src/python/ipv6tools/ ``` -=== Project Structure +## Project Structure + + ipv6-only/ + โ”œโ”€โ”€ src/ + โ”‚ โ”œโ”€โ”€ python/ # Python library + โ”‚ โ”‚ โ””โ”€โ”€ ipv6tools/ # Main package + โ”‚ โ”œโ”€โ”€ go/ # Go tools + โ”‚ โ”‚ โ””โ”€โ”€ cmd/ # Command-line tools + โ”‚ โ”œโ”€โ”€ web/ # Web application + โ”‚ โ””โ”€โ”€ scripts/ # Shell scripts + โ”œโ”€โ”€ tests/ # Test suites + โ”‚ โ”œโ”€โ”€ python/ # Python tests + โ”‚ โ””โ”€โ”€ go/ # Go tests + โ”œโ”€โ”€ docs/ # Documentation + โ”œโ”€โ”€ examples/ # Usage examples + โ””โ”€โ”€ docker/ # Docker configurations + +# ๐Ÿค Contributing -``` -ipv6-only/ -โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ python/ # Python library -โ”‚ โ”‚ โ””โ”€โ”€ ipv6tools/ # Main package -โ”‚ โ”œโ”€โ”€ go/ # Go tools -โ”‚ โ”‚ โ””โ”€โ”€ cmd/ # Command-line tools -โ”‚ โ”œโ”€โ”€ web/ # Web application -โ”‚ โ””โ”€โ”€ scripts/ # Shell scripts -โ”œโ”€โ”€ tests/ # Test suites -โ”‚ โ”œโ”€โ”€ python/ # Python tests -โ”‚ โ””โ”€โ”€ go/ # Go tests -โ”œโ”€โ”€ docs/ # Documentation -โ”œโ”€โ”€ examples/ # Usage examples -โ””โ”€โ”€ docker/ # Docker configurations -``` +Contributions are welcome! Please: -== ๐Ÿค Contributing +1. Fork the repository -Contributions are welcome! Please: +2. Create a feature branch + +3. Add tests for new functionality -1. Fork the repository -2. Create a feature branch -3. Add tests for new functionality -4. Ensure all tests pass -5. Submit a pull request +4. Ensure all tests pass -== ๐Ÿ“ License +5. Submit a pull request + +# ๐Ÿ“ License MIT License - see LICENSE file for details -== ๐Ÿ”— Resources +# ๐Ÿ”— Resources + +## RFCs -=== RFCs -- [RFC 8200](https://tools.ietf.org/html/rfc8200) - IPv6 Specification -- [RFC 4291](https://tools.ietf.org/html/rfc4291) - IPv6 Addressing Architecture -- [RFC 4862](https://tools.ietf.org/html/rfc4862) - IPv6 Stateless Address Autoconfiguration -- [RFC 4443](https://tools.ietf.org/html/rfc4443) - ICMPv6 +- \[RFC 8200\]() - IPv6 + Specification + +- \[RFC 4291\]() - IPv6 Addressing + Architecture + +- \[RFC 4862\]() - IPv6 Stateless + Address Autoconfiguration + +- \[RFC 4443\]() - ICMPv6 + +## Tools -=== Tools - `iproute2` - Modern Linux networking tools + - `nmap` - Network scanning with IPv6 support + - `wireshark` - Packet analysis -== ๐Ÿ“Š Examples +# ๐Ÿ“Š Examples -See the `examples/` directory for: -- Network planning scripts -- Address management examples -- Integration examples -- Testing scenarios +See the `examples/` directory for: - Network planning scripts - Address +management examples - Integration examples - Testing scenarios -== โšก Performance +# โšก Performance -The Go tools are optimized for performance: -- `ipv6-ping`: Concurrent pinging with configurable workers -- `ipv6-scan`: Fast network scanning with worker pools +The Go tools are optimized for performance: - `ipv6-ping`: Concurrent +pinging with configurable workers - `ipv6-scan`: Fast network scanning +with worker pools -Python library uses pure Python with no external dependencies for core functionality. +Python library uses pure Python with no external dependencies for core +functionality. -== ๐Ÿ›ก๏ธ Security +# ๐Ÿ›ก๏ธ Security -When using security scanning tools: -- Only scan networks you own or have permission to scan -- Be aware of rate limiting and network policies -- Use responsibly for authorized testing only +When using security scanning tools: - Only scan networks you own or have +permission to scan - Be aware of rate limiting and network policies - +Use responsibly for authorized testing only -== ๐Ÿ’ฌ Support +# ๐Ÿ’ฌ Support + +- Report issues on \[GitHub + Issues\]() -- Report issues on [GitHub Issues](https://github.com/Hyperpolymath/ipv6-only/issues) - Check documentation in the `docs/` directory + - See examples in `examples/` directory