NetWatcher CLI

NetWatcher CLI monitors outbound network connections on your local machine and enriches them with IP geolocation and ownership data to help identify potentially suspicious processes. See example output below.

Features

• Displays geolocation and BGP table details about remote internet connections.
• Retrieves process information associated with each connection.
• Flags reasons to suspect possibly malicious activity.
• Optionally generates threat assessment as HTML report.
• Optionally outputs serialized logs to disk.

See the CLI docs for the full CLI usage reference.

Example Output

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ IP      ┃ Geolocation     ┃ Ownership          ┃ Threat Level ┃ Assessment              ┃ Process Info            ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 8.8.8.8 │ City, State Zip │ - ISP: Example ISP │ Suspicious   │ - Hosting provider      │ - Executable Path: …    │
│         │ Country         │ - Org: Example Org │              │ - Proxy or VPN detected │ - Command Line: …       │
│         │                 │ - AS: ASEXAMPLE    │              │ ...                     │ - Process Name: sus.exe │
│         │                 │ - AS Name: EX      │              │                         │ - PID: 1234             │
│         │                 │ ...                │              │                         │ ...                     │
└─────────┴─────────────────┴────────────────────┴──────────────┴─────────────────────────┴─────────────────────────┘
...

Table of Contents

• Installation
• Basic Usage
• Development
• License

Installation

Install from PyPI:

pip install netwatcher-cli

Basic Usage

$ nw scan [OPTIONS]

Options:

• -c, --country-code TEXT: User's ISO 3166-1 alpha-2 two-leter country code. [default: US]
• --html-dir PATH: Optional directory location for which to write an HTML report.
• --lang TEXT: Language code for the IP API response. [default: en]
• --log-dir PATH: Optional directory location for which to write a log file.
• -v, --verbose: Increase verbosity (-v, -vv, -vvv) [default: 1]
• --help: Show this message and exit.

See the CLI docs for the full CLI usage reference.

Development

1. Install uv:

   To manage dependencies and install NetWatcher CLI efficiently, use uv. You can install uv (here).

2. Install Python >= 3.9:

uv python install 3.13

3. Create a virtual environment and activate it:

uv venv --python 3.13

# macOS and Linux
source .venv/activate/bin

# Windows
.venv\Scripts\activate

4. Install dependencies:

uv pip install -r pyproject.toml --all-extras

5. Run unit tests

uv run pytest [OPTIONS]

Some useful options:

• -s – allows print() output
• -vvv – increases verbosity

See the pytest docs for full usage and configuration details.

6. Run pre-commit (requires git-cliff, see Changelog Generation for more) to run the formatter/linter (Ruff), type checker (Pyright), doc generators (Typer/git-cliff), etc.

uv run pre-commit run --all-files

Changelog Generation

This project uses git-cliff to generate changelogs automatically based on conventional commit messages. To use or update the changelog, you must have git-cliff installed locally or in your CI environment. You can do this via cargo, the Rust package manager (which you can install here):

cargo install git-cliff

License

This project is licensed under the MIT License. See the LICENSE file for more details.