ipmg 2.4.0__tar.gz → 3.1.0__tar.gz

{ipmg-2.4.0 → ipmg-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 2.4.0
+Version: 3.1.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -29,16 +29,19 @@ Classifier: Environment :: Console
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pandas>=2.2.2
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: rich>=13.0
-Requires-Dist: fastapi>=0.110
-Requires-Dist: pydantic>=2.7
-Requires-Dist: uvicorn>=0.27
-Requires-Dist: websockets>=12
-Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == "web"
+Requires-Dist: pydantic>=2.7; extra == "web"
+Requires-Dist: uvicorn>=0.27; extra == "web"
+Requires-Dist: websockets>=12; extra == "web"
+Requires-Dist: python-multipart>=0.0.9; extra == "web"
+Provides-Extra: all
+Requires-Dist: ipmg[web]; extra == "all"
 Provides-Extra: dev
+Requires-Dist: ipmg[web]; extra == "dev"
 Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
@@ -151,11 +154,24 @@ The formula lives in
 and is updated with every release. Upgrade with `brew upgrade ipmg`, remove
 with `brew uninstall ipmg`.
 
-**Windows — two commands in PowerShell:**
+**Windows — one command in PowerShell:**
 
 ```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-uv tool install ipmg
+irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
+```
+
+It works in Windows PowerShell 5.1 and PowerShell 7 and needs no
+administrator rights: it installs uv if it is missing, installs IPMG, adds it
+to your user `PATH`, and checks that `ipmg --version` runs. To pin a release:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version 2.3.0
+```
+
+**Docker (amd64 and arm64):**
+
+```bash
+docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24
 ```
 
 Then check it works, on any platform:
@@ -164,6 +180,38 @@ Then check it works, on any platform:
 ipmg --version
 ```
 
+### Running in Docker
+
+The image carries `ping`, runs as an unprivileged user (uid 10001), and keeps
+everything a scan writes (reports and the history database) in `/data`. Mount
+a volume there to keep it between runs:
+
+```bash
+docker run --rm -v ipmg-data:/data ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24 --compare
+```
+
+Ping needs no added capability: it uses the unprivileged ICMP sockets that
+Docker and containerd enable by default, so it also works with
+`--cap-drop ALL` and under Kubernetes' restricted pod security profile. To
+scan your LAN rather than the container's network, add `--network host`
+(Linux).
+
+For IPMG Web, use the [`compose.yaml`](https://github.com/sameeralam3127/ipmg/blob/main/compose.yaml)
+in this repository. Inside a container IPMG Web must listen on `0.0.0.0` or
+nothing outside the container could reach it, so the compose file starts it
+with `web --host 0.0.0.0` and publishes the port on the host's `127.0.0.1`
+only. Set a fixed `IPMG_WEB_TOKEN` in `.env`, then:
+
+```bash
+docker compose up -d                                      # http://127.0.0.1:8080/#token=<your token>
+docker compose run --rm scan --input 10.0.0.0/24          # CLI scans land in the same history
+```
+
+Publishing the port more widely (`8080:8080`) exposes IPMG Web on your
+network over plain HTTP; put a reverse proxy with TLS in front first. Images
+are tagged with the release version (`2.4.0`), the minor line (`2.4`), and
+`latest`.
+
 ### Installing with pip
 
 `pip install ipmg` works inside a virtual environment, and inside one only.
@@ -193,6 +241,22 @@ python3 -m venv ~/.venvs/ipmg
 
 Please do not reach for `--break-system-packages`. It does what it says.
 
+### What gets installed
+
+`pip install ipmg` is the lean core: scanning, every report format
+(Excel included), history, change detection, notifications, and exit codes.
+It is about 9 MB and 7 packages. IPMG Web, the browser UI with its REST API
+and Prometheus `/metrics`, is the optional `web` extra, because its server
+stack is most of the weight:
+
+```bash
+pip install "ipmg[web]"             # or: uv tool install "ipmg[web]", pipx install "ipmg[web]"
+```
+
+The one-line installers, Homebrew, and the Docker image install it with the
+`web` extra already. Run `ipmg web` without it and IPMG tells you the command
+that adds it.
+
 ### The one thing IPMG needs from your system
 
 IPMG probes hosts with your operating system's `ping` command, and minimal
@@ -494,6 +558,57 @@ your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/ma
 covers authentication, errors, and worked `curl` examples; the running server
 also serves interactive docs at `http://127.0.0.1:8080/docs`.
 
+### Prometheus metrics
+
+`ipmg web --metrics` serves `/metrics` in the Prometheus text format, so the
+results of every scan, whether run from cron with the CLI or from the browser,
+land in the dashboards and alerts you already have. It reports the latest
+completed scan of each source, and it is off unless you pass the flag:
+
+```bash
+IPMG_WEB_TOKEN=$(cat /etc/ipmg/token) ipmg web --metrics --no-browser
+```
+
+```yaml
+# prometheus.yml: the token is the same one the web UI uses
+scrape_configs:
+  - job_name: ipmg
+    authorization:
+      credentials_file: /etc/prometheus/ipmg-token
+    static_configs:
+      - targets: ["127.0.0.1:8080"]
+
+# an alert rule: a host that stopped answering
+groups:
+  - name: ipmg
+    rules:
+      - alert: HostDown
+        expr: ipmg_host_up == 0
+        for: 10m
+        annotations:
+          summary: "{{ $labels.ip }} ({{ $labels.source }}) is not answering ping"
+```
+
+| Metric | Labels | Meaning |
+| --- | --- | --- |
+| `ipmg_host_up` | `source`, `ip` | 1 if the host answered, else 0 |
+| `ipmg_host_latency_seconds` | `source`, `ip` | Round-trip time, for hosts that answered |
+| `ipmg_host_open_ports` | `source`, `ip` | Open TCP ports, for scans run with `--scan-ports` |
+| `ipmg_host_info` | `source`, `ip`, `hostname` | Always 1; carries the reverse DNS name |
+| `ipmg_scan_hosts` | `source`, `status` | Hosts in the latest scan, by status |
+| `ipmg_scan_duration_seconds` | `source` | How long the latest scan took |
+| `ipmg_scan_timestamp_seconds` | `source` | When the latest scan finished; alert on `time() - this` to catch a stalled cron job |
+| `ipmg_scans_total` | `source` | Completed scans stored for the source |
+| `ipmg_metrics_sources_omitted` | | Sources left out by `--metrics-sources` |
+| `ipmg_build_info` | `version` | Always 1 |
+
+**Cardinality is bounded.** Host series carry only `source` and `ip`, never
+the hostname or status, which change, so a rename does not start a new series.
+Only the `--metrics-sources` most recently scanned sources are exported
+(default 20), and a scan holds at most 65,536 hosts, so the page stays at
+about `sources × hosts × 4` series at most. Give recurring scans a stable
+input (the same file) so each one updates its source rather than adding one.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects
@@ -517,9 +632,11 @@ of it (see [Security](#security)).
 
 Anywhere IPMG takes `--input`, you can give it any of these:
 
-- **A single IP** — `8.8.8.8`
-- **A CIDR block** — `10.0.0.0/24`
-- **A range** — `10.0.0.1-10.0.0.200`
+- **A single IP** — `8.8.8.8`, or IPv6 such as `2001:db8::1` or a link-local
+  `fe80::1%eth0`
+- **A CIDR block** — `10.0.0.0/24`, or an IPv6 prefix up to 65,536 hosts
+  (`2001:db8::/112`)
+- **A range** — `10.0.0.1-10.0.0.200` or `2001:db8::10-2001:db8::20`
 - **A text file** — one IP or CIDR per line. Blank lines and `#` comments are
   ignored, so you can annotate it:
 
@@ -529,7 +646,7 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   192.168.1.0/30
   ```
 
-- **An Excel or CSV file** (`.xlsx`, `.xls`, `.csv`) — must contain a column
+- **An Excel or CSV file** (`.xlsx`, `.csv`) — must contain a column
   named `IP Address`. Cells can hold single addresses or CIDR blocks:
 
   | IP Address  |
@@ -559,6 +676,16 @@ ipmg --input targets.txt 10.0.0.0/30 10.0.0.5
 ipmg --input targets.txt --input 10.0.0.5     # the same thing
 ```
 
+IPv4 and IPv6 targets mix freely in one scan, and reports, history, and change
+detection handle both. An IPv6 `/64` holds 2^64 addresses, far too many to
+sweep one by one, so it is rejected with a pointer to `--discover ipv6`, which
+finds the hosts on your local links through neighbour discovery instead:
+
+```bash
+ipmg --discover ipv6      # IPv6 neighbours on the local links
+ipmg --discover all       # the IPv4 /24 and the IPv6 neighbours together
+```
+
 Duplicate targets are removed automatically — across sources too, so a host
 that is both in the file and on the command line is scanned once — and one scan
 expands to at most 65,536 hosts in total. Larger CIDR blocks, ranges, or
@@ -708,7 +835,7 @@ cannot combine flags that exclude each other, such as `json` and `jsonl`.
 | Flag | Default | Description |
 | --- | --- | --- |
 | `--input` | `ip_list.xlsx` | What to scan: one or more files (`.xlsx`, `.xls`, `.csv`, `.json`, `.txt`, `.list`), IPs, CIDR blocks, or ranges (`10.0.0.1-10.0.0.50`), merged and de-duplicated |
-| `--discover` | off | Auto-detect and scan the local subnet instead |
+| `--discover [FAMILY]` | off | Scan this machine's networks instead: `ipv4` (the default) sweeps the local /24, `ipv6` finds link neighbours, `all` does both |
 | `--output` | `results` | Report file name prefix |
 | `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` (no file at all with `--json`/`--jsonl`) |
 | `--json` | off | Print the finished scan to stdout as a JSON array, human output on stderr |

ipmg-2.4.0/src/ipmg.egg-info/PKG-INFO → ipmg-3.1.0/README.md

@@ -1,52 +1,3 @@
-Metadata-Version: 2.4
-Name: ipmg
-Version: 2.4.0
-Summary: IP Management & Ping Monitoring CLI Tool
-Author: Sameer Alam
-Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
-License-Expression: MIT
-Project-URL: Homepage, https://sameeralam3127.github.io/ipmg/
-Project-URL: Documentation, https://github.com/sameeralam3127/ipmg#readme
-Project-URL: Repository, https://github.com/sameeralam3127/ipmg
-Project-URL: Issues, https://github.com/sameeralam3127/ipmg/issues
-Project-URL: Changelog, https://github.com/sameeralam3127/ipmg/releases
-Keywords: ip,network,ping,monitoring,cli,port-scan,network-scanner,ping-sweep,subnet-scanner,homelab,sysadmin
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Internet
-Classifier: Topic :: System :: Networking
-Classifier: Topic :: System :: Monitoring
-Classifier: Intended Audience :: System Administrators
-Classifier: Intended Audience :: Information Technology
-Classifier: Operating System :: OS Independent
-Classifier: Environment :: Console
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pandas>=2.2.2
-Requires-Dist: openpyxl>=3.1
-Requires-Dist: rich>=13.0
-Requires-Dist: fastapi>=0.110
-Requires-Dist: pydantic>=2.7
-Requires-Dist: uvicorn>=0.27
-Requires-Dist: websockets>=12
-Requires-Dist: python-multipart>=0.0.9
-Requires-Dist: tomli>=2.0.1; python_version < "3.11"
-Provides-Extra: dev
-Requires-Dist: pytest>=7.4; extra == "dev"
-Requires-Dist: pytest-cov>=5.0; extra == "dev"
-Requires-Dist: ruff>=0.4; extra == "dev"
-Requires-Dist: pre-commit>=3.5.0; extra == "dev"
-Requires-Dist: python-semantic-release>=10.5.3; extra == "dev"
-Requires-Dist: httpx>=0.27; extra == "dev"
-Dynamic: license-file
-
 # IPMG — IP Management & Ping Monitoring Tool
 
 [![PyPI](https://img.shields.io/pypi/v/ipmg)](https://pypi.org/project/ipmg/)
@@ -151,11 +102,24 @@ The formula lives in
 and is updated with every release. Upgrade with `brew upgrade ipmg`, remove
 with `brew uninstall ipmg`.
 
-**Windows — two commands in PowerShell:**
+**Windows — one command in PowerShell:**
 
 ```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-uv tool install ipmg
+irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
+```
+
+It works in Windows PowerShell 5.1 and PowerShell 7 and needs no
+administrator rights: it installs uv if it is missing, installs IPMG, adds it
+to your user `PATH`, and checks that `ipmg --version` runs. To pin a release:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version 2.3.0
+```
+
+**Docker (amd64 and arm64):**
+
+```bash
+docker run --rm ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24
 ```
 
 Then check it works, on any platform:
@@ -164,6 +128,38 @@ Then check it works, on any platform:
 ipmg --version
 ```
 
+### Running in Docker
+
+The image carries `ping`, runs as an unprivileged user (uid 10001), and keeps
+everything a scan writes (reports and the history database) in `/data`. Mount
+a volume there to keep it between runs:
+
+```bash
+docker run --rm -v ipmg-data:/data ghcr.io/sameeralam3127/ipmg --input 10.0.0.0/24 --compare
+```
+
+Ping needs no added capability: it uses the unprivileged ICMP sockets that
+Docker and containerd enable by default, so it also works with
+`--cap-drop ALL` and under Kubernetes' restricted pod security profile. To
+scan your LAN rather than the container's network, add `--network host`
+(Linux).
+
+For IPMG Web, use the [`compose.yaml`](https://github.com/sameeralam3127/ipmg/blob/main/compose.yaml)
+in this repository. Inside a container IPMG Web must listen on `0.0.0.0` or
+nothing outside the container could reach it, so the compose file starts it
+with `web --host 0.0.0.0` and publishes the port on the host's `127.0.0.1`
+only. Set a fixed `IPMG_WEB_TOKEN` in `.env`, then:
+
+```bash
+docker compose up -d                                      # http://127.0.0.1:8080/#token=<your token>
+docker compose run --rm scan --input 10.0.0.0/24          # CLI scans land in the same history
+```
+
+Publishing the port more widely (`8080:8080`) exposes IPMG Web on your
+network over plain HTTP; put a reverse proxy with TLS in front first. Images
+are tagged with the release version (`2.4.0`), the minor line (`2.4`), and
+`latest`.
+
 ### Installing with pip
 
 `pip install ipmg` works inside a virtual environment, and inside one only.
@@ -193,6 +189,22 @@ python3 -m venv ~/.venvs/ipmg
 
 Please do not reach for `--break-system-packages`. It does what it says.
 
+### What gets installed
+
+`pip install ipmg` is the lean core: scanning, every report format
+(Excel included), history, change detection, notifications, and exit codes.
+It is about 9 MB and 7 packages. IPMG Web, the browser UI with its REST API
+and Prometheus `/metrics`, is the optional `web` extra, because its server
+stack is most of the weight:
+
+```bash
+pip install "ipmg[web]"             # or: uv tool install "ipmg[web]", pipx install "ipmg[web]"
+```
+
+The one-line installers, Homebrew, and the Docker image install it with the
+`web` extra already. Run `ipmg web` without it and IPMG tells you the command
+that adds it.
+
 ### The one thing IPMG needs from your system
 
 IPMG probes hosts with your operating system's `ping` command, and minimal
@@ -494,6 +506,57 @@ your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/ma
 covers authentication, errors, and worked `curl` examples; the running server
 also serves interactive docs at `http://127.0.0.1:8080/docs`.
 
+### Prometheus metrics
+
+`ipmg web --metrics` serves `/metrics` in the Prometheus text format, so the
+results of every scan, whether run from cron with the CLI or from the browser,
+land in the dashboards and alerts you already have. It reports the latest
+completed scan of each source, and it is off unless you pass the flag:
+
+```bash
+IPMG_WEB_TOKEN=$(cat /etc/ipmg/token) ipmg web --metrics --no-browser
+```
+
+```yaml
+# prometheus.yml: the token is the same one the web UI uses
+scrape_configs:
+  - job_name: ipmg
+    authorization:
+      credentials_file: /etc/prometheus/ipmg-token
+    static_configs:
+      - targets: ["127.0.0.1:8080"]
+
+# an alert rule: a host that stopped answering
+groups:
+  - name: ipmg
+    rules:
+      - alert: HostDown
+        expr: ipmg_host_up == 0
+        for: 10m
+        annotations:
+          summary: "{{ $labels.ip }} ({{ $labels.source }}) is not answering ping"
+```
+
+| Metric | Labels | Meaning |
+| --- | --- | --- |
+| `ipmg_host_up` | `source`, `ip` | 1 if the host answered, else 0 |
+| `ipmg_host_latency_seconds` | `source`, `ip` | Round-trip time, for hosts that answered |
+| `ipmg_host_open_ports` | `source`, `ip` | Open TCP ports, for scans run with `--scan-ports` |
+| `ipmg_host_info` | `source`, `ip`, `hostname` | Always 1; carries the reverse DNS name |
+| `ipmg_scan_hosts` | `source`, `status` | Hosts in the latest scan, by status |
+| `ipmg_scan_duration_seconds` | `source` | How long the latest scan took |
+| `ipmg_scan_timestamp_seconds` | `source` | When the latest scan finished; alert on `time() - this` to catch a stalled cron job |
+| `ipmg_scans_total` | `source` | Completed scans stored for the source |
+| `ipmg_metrics_sources_omitted` | | Sources left out by `--metrics-sources` |
+| `ipmg_build_info` | `version` | Always 1 |
+
+**Cardinality is bounded.** Host series carry only `source` and `ip`, never
+the hostname or status, which change, so a rename does not start a new series.
+Only the `--metrics-sources` most recently scanned sources are exported
+(default 20), and a scan holds at most 65,536 hosts, so the page stays at
+about `sources × hosts × 4` series at most. Give recurring scans a stable
+input (the same file) so each one updates its source rather than adding one.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects
@@ -517,9 +580,11 @@ of it (see [Security](#security)).
 
 Anywhere IPMG takes `--input`, you can give it any of these:
 
-- **A single IP** — `8.8.8.8`
-- **A CIDR block** — `10.0.0.0/24`
-- **A range** — `10.0.0.1-10.0.0.200`
+- **A single IP** — `8.8.8.8`, or IPv6 such as `2001:db8::1` or a link-local
+  `fe80::1%eth0`
+- **A CIDR block** — `10.0.0.0/24`, or an IPv6 prefix up to 65,536 hosts
+  (`2001:db8::/112`)
+- **A range** — `10.0.0.1-10.0.0.200` or `2001:db8::10-2001:db8::20`
 - **A text file** — one IP or CIDR per line. Blank lines and `#` comments are
   ignored, so you can annotate it:
 
@@ -529,7 +594,7 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   192.168.1.0/30
   ```
 
-- **An Excel or CSV file** (`.xlsx`, `.xls`, `.csv`) — must contain a column
+- **An Excel or CSV file** (`.xlsx`, `.csv`) — must contain a column
   named `IP Address`. Cells can hold single addresses or CIDR blocks:
 
   | IP Address  |
@@ -559,6 +624,16 @@ ipmg --input targets.txt 10.0.0.0/30 10.0.0.5
 ipmg --input targets.txt --input 10.0.0.5     # the same thing
 ```
 
+IPv4 and IPv6 targets mix freely in one scan, and reports, history, and change
+detection handle both. An IPv6 `/64` holds 2^64 addresses, far too many to
+sweep one by one, so it is rejected with a pointer to `--discover ipv6`, which
+finds the hosts on your local links through neighbour discovery instead:
+
+```bash
+ipmg --discover ipv6      # IPv6 neighbours on the local links
+ipmg --discover all       # the IPv4 /24 and the IPv6 neighbours together
+```
+
 Duplicate targets are removed automatically — across sources too, so a host
 that is both in the file and on the command line is scanned once — and one scan
 expands to at most 65,536 hosts in total. Larger CIDR blocks, ranges, or
@@ -708,7 +783,7 @@ cannot combine flags that exclude each other, such as `json` and `jsonl`.
 | Flag | Default | Description |
 | --- | --- | --- |
 | `--input` | `ip_list.xlsx` | What to scan: one or more files (`.xlsx`, `.xls`, `.csv`, `.json`, `.txt`, `.list`), IPs, CIDR blocks, or ranges (`10.0.0.1-10.0.0.50`), merged and de-duplicated |
-| `--discover` | off | Auto-detect and scan the local subnet instead |
+| `--discover [FAMILY]` | off | Scan this machine's networks instead: `ipv4` (the default) sweeps the local /24, `ipv6` finds link neighbours, `all` does both |
 | `--output` | `results` | Report file name prefix |
 | `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` (no file at all with `--json`/`--jsonl`) |
 | `--json` | off | Print the finished scan to stdout as a JSON array, human output on stderr |

{ipmg-2.4.0 → ipmg-3.1.0}/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipmg"
-version = "2.4.0"  # Managed automatically by semantic-release
+version = "3.1.0"  # Managed automatically by semantic-release
 description = "IP Management & Ping Monitoring CLI Tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -48,15 +48,11 @@ classifiers = [
     "Environment :: Console",
 ]
 
+# The core is what a scan needs: the terminal UI, Excel reports and input,
+# and the config file parser. IPMG Web's server stack is the `web` extra.
 dependencies = [
-    "pandas>=2.2.2",
     "openpyxl>=3.1",
     "rich>=13.0",
-    "fastapi>=0.110",
-    "pydantic>=2.7",
-    "uvicorn>=0.27",
-    "websockets>=12",
-    "python-multipart>=0.0.9",
     # tomllib is in the standard library from 3.11; tomli 2.x is the same
     # parser with the same API, so the floor must not drop below it.
     "tomli>=2.0.1; python_version < '3.11'",
@@ -70,7 +66,18 @@ Issues = "https://github.com/sameeralam3127/ipmg/issues"
 Changelog = "https://github.com/sameeralam3127/ipmg/releases"
 
 [project.optional-dependencies]
+# IPMG Web (`ipmg web`): the browser UI, its REST API, and /metrics.
+web = [
+    "fastapi>=0.110",
+    "pydantic>=2.7",
+    "uvicorn>=0.27",
+    "websockets>=12",
+    "python-multipart>=0.0.9",
+]
+# Everything; what the one-line installers and the Docker image install.
+all = ["ipmg[web]"]
 dev = [
+    "ipmg[web]",
     "pytest>=7.4",
     "pytest-cov>=5.0",
     "ruff>=0.4",
@@ -89,6 +96,7 @@ ipmg = "ipmg.cli.commands:run"
 
 [dependency-groups]
 dev = [
+    "ipmg[web]",
     "pytest>=7.4",
     "pytest-cov>=5.0",
     "ruff>=0.4",

{ipmg-2.4.0 → ipmg-3.1.0}/src/ipmg/__init__.py

@@ -2,4 +2,4 @@
 ipmg - IP Management & Ping Monitoring Tool
 """
 
-__version__ = "2.4.0"
+__version__ = "3.1.0"

{ipmg-2.4.0 → ipmg-3.1.0}/src/ipmg/cli/commands.py

@@ -25,6 +25,17 @@ from ipmg.services.history_service import HistoryService
 from ipmg.services.scan_service import machine_output, run_scan
 from ipmg.utils.helpers import configure_logging
 
+#: Top-level modules of the `web` extra, to tell a missing extra from a bug.
+WEB_PACKAGES = frozenset({"fastapi", "pydantic", "starlette", "uvicorn", "websockets", "multipart"})
+
+WEB_EXTRA_MISSING = (
+    "IPMG Web needs the optional 'web' packages, which this install does not have. "
+    "Add them with whichever tool installed IPMG:\n"
+    "  uv tool install --force 'ipmg[web]'\n"
+    "  pipx install --force 'ipmg[web]'\n"
+    "  pip install 'ipmg[web]'"
+)
+
 EXIT_OK = 0
 EXIT_ERROR = 1
 EXIT_CHANGES_DETECTED = 2
@@ -57,14 +68,21 @@ def _web_command(argv: List[str]) -> int:
     ui.header("web")
     print_disclaimer_once()
 
-    # Imported lazily so plain CLI scans do not pay for the web stack.
-    from ipmg.web.server import run_dashboard
+    # Imported lazily so plain CLI scans do not pay for the web stack, which
+    # is the optional `web` extra.
+    try:
+        from ipmg.web.server import run_dashboard
+    except ModuleNotFoundError as exc:
+        if exc.name not in WEB_PACKAGES:
+            raise
+        raise IPMGError(WEB_EXTRA_MISSING) from exc
 
     run_dashboard(
         host=args.host,
         port=args.port,
         open_browser=not args.no_browser,
         db_path=args.db,
+        metrics_sources=max(args.metrics_sources, 1) if args.metrics else None,
     )
     return EXIT_OK
 

{ipmg-2.4.0 → ipmg-3.1.0}/src/ipmg/cli/config.py

@@ -264,6 +264,11 @@ def _coerce(action: argparse.Action, key: str, value: Any, path: Path) -> Any:
             raise ConfigError(f"{where} must be true or false, not {_kind(value)}.")
         return action.const if value else _KEEP
 
+    if action.nargs == "?" and isinstance(value, bool):
+        # A flag whose value is optional (--discover [FAMILY]): true is the bare
+        # flag, so "discover = true" keeps meaning what it did as a switch.
+        return action.const if value else _KEEP
+
     if action.nargs in ("+", "*"):
         values = value if isinstance(value, list) else [value]
         if not values:

{ipmg-2.4.0 → ipmg-3.1.0}/src/ipmg/cli/parser.py

@@ -6,6 +6,7 @@ import argparse
 
 from ipmg import __version__
 from ipmg.cli.config import add_config_arguments, config_help
+from ipmg.core.discovery import DISCOVERY_FAMILIES
 from ipmg.core.portscan import DEFAULT_PORTS, parse_port_list
 from ipmg.infrastructure.file_io import DEFAULT_INPUT_FILE
 from ipmg.infrastructure.incremental import (
@@ -26,6 +27,7 @@ from ipmg.infrastructure.notify import (
 )
 from ipmg.reporting.diff_report import DIFF_FORMATS
 from ipmg.reporting.live import DEFAULT_REFRESH_S, MAX_REFRESH_S, MIN_REFRESH_S
+from ipmg.reporting.metrics import DEFAULT_MAX_SOURCES
 
 PROG = "IPMG - IP Management & Ping Monitoring Tool"
 
@@ -259,8 +261,16 @@ def build_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--discover",
-        action="store_true",
-        help="Auto-detect this machine's subnet and scan it instead of --input.",
+        nargs="?",
+        const="ipv4",
+        default=None,
+        choices=DISCOVERY_FAMILIES,
+        metavar="FAMILY",
+        help=(
+            "Scan this machine's networks instead of --input: ipv4 (the default) "
+            "sweeps the local /24, ipv6 finds hosts on the local links through "
+            "neighbour discovery, all does both."
+        ),
     )
     parser.add_argument(
         "--resolve",
@@ -449,6 +459,24 @@ def build_web_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Do not open IPMG Web in a browser automatically.",
     )
+    parser.add_argument(
+        "--metrics",
+        action="store_true",
+        help=(
+            "Serve Prometheus metrics at /metrics for the latest completed scan of "
+            "each source (off by default; needs the access token)."
+        ),
+    )
+    parser.add_argument(
+        "--metrics-sources",
+        type=int,
+        default=DEFAULT_MAX_SOURCES,
+        metavar="N",
+        help=(
+            "Export only the N most recently scanned sources, which bounds the "
+            f"number of series (default: {DEFAULT_MAX_SOURCES})."
+        ),
+    )
     _add_database_argument(parser)
     parser.add_argument("--verbose", action="store_true")
     return parser

{ipmg-2.4.0 → ipmg-3.1.0}/src/ipmg/core/diff.py

@@ -256,13 +256,17 @@ def _index_by_hostname(snapshots: Mapping[str, HostSnapshot]) -> Dict[str, Set[s
     return index
 
 
-def ip_sort_key(value: str) -> Tuple[int, int, str]:
-    """Sort key placing valid IPs first in numeric order; shared with the DB layer."""
+def ip_sort_key(value: str) -> Tuple[int, int, int, str]:
+    """Sort key: IPv4 in numeric order, then IPv6, then anything unparsable.
+
+    The family comes before the number, or ``::1`` (the integer 1) would sort
+    ahead of every IPv4 address. Shared with the DB layer.
+    """
     try:
         address = ipaddress.ip_address(value)
     except ValueError:
-        return (1, 0, value)
-    return (0, int(address), "")
+        return (1, 0, 0, value)
+    return (0, address.version, int(address), value)
 
 
 def _sort_changes(changes: Sequence[HostChange]) -> Tuple[HostChange, ...]: