Skip to main content

# OpenNetPulse

**An open-source Python network diagnostics and monitoring toolkit.**

OpenNetPulse is a command-line network diagnostics toolkit designed to help developers and network enthusiasts investigate connectivity, monitor network performance, trace network routes, and inspect TCP port availability.

The project combines Python networking libraries with command-line tools to provide practical network troubleshooting capabilities.

## Features

### 1. Network Diagnostics (check)

- DNS resolution checks

- HTTP/HTTPS response checks

- TCP connectivity tests

- Connection and response timing

- JSON diagnostic reports

### 2. System Health Check (doctor)

- Python version verification

- Operating system information

- Package installation checks

- Internal module verification

- Required system utility checks

### 3. Network Monitoring (monitor)

- Continuous TCP connectivity monitoring

- Configurable monitoring intervals

- Connection success and failure tracking

- Average, minimum and maximum latency

- Median, P95 and P99 latency metrics

- Jitter-like latency variation

### 4. Route Tracing (trace)

- Traces the network path to a destination

- Displays intermediate network hops

- Shows responding IP addresses

- Measures probe response times

- Identifies non-responding hops

*Note: The current implementation uses the native Windows tracert utility.*

### 5. TCP Port Scanner (ports) — New

- Scans individual TCP ports or custom port lists

- Checks common service ports

- Identifies open and closed ports

- Detects connection timeouts

- Measures connection latency

- Displays scan summaries

- Supports configurable connection timeouts

## Technology Stack

| Technology | Purpose |

|---|---|

| Python | Core programming language |

| Socket | TCP and DNS networking |

| urllib | HTTP/HTTPS diagnostics |

| Argparse | Command-line interface |

| Subprocess | System traceroute integration |

| Unittest | Automated testing |

| Git & GitHub | Version control |

## Installation

### Prerequisites

- Python 3.10 or newer

- Git

- Windows, Linux or macOS (some system utilities are platform-dependent)

### Clone the repository

```bash

git clone https://github.com/shhhlxk/opennetpulse.git

```

```bash

cd opennetpulse

```

### Install the project

```bash

python -m pip install -e .

```

On Windows, if your Python launcher is configured differently, use your installed Python executable.

### Verify installation

```bash

opennetpulse --help

```

## Usage

### 1. Network Diagnostics

Check a domain:

```bash

opennetpulse check google.com

```

Specify a TCP port:

```bash

opennetpulse check google.com --port 443

```

Change timeout:

```bash

opennetpulse check google.com --timeout 5

```

Choose JSON report destination:

```bash

opennetpulse check google.com --output network-report.json

```

### 2. System Health Check

```bash

opennetpulse doctor

```

### 3. Network Monitoring

Monitor a host:

```bash

opennetpulse monitor google.com

```

Customize monitoring:

```bash

opennetpulse monitor google.com --interval 2 --duration 30

```

Specify a TCP port:

```bash

opennetpulse monitor google.com --port 443

```

### 4. Route Tracing

```bash

opennetpulse trace google.com

```

Customize maximum hops:

```bash

opennetpulse trace google.com --max-hops 20

```

Customize hop timeout:

```bash

opennetpulse trace google.com --hop-timeout 2000

```

### 5. TCP Port Scanning

Scan the default common ports:

```bash

opennetpulse ports localhost

```

Scan selected ports:

```bash

opennetpulse ports localhost --ports 80,443,8080

```

Scan database and web service ports:

```bash

opennetpulse ports localhost --ports 3306,5432,80,443

```

Customize connection timeout:

```bash

opennetpulse ports localhost --ports 22,80,443 --timeout 2

```

**Important:** Only scan computers and networks that you own or have explicit permission to test.

## Example Port Scanner Output

The following is an illustrative example, not a measured scan:

```text

OPENNETPULSE PORT SCANNER

==================================================

Target: localhost

Ports: 22, 80, 443, 3306, 5432

Timeout: 1.0 seconds

PORT STATUS LATENCY

------------------------------------------

22 CLOSED N/A

80 OPEN 2.5 ms

443 OPEN 3.1 ms

3306 CLOSED N/A

5432 CLOSED N/A

SCAN SUMMARY

------------------------------------------

Total ports: 5

Open ports: 2

Closed ports: 3

Timed out ports: 0

Other errors: 0

PORT SCAN COMPLETED

```

Actual results depend on the target machine and its network configuration.

## Project Structure

```text

opennetpulse/

│

├── src/

│ └── opennetpulse/

│ │

│ ├── __init__.py

│ ├── cli.py

│ │

│ ├── diagnostics/

│ │ ├── __init__.py

│ │ ├── dns.py

│ │ ├── http.py

│ │ ├── tcp.py

│ │ ├── doctor.py

│ │ ├── trace.py

│ │ └── ports.py

│ │

│ ├── monitoring/

│ │ ├── __init__.py

│ │ └── monitor.py

│ │

│ ├── analysis/

│ │ └── metrics.py

│ │

│ └── reporting/

│ └── json_report.py

│

├── tests/

│ ├── test_diagnostics.py

│ ├── test_metrics.py

│ ├── test_reporting.py

│ ├── test_doctor.py

│ ├── test_monitor.py

│ ├── test_trace.py

│ └── test_ports.py

│

├── README.md

├── LICENSE

├── pyproject.toml

└── .gitignore

```

## Running Tests

Run the complete automated test suite:

```bash

python -m unittest discover -s tests -v

```

Run port scanner tests independently:

```bash

python -m unittest tests.test_ports -v

```

## Technical Notes and Limitations

- DNS resolution time measures the operating system resolver operation and may be affected by caching.

- TCP connection time measures connection establishment, not application-level health.

- HTTP response timing measures the time until response headers are received, not the complete page download.

- Monitoring uses repeated TCP connection attempts rather than ICMP echo requests.

- Traceroute results depend on network routing and whether intermediate devices respond to probes.

- Port scanning reports TCP connection outcomes. A closed or filtered port may behave differently depending on firewall configuration.

- A successful TCP connection does not guarantee that the application running on that port is healthy.

## Future Development

Potential areas for future development:

- UDP diagnostics

- Cross-platform traceroute support

- Concurrent port scanning

- Network performance visualization

- Historical monitoring reports

- Advanced network analytics

- Real-time monitoring dashboard

- Network anomaly detection

## Contributing

Contributions, suggestions, bug reports and feature requests are welcome.

1. Fork the repository.

2. Create a feature branch.

3. Implement your changes.

4. Run the automated tests.

5. Submit a pull request.

## License

This project is licensed under the terms specified in the repository's LICENSE file.

## Author

**Shlok Bhendkar**

GitHub: [@shhhlxk](https://github.com/shhhlxk)

Project: [OpenNetPulse](https://github.com/shhhlxk/opennetpulse)

---

*OpenNetPulse — Explore, Diagnose, Monitor.*

Metadata

Release files for opennetpulse 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opennetpulse 0.1.0
File Size Uploaded Provenance Actions
opennetpulse-0.1.0.tar.gz 20.6 kB Without provenance Details for opennetpulse-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opennetpulse 0.1.0
File Interpreter ABI Platform Actions
opennetpulse-0.1.0-py3-none-any.whl Python 3 none any Details for opennetpulse-0.1.0-py3-none-any.whl

Total release size: 38.9 kB

Release files / opennetpulse-0.1.0.tar.gz

Download URL opennetpulse-0.1.0.tar.gz
Size 20.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1be936957806ab604c83101ba92308c5bf2357d3aa11678e17723b2758570836
BLAKE2b-256 checksum
How to use checksums
f4f4373d15cfeea7579fa38f54c397129ac2ceefa4bfbab7596fec12ab94b658
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.17

Release files / opennetpulse-0.1.0-py3-none-any.whl

Download URL opennetpulse-0.1.0-py3-none-any.whl
Size 18.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47635c50989e44cdfeb0fc1fbb236a0c9f8171ef3d19099b32196ed7e1070690
BLAKE2b-256 checksum
How to use checksums
6db7fdfef2020071309af386b8e2b2a570a2d94f3ac9f3f480a2b68ce512aabd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.17

Security for opennetpulse 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page