{"id":31068670,"url":"https://github.com/madebyjake/netnoise","last_synced_at":"2025-09-15T21:57:56.249Z","repository":{"id":314154932,"uuid":"1054427028","full_name":"madebyjake/netnoise","owner":"madebyjake","description":"NetNoise - A network troubleshooting utility that performs active connectivity testing across multiple protocols. It conducts ping, HTTP/HTTPS, and traceroute tests against configurable targets to help diagnose network issues and monitor connection health.","archived":false,"fork":false,"pushed_at":"2025-09-11T16:50:14.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-11T18:29:07.677Z","etag":null,"topics":["connectivity","network","network-analysis","network-testing","network-tools","network-troubleshooting"],"latest_commit_sha":null,"homepage":"https://github.com/madebyjake/netnoise","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madebyjake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-10T20:22:21.000Z","updated_at":"2025-09-11T15:26:15.000Z","dependencies_parsed_at":"2025-09-11T18:29:11.782Z","dependency_job_id":"d481941d-1970-45c5-9a30-b1f8b26b950c","html_url":"https://github.com/madebyjake/netnoise","commit_stats":null,"previous_names":["madebyjake/onp","madebyjake/netnoise"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/madebyjake/netnoise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebyjake%2Fnetnoise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebyjake%2Fnetnoise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebyjake%2Fnetnoise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebyjake%2Fnetnoise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madebyjake","download_url":"https://codeload.github.com/madebyjake/netnoise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebyjake%2Fnetnoise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275327139,"owners_count":25445050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["connectivity","network","network-analysis","network-testing","network-tools","network-troubleshooting"],"created_at":"2025-09-15T21:57:51.507Z","updated_at":"2025-09-15T21:57:56.235Z","avatar_url":"https://github.com/madebyjake.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NetNoise\n\n[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black)](https://www.linux.org/)\n[![Bash](https://img.shields.io/badge/Bash-4EAA25?logo=gnu-bash\u0026logoColor=white)](https://www.gnu.org/software/bash/)\n[![Make](https://img.shields.io/badge/Make-427819?logo=gnu\u0026logoColor=white)](https://www.gnu.org/software/make/)\n[![License](https://img.shields.io/badge/License-MIT-yellow?logo=open-source-initiative\u0026logoColor=white)](LICENSE)\n[![Test](https://github.com/madebyjake/netnoise/actions/workflows/test.yml/badge.svg)](https://github.com/madebyjake/netnoise/actions/workflows/test.yml)\n\nNetNoise is a network monitoring and troubleshooting utility that performs connectivity testing across multiple protocols. It provides automated testing of DNS resolution, ping, traceroute, HTTP/HTTPS connectivity, bandwidth analysis, port scanning, and MTU discovery against configurable targets for network diagnostics and monitoring.\n\n## Features\n\n- **Network Testing**: DNS resolution, ping, traceroute, HTTP/HTTPS connectivity\n- **Performance Analysis**: Bandwidth testing, MTU discovery, port scanning\n- **Monitoring**: Automated scheduling with systemd integration\n- **Alerting**: Email and webhook notifications on failures\n- **Logging**: Structured JSON output with configurable retention\n- **Configuration**: Flexible target lists and test parameters\n\n## Quick Reference\n\n```bash\n# Installation\ngit clone https://github.com/madebyjake/netnoise.git\ncd netnoise\nsudo ./install.sh\n\n# Upgrade\nmake upgrade    # Upgrade netnoise to latest version\n\n# Service Management\nmake start      # Start monitoring\nmake stop       # Stop monitoring\nmake restart    # Restart monitoring\nmake status     # Check service status\n\n# Configuration\nmake config     # Edit configuration\nmake check      # Validate configuration\nmake regenerate # Regenerate timer after config changes\n\n# Testing \u0026 Monitoring\nmake test       # Run test suite\nmake manual     # Run manual test\nmake health     # Show health status\nmake logs       # View recent logs\n\n# Maintenance\nmake clean      # Clean old logs and results\nmake version    # Show version information\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Linux system with systemd\n- Root or sudo access\n- Required tools: `ping`, `traceroute`, `curl`, `jq`, `bc`, `dig` or `nslookup`\n\n### Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/madebyjake/netnoise.git\n   cd netnoise\n   ```\n\n2. **Install netnoise:**\n   ```bash\n   sudo chmod +x install.sh\n   sudo ./install.sh\n   ```\n\n3. **Configure targets:**\n   ```bash\n   sudo nano /opt/netnoise/netnoise.conf\n   ```\n\n4. **Start monitoring:**\n   ```bash\n   sudo systemctl start netnoise.timer\n   ```\n\n### ⚠️ Security Reminder\n\n**Always review scripts before running with root/sudo privileges!**\n\n## Upgrading NetNoise\n\n### Automatic Upgrade (Recommended)\n\nThe easiest way to upgrade netnoise is to use the built-in upgrade functionality:\n\n```bash\n# Stop the service\nsudo systemctl stop netnoise.timer\nsudo systemctl stop netnoise.service\n\n# Navigate to your netnoise directory\ncd /path/to/netnoise\n\n# Pull the latest changes\ngit pull origin main\n\n# Reinstall with the new version\nsudo ./install.sh\n\n# Start the service\nsudo systemctl start netnoise.timer\n```\n\n### Manual Upgrade\n\nIf you prefer to upgrade manually or need more control:\n\n1. **Backup your configuration:**\n   ```bash\n   sudo cp /opt/netnoise/netnoise.conf /opt/netnoise/netnoise.conf.backup\n   ```\n\n2. **Stop the service:**\n   ```bash\n   sudo systemctl stop netnoise.timer\n   sudo systemctl stop netnoise.service\n   ```\n\n3. **Update the code:**\n   ```bash\n   cd /path/to/netnoise\n   git pull origin main\n   ```\n\n4. **Reinstall:**\n   ```bash\n   sudo ./install.sh\n   ```\n\n5. **Restore your configuration (if needed):**\n   ```bash\n   sudo cp /opt/netnoise/netnoise.conf.backup /opt/netnoise/netnoise.conf\n   ```\n\n6. **Start the service:**\n   ```bash\n   sudo systemctl start netnoise.timer\n   ```\n\n### Upgrade Verification\n\nAfter upgrading, verify everything is working correctly:\n\n```bash\n# Check service status\nsudo systemctl status netnoise.timer\nsudo systemctl status netnoise.service\n\n# Test configuration\nsudo /opt/netnoise/netnoise.sh --check\n\n# Run a manual test\nsudo /opt/netnoise/netnoise.sh\n\n# Check logs\nsudo journalctl -u netnoise.service -f\n```\n\n### Configuration Migration\n\nWhen upgrading, your existing configuration will be preserved. However, new features may require configuration updates:\n\n- **New targets**: The default configuration may include new monitoring targets\n- **New settings**: Additional configuration options may be available\n- **Deprecated options**: Some old configuration options may be deprecated\n\nCheck the project's release notes for detailed upgrade information and breaking changes.\n\n### Rollback\n\nIf you need to rollback to a previous version:\n\n```bash\n# Stop the service\nsudo systemctl stop netnoise.timer\nsudo systemctl stop netnoise.service\n\n# Checkout the previous version\ncd /path/to/netnoise\ngit checkout \u003cprevious-version-tag\u003e\n\n# Reinstall\nsudo ./install.sh\n\n# Start the service\nsudo systemctl start netnoise.timer\n```\n\n## Configuration\n\nEdit `/opt/netnoise/netnoise.conf` to configure monitoring:\n\n```bash\n# Monitoring targets\nTARGETS=(\n    # Core Internet Infrastructure\n    \"google.com\"                # Global search/CDN\n    \"cloudflare.com\"            # Major CDN/DNS provider\n    \"1.1.1.1\"                   # Cloudflare DNS (IPv4)\n    \"8.8.8.8\"                   # Google DNS (IPv4)\n    \n    # DNS Root Servers\n    \"a.root-servers.net\"        # Root DNS server A\n    \"b.root-servers.net\"        # Root DNS server B\n    \n    # Global Services\n    \"amazon.com\"                # Global e-commerce/CDN\n    \"microsoft.com\"             # Enterprise services\n    \"github.com\"                # Developer platform\n    \"wikipedia.org\"             # Global knowledge base\n    \n    # CDN Providers\n    \"fastly.com\"                # Major CDN provider\n    \"akamai.com\"                # Major CDN provider\n    \n    # Network Infrastructure\n    \"level3.net\"                # Major backbone provider\n    \"he.net\"                    # Hurricane Electric (global ISP)\n    \"cogentco.com\"              # Major backbone provider\n    \"ntt.net\"                   # Global backbone provider\n    \n    # Time Services\n    \"time.nist.gov\"             # NTP time server\n)\n\n# Ping settings - Basic connectivity testing\nPING_COUNT=4                    # Number of ping packets to send\nPING_TIMEOUT=10                 # Timeout per ping in seconds\n\n# Traceroute settings - Network path discovery\nTRACEROUTE_MAX_HOPS=30          # Maximum number of hops to trace\nTRACEROUTE_TIMEOUT=5            # Timeout per hop in seconds\n\n# DNS resolution test settings - Name resolution testing\nDNS_TIMEOUT=5                   # DNS query timeout in seconds\nDNS_ENABLED=true                # Enable DNS resolution tests\n\n# Bandwidth test settings - Network performance testing (resource intensive)\nBANDWIDTH_ENABLED=false         # Enable bandwidth testing\nBANDWIDTH_TIMEOUT=30            # Bandwidth test timeout in seconds\nBANDWIDTH_TEST_UPLOAD=false     # Include upload speed testing\n\n# Port scanning test settings - Service availability testing (security sensitive)\nPORT_SCAN_ENABLED=false         # Enable port scanning\nPORT_SCAN_TIMEOUT=5             # Port scan timeout in seconds\nPORT_SCAN_PORTS=\"22,80,443,25,53,110,143,993,995\"  # Ports to scan\n\n# MTU discovery test settings - Maximum transmission unit testing\nMTU_ENABLED=false               # Enable MTU discovery\nMTU_TIMEOUT=5                   # MTU test timeout in seconds\nMTU_MIN=576                     # Minimum MTU to test (bytes)\nMTU_MAX=1500                    # Maximum MTU to test (bytes)\nMTU_STEP=10                     # MTU test step size (bytes)\n\n# HTTP/HTTPS test settings - Web service connectivity\nHTTP_TIMEOUT=10                 # HTTP request timeout in seconds\nHTTP_USER_AGENT=\"netnoise/1.0\"  # User agent string for HTTP requests\n\n# Alert settings - Notification configuration\nALERT_ON_FAILURE=true           # Send alerts when tests fail\nALERT_EMAIL=\"\"                  # Email address for alerts (optional)\nALERT_WEBHOOK=\"\"                # Webhook URL for alerts (optional)\n\n# Timer settings - Service scheduling\nTIMER_INTERVAL=\"hourly\"         # How often to run tests\n# Options: \"minutely\", \"hourly\", \"daily\", \"weekly\", \"monthly\"\n# Or custom: \"*-*-* *:00:00\" (every hour), \"*-*-* *:*/15:00\" (every 15 minutes)\n# Or specific: \"Mon *-*-* 09:00:00\" (every Monday at 9 AM)\n\n# Log retention settings - Log management\nLOG_RETENTION_DAYS=30           # Days to retain log files\n```\n\n### DNS Testing Configuration\n\nDNS resolution testing can be configured with the following settings:\n\n- **`DNS_ENABLED`**: Enable/disable DNS testing (default: `true`)\n- **`DNS_TIMEOUT`**: DNS query timeout in seconds (default: `5`, range: 1-60)\n\nDNS testing uses `dig` (preferred) or `nslookup` as fallback. The test measures:\n- DNS resolution time\n- IP addresses returned\n- Success/failure status\n\n### Bandwidth Testing Configuration\n\nBandwidth testing can be configured with the following settings:\n\n- **`BANDWIDTH_ENABLED`**: Enable/disable bandwidth testing (default: `false`)\n- **`BANDWIDTH_TIMEOUT`**: Test timeout in seconds (default: `30`, range: 5-300)\n- **`BANDWIDTH_TEST_UPLOAD`**: Enable upload speed testing (default: `false`)\n\nBandwidth testing uses `curl` (preferred) or `wget` as fallback. The test measures:\n- Download speed in Mbps\n- Upload speed in Mbps (if enabled)\n- Test duration and success/failure status\n\n**Note**: Bandwidth testing is disabled by default as it can consume significant bandwidth and time.\n\n### Port Scanning Configuration\n\nPort scanning can be configured with the following settings:\n\n- **`PORT_SCAN_ENABLED`**: Enable/disable port scanning (default: `false`)\n- **`PORT_SCAN_TIMEOUT`**: Connection timeout per port in seconds (default: `5`, range: 1-30)\n- **`PORT_SCAN_PORTS`**: Comma-separated list of ports to scan (default: `\"22,80,443,25,53,110,143,993,995\"`)\n\nPort scanning uses `nc` (netcat) as the preferred method or `/dev/tcp` as fallback. The test measures:\n- Open ports on the target host\n- Connection success/failure for each port\n- Total scan duration and statistics\n\n**Common Ports:**\n- **22**: SSH\n- **80**: HTTP\n- **443**: HTTPS\n- **25**: SMTP\n- **53**: DNS\n- **110**: POP3\n- **143**: IMAP\n- **993**: IMAPS\n- **995**: POP3S\n\n**Note**: Port scanning is disabled by default as it can be seen as intrusive by some network administrators.\n\n### MTU Discovery Configuration\n\nMTU discovery can be configured with the following settings:\n\n- **`MTU_ENABLED`**: Enable/disable MTU discovery (default: `false`)\n- **`MTU_TIMEOUT`**: Per-test timeout in seconds (default: `5`, range: 1-30)\n- **`MTU_MIN`**: Minimum MTU to test in bytes (default: `576`, range: 68-9000)\n- **`MTU_MAX`**: Maximum MTU to test in bytes (default: `1500`, range: 68-9000)\n- **`MTU_STEP`**: Step size for binary search in bytes (default: `10`, range: 1-100)\n\nMTU discovery uses `ping -M do` (Don't Fragment) with binary search algorithm. The test measures:\n- Optimal MTU size for the network path\n- Number of tests performed during discovery\n- Total discovery time and success/failure status\n\n**How it works:**\n1. Uses binary search between MTU_MIN and MTU_MAX\n2. Tests each MTU size with `ping -M do -s \u003cpayload_size\u003e`\n3. Finds the largest MTU that doesn't require fragmentation\n4. Reports the optimal MTU size for the network path\n\n**Note**: MTU discovery is disabled by default as it can be time-consuming and may generate significant network traffic.\n\n### Timer Configuration\n\nThe monitoring interval is configurable via the `TIMER_INTERVAL` setting:\n\n- **Predefined intervals**: `minutely`, `hourly`, `daily`, `weekly`, `monthly`\n- **Custom intervals**: Use systemd calendar expressions\n  - `\"*-*-* *:00:00\"` - Every hour\n  - `\"*-*-* *:*/15:00\"` - Every 15 minutes\n  - `\"*-*-* 09:00:00\"` - Every day at 9 AM\n\nAfter changing the timer interval, regenerate the timer:\n```bash\nmake regenerate\n```\n\n## Usage\n\n### Service Management\n\n```bash\n# Start/stop/restart monitoring\nsudo systemctl start netnoise.timer\nsudo systemctl stop netnoise.timer\nsudo systemctl restart netnoise.timer\n\n# Check status\nsudo systemctl status netnoise.timer\n\n# View logs\nsudo journalctl -u netnoise.service -f\n```\n\n### Enabling Bandwidth Testing\n\nTo enable bandwidth testing, edit the configuration file:\n\n```bash\n# Edit configuration\nsudo nano /opt/netnoise/netnoise.conf\n\n# Enable bandwidth testing\nBANDWIDTH_ENABLED=true\nBANDWIDTH_TIMEOUT=30\nBANDWIDTH_TEST_UPLOAD=false  # Optional: enable upload testing\n\n# Restart service to apply changes\nsudo systemctl restart netnoise.timer\n```\n\n### Enabling Port Scanning\n\nTo enable port scanning, edit the configuration file:\n\n```bash\n# Edit configuration\nsudo nano /opt/netnoise/netnoise.conf\n\n# Enable port scanning\nPORT_SCAN_ENABLED=true\nPORT_SCAN_TIMEOUT=5\nPORT_SCAN_PORTS=\"22,80,443,25,53\"  # Customize ports as needed\n\n# Restart service to apply changes\nsudo systemctl restart netnoise.timer\n```\n\n### Enabling MTU Discovery\n\nTo enable MTU discovery, edit the configuration file:\n\n```bash\n# Edit configuration\nsudo nano /opt/netnoise/netnoise.conf\n\n# Enable MTU discovery\nMTU_ENABLED=true\nMTU_TIMEOUT=5\nMTU_MIN=576\nMTU_MAX=1500\nMTU_STEP=10\n\n# Restart service to apply changes\nsudo systemctl restart netnoise.timer\n```\n\n\n### Advanced Features\n\n**Configuration Validation:**\n```bash\nmake check  # Validate configuration\n```\n\n**Performance Monitoring:**\n- Operation timing and resource usage tracking\n- Performance logs: `logs/netnoise-performance-YYYYMMDD.log`\n\n**Health Check:**\n```bash\nmake health  # Show health status\n```\nHealth data is stored in `/opt/netnoise/health.json` for monitoring integration.\n\n### Viewing Results\n\n```bash\n# View logs\nmake logs\n\n# View JSON results\nsudo cat /opt/netnoise/results/netnoise-results-$(date +%Y%m%d).json | jq\n\n# View specific target results\nsudo cat /opt/netnoise/results/netnoise-results-$(date +%Y%m%d).json | jq '.[] | select(.target == \"google.com\")'\n\n# View bandwidth test results only\nsudo cat /opt/netnoise/results/netnoise-results-$(date +%Y%m%d).json | jq '.[] | select(.target == \"google.com\") | .bandwidth'\n\n# View port scanning results only\nsudo cat /opt/netnoise/results/netnoise-results-$(date +%Y%m%d).json | jq '.[] | select(.target == \"google.com\") | .ports'\n\n# View MTU discovery results only\nsudo cat /opt/netnoise/results/netnoise-results-$(date +%Y%m%d).json | jq '.[] | select(.target == \"google.com\") | .mtu'\n```\n\n## Alerting\n\nConfigure alerts in `netnoise.conf`:\n\n- **Email alerts**: Set `ALERT_EMAIL` (requires `mail` command)\n- **Webhook alerts**: Set `ALERT_WEBHOOK` for HTTP POST endpoints (Slack, Discord, etc.)\n\n## Security Considerations\n\n- **Always review scripts before running with sudo/root privileges**\n- Service runs as root to access network tools (ping, traceroute)\n- Logs may contain sensitive network information\n- Keep installation directory (`/opt/netnoise`) secure\n- Use strong authentication for alert webhooks\n\n## Troubleshooting\n\n**Missing Dependencies:**\n```bash\n# Ubuntu/Debian\nsudo apt install traceroute curl jq bc dnsutils\n\n# CentOS/RHEL\nsudo dnf install traceroute curl jq bc bind-utils\n\n# openSUSE\nsudo zypper install traceroute curl jq bc bind-utils\n\n# macOS\nbrew install traceroute curl jq bc\n```\n\n**Service Issues:**\n```bash\n# Check status\nsudo systemctl status netnoise.timer\n\n# Check logs\nsudo journalctl -u netnoise.service -n 50\n\n# Test manually\nsudo /opt/netnoise/netnoise.sh\n\n# Debug mode\nsudo bash -x /opt/netnoise/netnoise.sh\n```\n\n## Uninstallation\n\n```bash\nsudo ./install.sh uninstall\n```\n\nThis removes the systemd service, installation directory, and all logs.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadebyjake%2Fnetnoise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadebyjake%2Fnetnoise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadebyjake%2Fnetnoise/lists"}