check-opencloud-security 1.2.2__tar.gz → 1.2.3__tar.gz

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/CHANGELOG.md

@@ -12,6 +12,14 @@ entry to `RELEASE.md` and uses it as the body of the GitHub release.
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-08-13
+
+### Security
+
+- Block webhook notifications to private, loopback, and link-local addresses
+  by default to prevent server-side request forgery. Internal receivers require
+  the explicit `--allow-private-webhooks` / `COS_ALLOW_PRIVATE_WEBHOOKS` opt-out.
+
 ## [1.2.2] - 2026-08-13
 
 ### Documentation

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: check-opencloud-security
-Version: 1.2.2
+Version: 1.2.3
 Summary: Check the security level of your OpenCloud instance with a built-in scanner - no API access required
 Author: Massoud Ahmed
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -1194,6 +1194,7 @@ check-opencloud-security --host <Hostname> --check-hardening
 | `--webhook-on`      | Lowest state that triggers the webhook (`critical`, `warning`, `unknown`, `always`) | `critical` | `COS_WEBHOOK_ON` |
 | `--webhook-header`  | Extra header for the webhook request, repeatable       | *None*       | `COS_WEBHOOK_HEADERS` |
 | `--webhook-timeout` | HTTP timeout in seconds for the webhook call           | `10`         | `COS_WEBHOOK_TIMEOUT` |
+| `--allow-private-webhooks` | Permit webhooks to private, loopback, or link-local addresses | *False* | `COS_ALLOW_PRIVATE_WEBHOOKS` |
 | `--retries`         | Retry attempts for transient network errors            | `2`          | `COS_RETRIES`         |
 | `--backoff-factor`  | Exponential backoff factor (seconds) between retries   | `0.5`        | `COS_BACKOFF_FACTOR`  |
 | `--config`          | Path to the configuration file (`.json` as JSON, else YAML) | auto-discovered | `COS_CONFIG_FILE`  |
@@ -1979,6 +1980,10 @@ check-opencloud-security --host opencloud.example.com \
   environment variable: `COS_WEBHOOK_HEADERS="X-Auth-Token: abc; X-Env: prod"`.
 - `--webhook-timeout` / `COS_WEBHOOK_TIMEOUT` (default `10`) limits the
   webhook call; it is independent of the scan `--timeout`.
+- Webhook destinations that resolve to private, loopback, or link-local
+  addresses are blocked to prevent server-side request forgery. Set
+  `--allow-private-webhooks` or `COS_ALLOW_PRIVATE_WEBHOOKS=true` only for an
+  intentional internal receiver.
 
 Delivery reuses `--retries` / `--backoff-factor`. **A failing webhook never
 changes the check result** - the plugin appends `Webhook delivery failed` to

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/README.md

@@ -505,6 +505,7 @@ check-opencloud-security --host <Hostname> --check-hardening
 | `--webhook-on`      | Lowest state that triggers the webhook (`critical`, `warning`, `unknown`, `always`) | `critical` | `COS_WEBHOOK_ON` |
 | `--webhook-header`  | Extra header for the webhook request, repeatable       | *None*       | `COS_WEBHOOK_HEADERS` |
 | `--webhook-timeout` | HTTP timeout in seconds for the webhook call           | `10`         | `COS_WEBHOOK_TIMEOUT` |
+| `--allow-private-webhooks` | Permit webhooks to private, loopback, or link-local addresses | *False* | `COS_ALLOW_PRIVATE_WEBHOOKS` |
 | `--retries`         | Retry attempts for transient network errors            | `2`          | `COS_RETRIES`         |
 | `--backoff-factor`  | Exponential backoff factor (seconds) between retries   | `0.5`        | `COS_BACKOFF_FACTOR`  |
 | `--config`          | Path to the configuration file (`.json` as JSON, else YAML) | auto-discovered | `COS_CONFIG_FILE`  |
@@ -1290,6 +1291,10 @@ check-opencloud-security --host opencloud.example.com \
   environment variable: `COS_WEBHOOK_HEADERS="X-Auth-Token: abc; X-Env: prod"`.
 - `--webhook-timeout` / `COS_WEBHOOK_TIMEOUT` (default `10`) limits the
   webhook call; it is independent of the scan `--timeout`.
+- Webhook destinations that resolve to private, loopback, or link-local
+  addresses are blocked to prevent server-side request forgery. Set
+  `--allow-private-webhooks` or `COS_ALLOW_PRIVATE_WEBHOOKS=true` only for an
+  intentional internal receiver.
 
 Delivery reuses `--retries` / `--backoff-factor`. **A failing webhook never
 changes the check result** - the plugin appends `Webhook delivery failed` to

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/check_opencloud_security.py

@@ -16,6 +16,7 @@ import contextlib
 import io
 import ipaddress
 import logging
+import socket
 import sys
 import time
 from collections import Counter
@@ -24,6 +25,7 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from enum import IntEnum
 from typing import Any, NoReturn, TypeVar
+from urllib.parse import urlsplit
 
 import requests
 
@@ -146,6 +148,7 @@ class ScanContext:
     webhook_url: str | None = None
     webhook_on: str = DEFAULT_WEBHOOK_ON
     webhook_timeout: int = DEFAULT_WEBHOOK_TIMEOUT_SECONDS
+    allow_private_webhooks: bool = False
     # Stored as a tuple of pairs so ScanContext stays hashable/frozen.
     webhook_headers: tuple[tuple[str, str], ...] = ()
     scanner_settings: ScannerSettings | None = None
@@ -196,6 +199,17 @@ def _env_bool(name: str) -> bool:
     return _CONFIG.get_bool(name)
 
 
+def _allow_private_webhooks_default() -> bool:
+    """Read the webhook opt-out from its public environment or nested config key."""
+    name = "ALLOW_PRIVATE_WEBHOOKS"
+    if any(
+        f"{ENV_PREFIX}{suffix}" in _CONFIG.environ
+        for suffix in (name, f"{name}_FILE")
+    ):
+        return _env_bool(name)
+    return _env_bool(f"WEBHOOK_{name}")
+
+
 def _waiver_patterns(values: list[str] | None) -> tuple[str, ...] | None:
     """
     Split repeated --ignore-hardening values into a flat list of patterns.
@@ -633,6 +647,12 @@ def _send_webhook(context: ScanContext, payload: dict[str, Any]) -> bool:
     url = context.webhook_url
     if not url:
         return True
+    if not context.allow_private_webhooks and not _is_safe_webhook_url(url):
+        LOGGER.warning(
+            "Webhook URL points to a restricted private/local IP address and was blocked: %s",
+            url,
+        )
+        return False
 
     headers = {"Content-Type": "application/json"}
     headers.update(dict(context.webhook_headers))
@@ -665,6 +685,18 @@ def _send_webhook(context: ScanContext, payload: dict[str, Any]) -> bool:
     return True
 
 
+def _is_safe_webhook_url(url: str) -> bool:
+    """Return whether url resolves to an address that is safe for a webhook."""
+    try:
+        hostname = urlsplit(url).hostname
+        if not hostname:
+            return False
+        address = ipaddress.ip_address(socket.gethostbyname(hostname))
+    except (ValueError, socket.gaierror):
+        return False
+    return not (address.is_private or address.is_loopback or address.is_link_local)
+
+
 def _notify_and_fail(
     context: ScanContext,
     message: str,
@@ -1339,6 +1371,15 @@ def build_arg_parser() -> argparse.ArgumentParser:
             f"Default: {DEFAULT_WEBHOOK_TIMEOUT_SECONDS} (env: {ENV_PREFIX}WEBHOOK_TIMEOUT)."
         ),
     )
+    parser.add_argument(
+        "--allow-private-webhooks",
+        action="store_true",
+        default=_allow_private_webhooks_default(),
+        help=(
+            "Allow webhooks to private, loopback, and link-local addresses. "
+            f"Default: False (env: {ENV_PREFIX}ALLOW_PRIVATE_WEBHOOKS)."
+        ),
+    )
     parser.add_argument(
         "--backoff-factor",
         type=float,
@@ -1495,6 +1536,7 @@ def _build_context(host: str, args: argparse.Namespace) -> ScanContext:
         webhook_url=args.webhook_url,
         webhook_on=args.webhook_on,
         webhook_timeout=args.webhook_timeout,
+        allow_private_webhooks=args.allow_private_webhooks,
         webhook_headers=_parse_webhook_headers(args.webhook_header),
         scanner_settings=scanner_settings,
         release_settings=release_settings,

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/opencloud_local_scan/wizard.py

@@ -334,6 +334,19 @@ def optional_groups() -> list[Group]:
                     example="X-Auth-Token: s3cr3t; X-Env: prod",
                     secret=True,
                 ),
+                Question(
+                    key="webhook.allow_private_webhooks",
+                    prompt="Allow private webhook addresses",
+                    explain=(
+                        "Permit delivery to private, loopback, or link-local "
+                        "addresses. Leave this off unless the receiver is an "
+                        "intentional internal service."
+                    ),
+                    example="no",
+                    default="no",
+                    validate=_choice(tuple(YES | NO)),
+                    cast=lambda value: value.strip().lower() in YES,
+                ),
             ],
         ),
         Group(

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "check-opencloud-security"
-version = "1.2.2"
+version = "1.2.3"
 description = "Check the security level of your OpenCloud instance with a built-in scanner - no API access required"
 authors = [{ name = "Massoud Ahmed" }]
 requires-python = ">=3.10"

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/tests/test_env_config.py

@@ -67,6 +67,7 @@ def test_boolean_flags_are_read_from_the_environment(monkeypatch, reload_plugin)
     monkeypatch.setenv("COS_INSECURE", "yes")
     monkeypatch.setenv("COS_UPDATE_WARNING", "1")
     monkeypatch.setenv("COS_NO_DEBUG_PORTS", "on")
+    monkeypatch.setenv("COS_ALLOW_PRIVATE_WEBHOOKS", "true")
 
     module = reload_plugin()
     args = module.build_arg_parser().parse_args([])
@@ -75,6 +76,7 @@ def test_boolean_flags_are_read_from_the_environment(monkeypatch, reload_plugin)
     assert args.insecure is True
     assert args.update_warning is True
     assert args.no_debug_ports is True
+    assert args.allow_private_webhooks is True
 
 
 @pytest.mark.parametrize("value", ["false", "no", "0", "off", ""])
@@ -161,6 +163,8 @@ def test_config_file_supplies_defaults(monkeypatch, reload_plugin, tmp_path):
         "host: cloud.example.com\n"
         "warning: 4\n"
         "check_hardening: true\n"
+        "webhook:\n"
+        "  allow_private_webhooks: true\n"
         "scanner:\n"
         "  timeout: 25\n"
         "releases:\n"
@@ -178,6 +182,7 @@ def test_config_file_supplies_defaults(monkeypatch, reload_plugin, tmp_path):
     context = module._build_context("cloud.example.com", args)
     assert context.scanner_settings.timeout == 25
     assert context.release_settings.mode == "bundled"
+    assert context.allow_private_webhooks is True
 
 
 def test_environment_beats_the_config_file(monkeypatch, reload_plugin, tmp_path):

{check_opencloud_security-1.2.2 → check_opencloud_security-1.2.3}/tests/test_webhook.py

@@ -46,7 +46,7 @@ def posts(monkeypatch):
 
 def run(result, **kwargs):
     """Run the check and return its exit code."""
-    context = ScanContext(host="cloud.example.com", **kwargs)
+    context = ScanContext(host="cloud.example.com", allow_private_webhooks=True, **kwargs)
     with pytest.raises(SystemExit) as excinfo:
         plugin.check_vulnerabilities(
             context, ScanResult(response=result, uuid="local-x"), duration_seconds=1.0
@@ -61,6 +61,11 @@ def test_no_webhook_url_means_no_request(posts):
     assert posts == []
 
 
+def test_private_webhook_protection_is_enabled_by_default():
+    """Webhook destinations must be protected unless an operator opts out."""
+    assert ScanContext(host="cloud.example.com").allow_private_webhooks is False
+
+
 def test_critical_result_fires_the_webhook(posts):
     """The default trigger is 'critical'."""
     run(CRITICAL_RESULT, webhook_url="https://hooks.example.com/x")
@@ -172,6 +177,7 @@ def test_webhook_fires_for_an_unreachable_instance(posts, monkeypatch):
         host="down.example.com",
         webhook_url="https://x/",
         webhook_on="unknown",
+        allow_private_webhooks=True,
         scanner_settings=None,
     )
 
@@ -196,3 +202,63 @@ def test_webhook_uses_the_configured_proxy(posts):
         "http": "http://proxy:3128",
         "https": "http://proxy:3128",
     }
+
+
+def test_private_webhook_addresses_are_blocked(monkeypatch, caplog):
+    """A webhook must not be usable to reach internal services by default."""
+    posted = []
+    monkeypatch.setattr(plugin.socket, "gethostbyname", lambda hostname: "127.0.0.1")
+    monkeypatch.setattr(
+        plugin.requests,
+        "post",
+        lambda *args, **kwargs: posted.append((args, kwargs)),
+    )
+
+    sent = plugin._send_webhook(
+        ScanContext(host="cloud.example.com", webhook_url="https://hooks.example.com/x"),
+        {"status": "CRITICAL"},
+    )
+
+    assert sent is False
+    assert posted == []
+    assert "restricted private/local IP address" in caplog.text
+
+
+def test_private_webhooks_require_an_explicit_opt_out(monkeypatch):
+    """An intentional internal receiver remains available with an opt-out."""
+    posted = []
+    monkeypatch.setattr(plugin.socket, "gethostbyname", lambda hostname: "127.0.0.1")
+
+    class _Response:
+        def raise_for_status(self):
+            pass
+
+    monkeypatch.setattr(
+        plugin.requests,
+        "post",
+        lambda url, **kwargs: posted.append((url, kwargs)) or _Response(),
+    )
+
+    sent = plugin._send_webhook(
+        ScanContext(
+            host="cloud.example.com",
+            webhook_url="https://hooks.example.com/x",
+            allow_private_webhooks=True,
+        ),
+        {"status": "CRITICAL"},
+    )
+
+    assert sent is True
+    assert posted[0][0] == "https://hooks.example.com/x"
+
+
+@pytest.mark.parametrize("url", ["not a URL", "https://unresolvable.example.com/x"])
+def test_invalid_or_unresolvable_webhook_urls_are_blocked(monkeypatch, url):
+    """A malformed or unresolvable destination must fail closed."""
+    monkeypatch.setattr(
+        plugin.socket,
+        "gethostbyname",
+        lambda hostname: (_ for _ in ()).throw(plugin.socket.gaierror()),
+    )
+
+    assert plugin._is_safe_webhook_url(url) is False