# NetWatcher
**NetWatcher** is a lightweight network connection monitoring tool written in Python. It helps you track active outbound
connections on your system, monitor associated processes, and provides geolocation information for remote IP addresses.
This tool is designed for:
- Developers monitoring network traffic.
- Security-conscious users detecting unauthorized network connections.
- Anyone interested in inspecting live network connections and associated processes.
## Features
- Monitor active network connections.
- View details about local and remote connections (IP address, port).
- Retrieve process information associated with each connection (PID, process name).
- Geolocation lookup for remote IP addresses.
- Lightweight and fast CLI tool built with **Typer**.
- Uses **uv**, the fast Python package and project manager, to manage dependencies and execution.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [CLI Usage](#cli-usage)
- [Configuration](#configuration)
- [License](#license)
## Installation
### Install with `uv`
1. **Install `uv`**:
To manage dependencies and install **NetWatcher** efficiently, use **uv**. First, install `uv` if you haven't already
([instructions](https://docs.astral.sh/uv/getting-started/installation/)).
### From Source
1. Clone the repository:
```bash
git clone https://github.com/pfischer1687/netwatcher.git
cd netwatcher
```
2. Install Python 3.13:
```bash
uv python install 3.13
```
3. Create a virtual environment and activate it:
```bash
uv venv --python 3.13
# macOS and Linux
source .venv/activate/bin
# Windows
.venv\Scripts\activate
```
4. Install dependencies:
```bash
uv pip install -r pyproject.toml --all-extras
```
5. Run the script:
```bash
uv run nw scan
```
## Usage
### CLI Usage
The primary interface for NetWatcher is a command-line tool that can be executed with the following command:
```bash
uv run nw scan
```
This will scan active network connections and output the following information:
- Local IP and Port: The local endpoint of the connection.
- Remote IP and Port: The external endpoint the local process is connected to.
- Process Name (PID): The name and PID of the process using the connection.
- Geolocation Information: The city, region, and country of the remote IP.
## For Developers
### Running Tests
```bash
# -s allows print() output
# -vvv increases verbosity
uv run pytest -s -vvv
```
### Changelog Generation
This project uses [`git-cliff`](https://git-cliff.org/docs/) 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](https://www.rust-lang.org/tools/install)):
```bash
cargo install git-cliff
```
### Run All Pre-Commit Hooks
```bash
# This runs formatters, linters, type checks (Pyright), secret scanners, and doc generators.
uv run pre-commit run --all-files
```
## Configuration
By default, NetWatcher uses the `ipapi` service for IP geolocation lookups. If you need to change the geolocation
service or provide your own API key, you can modify the `ip_lookup.py` file.
### Configure a Custom Geolocation Service
To use a different geolocation service, update the httpx API call in `ip_lookup.py` to integrate with your preferred
provider. Ensure the response format remains consistent.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
NetWatcher is a tool for monitoring active network connections with ease, using a simple and extensible design. Whether
you're troubleshooting, securing your network, or just curious about what's happening on your machine, NetWatcher makes
network monitoring simple and accessible.
Raw data
{
"_id": null,
"home_page": null,
"name": "netwatcher-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Paul Fischer <paulfischerdev@gmail.com>",
"keywords": "CLI, Typer, monitoring, network, security",
"author": null,
"author_email": "Paul Fischer <paulfischerdev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/44/fa/39c59a2c401844a5911f98c8a8fc2dfdafeda36f934dfd2d1a11a63501dd/netwatcher_cli-0.1.0.tar.gz",
"platform": null,
"description": "# NetWatcher\n\n**NetWatcher** is a lightweight network connection monitoring tool written in Python. It helps you track active outbound\nconnections on your system, monitor associated processes, and provides geolocation information for remote IP addresses.\n\nThis tool is designed for:\n\n- Developers monitoring network traffic.\n- Security-conscious users detecting unauthorized network connections.\n- Anyone interested in inspecting live network connections and associated processes.\n\n## Features\n\n- Monitor active network connections.\n- View details about local and remote connections (IP address, port).\n- Retrieve process information associated with each connection (PID, process name).\n- Geolocation lookup for remote IP addresses.\n- Lightweight and fast CLI tool built with **Typer**.\n- Uses **uv**, the fast Python package and project manager, to manage dependencies and execution.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [CLI Usage](#cli-usage)\n- [Configuration](#configuration)\n- [License](#license)\n\n## Installation\n\n### Install with `uv`\n\n1. **Install `uv`**:\n\n To manage dependencies and install **NetWatcher** efficiently, use **uv**. First, install `uv` if you haven't already\n ([instructions](https://docs.astral.sh/uv/getting-started/installation/)).\n\n### From Source\n\n1. Clone the repository:\n\n ```bash\n git clone https://github.com/pfischer1687/netwatcher.git\n cd netwatcher\n ```\n\n2. Install Python 3.13:\n\n```bash\nuv python install 3.13\n```\n\n3. Create a virtual environment and activate it:\n\n```bash\nuv venv --python 3.13\n\n# macOS and Linux\nsource .venv/activate/bin\n\n# Windows\n.venv\\Scripts\\activate\n```\n\n4. Install dependencies:\n\n```bash\nuv pip install -r pyproject.toml --all-extras\n```\n\n5. Run the script:\n\n```bash\nuv run nw scan\n```\n\n## Usage\n\n### CLI Usage\n\nThe primary interface for NetWatcher is a command-line tool that can be executed with the following command:\n\n```bash\nuv run nw scan\n```\n\nThis will scan active network connections and output the following information:\n\n- Local IP and Port: The local endpoint of the connection.\n- Remote IP and Port: The external endpoint the local process is connected to.\n- Process Name (PID): The name and PID of the process using the connection.\n- Geolocation Information: The city, region, and country of the remote IP.\n\n## For Developers\n\n### Running Tests\n\n```bash\n# -s allows print() output\n# -vvv increases verbosity\nuv run pytest -s -vvv\n```\n\n### Changelog Generation\n\nThis project uses [`git-cliff`](https://git-cliff.org/docs/) to generate changelogs automatically based on conventional\ncommit messages. To use or update the changelog, you must have `git-cliff` installed locally or in your CI environment.\nYou can do this via cargo, the Rust package manager (which you can install\n[here](https://www.rust-lang.org/tools/install)):\n\n```bash\ncargo install git-cliff\n```\n\n### Run All Pre-Commit Hooks\n\n```bash\n# This runs formatters, linters, type checks (Pyright), secret scanners, and doc generators.\nuv run pre-commit run --all-files\n```\n\n## Configuration\n\nBy default, NetWatcher uses the `ipapi` service for IP geolocation lookups. If you need to change the geolocation\nservice or provide your own API key, you can modify the `ip_lookup.py` file.\n\n### Configure a Custom Geolocation Service\n\nTo use a different geolocation service, update the httpx API call in `ip_lookup.py` to integrate with your preferred\nprovider. Ensure the response format remains consistent.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\nNetWatcher is a tool for monitoring active network connections with ease, using a simple and extensible design. Whether\nyou're troubleshooting, securing your network, or just curious about what's happening on your machine, NetWatcher makes\nnetwork monitoring simple and accessible.\n",
"bugtrack_url": null,
"license": null,
"summary": "Monitor and track active network connections",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/pfischer1687/netwatcher/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/pfischer1687/netwatcher/blob/main/docs/cli.md",
"Issues": "https://github.com/pfischer1687/netwatcher/issues",
"Repository": "https://github.com/pfischer1687/netwatcher"
},
"split_keywords": [
"cli",
" typer",
" monitoring",
" network",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "147d5cfc052b9b228e3929746f34548024d05b72af15f08c3001b84fd537ab76",
"md5": "39481a0095863dca117da1f754bacd39",
"sha256": "621b2ebe335241ab9a52da2773d4c6c9b7b890e340195c2c74de2edab4d86c11"
},
"downloads": -1,
"filename": "netwatcher_cli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39481a0095863dca117da1f754bacd39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 3180,
"upload_time": "2025-05-18T07:35:08",
"upload_time_iso_8601": "2025-05-18T07:35:08.842036Z",
"url": "https://files.pythonhosted.org/packages/14/7d/5cfc052b9b228e3929746f34548024d05b72af15f08c3001b84fd537ab76/netwatcher_cli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "44fa39c59a2c401844a5911f98c8a8fc2dfdafeda36f934dfd2d1a11a63501dd",
"md5": "a911c6eead70e86800d5461735fe0980",
"sha256": "319b8d71390495ca5d181fc83d1c1f3b8c88f842a5afc90db629aca20b38468d"
},
"downloads": -1,
"filename": "netwatcher_cli-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a911c6eead70e86800d5461735fe0980",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 78821,
"upload_time": "2025-05-18T07:35:10",
"upload_time_iso_8601": "2025-05-18T07:35:10.477773Z",
"url": "https://files.pythonhosted.org/packages/44/fa/39c59a2c401844a5911f98c8a8fc2dfdafeda36f934dfd2d1a11a63501dd/netwatcher_cli-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-05-18 07:35:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pfischer1687",
"github_project": "netwatcher",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "netwatcher-cli"
}
JSON
