ipmg 2.2.0__tar.gz → 2.4.0__tar.gz

{ipmg-2.2.0/src/ipmg.egg-info → ipmg-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 2.2.0
+Version: 2.4.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -33,9 +33,11 @@ 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"
@@ -330,8 +332,10 @@ Or pick a ready-made command:
 | --- | --- |
 | Scan the network I am on | `ipmg --discover` |
 | Scan hosts listed in a file | `ipmg --input targets.txt` |
+| Scan a file plus a few extra hosts | `ipmg --input targets.txt 10.0.0.0/30 10.0.0.5` |
 | Get names, not just IP addresses | `ipmg --input targets.txt --resolve` |
 | Get a report I can send to someone | `ipmg --input targets.txt --formats md csv` |
+| Pipe the results into a script | `ipmg --input targets.txt --json \| jq .` |
 | See hosts appear as they answer | `ipmg --input 192.168.1.0/24 --stream` |
 | See what changed since last time | `ipmg --input targets.txt --compare` |
 | Check which services are listening | `ipmg --input targets.txt --scan-ports` |
@@ -390,6 +394,21 @@ ipmg diff --fail-on-change            # exit 2 when anything changed (CI)
 ipmg history --limit 10               # list stored scans
 ```
 
+To hear about changes without watching the terminal, send them to Slack,
+Microsoft Teams, any JSON webhook, or email. Any `--notify-*` flag turns on
+`--compare`, and with `--interval` every pass that changes something alerts:
+
+```bash
+ipmg --input targets.txt --interval 15 --notify-slack        # URL from $IPMG_NOTIFY_SLACK
+ipmg --input targets.txt --notify-email ops@example.com --smtp-host smtp.example.com
+ipmg diff --notify-webhook https://ops.example.com/ipmg --notify-severity critical
+```
+
+Only changes at or above `--notify-severity` (default `warning`) trigger a
+notification. A notification that fails is reported but never fails the scan.
+Secrets such as webhook URLs and `IPMG_SMTP_PASSWORD` can come from environment
+variables; see [Notifications](docs/COMMANDS.md#notifications) for all of them.
+
 What counts as a change:
 
 | Change | Severity | Meaning |
@@ -422,6 +441,11 @@ source**, so file-based and `--discover` runs do not get mixed up. Pass
 | `--latency-threshold` | `5` | Minimum latency delta in ms |
 | `--latency-pct` | `25` | Minimum relative latency change |
 | `--fail-on-change` | off | `ipmg diff` exits 2 when changes are found |
+| `--notify-webhook` | off | POST the change report as JSON to a URL |
+| `--notify-slack` | off | Post changes to a Slack incoming webhook |
+| `--notify-teams` | off | Post changes to a Microsoft Teams Workflows webhook |
+| `--notify-email` | off | Email the Markdown change report (with `--smtp-host`, `--smtp-port`, `--smtp-security`, `--smtp-user`, `--smtp-from`) |
+| `--notify-severity` | `warning` | Only notify for changes at least this severe |
 
 ---
 
@@ -462,6 +486,14 @@ package, nothing is loaded from a CDN. It gives you:
 | `--no-browser` | off | Don't open the browser automatically |
 | `--db` | `~/.ipmg/dashboard.db` | History database location |
 
+### Scripting IPMG Web
+
+Everything the dashboard does goes through a documented, versioned REST API
+under `/api/v1`, so you can start scans, fetch results, and compare scans from
+your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/API.md)
+covers authentication, errors, and worked `curl` examples; the running server
+also serves interactive docs at `http://127.0.0.1:8080/docs`.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects
@@ -505,9 +537,32 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   | 192.168.1.1 |
   | 10.0.1.0/30 |
 
-Duplicate targets are removed automatically, and one scan expands to at most
-65,536 hosts — larger CIDR blocks or ranges are rejected up front, before the
-scan starts.
+- **A JSON file** (`.json`) — a list of addresses, a list of objects keyed by
+  `IP Address`, `ip`, or `target`, or an object with a `targets` or `ips` array:
+
+  ```json
+  ["192.168.1.1", "10.0.1.0/30"]
+  ```
+
+  Because `IP Address` is one of the keys it accepts, a report IPMG wrote with
+  `--formats json` can be fed straight back in:
+
+  ```bash
+  ipmg --input results_20260628_120000.json
+  ```
+
+`--input` takes as many of these as you like, in any mix, and may also be
+repeated:
+
+```bash
+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
+```
+
+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
+combinations are rejected up front, before the scan starts.
 
 ---
 
@@ -557,6 +612,22 @@ preferring `jsonl` or `csv` (current to the last host) over `json` or `xlsx`
 (current to the last autosave). Hosts dropped from the target list since are
 left out of the finished report.
 
+**Piping results into a script.** `--json` prints the finished scan to stdout as
+a JSON array, and `--jsonl` prints one object per host the moment its probe
+finishes. The human output moves to stderr, so stdout is nothing but data and no
+temp file or glob is needed:
+
+```bash
+ipmg --input 10.0.0.0/24 --json | jq '.[] | select(.Status == "Active")'
+ipmg --input 10.0.0.0/24 --jsonl | while read -r host; do notify "$host"; done
+ipmg --input 10.0.0.0/24 --json 2>/dev/null > hosts.json   # data only
+```
+
+The field names are the report columns above, and both flags print a host
+identically — `--json` is what `--jsonl` prints, gathered into an array. Unless
+you ask for `--formats` explicitly, a piped scan writes no report file at all.
+Exit codes are unchanged.
+
 **Open ports.** `Open Ports` is only populated when `--scan-ports` is set: for
 each host that answers, IPMG probes a list of common TCP ports (SSH, HTTP,
 HTTPS, RDP, SMB, FTP, SMTP, DNS, MSSQL, MySQL, PostgreSQL by default)
@@ -573,6 +644,61 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 ---
 
+## Default options in a file
+
+If every run repeats the same flags, put them in **`ipmg.toml`** next to your
+work instead:
+
+```toml
+threads = 200
+timeout = 1
+resolve = true
+formats = ["md", "csv"]
+
+[profile.datacenter]
+threads = 400
+scan-ports = true
+ports = "22,80,443"
+```
+
+```bash
+ipmg --input targets.txt                        # uses the file's defaults
+ipmg --input targets.txt --profile datacenter   # and the profile on top
+ipmg --input targets.txt --threads 20           # a flag always wins
+```
+
+Any long flag can be a key, written as the flag is (`scan-ports`) or with
+underscores (`scan_ports`). A switch takes `true` to mean "as if the flag were
+passed" — `no-history = true` is `--no-history`. Files are read from
+`~/.config/ipmg/config.toml` first (or `$XDG_CONFIG_HOME`), then `./ipmg.toml`
+on top, so a project can override your global defaults:
+
+| Flag | What it does |
+| --- | --- |
+| `--config PATH` | Read that file instead of searching |
+| `--no-config` | Ignore every file and use the built-in defaults |
+| `--profile NAME` | Apply the `[profile.NAME]` section as well |
+
+**The command line always wins.** A flag that appears on it ignores the file
+entirely for that flag — including `--input`, which merges several sources on
+one command line but replaces the file's list rather than adding to it.
+
+A key that is not a flag, a value of the wrong type, or a value outside a
+flag's choices is an error naming the key and the file it came from:
+
+```text
+✗ Unknown option 'thredas' in ipmg.toml. Did you mean 'threads'?
+✗ 'formats' in ipmg.toml: 'pdf' is not one of xlsx, csv, json, jsonl, md.
+```
+
+A project's `./ipmg.toml` comes with whatever directory you scan from,
+including a repository you just cloned, so it cannot say where results are
+sent: the `--notify-*` destinations and `--smtp-*` settings are only read from
+`~/.config/ipmg/config.toml` or a file you pass with `--config`. A file also
+cannot combine flags that exclude each other, such as `json` and `jsonl`.
+
+---
+
 ## All options
 
 `ipmg --help` always lists the current set. Grouped for reading:
@@ -581,10 +707,12 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 | Flag | Default | Description |
 | --- | --- | --- |
-| `--input` | `ip_list.xlsx` | What to scan: a file (`.xlsx`, `.xls`, `.csv`, `.txt`, `.list`), a single IP, a CIDR block, or a range (`10.0.0.1-10.0.0.50`) |
+| `--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 |
 | `--output` | `results` | Report file name prefix |
-| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` |
+| `--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 |
+| `--jsonl` | off | Stream one JSON object per host to stdout as each probe finishes |
 | `--no-incremental` | off | Only write the report once the scan has finished |
 | `--autosave` | `30` | How often a running scan re-saves `xlsx`, `json`, and `md` |
 | `--resume` | off | Finish an interrupted scan from its partial report (newest one, or the path given) |
@@ -616,13 +744,25 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--stream-all` | off | Stream every result, including hosts that did not answer (implies `--stream`) |
 | `--stream-refresh` | `0.25` | Seconds between progress-bar redraws while streaming (0.05-5) |
 | `--verbose` | off | Debug logging |
+| `--config` | search | Read defaults from this file instead of searching for `ipmg.toml` |
+| `--no-config` | off | Ignore every configuration file |
+| `--profile` | none | Apply a `[profile.NAME]` section from the configuration file |
+
+**Exit status**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--fail-on-down` | off | Exit 3 if any target is not `Active` (reports are still written) |
+| `--min-active` | off | Exit 3 if fewer than this percentage of targets are `Active` |
 
 **History and changes** — see [Change detection](#change-detection) for
 `--compare`, `--no-history`, `--db`, `--diff-formats`, `--diff-output`,
-`--latency-threshold`, `--latency-pct`, and `--fail-on-change`.
+`--latency-threshold`, `--latency-pct`, `--fail-on-change`, and the
+`--notify-*` flags.
 
 Exit codes: `0` success, `1` error, `2` changes detected
-(`ipmg diff --fail-on-change`), `130` interrupted.
+(`ipmg diff --fail-on-change`), `3` hosts down (`--fail-on-down`,
+`--min-active`), `130` interrupted.
 
 ---
 
@@ -643,12 +783,15 @@ itself is hardened accordingly:
 - Uploads are capped at 5 MB and one scan expands to at most 65,536 hosts,
   so a bad input file cannot exhaust memory
 - All database access uses parameterized SQL
+- The only outbound requests IPMG makes are the notifications you ask for
+  with a `--notify-*` flag. Their URLs and the SMTP password can come from
+  environment variables, and error messages never repeat them
 
 If you bind to a non-local address with `--host`, the token still guards the
 API. It travels over plain HTTP, though, so use an SSH tunnel or a reverse
 proxy with TLS on any network you don't trust.
 
-Found a vulnerability? See [SECURITY.md](SECURITY.md) for how to report it.
+Found a vulnerability? See [SECURITY.md](.github/SECURITY.md) for how to report it.
 
 ---
 
@@ -657,6 +800,9 @@ Found a vulnerability? See [SECURITY.md](SECURITY.md) for how to report it.
 - **[Command reference](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMMANDS.md)** —
   every command and flag with copy-paste examples, a safe session that tries
   everything on your own machine, exit codes, and error messages
+- **[Web API guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/API.md)** —
+  script IPMG Web over HTTP: start scans, fetch results, compare scans,
+  and follow live events
 - **[Troubleshooting](https://github.com/sameeralam3127/ipmg/blob/main/docs/TROUBLESHOOTING.md)** —
   install errors, `command not found`, every host timing out, slow scans,
   rejected input files
@@ -670,11 +816,11 @@ Found a vulnerability? See [SECURITY.md](SECURITY.md) for how to report it.
 ## Contributing
 
 Contributions are welcome.
-[CONTRIBUTING.md](https://github.com/sameeralam3127/ipmg/blob/main/CONTRIBUTING.md)
+[CONTRIBUTING.md](https://github.com/sameeralam3127/ipmg/blob/main/.github/CONTRIBUTING.md)
 covers setting up a development environment, running the tests, the commit
 message format that drives automated releases, and how the project website and
 IPMG Web demo are built. Everyone taking part is expected to follow the
-[Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/CODE_OF_CONDUCT.md).
+[Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/.github/CODE_OF_CONDUCT.md).
 
 ---
 

{ipmg-2.2.0 → ipmg-2.4.0}/README.md

@@ -283,8 +283,10 @@ Or pick a ready-made command:
 | --- | --- |
 | Scan the network I am on | `ipmg --discover` |
 | Scan hosts listed in a file | `ipmg --input targets.txt` |
+| Scan a file plus a few extra hosts | `ipmg --input targets.txt 10.0.0.0/30 10.0.0.5` |
 | Get names, not just IP addresses | `ipmg --input targets.txt --resolve` |
 | Get a report I can send to someone | `ipmg --input targets.txt --formats md csv` |
+| Pipe the results into a script | `ipmg --input targets.txt --json \| jq .` |
 | See hosts appear as they answer | `ipmg --input 192.168.1.0/24 --stream` |
 | See what changed since last time | `ipmg --input targets.txt --compare` |
 | Check which services are listening | `ipmg --input targets.txt --scan-ports` |
@@ -343,6 +345,21 @@ ipmg diff --fail-on-change            # exit 2 when anything changed (CI)
 ipmg history --limit 10               # list stored scans
 ```
 
+To hear about changes without watching the terminal, send them to Slack,
+Microsoft Teams, any JSON webhook, or email. Any `--notify-*` flag turns on
+`--compare`, and with `--interval` every pass that changes something alerts:
+
+```bash
+ipmg --input targets.txt --interval 15 --notify-slack        # URL from $IPMG_NOTIFY_SLACK
+ipmg --input targets.txt --notify-email ops@example.com --smtp-host smtp.example.com
+ipmg diff --notify-webhook https://ops.example.com/ipmg --notify-severity critical
+```
+
+Only changes at or above `--notify-severity` (default `warning`) trigger a
+notification. A notification that fails is reported but never fails the scan.
+Secrets such as webhook URLs and `IPMG_SMTP_PASSWORD` can come from environment
+variables; see [Notifications](docs/COMMANDS.md#notifications) for all of them.
+
 What counts as a change:
 
 | Change | Severity | Meaning |
@@ -375,6 +392,11 @@ source**, so file-based and `--discover` runs do not get mixed up. Pass
 | `--latency-threshold` | `5` | Minimum latency delta in ms |
 | `--latency-pct` | `25` | Minimum relative latency change |
 | `--fail-on-change` | off | `ipmg diff` exits 2 when changes are found |
+| `--notify-webhook` | off | POST the change report as JSON to a URL |
+| `--notify-slack` | off | Post changes to a Slack incoming webhook |
+| `--notify-teams` | off | Post changes to a Microsoft Teams Workflows webhook |
+| `--notify-email` | off | Email the Markdown change report (with `--smtp-host`, `--smtp-port`, `--smtp-security`, `--smtp-user`, `--smtp-from`) |
+| `--notify-severity` | `warning` | Only notify for changes at least this severe |
 
 ---
 
@@ -415,6 +437,14 @@ package, nothing is loaded from a CDN. It gives you:
 | `--no-browser` | off | Don't open the browser automatically |
 | `--db` | `~/.ipmg/dashboard.db` | History database location |
 
+### Scripting IPMG Web
+
+Everything the dashboard does goes through a documented, versioned REST API
+under `/api/v1`, so you can start scans, fetch results, and compare scans from
+your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/API.md)
+covers authentication, errors, and worked `curl` examples; the running server
+also serves interactive docs at `http://127.0.0.1:8080/docs`.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects
@@ -458,9 +488,32 @@ Anywhere IPMG takes `--input`, you can give it any of these:
   | 192.168.1.1 |
   | 10.0.1.0/30 |
 
-Duplicate targets are removed automatically, and one scan expands to at most
-65,536 hosts — larger CIDR blocks or ranges are rejected up front, before the
-scan starts.
+- **A JSON file** (`.json`) — a list of addresses, a list of objects keyed by
+  `IP Address`, `ip`, or `target`, or an object with a `targets` or `ips` array:
+
+  ```json
+  ["192.168.1.1", "10.0.1.0/30"]
+  ```
+
+  Because `IP Address` is one of the keys it accepts, a report IPMG wrote with
+  `--formats json` can be fed straight back in:
+
+  ```bash
+  ipmg --input results_20260628_120000.json
+  ```
+
+`--input` takes as many of these as you like, in any mix, and may also be
+repeated:
+
+```bash
+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
+```
+
+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
+combinations are rejected up front, before the scan starts.
 
 ---
 
@@ -510,6 +563,22 @@ preferring `jsonl` or `csv` (current to the last host) over `json` or `xlsx`
 (current to the last autosave). Hosts dropped from the target list since are
 left out of the finished report.
 
+**Piping results into a script.** `--json` prints the finished scan to stdout as
+a JSON array, and `--jsonl` prints one object per host the moment its probe
+finishes. The human output moves to stderr, so stdout is nothing but data and no
+temp file or glob is needed:
+
+```bash
+ipmg --input 10.0.0.0/24 --json | jq '.[] | select(.Status == "Active")'
+ipmg --input 10.0.0.0/24 --jsonl | while read -r host; do notify "$host"; done
+ipmg --input 10.0.0.0/24 --json 2>/dev/null > hosts.json   # data only
+```
+
+The field names are the report columns above, and both flags print a host
+identically — `--json` is what `--jsonl` prints, gathered into an array. Unless
+you ask for `--formats` explicitly, a piped scan writes no report file at all.
+Exit codes are unchanged.
+
 **Open ports.** `Open Ports` is only populated when `--scan-ports` is set: for
 each host that answers, IPMG probes a list of common TCP ports (SSH, HTTP,
 HTTPS, RDP, SMB, FTP, SMTP, DNS, MSSQL, MySQL, PostgreSQL by default)
@@ -526,6 +595,61 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 ---
 
+## Default options in a file
+
+If every run repeats the same flags, put them in **`ipmg.toml`** next to your
+work instead:
+
+```toml
+threads = 200
+timeout = 1
+resolve = true
+formats = ["md", "csv"]
+
+[profile.datacenter]
+threads = 400
+scan-ports = true
+ports = "22,80,443"
+```
+
+```bash
+ipmg --input targets.txt                        # uses the file's defaults
+ipmg --input targets.txt --profile datacenter   # and the profile on top
+ipmg --input targets.txt --threads 20           # a flag always wins
+```
+
+Any long flag can be a key, written as the flag is (`scan-ports`) or with
+underscores (`scan_ports`). A switch takes `true` to mean "as if the flag were
+passed" — `no-history = true` is `--no-history`. Files are read from
+`~/.config/ipmg/config.toml` first (or `$XDG_CONFIG_HOME`), then `./ipmg.toml`
+on top, so a project can override your global defaults:
+
+| Flag | What it does |
+| --- | --- |
+| `--config PATH` | Read that file instead of searching |
+| `--no-config` | Ignore every file and use the built-in defaults |
+| `--profile NAME` | Apply the `[profile.NAME]` section as well |
+
+**The command line always wins.** A flag that appears on it ignores the file
+entirely for that flag — including `--input`, which merges several sources on
+one command line but replaces the file's list rather than adding to it.
+
+A key that is not a flag, a value of the wrong type, or a value outside a
+flag's choices is an error naming the key and the file it came from:
+
+```text
+✗ Unknown option 'thredas' in ipmg.toml. Did you mean 'threads'?
+✗ 'formats' in ipmg.toml: 'pdf' is not one of xlsx, csv, json, jsonl, md.
+```
+
+A project's `./ipmg.toml` comes with whatever directory you scan from,
+including a repository you just cloned, so it cannot say where results are
+sent: the `--notify-*` destinations and `--smtp-*` settings are only read from
+`~/.config/ipmg/config.toml` or a file you pass with `--config`. A file also
+cannot combine flags that exclude each other, such as `json` and `jsonl`.
+
+---
+
 ## All options
 
 `ipmg --help` always lists the current set. Grouped for reading:
@@ -534,10 +658,12 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 | Flag | Default | Description |
 | --- | --- | --- |
-| `--input` | `ip_list.xlsx` | What to scan: a file (`.xlsx`, `.xls`, `.csv`, `.txt`, `.list`), a single IP, a CIDR block, or a range (`10.0.0.1-10.0.0.50`) |
+| `--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 |
 | `--output` | `results` | Report file name prefix |
-| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` |
+| `--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 |
+| `--jsonl` | off | Stream one JSON object per host to stdout as each probe finishes |
 | `--no-incremental` | off | Only write the report once the scan has finished |
 | `--autosave` | `30` | How often a running scan re-saves `xlsx`, `json`, and `md` |
 | `--resume` | off | Finish an interrupted scan from its partial report (newest one, or the path given) |
@@ -569,13 +695,25 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--stream-all` | off | Stream every result, including hosts that did not answer (implies `--stream`) |
 | `--stream-refresh` | `0.25` | Seconds between progress-bar redraws while streaming (0.05-5) |
 | `--verbose` | off | Debug logging |
+| `--config` | search | Read defaults from this file instead of searching for `ipmg.toml` |
+| `--no-config` | off | Ignore every configuration file |
+| `--profile` | none | Apply a `[profile.NAME]` section from the configuration file |
+
+**Exit status**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--fail-on-down` | off | Exit 3 if any target is not `Active` (reports are still written) |
+| `--min-active` | off | Exit 3 if fewer than this percentage of targets are `Active` |
 
 **History and changes** — see [Change detection](#change-detection) for
 `--compare`, `--no-history`, `--db`, `--diff-formats`, `--diff-output`,
-`--latency-threshold`, `--latency-pct`, and `--fail-on-change`.
+`--latency-threshold`, `--latency-pct`, `--fail-on-change`, and the
+`--notify-*` flags.
 
 Exit codes: `0` success, `1` error, `2` changes detected
-(`ipmg diff --fail-on-change`), `130` interrupted.
+(`ipmg diff --fail-on-change`), `3` hosts down (`--fail-on-down`,
+`--min-active`), `130` interrupted.
 
 ---
 
@@ -596,12 +734,15 @@ itself is hardened accordingly:
 - Uploads are capped at 5 MB and one scan expands to at most 65,536 hosts,
   so a bad input file cannot exhaust memory
 - All database access uses parameterized SQL
+- The only outbound requests IPMG makes are the notifications you ask for
+  with a `--notify-*` flag. Their URLs and the SMTP password can come from
+  environment variables, and error messages never repeat them
 
 If you bind to a non-local address with `--host`, the token still guards the
 API. It travels over plain HTTP, though, so use an SSH tunnel or a reverse
 proxy with TLS on any network you don't trust.
 
-Found a vulnerability? See [SECURITY.md](SECURITY.md) for how to report it.
+Found a vulnerability? See [SECURITY.md](.github/SECURITY.md) for how to report it.
 
 ---
 
@@ -610,6 +751,9 @@ Found a vulnerability? See [SECURITY.md](SECURITY.md) for how to report it.
 - **[Command reference](https://github.com/sameeralam3127/ipmg/blob/main/docs/COMMANDS.md)** —
   every command and flag with copy-paste examples, a safe session that tries
   everything on your own machine, exit codes, and error messages
+- **[Web API guide](https://github.com/sameeralam3127/ipmg/blob/main/docs/API.md)** —
+  script IPMG Web over HTTP: start scans, fetch results, compare scans,
+  and follow live events
 - **[Troubleshooting](https://github.com/sameeralam3127/ipmg/blob/main/docs/TROUBLESHOOTING.md)** —
   install errors, `command not found`, every host timing out, slow scans,
   rejected input files
@@ -623,11 +767,11 @@ Found a vulnerability? See [SECURITY.md](SECURITY.md) for how to report it.
 ## Contributing
 
 Contributions are welcome.
-[CONTRIBUTING.md](https://github.com/sameeralam3127/ipmg/blob/main/CONTRIBUTING.md)
+[CONTRIBUTING.md](https://github.com/sameeralam3127/ipmg/blob/main/.github/CONTRIBUTING.md)
 covers setting up a development environment, running the tests, the commit
 message format that drives automated releases, and how the project website and
 IPMG Web demo are built. Everyone taking part is expected to follow the
-[Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/CODE_OF_CONDUCT.md).
+[Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/.github/CODE_OF_CONDUCT.md).
 
 ---
 

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

@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipmg"
-version = "2.2.0"  # Managed automatically by semantic-release
+version = "2.4.0"  # Managed automatically by semantic-release
 description = "IP Management & Ping Monitoring CLI Tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -53,9 +53,13 @@ dependencies = [
     "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'",
 ]
 
 [project.urls]
@@ -109,6 +113,9 @@ commit_message = "chore(release): {version}"
 build_command = "python -m build"
 major_on_zero = false
 
+[tool.semantic_release.changelog.default_templates]
+changelog_file = ".github/CHANGELOG.md"
+
 
 # ==========================================================
 # Setuptools (src layout)

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

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

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

@@ -6,6 +6,7 @@ import logging
 import sys
 from typing import Callable, Dict, List, Optional
 
+from ipmg.cli import config
 from ipmg.cli.parser import (
     build_diff_parser,
     build_history_parser,
@@ -13,26 +14,37 @@ from ipmg.cli.parser import (
     build_web_parser,
 )
 from ipmg.core.diff import DiffOptions
+from ipmg.core.health import HostsDownError
 from ipmg.core.security import print_disclaimer_once
 from ipmg.exceptions import IPMGError
+from ipmg.infrastructure.notify import notify_options, send_notifications
 from ipmg.reporting import ui
 from ipmg.reporting.diff_report import export_diff, print_diff
 from ipmg.reporting.summary import print_scan_history
 from ipmg.services.history_service import HistoryService
-from ipmg.services.scan_service import run_scan
+from ipmg.services.scan_service import machine_output, run_scan
 from ipmg.utils.helpers import configure_logging
 
 EXIT_OK = 0
 EXIT_ERROR = 1
 EXIT_CHANGES_DETECTED = 2
+EXIT_HOSTS_DOWN = 3
 EXIT_INTERRUPTED = 130
 
 log = logging.getLogger(__name__)
 
 
 def _scan_command(argv: List[str]) -> int:
-    args = build_parser().parse_args(argv)
+    parser = build_parser()
+    # Before parsing: the file supplies the defaults, so anything on the
+    # command line still overrides it.
+    config.apply(parser, build_parser, argv)
+    args = parser.parse_args(argv)
     configure_logging(args.verbose)
+    if machine_output(args).enabled:
+        # Before the banner: with --json or --jsonl stdout carries the results
+        # and nothing else, so every line a person reads goes to stderr.
+        ui.use_stderr()
     ui.header("scan")
     print_disclaimer_once()
     run_scan(args)
@@ -77,6 +89,7 @@ def _diff_command(argv: List[str]) -> int:
         ui.error("Provide at most two scan ids: BASELINE TARGET.")
         return EXIT_ERROR
 
+    notify = notify_options(args)
     history = HistoryService.open(args.db)
     options = DiffOptions(
         latency_abs_ms=max(args.latency_threshold, 0.0),
@@ -93,6 +106,7 @@ def _diff_command(argv: List[str]) -> int:
     print_diff(diff, limit=args.limit)
     if args.diff_formats:
         export_diff(diff, args.diff_output, args.diff_formats)
+    send_notifications(diff, notify)
 
     if args.fail_on_change and diff.has_changes:
         return EXIT_CHANGES_DETECTED
@@ -134,6 +148,12 @@ def run(argv: Optional[List[str]] = None) -> int:
 
     try:
         return handler(handler_argv)
+    except HostsDownError as exc:
+        # Not an error: the scan finished and wrote its reports, but failed
+        # the check it was asked to make.
+        ui.blank()
+        ui.warn(str(exc))
+        return EXIT_HOSTS_DOWN
     except IPMGError as exc:
         ui.blank()
         ui.error(str(exc))