ipmg 4.0.0__tar.gz → 4.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. {ipmg-4.0.0/src/ipmg.egg-info → ipmg-4.1.0}/PKG-INFO +93 -72
  2. {ipmg-4.0.0 → ipmg-4.1.0}/README.md +87 -69
  3. {ipmg-4.0.0 → ipmg-4.1.0}/pyproject.toml +21 -7
  4. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/__init__.py +1 -1
  5. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/cli/commands.py +15 -13
  6. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/cli/completion.py +10 -10
  7. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/cli/config.py +62 -23
  8. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/cli/parser.py +72 -0
  9. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/cron.py +8 -11
  10. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/diff.py +199 -42
  11. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/discovery.py +14 -15
  12. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/engine.py +19 -18
  13. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/health.py +3 -3
  14. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/httpcheck.py +15 -15
  15. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/neighbours.py +21 -21
  16. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/ping.py +5 -9
  17. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/portscan.py +11 -11
  18. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/security.py +1 -1
  19. ipmg-4.1.0/src/ipmg/core/snmp/__init__.py +57 -0
  20. ipmg-4.1.0/src/ipmg/core/snmp/ber.py +265 -0
  21. ipmg-4.1.0/src/ipmg/core/snmp/client.py +543 -0
  22. ipmg-4.1.0/src/ipmg/core/snmp/poller.py +331 -0
  23. ipmg-4.1.0/src/ipmg/core/snmp/usm.py +152 -0
  24. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/infrastructure/database.py +200 -42
  25. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/infrastructure/file_io.py +165 -2
  26. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/infrastructure/incremental.py +28 -27
  27. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/infrastructure/notify.py +27 -25
  28. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/infrastructure/retention.py +19 -17
  29. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/diff_report.py +8 -8
  30. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/frames.py +11 -10
  31. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/live.py +6 -5
  32. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/machine.py +4 -4
  33. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/metrics.py +7 -7
  34. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/summary.py +72 -3
  35. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/ui.py +11 -8
  36. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/services/history_service.py +17 -12
  37. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/services/scan_service.py +119 -33
  38. ipmg-4.1.0/src/ipmg/services/snmp_settings.py +147 -0
  39. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/utils/helpers.py +7 -8
  40. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/app.py +74 -54
  41. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/manager.py +10 -10
  42. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/network.py +18 -18
  43. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/scheduler.py +10 -9
  44. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/schemas.py +88 -51
  45. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/server.py +4 -5
  46. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/css/app.css +2 -0
  47. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/index.html +2 -2
  48. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/js/api.js +2 -1
  49. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/js/app.js +2 -2
  50. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/js/demo.js +16 -1
  51. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/js/views.js +139 -8
  52. {ipmg-4.0.0 → ipmg-4.1.0/src/ipmg.egg-info}/PKG-INFO +93 -72
  53. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg.egg-info/SOURCES.txt +9 -0
  54. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg.egg-info/requires.txt +6 -2
  55. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_api_contract.py +7 -7
  56. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_httpcheck.py +1 -0
  57. ipmg-4.1.0/tests/test_snmp.py +546 -0
  58. ipmg-4.1.0/tests/test_snmp_agents.py +291 -0
  59. ipmg-4.1.0/tests/test_snmp_scan.py +516 -0
  60. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_web_api.py +37 -10
  61. {ipmg-4.0.0 → ipmg-4.1.0}/LICENSE +0 -0
  62. {ipmg-4.0.0 → ipmg-4.1.0}/setup.cfg +0 -0
  63. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/__main__.py +0 -0
  64. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/cli/__init__.py +0 -0
  65. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/__init__.py +0 -0
  66. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/core/wake.py +0 -0
  67. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/data/oui.tsv.gz +0 -0
  68. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/exceptions.py +0 -0
  69. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/infrastructure/__init__.py +0 -0
  70. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/reporting/__init__.py +0 -0
  71. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/services/__init__.py +0 -0
  72. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/utils/__init__.py +0 -0
  73. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/__init__.py +0 -0
  74. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/db.py +0 -0
  75. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg/web/static/js/charts.js +0 -0
  76. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg.egg-info/dependency_links.txt +0 -0
  77. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg.egg-info/entry_points.txt +0 -0
  78. {ipmg-4.0.0 → ipmg-4.1.0}/src/ipmg.egg-info/top_level.txt +0 -0
  79. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_commands.py +0 -0
  80. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_completion.py +0 -0
  81. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_config.py +0 -0
  82. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_contrib.py +0 -0
  83. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_database_history.py +0 -0
  84. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_diff.py +0 -0
  85. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_diff_report.py +0 -0
  86. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_discover.py +0 -0
  87. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_engine.py +0 -0
  88. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_file_io.py +0 -0
  89. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_health.py +0 -0
  90. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_history_service.py +0 -0
  91. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_incremental.py +0 -0
  92. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_ipv6.py +0 -0
  93. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_live.py +0 -0
  94. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_machine_output.py +0 -0
  95. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_metrics.py +0 -0
  96. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_neighbours.py +0 -0
  97. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_notify.py +0 -0
  98. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_parser.py +0 -0
  99. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_ping.py +0 -0
  100. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_ping_command.py +0 -0
  101. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_portscan.py +0 -0
  102. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_retention.py +0 -0
  103. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_scan_service.py +0 -0
  104. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_schedules.py +0 -0
  105. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_tcp_probe.py +0 -0
  106. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_ui.py +0 -0
  107. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_utils.py +0 -0
  108. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_wake.py +0 -0
  109. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_web_db.py +0 -0
  110. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_web_manager.py +0 -0
  111. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_web_network.py +0 -0
  112. {ipmg-4.0.0 → ipmg-4.1.0}/tests/test_web_server.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ipmg
3
- Version: 4.0.0
3
+ Version: 4.1.0
4
4
  Summary: Network discovery and change detection: ping sweeps, scan history, and reports for what changed on your network
5
5
  Author: Sameer Alam
6
6
  Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -37,113 +37,137 @@ Requires-Dist: pydantic>=2.7; extra == "web"
37
37
  Requires-Dist: uvicorn>=0.27; extra == "web"
38
38
  Requires-Dist: websockets>=12; extra == "web"
39
39
  Requires-Dist: python-multipart>=0.0.9; extra == "web"
40
+ Provides-Extra: snmp
41
+ Requires-Dist: cryptography>=42; extra == "snmp"
40
42
  Provides-Extra: all
41
- Requires-Dist: ipmg[web]; extra == "all"
43
+ Requires-Dist: ipmg[snmp,web]; extra == "all"
42
44
  Provides-Extra: dev
43
- Requires-Dist: ipmg[web]; extra == "dev"
45
+ Requires-Dist: ipmg[snmp,web]; extra == "dev"
44
46
  Requires-Dist: pytest>=7.4; extra == "dev"
45
47
  Requires-Dist: pytest-cov>=5.0; extra == "dev"
46
48
  Requires-Dist: ruff>=0.4; extra == "dev"
49
+ Requires-Dist: mypy>=1.10; extra == "dev"
47
50
  Requires-Dist: pre-commit>=3.5.0; extra == "dev"
48
51
  Requires-Dist: python-semantic-release>=10.5.3; extra == "dev"
49
52
  Requires-Dist: httpx>=0.27; extra == "dev"
50
53
  Requires-Dist: httpx2>=2.0; extra == "dev"
51
54
  Dynamic: license-file
52
55
 
53
- # IPMG — IP Management & Ping Monitoring Tool
54
-
55
- [![PyPI](https://img.shields.io/pypi/v/ipmg)](https://pypi.org/project/ipmg/)
56
- ![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
57
- ![License](https://img.shields.io/badge/license-MIT-green)
58
- [![Publish](https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml/badge.svg)](https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml)
59
-
60
- **Know what changed on your network since the last scan.**
56
+ <p align="center">
57
+ <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-logo.svg" alt="" width="88">
58
+ </p>
61
59
 
62
- IPMG scans IPs, CIDR blocks, and ranges in parallel, keeps a history of every
63
- scan, and tells you what moved between two of them: hosts that went offline or
64
- appeared, IP addresses, hostnames, and MAC addresses that changed, latency that
65
- shifted, web services that started failing. Every change carries a severity,
66
- so only the ones that matter reach Slack, Teams, a webhook, or email, or fail a
67
- cron job or CI step. Use it from the command line or from IPMG Web, a local
68
- dashboard that works offline.
60
+ <h1 align="center">IPMG</h1>
69
61
 
70
62
  <p align="center">
71
- <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts with --stream, printing each one as it answers; a new address is added to the target file; a second scan with --compare reports it as a new host (warning) against the first" width="820">
63
+ <b>IP Management &amp; Ping Monitoring Tool</b><br>
64
+ Know what changed on your network since the last scan.
72
65
  </p>
73
66
 
74
- ```bash
75
- curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash
76
- ipmg --discover # scan the network you are on, right now
77
- ipmg --discover --compare # later: scan again and see what changed
78
- ipmg web --lan # open the dashboard from any machine on your network
79
- ```
67
+ <p align="center">
68
+ <a href="https://pypi.org/project/ipmg/"><img src="https://img.shields.io/pypi/v/ipmg" alt="PyPI"></a>
69
+ <a href="https://pypi.org/project/ipmg/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python Version"></a>
70
+ <a href="https://github.com/sameeralam3127/ipmg/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
71
+ <a href="https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml"><img src="https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml/badge.svg" alt="Publish"></a>
72
+ </p>
80
73
 
81
- > **Please read:** only scan networks you are authorized to scan. Unauthorized
82
- > scanning may violate your organization's policies or the law.
74
+ <p align="center">
75
+ <a href="https://sameeralam3127.github.io/ipmg/"><b>Website</b></a>
76
+ &nbsp;·&nbsp;
77
+ <a href="https://sameeralam3127.github.io/ipmg/demo/"><b>Live demo</b></a>
78
+ &nbsp;·&nbsp;
79
+ <a href="https://sameeralam3127.github.io/ipmg/#builder"><b>Command builder</b></a>
80
+ &nbsp;·&nbsp;
81
+ <a href="https://github.com/sameeralam3127/ipmg#documentation"><b>Docs</b></a>
82
+ </p>
83
83
 
84
- **Website:** [sameeralam3127.github.io/ipmg](https://sameeralam3127.github.io/ipmg/) ·
85
- **Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/) ·
86
- **Command builder:** [pick what you want, copy the command](https://sameeralam3127.github.io/ipmg/#builder) ·
87
- **Docs:** [everything else](#documentation)
84
+ <p align="center">
85
+ <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts with --stream, printing each one as it answers; a new address is added to the target file; a second scan with --compare reports it as a new host (warning) against the first" width="820">
86
+ </p>
88
87
 
89
- ---
88
+ IPMG sweeps IPs, CIDR blocks, and ranges in parallel, remembers every scan, and
89
+ tells you what changed since the last one: hosts that went down or appeared, a
90
+ new MAC address or hostname behind an address, slower replies, a web service
91
+ that started failing. Only the changes that matter reach Slack, Teams, a
92
+ webhook, or email, or fail your cron job or CI step.
90
93
 
91
- ## What it does
94
+ ## Features
92
95
 
93
- - **Scans fast, without root.** IPv4 and IPv6, CIDR blocks, ranges, and
94
- target files (text, CSV, Excel, JSON), `--threads` hosts at a time, using
95
- your system's own `ping`.
96
+ - **Fast, without root.** IPv4 and IPv6, CIDR blocks, ranges, and target
97
+ files (text, CSV, Excel, JSON), many hosts at a time, using your system's own
98
+ `ping`.
96
99
  - **Finds hosts that block ping** with TCP probes (`--probe icmp,tcp`), and
97
100
  checks web services (`--http-check`: status, response time, TLS, certificate
98
101
  expiry).
99
- - **Identifies devices** by reverse DNS name and, on your LAN, by MAC address
102
+ - **Names every device** by reverse DNS and, on your LAN, by MAC address
100
103
  and vendor (`--mac`). Wakes them with Wake-on-LAN (`ipmg wake`).
101
- - **Remembers every scan** and reports what changed, with severities and
102
- alerts to Slack, Teams, webhooks, or email.
103
- - **Fits into automation:** exit codes for cron and CI, a GitHub Action,
104
+ - **Tells you what changed** since the last scan, with a severity for each
105
+ change, and alerts Slack, Teams, webhooks, or email.
106
+ - **Made for automation:** exit codes for cron and CI, a GitHub Action,
104
107
  `--json` for scripts, systemd and launchd templates, Prometheus metrics.
105
108
  - **IPMG Web**, a local dashboard: live scans, history, changes, inventory,
106
109
  and scheduled scans.
107
110
  - **Reports** in Excel, CSV, JSON, JSON Lines, and Markdown, written as the
108
- scan runs, so an interrupted scan keeps its results and can be resumed.
111
+ scan runs, so an interrupted scan keeps its results.
109
112
 
110
- [How it compares](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMPARISON.md)
113
+ [How IPMG compares](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMPARISON.md)
111
114
  with nmap, fping, and Uptime Kuma.
112
115
 
113
- ---
114
-
115
116
  ## Install
116
117
 
117
- **Linux and macOS**, on any distribution, with no Python needed:
118
-
119
118
  ```bash
119
+ # Linux and macOS, no Python needed
120
120
  curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash
121
121
  ```
122
122
 
123
- **Windows** (PowerShell, no administrator rights):
124
-
125
123
  ```powershell
124
+ # Windows, no administrator rights
126
125
  irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
127
126
  ```
128
127
 
129
- **Homebrew:** `brew install sameeralam3127/tap/ipmg` ·
130
- **uv:** `uv tool install --python ">=3.10" "ipmg[web]"` ·
131
- **pipx:** `pipx install "ipmg[web]"` ·
132
- **Docker:** `docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24`
128
+ Or from PyPI, with Python 3.10 or newer:
133
129
 
134
- IPMG needs Python 3.10 or newer (the installers bring their own) and the
135
- system `ping` command. Minimal images, version pinning, upgrading from 3.x,
136
- tab completion, and the systems CI verifies are in the
137
- [install guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/INSTALL.md).
130
+ ```bash
131
+ # With pip, in a virtual environment
132
+ pip install ipmg # the command line
133
+ pip install "ipmg[web]" # the command line and IPMG Web, the browser dashboard
134
+ ```
135
+
136
+ ```bash
137
+ # With pipx
138
+ pipx install "ipmg[web]"
139
+ ```
140
+
141
+ ```bash
142
+ # With uv, which fetches Python 3.10+ if you need it
143
+ uv tool install --python ">=3.10" "ipmg[web]"
144
+ ```
145
+
146
+ Also on:
147
+
148
+ - **Homebrew:** `brew install sameeralam3127/tap/ipmg`
149
+ - **Docker:** `docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24`
138
150
 
139
- ---
151
+ > **Tip:** `[web]` adds IPMG Web; `pip install ipmg` alone is the command line.
152
+ > Where the system Python is older than 3.10 (RHEL 9, Ubuntu 20.04, SLES 15),
153
+ > pip and pipx quietly install an older IPMG: use the installer or uv there. The
154
+ > [install guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/INSTALL.md)
155
+ > covers version pinning, upgrading from 3.x, and tab completion.
140
156
 
141
- ## Your first scan
157
+ ## Quick start
142
158
 
143
159
  ```bash
144
- ipmg --input 192.168.1.0/24 --stream # each host as it answers
160
+ ipmg --discover # scan the network you are on, right now
161
+ ipmg --discover --compare # later: scan again and see what changed
162
+ ipmg web --lan # open the dashboard from any machine on your network
145
163
  ```
146
164
 
165
+ Every scan is saved to a local history (`~/.ipmg/dashboard.db`), so
166
+ `--compare` always has the previous scan to compare with.
167
+
168
+ <details>
169
+ <summary>What a scan prints</summary>
170
+
147
171
  ```text
148
172
  ipmg X.Y.Z · scan
149
173
  ICMP probes only — scan only networks you are authorized to scan.
@@ -161,10 +185,10 @@ ipmg --input 192.168.1.0/24 --stream # each host as it answers
161
185
  Saved results_20261018_091502.xlsx
162
186
  ```
163
187
 
164
- Every scan is stored in a local history (`~/.ipmg/dashboard.db`). Scan again
165
- with `--compare` to see what changed, or open IPMG Web to browse it.
188
+ </details>
166
189
 
167
- ---
190
+ > **Note:** only scan networks you are authorized to scan. Unauthorized scanning
191
+ > may violate your organization's policies or the law.
168
192
 
169
193
  ## Common tasks
170
194
 
@@ -177,6 +201,7 @@ with `--compare` to see what changed, or open IPMG Web to browse it.
177
201
  | Find hosts that block ping | `ipmg --input 10.0.0.0/24 --probe icmp,tcp` |
178
202
  | Know which device each address is | `ipmg --discover --resolve --mac` |
179
203
  | Check that a web service works | `ipmg --http-check https://intranet.example.com/` |
204
+ | Watch switches and routers: reboots, interfaces going down | `ipmg --input switches.txt --snmp --compare` |
180
205
  | See which services are listening | `ipmg --input targets.txt --scan-ports` |
181
206
  | Get a report I can send to someone | `ipmg --input targets.txt --formats md csv` |
182
207
  | Pipe the results into a script | `ipmg --input targets.txt --json \| jq .` |
@@ -186,8 +211,6 @@ with `--compare` to see what changed, or open IPMG Web to browse it.
186
211
  | Keep it running after logout and reboots | [systemd and launchd templates](https://github.com/sameeralam3127/ipmg/blob/main/docs/SERVICES.md) |
187
212
  | See every option | `ipmg --help`, or the [command reference](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMMANDS.md) |
188
213
 
189
- ---
190
-
191
214
  ## IPMG Web
192
215
 
193
216
  ```bash
@@ -206,10 +229,8 @@ IPMG Web runs). Every request needs the token in that link.
206
229
 
207
230
  Dashboard, live monitor, history, changes, inventory with Wake-on-LAN, and
208
231
  scheduled scans; see the
209
- [IPMG Web guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/WEB.md).
210
- Try it first with the [live demo](https://sameeralam3127.github.io/ipmg/demo/).
211
-
212
- ---
232
+ [IPMG Web guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/WEB.md),
233
+ or try it first in the [live demo](https://sameeralam3127.github.io/ipmg/demo/).
213
234
 
214
235
  ## Documentation
215
236
 
@@ -221,12 +242,11 @@ Try it first with the [live demo](https://sameeralam3127.github.io/ipmg/demo/).
221
242
  | [Web API](https://github.com/sameeralam3127/ipmg/blob/main/docs/API.md) | Scripting IPMG Web over HTTP and WebSocket |
222
243
  | [Running as a service](https://github.com/sameeralam3127/ipmg/blob/main/docs/SERVICES.md) | systemd and launchd templates for scheduled scans and IPMG Web |
223
244
  | [GitHub Action](https://github.com/sameeralam3127/ipmg/blob/main/docs/GITHUB-ACTION.md) | Reachability checks in CI, before a deploy or on a schedule |
245
+ | [SNMP polling](https://github.com/sameeralam3127/ipmg/blob/main/docs/SNMP.md) | Switches and routers over SNMP v2c and v3: credentials, interfaces, reboots, reports |
224
246
  | [How it compares](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMPARISON.md) | IPMG next to nmap, fping, and Uptime Kuma |
225
247
  | [Troubleshooting](https://github.com/sameeralam3127/ipmg/blob/main/docs/TROUBLESHOOTING.md) and [FAQ](https://github.com/sameeralam3127/ipmg/blob/main/docs/FAQ.md) | Install errors, timeouts, slow scans, empty MAC addresses, common questions |
226
248
  | [Architecture](https://github.com/sameeralam3127/ipmg/blob/main/docs/ARCHITECTURE.md) | How the code fits together, for contributors |
227
249
 
228
- ---
229
-
230
250
  ## Security
231
251
 
232
252
  IPMG runs `ping` as a direct process call with no shell, validates every
@@ -237,8 +257,6 @@ requests IPMG makes are the notifications and HTTP checks you ask for. Found a
237
257
  vulnerability? See
238
258
  [SECURITY.md](https://github.com/sameeralam3127/ipmg/blob/main/.github/SECURITY.md).
239
259
 
240
- ---
241
-
242
260
  ## Contributing
243
261
 
244
262
  Contributions are welcome.
@@ -249,6 +267,9 @@ releases, and
249
267
  explains the code. Everyone taking part is expected to follow the
250
268
  [Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/.github/CODE_OF_CONDUCT.md).
251
269
 
270
+ If IPMG saves you time, a star on
271
+ [GitHub](https://github.com/sameeralam3127/ipmg) helps other people find it.
272
+
252
273
  ## License
253
274
 
254
275
  MIT — free for commercial and personal use.
@@ -1,97 +1,118 @@
1
- # IPMG — IP Management & Ping Monitoring Tool
2
-
3
- [![PyPI](https://img.shields.io/pypi/v/ipmg)](https://pypi.org/project/ipmg/)
4
- ![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
5
- ![License](https://img.shields.io/badge/license-MIT-green)
6
- [![Publish](https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml/badge.svg)](https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml)
7
-
8
- **Know what changed on your network since the last scan.**
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-logo.svg" alt="" width="88">
3
+ </p>
9
4
 
10
- IPMG scans IPs, CIDR blocks, and ranges in parallel, keeps a history of every
11
- scan, and tells you what moved between two of them: hosts that went offline or
12
- appeared, IP addresses, hostnames, and MAC addresses that changed, latency that
13
- shifted, web services that started failing. Every change carries a severity,
14
- so only the ones that matter reach Slack, Teams, a webhook, or email, or fail a
15
- cron job or CI step. Use it from the command line or from IPMG Web, a local
16
- dashboard that works offline.
5
+ <h1 align="center">IPMG</h1>
17
6
 
18
7
  <p align="center">
19
- <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts with --stream, printing each one as it answers; a new address is added to the target file; a second scan with --compare reports it as a new host (warning) against the first" width="820">
8
+ <b>IP Management &amp; Ping Monitoring Tool</b><br>
9
+ Know what changed on your network since the last scan.
20
10
  </p>
21
11
 
22
- ```bash
23
- curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash
24
- ipmg --discover # scan the network you are on, right now
25
- ipmg --discover --compare # later: scan again and see what changed
26
- ipmg web --lan # open the dashboard from any machine on your network
27
- ```
12
+ <p align="center">
13
+ <a href="https://pypi.org/project/ipmg/"><img src="https://img.shields.io/pypi/v/ipmg" alt="PyPI"></a>
14
+ <a href="https://pypi.org/project/ipmg/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python Version"></a>
15
+ <a href="https://github.com/sameeralam3127/ipmg/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
16
+ <a href="https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml"><img src="https://github.com/sameeralam3127/ipmg/actions/workflows/publish.yml/badge.svg" alt="Publish"></a>
17
+ </p>
28
18
 
29
- > **Please read:** only scan networks you are authorized to scan. Unauthorized
30
- > scanning may violate your organization's policies or the law.
19
+ <p align="center">
20
+ <a href="https://sameeralam3127.github.io/ipmg/"><b>Website</b></a>
21
+ &nbsp;·&nbsp;
22
+ <a href="https://sameeralam3127.github.io/ipmg/demo/"><b>Live demo</b></a>
23
+ &nbsp;·&nbsp;
24
+ <a href="https://sameeralam3127.github.io/ipmg/#builder"><b>Command builder</b></a>
25
+ &nbsp;·&nbsp;
26
+ <a href="https://github.com/sameeralam3127/ipmg#documentation"><b>Docs</b></a>
27
+ </p>
31
28
 
32
- **Website:** [sameeralam3127.github.io/ipmg](https://sameeralam3127.github.io/ipmg/) ·
33
- **Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/) ·
34
- **Command builder:** [pick what you want, copy the command](https://sameeralam3127.github.io/ipmg/#builder) ·
35
- **Docs:** [everything else](#documentation)
29
+ <p align="center">
30
+ <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts with --stream, printing each one as it answers; a new address is added to the target file; a second scan with --compare reports it as a new host (warning) against the first" width="820">
31
+ </p>
36
32
 
37
- ---
33
+ IPMG sweeps IPs, CIDR blocks, and ranges in parallel, remembers every scan, and
34
+ tells you what changed since the last one: hosts that went down or appeared, a
35
+ new MAC address or hostname behind an address, slower replies, a web service
36
+ that started failing. Only the changes that matter reach Slack, Teams, a
37
+ webhook, or email, or fail your cron job or CI step.
38
38
 
39
- ## What it does
39
+ ## Features
40
40
 
41
- - **Scans fast, without root.** IPv4 and IPv6, CIDR blocks, ranges, and
42
- target files (text, CSV, Excel, JSON), `--threads` hosts at a time, using
43
- your system's own `ping`.
41
+ - **Fast, without root.** IPv4 and IPv6, CIDR blocks, ranges, and target
42
+ files (text, CSV, Excel, JSON), many hosts at a time, using your system's own
43
+ `ping`.
44
44
  - **Finds hosts that block ping** with TCP probes (`--probe icmp,tcp`), and
45
45
  checks web services (`--http-check`: status, response time, TLS, certificate
46
46
  expiry).
47
- - **Identifies devices** by reverse DNS name and, on your LAN, by MAC address
47
+ - **Names every device** by reverse DNS and, on your LAN, by MAC address
48
48
  and vendor (`--mac`). Wakes them with Wake-on-LAN (`ipmg wake`).
49
- - **Remembers every scan** and reports what changed, with severities and
50
- alerts to Slack, Teams, webhooks, or email.
51
- - **Fits into automation:** exit codes for cron and CI, a GitHub Action,
49
+ - **Tells you what changed** since the last scan, with a severity for each
50
+ change, and alerts Slack, Teams, webhooks, or email.
51
+ - **Made for automation:** exit codes for cron and CI, a GitHub Action,
52
52
  `--json` for scripts, systemd and launchd templates, Prometheus metrics.
53
53
  - **IPMG Web**, a local dashboard: live scans, history, changes, inventory,
54
54
  and scheduled scans.
55
55
  - **Reports** in Excel, CSV, JSON, JSON Lines, and Markdown, written as the
56
- scan runs, so an interrupted scan keeps its results and can be resumed.
56
+ scan runs, so an interrupted scan keeps its results.
57
57
 
58
- [How it compares](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMPARISON.md)
58
+ [How IPMG compares](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMPARISON.md)
59
59
  with nmap, fping, and Uptime Kuma.
60
60
 
61
- ---
62
-
63
61
  ## Install
64
62
 
65
- **Linux and macOS**, on any distribution, with no Python needed:
66
-
67
63
  ```bash
64
+ # Linux and macOS, no Python needed
68
65
  curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash
69
66
  ```
70
67
 
71
- **Windows** (PowerShell, no administrator rights):
72
-
73
68
  ```powershell
69
+ # Windows, no administrator rights
74
70
  irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
75
71
  ```
76
72
 
77
- **Homebrew:** `brew install sameeralam3127/tap/ipmg` ·
78
- **uv:** `uv tool install --python ">=3.10" "ipmg[web]"` ·
79
- **pipx:** `pipx install "ipmg[web]"` ·
80
- **Docker:** `docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24`
73
+ Or from PyPI, with Python 3.10 or newer:
81
74
 
82
- IPMG needs Python 3.10 or newer (the installers bring their own) and the
83
- system `ping` command. Minimal images, version pinning, upgrading from 3.x,
84
- tab completion, and the systems CI verifies are in the
85
- [install guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/INSTALL.md).
75
+ ```bash
76
+ # With pip, in a virtual environment
77
+ pip install ipmg # the command line
78
+ pip install "ipmg[web]" # the command line and IPMG Web, the browser dashboard
79
+ ```
80
+
81
+ ```bash
82
+ # With pipx
83
+ pipx install "ipmg[web]"
84
+ ```
85
+
86
+ ```bash
87
+ # With uv, which fetches Python 3.10+ if you need it
88
+ uv tool install --python ">=3.10" "ipmg[web]"
89
+ ```
90
+
91
+ Also on:
92
+
93
+ - **Homebrew:** `brew install sameeralam3127/tap/ipmg`
94
+ - **Docker:** `docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24`
86
95
 
87
- ---
96
+ > **Tip:** `[web]` adds IPMG Web; `pip install ipmg` alone is the command line.
97
+ > Where the system Python is older than 3.10 (RHEL 9, Ubuntu 20.04, SLES 15),
98
+ > pip and pipx quietly install an older IPMG: use the installer or uv there. The
99
+ > [install guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/INSTALL.md)
100
+ > covers version pinning, upgrading from 3.x, and tab completion.
88
101
 
89
- ## Your first scan
102
+ ## Quick start
90
103
 
91
104
  ```bash
92
- ipmg --input 192.168.1.0/24 --stream # each host as it answers
105
+ ipmg --discover # scan the network you are on, right now
106
+ ipmg --discover --compare # later: scan again and see what changed
107
+ ipmg web --lan # open the dashboard from any machine on your network
93
108
  ```
94
109
 
110
+ Every scan is saved to a local history (`~/.ipmg/dashboard.db`), so
111
+ `--compare` always has the previous scan to compare with.
112
+
113
+ <details>
114
+ <summary>What a scan prints</summary>
115
+
95
116
  ```text
96
117
  ipmg X.Y.Z · scan
97
118
  ICMP probes only — scan only networks you are authorized to scan.
@@ -109,10 +130,10 @@ ipmg --input 192.168.1.0/24 --stream # each host as it answers
109
130
  Saved results_20261018_091502.xlsx
110
131
  ```
111
132
 
112
- Every scan is stored in a local history (`~/.ipmg/dashboard.db`). Scan again
113
- with `--compare` to see what changed, or open IPMG Web to browse it.
133
+ </details>
114
134
 
115
- ---
135
+ > **Note:** only scan networks you are authorized to scan. Unauthorized scanning
136
+ > may violate your organization's policies or the law.
116
137
 
117
138
  ## Common tasks
118
139
 
@@ -125,6 +146,7 @@ with `--compare` to see what changed, or open IPMG Web to browse it.
125
146
  | Find hosts that block ping | `ipmg --input 10.0.0.0/24 --probe icmp,tcp` |
126
147
  | Know which device each address is | `ipmg --discover --resolve --mac` |
127
148
  | Check that a web service works | `ipmg --http-check https://intranet.example.com/` |
149
+ | Watch switches and routers: reboots, interfaces going down | `ipmg --input switches.txt --snmp --compare` |
128
150
  | See which services are listening | `ipmg --input targets.txt --scan-ports` |
129
151
  | Get a report I can send to someone | `ipmg --input targets.txt --formats md csv` |
130
152
  | Pipe the results into a script | `ipmg --input targets.txt --json \| jq .` |
@@ -134,8 +156,6 @@ with `--compare` to see what changed, or open IPMG Web to browse it.
134
156
  | Keep it running after logout and reboots | [systemd and launchd templates](https://github.com/sameeralam3127/ipmg/blob/main/docs/SERVICES.md) |
135
157
  | See every option | `ipmg --help`, or the [command reference](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMMANDS.md) |
136
158
 
137
- ---
138
-
139
159
  ## IPMG Web
140
160
 
141
161
  ```bash
@@ -154,10 +174,8 @@ IPMG Web runs). Every request needs the token in that link.
154
174
 
155
175
  Dashboard, live monitor, history, changes, inventory with Wake-on-LAN, and
156
176
  scheduled scans; see the
157
- [IPMG Web guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/WEB.md).
158
- Try it first with the [live demo](https://sameeralam3127.github.io/ipmg/demo/).
159
-
160
- ---
177
+ [IPMG Web guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/WEB.md),
178
+ or try it first in the [live demo](https://sameeralam3127.github.io/ipmg/demo/).
161
179
 
162
180
  ## Documentation
163
181
 
@@ -169,12 +187,11 @@ Try it first with the [live demo](https://sameeralam3127.github.io/ipmg/demo/).
169
187
  | [Web API](https://github.com/sameeralam3127/ipmg/blob/main/docs/API.md) | Scripting IPMG Web over HTTP and WebSocket |
170
188
  | [Running as a service](https://github.com/sameeralam3127/ipmg/blob/main/docs/SERVICES.md) | systemd and launchd templates for scheduled scans and IPMG Web |
171
189
  | [GitHub Action](https://github.com/sameeralam3127/ipmg/blob/main/docs/GITHUB-ACTION.md) | Reachability checks in CI, before a deploy or on a schedule |
190
+ | [SNMP polling](https://github.com/sameeralam3127/ipmg/blob/main/docs/SNMP.md) | Switches and routers over SNMP v2c and v3: credentials, interfaces, reboots, reports |
172
191
  | [How it compares](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMPARISON.md) | IPMG next to nmap, fping, and Uptime Kuma |
173
192
  | [Troubleshooting](https://github.com/sameeralam3127/ipmg/blob/main/docs/TROUBLESHOOTING.md) and [FAQ](https://github.com/sameeralam3127/ipmg/blob/main/docs/FAQ.md) | Install errors, timeouts, slow scans, empty MAC addresses, common questions |
174
193
  | [Architecture](https://github.com/sameeralam3127/ipmg/blob/main/docs/ARCHITECTURE.md) | How the code fits together, for contributors |
175
194
 
176
- ---
177
-
178
195
  ## Security
179
196
 
180
197
  IPMG runs `ping` as a direct process call with no shell, validates every
@@ -185,8 +202,6 @@ requests IPMG makes are the notifications and HTTP checks you ask for. Found a
185
202
  vulnerability? See
186
203
  [SECURITY.md](https://github.com/sameeralam3127/ipmg/blob/main/.github/SECURITY.md).
187
204
 
188
- ---
189
-
190
205
  ## Contributing
191
206
 
192
207
  Contributions are welcome.
@@ -197,6 +212,9 @@ releases, and
197
212
  explains the code. Everyone taking part is expected to follow the
198
213
  [Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/.github/CODE_OF_CONDUCT.md).
199
214
 
215
+ If IPMG saves you time, a star on
216
+ [GitHub](https://github.com/sameeralam3127/ipmg) helps other people find it.
217
+
200
218
  ## License
201
219
 
202
220
  MIT — free for commercial and personal use.
@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
13
13
 
14
14
  [project]
15
15
  name = "ipmg"
16
- version = "4.0.0" # Managed automatically by semantic-release
16
+ version = "4.1.0" # Managed automatically by semantic-release
17
17
  description = "Network discovery and change detection: ping sweeps, scan history, and reports for what changed on your network"
18
18
  readme = "README.md"
19
19
  requires-python = ">=3.10"
@@ -73,13 +73,17 @@ web = [
73
73
  "websockets>=12",
74
74
  "python-multipart>=0.0.9",
75
75
  ]
76
- # Everything; what the one-line installers and the Docker image install.
77
- all = ["ipmg[web]"]
76
+ # SNMPv3 encryption (`--snmp` with a privacy key). SNMP v2c and v3 without
77
+ # encryption need nothing extra.
78
+ snmp = ["cryptography>=42"]
79
+ # Everything.
80
+ all = ["ipmg[web,snmp]"]
78
81
  dev = [
79
- "ipmg[web]",
82
+ "ipmg[web,snmp]",
80
83
  "pytest>=7.4",
81
84
  "pytest-cov>=5.0",
82
85
  "ruff>=0.4",
86
+ "mypy>=1.10",
83
87
  "pre-commit>=3.5.0",
84
88
  "python-semantic-release>=10.5.3",
85
89
  # The TestClient's HTTP client. Starlette 1.x wants httpx2 and warns
@@ -99,10 +103,11 @@ ipmg = "ipmg.cli.commands:run"
99
103
 
100
104
  [dependency-groups]
101
105
  dev = [
102
- "ipmg[web]",
106
+ "ipmg[web,snmp]",
103
107
  "pytest>=7.4",
104
108
  "pytest-cov>=5.0",
105
109
  "ruff>=0.4",
110
+ "mypy>=1.10",
106
111
  "pre-commit>=3.5.0",
107
112
  "python-semantic-release>=10.5.3",
108
113
  # The TestClient's HTTP client. Starlette 1.x wants httpx2 and warns
@@ -160,6 +165,14 @@ where = ["src"]
160
165
  # Testing
161
166
  # ==========================================================
162
167
 
168
+ [tool.mypy]
169
+ python_version = "3.10"
170
+ # Optional extras (openpyxl stubs, pysnmp) are not all typed.
171
+ ignore_missing_imports = true
172
+ warn_unused_ignores = true
173
+ files = ["src"]
174
+
175
+
163
176
  [tool.pytest.ini_options]
164
177
  testpaths = ["tests"]
165
178
  pythonpath = ["src"]
@@ -189,8 +202,9 @@ line-length = 100
189
202
  target-version = "py310"
190
203
 
191
204
  [tool.ruff.lint]
192
- select = ["E", "F", "W", "I", "C90"]
193
- ignore = ["E501"]
205
+ select = ["E", "F", "W", "I", "C90", "UP"]
206
+ # UP038 (isinstance(x, A | B)) is slower than a tuple and deprecated in ruff.
207
+ ignore = ["E501", "UP038"]
194
208
 
195
209
  [tool.ruff.lint.isort]
196
210
  combine-as-imports = true
@@ -2,4 +2,4 @@
2
2
  ipmg - IP Management & Ping Monitoring Tool
3
3
  """
4
4
 
5
- __version__ = "4.0.0"
5
+ __version__ = "4.1.0"