From 5aa5999db44c36bd584dcb4d2e68e463e2f840ee Mon Sep 17 00:00:00 2001 From: Marco Cadetg Date: Wed, 27 Aug 2025 17:50:24 +0200 Subject: [PATCH] updated changelog and readme --- CHANGELOG.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 25 +++++++++++++++------- 2 files changed, 77 insertions(+), 7 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e0f8ae8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,59 @@ +# Changelog + +All notable changes to RustNet will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.2.0] - 2024-12-19 + +### Added +- **Enhanced PKTAP Support on macOS**: Comprehensive process identification using macOS PKTAP (Packet Tap) headers + - Direct extraction of process names and PIDs from kernel packet metadata + - Robust handling of 20-byte PKTAP process name fields with proper normalization + - Support for both `pth_comm` and `pth_e_comm` (effective command name) fields + - Fallback to `lsof` system commands when PKTAP data is unavailable +- **Process Data Immutability System**: Once process information is set from any source, it becomes immutable to prevent display inconsistencies +- **Advanced Process Name Normalization**: Handles all types of whitespace, control characters, and padding in process names +- **Comprehensive Debug Logging**: Extensive logging for PKTAP header processing, process name extraction, and data flow tracking + +### Fixed +- **Process Display Stability on macOS**: Fixed issue where process names would change format during UI scrolling (e.g., "firefox (123)" → "firefox (123)") +- **PKTAP Header Processing**: Improved parsing of raw PKTAP packet headers with better error handling and validation +- **Process Name Consistency**: Eliminated race conditions and data inconsistencies in process name display +- **Whitespace Normalization**: Fixed handling of tabs, multiple spaces, unicode whitespace, and control characters in process names + +### Changed +- **Process Enrichment Logic**: Modified to respect existing PKTAP data and only fill in missing information from `lsof` +- **UI Rendering Optimization**: Simplified process name rendering to use pre-normalized data from sources +- **Error Handling**: Enhanced error reporting for PKTAP processing and process lookup failures + +### Technical Details +- Implemented `extract_process_name_from_bytes()` function for robust PKTAP process name extraction +- Added immutability enforcement in connection merge logic with violation detection +- Enhanced macOS process lookup with `normalize_process_name_robust()` function +- Improved byte-level debugging and logging for process identification troubleshooting + +### Platform-Specific Improvements +- **macOS**: PKTAP now provides primary process identification with significant performance and accuracy improvements over `lsof`-only approach +- **Linux**: Process enrichment logic updated to work consistently with new immutability system + +## [0.1.0] - 2024-XX-XX + +### Added +- Initial release of RustNet +- Real-time network connection monitoring +- Deep packet inspection (DPI) for HTTP, HTTPS, DNS, SSH, and QUIC +- Cross-platform support (Linux, macOS, Windows) +- Terminal user interface with ratatui +- Multi-threaded packet processing +- Process identification using platform-specific APIs +- Service name resolution +- Configurable refresh intervals and filtering options +- Optional logging with multiple log levels + +[Unreleased]: https://github.com/domcyrus/rustnet/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/domcyrus/rustnet/compare/v0.1.0...v0.2.0 +[0.1.0]: https://github.com/domcyrus/rustnet/releases/tag/v0.1.0 \ No newline at end of file diff --git a/README.md b/README.md index 9f09138..c7613bf 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ A high-performance, cross-platform network monitoring tool built with Rust. Rust ```bash # Clone the repository -git clone https://github.com/yourusername/rustnet.git +git clone https://github.com/domcyrus/rustnet.git cd rustnet # Build in release mode @@ -262,6 +262,7 @@ RustNet requires elevated privileges to capture network packets because accessin ### Why Permissions Are Required Network packet capture requires access to: + - **Raw sockets** for low-level network access - **Network interfaces** in promiscuous mode - **BPF (Berkeley Packet Filter) devices** on macOS/BSD systems @@ -286,6 +287,7 @@ sudo ./target/release/rustnet Add your user to the `access_bpf` group for passwordless packet capture: **Using Wireshark's ChmodBPF (Easiest):** + ```bash # Install Wireshark's BPF permission helper brew install --cask wireshark-chmodbpf @@ -296,6 +298,7 @@ rustnet ``` **Manual BPF Group Setup:** + ```bash # Create the access_bpf group (if it doesn't exist) sudo dseditgroup -o create access_bpf @@ -348,6 +351,7 @@ sudo setcap cap_net_raw,cap_net_admin=eip ./target/release/rustnet ``` **For system-wide installation:** + ```bash # If installed via package manager or copied to /usr/local/bin sudo setcap cap_net_raw,cap_net_admin=eip /usr/local/bin/rustnet @@ -380,6 +384,7 @@ Windows support is currently limited, but when available: To verify that permissions are set up correctly: #### macOS + ```bash # Check BPF device permissions ls -la /dev/bpf* @@ -392,6 +397,7 @@ rustnet --help ``` #### Linux + ```bash # Check capabilities on the binary getcap ./target/release/rustnet @@ -406,12 +412,14 @@ rustnet --help #### "Permission denied" errors **On macOS:** + - Ensure you're in the `access_bpf` group: `groups | grep access_bpf` - Check BPF device permissions: `ls -la /dev/bpf0` - Try running with sudo to confirm it's a permission issue - Log out and back in after group changes **On Linux:** + - Check if capabilities are set: `getcap $(which rustnet)` - Verify libpcap is installed: `ldconfig -p | grep pcap` - Try running with sudo to confirm it's a permission issue @@ -439,10 +447,11 @@ rustnet --help 4. **Consider network segmentation** if running on production systems 5. **Monitor log files** for unauthorized usage 6. **Remove capabilities** when RustNet is no longer needed: + ```bash # Linux: Remove capabilities sudo setcap -r /path/to/rustnet - + # macOS: Remove from group sudo dseditgroup -o edit -d $USER -t user access_bpf ``` @@ -450,6 +459,7 @@ rustnet --help ### Integration with System Monitoring For production environments, consider: + - **Audit logging** of packet capture access - **Network monitoring policies** and compliance requirements - **User access reviews** for privileged network access @@ -506,7 +516,7 @@ git push origin v0.2.0 #### 3. Create GitHub Release -1. Go to the [GitHub repository releases page](https://github.com/yourusername/rustnet/releases) +1. Go to the [GitHub repository releases page](https://github.com/domcyrus/rustnet/releases) 2. Click "Create a new release" 3. Select the tag you just pushed (v0.2.0) 4. Set the release title (e.g., "RustNet v0.2.0") @@ -533,7 +543,7 @@ After creating the GitHub release, update the Homebrew formula: ```bash # Calculate SHA256 of the source tarball -curl -L "https://github.com/yourusername/rustnet/archive/v0.2.0.tar.gz" | shasum -a 256 +curl -L "https://github.com/domcyrus/rustnet/archive/v0.2.0.tar.gz" | shasum -a 256 # The output will be something like: # a1b2c3d4e5f6... (64-character hash) @@ -544,8 +554,8 @@ Update the Homebrew formula file (`rustnet.rb` in your tap repository): ```ruby class Rustnet < Formula desc "High-performance network monitoring tool with TUI" - homepage "https://github.com/yourusername/rustnet" - url "https://github.com/yourusername/rustnet/archive/v0.2.0.tar.gz" + homepage "https://github.com/domcyrus/homebrew-rustnet" + url "https://github.com/domcyrus/rustnet/archive/v0.2.0.tar.gz" sha256 "a1b2c3d4e5f6..." # Replace with actual SHA256 from above license "Apache-2.0" @@ -565,7 +575,7 @@ end ```bash # Clone or update your homebrew tap repository -git clone https://github.com/yourusername/homebrew-rustnet.git +git clone https://github.com/domcyrus/homebrew-rustnet.git cd homebrew-rustnet # Update the formula file with new version and SHA256 @@ -644,6 +654,7 @@ RustNet follows [Semantic Versioning (SemVer)](https://semver.org/): - **PATCH** version for backward-compatible bug fixes Examples: + - `v0.1.0` → `v0.1.1` (bug fixes) - `v0.1.1` → `v0.2.0` (new features) - `v0.2.0` → `v1.0.0` (major changes, API stability)