Fix README.md

2025-08-11 00:58:50 +02:00
parent f3f2931659
commit 794dcc9d14
1 changed files with 152 additions and 17 deletions
@@ -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 <repository-url>
+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 <sam@hocevar.net>
+
+ 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]
+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