ipmg 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 2.2.0
+Version: 2.3.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -33,6 +33,7 @@ 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
@@ -390,6 +391,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 +438,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 +483,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
@@ -617,12 +646,21 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--stream-refresh` | `0.25` | Seconds between progress-bar redraws while streaming (0.05-5) |
 | `--verbose` | off | Debug logging |
 
+**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 +681,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 +698,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 +714,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.3.0}/README.md

@@ -343,6 +343,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 +390,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 +435,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
@@ -570,12 +598,21 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--stream-refresh` | `0.25` | Seconds between progress-bar redraws while streaming (0.05-5) |
 | `--verbose` | off | Debug logging |
 
+**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 +633,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 +650,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 +666,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.3.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.3.0"  # Managed automatically by semantic-release
 description = "IP Management & Ping Monitoring CLI Tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -53,6 +53,7 @@ dependencies = [
     "openpyxl>=3.1",
     "rich>=13.0",
     "fastapi>=0.110",
+    "pydantic>=2.7",
     "uvicorn>=0.27",
     "websockets>=12",
     "python-multipart>=0.0.9",
@@ -109,6 +110,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.3.0}/src/ipmg/__init__.py

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

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

@@ -13,8 +13,10 @@ 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
@@ -25,6 +27,7 @@ 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__)
@@ -77,6 +80,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 +97,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 +139,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))

{ipmg-2.2.0 → ipmg-2.3.0}/src/ipmg/cli/parser.py

@@ -13,6 +13,16 @@ from ipmg.infrastructure.incremental import (
     MIN_AUTOSAVE_S,
     REPORT_FORMATS,
 )
+from ipmg.infrastructure.notify import (
+    DEFAULT_NOTIFY_SEVERITY,
+    ENV_EMAIL,
+    ENV_SLACK,
+    ENV_SMTP_PASSWORD,
+    ENV_TEAMS,
+    ENV_WEBHOOK,
+    NOTIFY_SEVERITIES,
+    SMTP_SECURITY,
+)
 from ipmg.reporting.diff_report import DIFF_FORMATS
 from ipmg.reporting.live import DEFAULT_REFRESH_S, MAX_REFRESH_S, MIN_REFRESH_S
 
@@ -43,6 +53,16 @@ def _port_list(value: str) -> tuple:
         raise argparse.ArgumentTypeError(str(exc)) from exc
 
 
+def _percent(value: str) -> float:
+    try:
+        percent = float(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"invalid percentage: {value!r}") from None
+    if not 0 <= percent <= 100:
+        raise argparse.ArgumentTypeError(f"percentage out of range (0-100): {value}")
+    return percent
+
+
 def _add_database_argument(parser) -> None:
     parser.add_argument(
         "--db",
@@ -87,6 +107,84 @@ def _add_diff_export_arguments(parser) -> None:
     )
 
 
+def _add_notify_arguments(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_argument_group(
+        "change notifications",
+        "Send the change report when a comparison finds changes. Each URL flag may be "
+        "given without a value to read it from its environment variable, which keeps "
+        "webhook secrets out of the process list and your crontab.",
+    )
+    group.add_argument(
+        "--notify-webhook",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="URL",
+        help=f"POST the change report as JSON to URL (or ${ENV_WEBHOOK}).",
+    )
+    group.add_argument(
+        "--notify-slack",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="URL",
+        help=f"Post the changes to a Slack incoming webhook (or ${ENV_SLACK}).",
+    )
+    group.add_argument(
+        "--notify-teams",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="URL",
+        help=f"Post the changes to a Microsoft Teams Workflows webhook (or ${ENV_TEAMS}).",
+    )
+    group.add_argument(
+        "--notify-email",
+        nargs="*",
+        default=None,
+        metavar="ADDRESS",
+        help=(
+            "Email the Markdown change report to these addresses "
+            f"(or the comma-separated ${ENV_EMAIL}). Needs --smtp-host."
+        ),
+    )
+    group.add_argument(
+        "--notify-severity",
+        choices=NOTIFY_SEVERITIES,
+        default=DEFAULT_NOTIFY_SEVERITY,
+        help=(
+            "Only notify when a change is at least this severe "
+            f"(default: {DEFAULT_NOTIFY_SEVERITY})."
+        ),
+    )
+    group.add_argument(
+        "--smtp-host",
+        metavar="HOST",
+        help="Mail server for --notify-email (or $IPMG_SMTP_HOST).",
+    )
+    group.add_argument(
+        "--smtp-port",
+        type=int,
+        metavar="PORT",
+        help="Mail server port (or $IPMG_SMTP_PORT; default: 587, 465 with ssl, 25 with none).",
+    )
+    group.add_argument(
+        "--smtp-security",
+        choices=SMTP_SECURITY,
+        help="How to encrypt the mail connection (or $IPMG_SMTP_SECURITY; default: starttls).",
+    )
+    group.add_argument(
+        "--smtp-user",
+        metavar="USER",
+        help=f"Mail server login (or $IPMG_SMTP_USER). The password is read from ${ENV_SMTP_PASSWORD}.",
+    )
+    group.add_argument(
+        "--smtp-from",
+        metavar="ADDRESS",
+        help="Sender address (or $IPMG_SMTP_FROM; default: the login, else ipmg@<this host>).",
+    )
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = ScanParser(
         prog="ipmg",
@@ -178,6 +276,20 @@ def build_parser() -> argparse.ArgumentParser:
         help="Start IPMG Web, the local browser UI (same as 'ipmg web').",
     )
 
+    checks = parser.add_argument_group("exit status (for cron and monitoring)")
+    checks.add_argument(
+        "--fail-on-down",
+        action="store_true",
+        help="Exit with status 3 if any target is not Active. Reports are still written.",
+    )
+    checks.add_argument(
+        "--min-active",
+        type=_percent,
+        default=None,
+        metavar="PERCENT",
+        help="Exit with status 3 if fewer than PERCENT of the targets are Active (0-100).",
+    )
+
     ports_group = parser.add_argument_group("TCP service discovery")
     ports_group.add_argument(
         "--scan-ports",
@@ -264,7 +376,10 @@ def build_parser() -> argparse.ArgumentParser:
     history.add_argument(
         "--compare",
         action="store_true",
-        help="Compare this scan against the previous one and print a change report.",
+        help=(
+            "Compare this scan against the previous one and print a change report "
+            "(implied by any --notify-* flag)."
+        ),
     )
     history.add_argument(
         "--compare-any-source",
@@ -274,6 +389,7 @@ def build_parser() -> argparse.ArgumentParser:
     _add_database_argument(history)
     _add_diff_export_arguments(history)
     _add_diff_threshold_arguments(parser)
+    _add_notify_arguments(parser)
     parser.set_defaults(history=True)
     return parser
 
@@ -363,5 +479,6 @@ def build_diff_parser() -> argparse.ArgumentParser:
     _add_database_argument(parser)
     _add_diff_export_arguments(parser)
     _add_diff_threshold_arguments(parser)
+    _add_notify_arguments(parser)
     parser.add_argument("--verbose", action="store_true")
     return parser

{ipmg-2.2.0 → ipmg-2.3.0}/src/ipmg/core/diff.py

@@ -48,6 +48,12 @@ _SEVERITY_BY_TYPE: Dict[ChangeType, Severity] = {
 
 _SEVERITY_RANK = {Severity.CRITICAL: 0, Severity.WARNING: 1, Severity.INFO: 2}
 
+
+def meets_severity(severity: Severity, minimum: Severity) -> bool:
+    """Whether ``severity`` is at least as serious as ``minimum``."""
+    return _SEVERITY_RANK[severity] <= _SEVERITY_RANK[minimum]
+
+
 _TYPE_RANK = {change_type: index for index, change_type in enumerate(ChangeType)}
 
 CHANGE_LABELS: Dict[ChangeType, str] = {

ipmg-2.3.0/src/ipmg/core/health.py

@@ -0,0 +1,64 @@
+"""Pass/fail checks on a finished scan, for cron jobs and monitoring probes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from ipmg.core.diff import ip_sort_key
+from ipmg.core.engine import HostResult
+from ipmg.exceptions import IPMGError
+
+ACTIVE_STATUS = "Active"
+
+#: How many down hosts a failure message names before it summarises the rest.
+MAX_NAMED_HOSTS = 5
+
+
+class HostsDownError(IPMGError):
+    """Raised after a finished scan fails --fail-on-down or --min-active."""
+
+
+@dataclass(frozen=True)
+class HealthPolicy:
+    """When a scan counts as failed. The default policy never fails."""
+
+    #: Fail if any target is not ``Active``.
+    fail_on_down: bool = False
+    #: Fail if fewer than this percentage of targets are ``Active``.
+    min_active_pct: Optional[float] = None
+
+    @property
+    def enabled(self) -> bool:
+        return self.fail_on_down or self.min_active_pct is not None
+
+
+def _name_hosts(ips: Sequence[str]) -> str:
+    # Results arrive in completion order; the message should read like the target list.
+    ips = sorted(ips, key=ip_sort_key)
+    named = ", ".join(ips[:MAX_NAMED_HOSTS])
+    hidden = len(ips) - MAX_NAMED_HOSTS
+    return f"{named} and {hidden} more" if hidden > 0 else named
+
+
+def _format_pct(value: float) -> str:
+    return f"{value:.1f}".rstrip("0").rstrip(".") + "%"
+
+
+def check_health(results: Sequence[HostResult], policy: HealthPolicy) -> Optional[str]:
+    """Why ``results`` fail ``policy``, or None when they pass."""
+    if not policy.enabled:
+        return None
+
+    total = len(results)
+    down = [result.ip for result in results if result.status != ACTIVE_STATUS]
+    active_pct = (total - len(down)) / total * 100 if total else 0.0
+
+    if policy.min_active_pct is not None and active_pct < policy.min_active_pct:
+        return (
+            f"Only {_format_pct(active_pct)} of {total} hosts are active, "
+            f"below --min-active {_format_pct(policy.min_active_pct)}."
+        )
+    if policy.fail_on_down and down:
+        return f"{len(down)} of {total} hosts are not active: {_name_hosts(down)}."
+    return None

{ipmg-2.2.0 → ipmg-2.3.0}/src/ipmg/exceptions.py

@@ -27,3 +27,7 @@ class ReportError(IPMGError):
 
 class HistoryError(IPMGError):
     """Raised when scan history cannot be stored, read, or compared."""
+
+
+class NotifyError(IPMGError):
+    """Raised when change notifications are configured incorrectly."""