From 794dcc9d146b461b4f7d1744e9714c9caf3d071b Mon Sep 17 00:00:00 2001 From: Kiyomichi Kosaka Date: Mon, 11 Aug 2025 00:58:50 +0200 Subject: [PATCH] Fix README.md --- README.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 152 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index fdc3199..b2e1e96 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,31 @@ # NetTest - Network Connectivity Testing Tool -A comprehensive command-line tool written in Rust for testing network connectivity and DNS resolution across various dimensions. +A comprehensive command-line tool written in Rust for testing network connectivity, DNS resolution, and network path characteristics across IPv4 and IPv6. + +**Key Features:** +- 🌐 Comprehensive IPv4/IPv6 connectivity testing +- 🔍 Advanced DNS testing with sinkhole detection +- 📊 MTU discovery and path analysis +- 🛡️ DNS filtering effectiveness analysis +- 🚀 High-performance async implementation +- 📋 Human-readable and JSON output formats + +## Quick Start + +```bash +# Clone and build +git clone https://github.com/your-username/nettest.git +cd nettest && cargo build --release + +# Run comprehensive tests +./target/release/nettest full google.com + +# Test DNS with IPv6 +./target/release/nettest network ping google.com --ip-version v6 + +# Check DNS filtering effectiveness +./target/release/nettest dns filtering +``` ## Features @@ -20,6 +45,9 @@ A comprehensive command-line tool written in Rust for testing network connectivi - **Comprehensive record types** - A, AAAA, MX, NS, TXT, CNAME, SOA, PTR, and more - **Multiple DNS servers** - Test against Google, Cloudflare, Quad9, OpenDNS, and others - **TCP and UDP queries** - Support for both DNS transport protocols +- **Sinkhole detection** - Automatically detects DNS sinkholing (0.0.0.0, 127.0.0.1, etc.) +- **Smart error handling** - Distinguishes between DNS failures and missing records +- **System DNS integration** - Uses system DNS configuration while avoiding search domain expansion - **Large query testing** - Test handling of large DNS responses - **International domains** - Support for IDN (Internationalized Domain Names) @@ -41,9 +69,11 @@ A comprehensive command-line tool written in Rust for testing network connectivi ## Installation +### From Source + ```bash # Clone the repository -git clone +git clone https://github.com/your-username/nettest.git cd nettest # Build the project @@ -53,6 +83,21 @@ cargo build --release cargo install --path . ``` +### Using Cargo + +```bash +# Install directly from source (when published) +cargo install nettest +``` + +### Requirements + +- Rust 1.70 or later +- Root/administrator privileges may be required for: + - ICMP ping tests + - Raw socket operations + - Some MTU discovery operations + ## Usage ### Basic Commands @@ -129,6 +174,25 @@ nettest dns categories --category all # DNS filtering effectiveness nettest dns filtering + +# Show system DNS configuration +nettest dns debug +``` + +### DNS Sinkhole Detection + +NetTest automatically detects when domains are being sinkholed (redirected to special IP addresses): + +```bash +# Example output showing sinkhole detection +$ nettest dns query blocked-domain.com --record-type a +PASS DNS A query for blocked-domain.com (UDP) (45ms) + ✓ A records: 🕳️ SINKHOLED (security success): Redirected to sinkhole IPs: 0.0.0.0 + +# Example showing missing records (not an error) +$ nettest dns query image.example.com --record-type mx +PASS DNS MX query for image.example.com (UDP) (32ms) + ✓ MX records: (none - no mail servers configured) ``` ### Comprehensive Testing @@ -162,13 +226,6 @@ Machine-readable JSON output for integration with other tools: nettest --json dns query google.com ``` -## Requirements - -- Rust 1.70 or later -- Root/administrator privileges may be required for: - - ICMP ping tests - - Raw socket operations - - MTU discovery ## Testing @@ -187,13 +244,31 @@ cargo test -- --nocapture ## Architecture -The tool is organized into several modules: +NetTest is built with a modular architecture for maintainability and extensibility: -- **cli** - Command-line argument parsing and interface -- **network** - TCP, UDP, and ICMP connectivity testing -- **dns** - DNS resolution and query testing -- **mtu** - MTU discovery and testing -- **utils** - Common utilities and error handling +``` +src/ +├── cli/ # Command-line interface and argument parsing +├── network/ # Network connectivity testing +│ ├── icmp.rs # ICMP ping tests with IPv6 support +│ ├── tcp.rs # TCP connection testing +│ └── udp.rs # UDP connectivity testing +├── dns/ # DNS testing and analysis +│ ├── categories.rs # Domain category definitions +│ ├── queries.rs # DNS query implementations +│ └── mod.rs # Core DNS logic with sinkhole detection +├── mtu/ # MTU discovery and testing +├── utils/ # Common utilities and error handling +└── main.rs # Application entry point and orchestration +``` + +### Key Design Principles + +- **Async-first**: All network operations are asynchronous for better performance +- **Error handling**: Comprehensive error handling with descriptive messages +- **Cross-platform**: Works on macOS, Linux, and Windows +- **IPv6 ready**: Full support for IPv6 alongside IPv4 +- **Extensible**: Easy to add new test types and protocols ## Security Considerations @@ -207,8 +282,68 @@ This tool is designed for defensive security testing and network diagnostics. It ## License -[Add your license here] +This project is licensed under the **WTFPL** (Do What The F*ck You Want To Public License) Version 2. + +``` + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + Version 2, December 2004 + + Copyright (C) 2004 Sam Hocevar + + Everyone is permitted to copy and distribute verbatim or modified + copies of this license document, and changing it is allowed as long + as the name is changed. + + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. You just DO WHAT THE FUCK YOU WANT TO. +``` + +**TL;DR:** Do whatever you want with this code! 🎉 ## Contributing -[Add contribution guidelines here] \ No newline at end of file +Since this project is licensed under WTFPL, you can do whatever you want! But if you'd like to contribute: + +1. **Fork the repository** +2. **Create a feature branch**: `git checkout -b feature/amazing-feature` +3. **Make your changes and test**: `cargo test && cargo clippy` +4. **Commit your changes**: `git commit -m 'Add amazing feature'` +5. **Push to the branch**: `git push origin feature/amazing-feature` +6. **Open a Pull Request** + +### Development Setup + +```bash +# Clone your fork +git clone https://github.com/your-username/nettest.git +cd nettest + +# Install development dependencies +cargo build + +# Run all quality checks +cargo fmt # Format code +cargo clippy # Lint code +cargo test # Run tests +cargo audit # Security audit +``` + +### Code Quality + +The project maintains high code quality standards: +- ✅ All tests must pass +- ✅ Zero clippy warnings +- ✅ Proper formatting with rustfmt +- ✅ No security vulnerabilities +- ✅ Comprehensive error handling + +## Changelog + +### Recent Improvements +- 🔧 **Fixed IPv6 ping issues** - IPv6 ICMP now works correctly on macOS +- 🛡️ **Enhanced DNS security** - Added sinkhole detection and improved error handling +- 📦 **Updated dependencies** - Migrated from trust-dns to hickory-dns for better maintenance +- 🎯 **Improved accuracy** - Fixed DNS search domain issues for more accurate testing +- ⚡ **Better performance** - Async implementation with proper timeout handling