{"id":23537309,"url":"https://github.com/cenab/processportmonitor","last_synced_at":"2026-03-11T14:37:34.902Z","repository":{"id":264269044,"uuid":"892885057","full_name":"cenab/processportmonitor","owner":"cenab","description":"a Python package that allows you to monitor active TCP ports used by a specific process (PID) in real-time","archived":false,"fork":false,"pushed_at":"2024-11-23T04:09:23.000Z","size":62,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-16T23:24:23.546Z","etag":null,"topics":["lsof","mac","network-monitoring","pid","process","process-level-network-monitoring"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/processportmonitor/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cenab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-23T01:11:20.000Z","updated_at":"2025-05-13T22:14:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"0e992234-4f48-4661-b6ea-2e9dfffb70bc","html_url":"https://github.com/cenab/processportmonitor","commit_stats":null,"previous_names":["cenab/portmonitor"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/cenab/processportmonitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenab%2Fprocessportmonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenab%2Fprocessportmonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenab%2Fprocessportmonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenab%2Fprocessportmonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cenab","download_url":"https://codeload.github.com/cenab/processportmonitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenab%2Fprocessportmonitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30384091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lsof","mac","network-monitoring","pid","process","process-level-network-monitoring"],"created_at":"2024-12-26T03:14:25.623Z","updated_at":"2026-03-11T14:37:34.894Z","avatar_url":"https://github.com/cenab.png","language":"Python","readme":"# processportmonitor\n\n**processportmonitor** is a Python package that allows you to monitor active TCP ports used by a specific process (PID) in real-time. It provides both a command-line interface (CLI) and an importable module for integration into your Python scripts.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Command-Line Interface](#command-line-interface)\n    - [Basic Usage](#basic-usage)\n    - [Options](#options)\n  - [As a Python Module](#as-a-python-module)\n    - [Basic Usage](#basic-usage-module)\n    - [Customizing the Callback Function](#customizing-the-callback-function)\n    - [Accessing Port History](#accessing-port-history)\n- [Examples](#examples)\n  - [Example CLI Session](#example-cli-session)\n  - [Example Python Script](#example-python-script)\n- [Requirements](#requirements)\n- [Limitations](#limitations)\n- [License](#license)\n\n---\n\n## Features\n\n- **Real-Time Monitoring**: Continuously monitors active TCP ports used by a specific PID.\n- **Asynchronous Operation**: Runs in a separate thread to avoid blocking your main program.\n- **Callback Mechanism**: Triggers a user-defined callback function when port changes are detected.\n- **Port History Tracking**: Maintains a history of port additions and removals with timestamps.\n- **Command-Line Interface**: Provides a convenient CLI for quick monitoring from the terminal.\n- **Python Module**: Can be imported and used within your Python applications without terminal output.\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Python 3.6 or higher**\n- **`lsof` command**: Available on most Unix-like systems (macOS, Linux).\n- **`jc` library**: JSON Convert library for parsing command output.\n\n### Install Using `pip`\n\n```bash\npip install processportmonitor\n```\n\nTo upgrade to the latest version:\n```bash\npip install --upgrade processportmonitor\n```\n\nFor system-wide installation (may require sudo):\n```bash\nsudo pip install processportmonitor\n```\n\nAlternatively, you can install from source:\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone https://github.com/cenab/processportmonitor.git\n   ```\n\n2. **Navigate to the Package Directory**\n\n   ```bash\n   cd processportmonitor\n   ```\n\n3. **Install the Package**\n\n   ```bash\n   pip install .\n   ```\n\n---\n\n## Usage\n\n### Command-Line Interface\n\n#### Basic Usage\n\nRun `processportmonitor` followed by the PID of the process you wish to monitor. You may need to run the command with `sudo` to have the necessary permissions.\n\n```bash\nsudo processportmonitor \u003cPID\u003e\n```\n\n#### Options\n\n- `--interval INTERVAL`: Set the monitoring interval in seconds (default is 1.0 second).\n\n```bash\nsudo processportmonitor \u003cPID\u003e --interval 0.5\n```\n\n#### Example\n\n```bash\nsudo processportmonitor 16609 --interval 1\n```\n\n**Output:**\n\n```\nMonitoring active ports for PID 16609 every 1.0 second(s). Press Ctrl+C to stop.\nNew ports opened: {50260}\nActive ports: {50260}\nNew ports opened: {50390}\nActive ports: {50260, 50390}\nPorts closed: {50260}\nActive ports: {50390}\n```\n\n### As a Python Module\n\n#### Basic Usage (Module)\n\nImport the `ProcessPortMonitor` class into your Python script:\n\n```python\nfrom processportmonitor import ProcessPortMonitor\nimport time\n\ndef my_callback(new_ports, closed_ports, active_ports, port_history):\n    # Handle port changes here\n    if new_ports:\n        print(f\"Ports added: {new_ports}\")\n    if closed_ports:\n        print(f\"Ports removed: {closed_ports}\")\n    # You can also process active_ports and port_history as needed\n\npid_to_monitor = 16609  # Replace with the actual PID\nmonitor = ProcessPortMonitor(pid_to_monitor, interval=1.0, callback=my_callback)\nmonitor.start()\n\ntry:\n    while True:\n        # Your main program logic here\n        time.sleep(1)\nexcept KeyboardInterrupt:\n    monitor.stop()\n    print(\"Stopped monitoring.\")\n```\n\n#### Customizing the Callback Function\n\nThe callback function should accept four parameters:\n\n- `new_ports`: A set of ports that have been added since the last check.\n- `closed_ports`: A set of ports that have been closed since the last check.\n- `active_ports`: The current set of active ports.\n- `port_history`: A list of dictionaries containing the history of port changes with timestamps.\n\nExample of a callback function:\n\n```python\ndef my_callback(new_ports, closed_ports, active_ports, port_history):\n    if new_ports:\n        print(f\"New ports opened: {new_ports}\")\n    if closed_ports:\n        print(f\"Ports closed: {closed_ports}\")\n    print(f\"Current active ports: {active_ports}\")\n    # Optionally, process port_history\n```\n\n#### Accessing Port History\n\nThe `port_history` attribute of the `ProcessPortMonitor` instance stores the history of port changes.\n\n```python\n# Access the port history\nprint(monitor.port_history)\n```\n\nEach entry in `port_history` is a dictionary:\n\n```python\n{\n    'timestamp': '2023-10-03T12:00:00.000000',\n    'port': 50260,\n    'action': 'added'  # or 'removed'\n}\n```\n\n---\n\n## Examples\n\n### Example CLI Session\n\n```bash\nsudo processportmonitor 12345 --interval 0.5\n```\n\n**Output:**\n\n```\nMonitoring active ports for PID 12345 every 0.5 second(s). Press Ctrl+C to stop.\nNew ports opened: {8080}\nActive ports: {8080}\nPorts closed: {8080}\nActive ports: set()\n```\n\n### Example Python Script\n\n```python\nfrom processportmonitor import ProcessPortMonitor\nimport time\n\ndef log_port_changes(new_ports, closed_ports, active_ports, port_history):\n    if new_ports:\n        print(f\"[+] Ports opened: {new_ports}\")\n    if closed_ports:\n        print(f\"[-] Ports closed: {closed_ports}\")\n    print(f\"[=] Current ports: {active_ports}\")\n\npid = 12345\nmonitor = ProcessPortMonitor(pid, interval=0.5, callback=log_port_changes)\nmonitor.start()\n\ntry:\n    while True:\n        # Main application logic\n        time.sleep(1)\nexcept KeyboardInterrupt:\n    monitor.stop()\n    print(\"Monitoring stopped.\")\n```\n\n---\n\n## Requirements\n\n- **Python 3.6 or higher**\n- **`lsof` command**: The script uses `lsof` to retrieve active TCP connections.\n- **`jc` library**: Install via `pip3 install jc`.\n\n---\n\n## Limitations\n\n- **Permissions**: Monitoring processes other than your own may require root privileges.\n- **Platform Compatibility**: Designed for Unix-like systems (macOS, Linux) with `lsof` available.\n- **System Resources**: Frequent monitoring intervals may impact system performance due to repeated `lsof` calls.\n- **TCP Connections Only**: Currently monitors TCP connections in the `ESTABLISHED` state.\n\n---\n\n## License\n\n**processportmonitor** is released under the [MIT License](https://opensource.org/licenses/MIT).\n\n---\n\n## Contributing\n\nContributions are welcome! Please submit a pull request or open an issue to discuss improvements or report bugs.\n\n---\n\n## Contact\n\nFor questions or support, please open an issue on the [GitHub repository](https://github.com/cenab/processportmonitor) or contact the maintainer at [batu.bora.tech@gmail.com](mailto:batu.bora.tech@gmail.com).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcenab%2Fprocessportmonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcenab%2Fprocessportmonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcenab%2Fprocessportmonitor/lists"}