Skip to content

NETWATCH 1.3.0

Choose a tag to compare

@sudomarc sudomarc released this 01 Sep 04:49

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