Repository navigation
NETWATCH 1.3.0
NETWATCH 1.3.0 expands the project from IPv4-focused Linux network monitoring into a broader Linux network administration toolkit.
This release is Linux-only and keeps Android/Termux and Windows/PowerShell outside the project scope.
Highlights
Linux-only architecture
NETWATCH now targets Linux exclusively.
Removed platform implementations:
- "netwatch-android.sh"
- "netwatch.ps1"
The repository is focused on Linux networking and administration.
IPv4 Network Discovery
NETWATCH automatically detects the active Linux network using:
- default gateway
- active interface
- local IPv4 address
- network prefix
Network discovery supports subnet information obtained from the Linux networking stack and "ipcalc" when available.
The scanner continues to refresh stale neighbor entries before resolving MAC addresses:
ip neigh flush nud stale
This helps ensure that neighbor information is current before device information is collected.
Device Discovery
The IPv4 scanner uses Nmap host discovery and reports:
- IPv4 address
- MAC address
- hostname
- vendor
- blocked state
- throttling state
Supported scan formats:
sudo ./netwatch.sh scan
sudo ./netwatch.sh scan json
sudo ./netwatch.sh scan csv
Device Identification
NETWATCH provides a deeper fingerprinting workflow for individual devices.
Identification can include:
- IPv4 address
- MAC address
- reverse DNS
- hardware vendor
- mDNS / Bonjour services
- NetBIOS / SMB name
- open TCP ports
- service/version detection
- OS fingerprinting
The core identification engine uses Nmap:
nmap -sV -O --osscan-guess
Optional Linux utilities extend the information available for specific devices.
Hardware Vendor Detection
NETWATCH includes a local OUI mapping and can optionally query "macvendors.com".
Vendor identification is therefore available through both local and remote lookup paths.
The local mapping covers a set of common vendors, while remote lookup can provide additional information when network access is available.
OS & Service Fingerprinting
The "identify" command performs service and operating-system discovery when Nmap has sufficient network visibility and privileges.
Example:
sudo ./netwatch.sh identify 192.168.1.42
The result can include:
Open ports
Services
Service versions
OS details
OS confidence information
Actual OS detection depends on what the target exposes to Nmap.
IPv4 Gateway Blocking
NETWATCH supports gateway-based device blocking.
The Linux host must actually be operating as an IPv4 gateway/router with forwarding enabled.
The blocking path uses a dedicated Netfilter chain:
NETWATCH_BLOCK
This keeps the control rules identifiable as Netwatch-owned rules.
A target cannot be the default gateway itself.
Example:
sudo ./netwatch.sh block 192.168.1.50
or:
sudo ./netwatch.sh block AA:BB:CC:DD:EE:FF
ARP Spoofing Support
When "arpspoof" is installed, the Linux gateway blocking path can additionally establish an ARP spoofing pair between the target and gateway.
Required package on Debian/Ubuntu:
sudo apt install dsniff
NETWATCH tracks the spawned ARP spoofing processes so they can be terminated by "unblock".
Example:
sudo ./netwatch.sh unblock 192.168.1.50
The repository continues to restrict this functionality to authorized gateway/router environments.
Bandwidth Throttling
NETWATCH supports Linux traffic shaping using:
- "iptables"
- packet marks
- "tc"
- HTB classes
Example:
sudo ./netwatch.sh throttle AA:BB:CC:DD:EE:FF 1mbit
Accepted rate examples include:
512kbit
1mbit
2mbit
5mbit
1gbit
Input validation rejects malformed rate specifications.
IPv6 Support
NETWATCH 1.3.0 adds a dedicated Linux IPv6 helper:
netwatch-ipv6.sh
The helper provides:
- IPv6 interface detection
- IPv6 default-route detection
- global IPv6 address detection
- on-link neighbor discovery
- IPv6 MAC/neighbor information
- IPv6 identification
- CSV export
- JSON export
- IPv6 gateway blocking
- IPv6 unblocking
- dry-run support
IPv6 Neighbor Discovery
The IPv6 helper can stimulate neighbor discovery using the IPv6 all-nodes multicast address:
ff02::1
It then reads the Linux IPv6 neighbor table using:
ip -6 neigh
This makes IPv6 discovery rely on the local Linux networking stack rather than assuming an IPv4-style subnet sweep.
IPv6 Identification
Individual IPv6 targets can be fingerprinted with Nmap's IPv6 mode:
sudo ./netwatch-ipv6.sh identify 2001:db8::10
The identification path uses:
nmap -6 -sV -O --osscan-guess
IPv6 Gateway Blocking
IPv6 blocking uses a dedicated IPv6 firewall chain:
NETWATCH6_BLOCK
The helper verifies that:
- the target is a valid IPv6 address;
- the target is not the default IPv6 gateway;
- IPv6 forwarding is enabled;
- the Linux host is acting as an IPv6 router/gateway.
Example:
sudo ./netwatch-ipv6.sh block 2001:db8::10
Unblock:
sudo ./netwatch-ipv6.sh unblock 2001:db8::10
IPv6 Dry Run
Control operations support:
--dry-run
Example:
sudo ./netwatch-ipv6.sh --dry-run block 2001:db8::10
No "ip6tables" changes are applied in dry-run mode.
Router Integration
NETWATCH 1.3.0 also introduces:
netwatch-router.sh
This is a vendor-neutral SSH integration bridge.
It does not pretend that every router exposes the same configuration language.
Instead, administrators provide the router host, account, optional SSH key, and the router-side commands appropriate for their hardware.
Router SSH Configuration
Configuration can be supplied through environment variables:
export NETWATCH_ROUTER_HOST="192.168.1.1"
export NETWATCH_ROUTER_USER="admin"
export NETWATCH_ROUTER_PORT="22"
export NETWATCH_ROUTER_KEY="$HOME/.ssh/router_key"
Connection test:
./netwatch-router.sh check
Remote Router Commands
Administrators can execute explicitly supplied router commands through SSH:
./netwatch-router.sh exec [args...]
The helper passes the supplied command as SSH arguments rather than building a local shell command dynamically.
Router Script Application
A local administrator-provided script can be sent over SSH:
./netwatch-router.sh apply router-config.sh
The router-side shell executes the supplied script through standard input.
This provides a generic integration mechanism without embedding vendor-specific syntax into NETWATCH.
Interactive Menu
The Linux implementation includes an interactive terminal interface.
Available functions include:
Scan
Show devices
Identify
Block
Unblock
Throttle
Unthrottle
Monitor
Export
List state
Reset
Update
Quit
Monitor Mode
The monitor continuously refreshes the network view.
Example:
sudo ./netwatch.sh monitor 10
The refresh interval is validated and limited to a safe operational range.
Export
NETWATCH can export discovery results as:
CSV
JSON
Example:
sudo ./netwatch.sh export csv
sudo ./netwatch.sh export json
Dry Run
The main Linux implementation supports:
--dry-run
Example:
sudo ./netwatch.sh --dry-run block 192.168.1.50
This allows administrators to preview control operations before applying them.
Configuration
Default configuration directory:
~/.config/netwatch/
It can be overridden:
export NETWATCH_CONFIG=/path/to/config
Typical runtime state includes:
blocked_macs
blocked_ips
throttled_macs
blocked_ipv6
scan_history.log
Generated exports are stored alongside runtime configuration.
Runtime data is excluded from version control.
Dependencies
Core Linux requirements
bash
nmap
ip
iproute2
iptables
tc
awk
Optional functionality
arpspoof / dsniff
curl
wget
ipcalc
dig
avahi-utils
samba-common-bin
IPv6 firewall control additionally requires:
ip6tables
Router integration requires:
ssh
Debian / Ubuntu Installation
Core packages:
sudo apt install bash nmap iproute2 iptables curl ipcalc dnsutils
For ARP spoofing support:
sudo apt install dsniff
For optional discovery services:
sudo apt install avahi-utils samba-common-bin
Installation
Clone the repository:
git clone https://github.com/sudomarc/NETWATCH-carbone.git
cd NETWATCH-carbone
chmod +x netwatch.sh netwatch-ipv6.sh netwatch-router.sh
Run the main application:
sudo ./netwatch.sh
Project Structure
The project is now organized around Linux components:
netwatch.sh
netwatch-ipv6.sh
netwatch-router.sh
README.md
CONTRIBUTING.md
LICENSE
.gitignore
Android and Windows implementations are not part of this release.
Security Model
Network-control operations require elevated Linux privileges where necessary.
Gateway-dependent functionality is intentionally restricted to environments where the Linux machine is actually positioned as a router/gateway.
NETWATCH should only be used on networks and systems that the operator owns or is explicitly authorized to administer.
Particular care is required with:
- firewall modifications
- traffic shaping
- IPv6 firewall rules
- ARP spoofing
- router administration
- persistent configuration changes
IPv6 and Router Integration Scope
IPv6 support is implemented specifically for the Linux networking stack.
Router integration is intentionally vendor-neutral.
Because router operating systems do not share a universal command language, vendor-specific configuration remains administrator-defined through the SSH bridge rather than being guessed or hard-coded.
Version
NETWATCH 1.3.0
Release focus
Linux-only
IPv4 monitoring
Device identification
OS/service fingerprinting
Vendor detection
Gateway blocking
ARP spoofing support
Bandwidth throttling
IPv6 discovery
IPv6 identification
IPv6 gateway control
SSH router integration
CSV/JSON export
Interactive monitoring
Dry-run operations
Important Notice
NETWATCH is an administration and security tool.
Do not use discovery, blocking, ARP spoofing, traffic shaping, IPv6 control, or router administration features against networks or devices without authorization.
License
MIT License.
See "LICENSE" for the complete license text.
What's Changed
- Implement and Refine Robust Windows Port (netwatch.ps1) and Coexist with Linux by @sudomarc in #2
- Implement Robust Automatic Checking and Update System by @sudomarc in #3
Full Changelog: 1.1...v1.3.0