diff --git a/README.md b/README.md index d157404..961604e 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,8 @@ flood can delay or hide a real attacker that appears only once. The limit resets An alert fires when an IP's flag enters the alert set (`--alert-on`, default `veneer,paradox,threat`) or changes, not on every sighting. Alerts go to stdout (one JSON object per line with `--json`) and, with a webhook, are POSTed as JSON. Set the URL as `PARADOX_WEBHOOK`, in `.env` for instance: it works like a -password for its channel, and `--webhook` puts it in process listings and shell history. `--webhook` wins if both are set. The payload's `text` field works +password for its channel, and `--webhook` puts it in process listings and shell history. `--webhook` wins if both are set. It must be `https://`, or `http://` on +loopback; `PARADOX_WEBHOOK_ALLOW_HTTP=1` allows other `http://` URLs, for a trusted network. The payload's `text` field works as-is with Slack and Mattermost incoming webhooks. Log lines are untrusted and can hold private details, so the `sample` line appears only in `--json` stdout, never in `text` or a webhook post. `docker stop` and Ctrl+C shut it down cleanly. It exits 1 if anything alerted. diff --git a/ROADMAP.md b/ROADMAP.md index 82a7291..0108552 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -422,9 +422,9 @@ third party. The URL works like a password for its channel, and on the command line it shows up in process listings and shell history. -### 4.9 Refuse unencrypted webhooks · S +### 4.9 Refuse unencrypted webhooks · S · ✅ shipped -- [ ] **PDX-36: Refuse `http://` webhooks.** Done when: the watcher refuses to start with a non-HTTPS webhook unless it points at loopback or an explicit override is set, with tests for each case. +- [x] **PDX-36: Refuse `http://` webhooks.** Done when: the watcher refuses to start with a non-HTTPS webhook unless it points at loopback or an explicit override is set, with tests for each case. ### 4.10 Warn about a loose `.env` · S @@ -551,7 +551,7 @@ and fix the top issues. Repeat after 5.6. It also doubles as class material. | When | Items | Why first | |---|---|---| | Now | ~~1.1, 1.2, 1.5, 3.2, 5.1~~ (done) | Small, keyless, and fix the biggest measured weakness (the scanner rule's dependence on GreyNoise); 5.1 makes that dependence visible | -| Next | 1.3, 3.1, 3.5, 3.6, 4.1, 4.9, 4.10, ~~4.6, 4.7, 4.8, 4.5, 1.7, 1.8, 3.7, 1.4, 1.6, 5.2, 5.4~~ (done) | Close the known false positives, build adversarial and hiding-place test sets, test the AI summarizer under attack, and show watch state and claim checks in the UI | +| Next | 1.3, 3.1, 3.5, 3.6, 4.1, 4.10, ~~4.6, 4.7, 4.8, 4.9, 4.5, 1.7, 1.8, 3.7, 1.4, 1.6, 5.2, 5.4~~ (done) | Close the known false positives, build adversarial and hiding-place test sets, test the AI summarizer under attack, and show watch state and claim checks in the UI | | Then | 2.1, 2.3, 3.3, 3.4, 4.2, ~~4.3, 4.4~~ (done), 5.3, 5.5–5.7 | New unmasking signals plus self-measurement once history has accumulated, with the UI restructured to hold them | | Later | 2.2, 2.4, 2.5 | Bigger extensions: domains, campaigns, more beacons | diff --git a/SECURITY.md b/SECURITY.md index 763cca2..631610c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -102,6 +102,8 @@ more than people expect. - The Slack-compatible `text` field holds only the flag, IP, scores and verdict. The raw `sample` log line is removed from everything posted, and appears only in `--json` stdout on your own machine. +- The watcher won't start with a webhook that isn't `https://` or `http://` on loopback, and the refusal doesn't quote + the URL. - Webhooks are opt-in, and a failed post is reported on stderr without stopping the watcher. **Open:** @@ -110,7 +112,8 @@ more than people expect. - `text` can quote a third-party label in the verdict, so a chat channel or bot reading it sees attacker-influenced text. - The URL is effectively a password for its channel. `PARADOX_WEBHOOK` keeps it off the command line, but `--webhook` still works and would show it in process listings and shell history. -- Nothing stops an `http://` URL, which would send alerts unencrypted. +- `PARADOX_WEBHOOK_ALLOW_HTTP=1` allows unencrypted posts when someone sets it, and a server's redirect is followed + without this check. ## `.env` handling diff --git a/paradox/cli.py b/paradox/cli.py index 77496ee..32a7901 100644 --- a/paradox/cli.py +++ b/paradox/cli.py @@ -179,14 +179,18 @@ def cmd_log(args) -> int: def cmd_watch(args) -> int: - from .watch import Watcher + from .watch import Watcher, webhook_problem alert_on = [f.strip() for f in args.alert_on.split(",") if f.strip()] bad = set(alert_on) - {"veneer", "paradox", "threat", "watch"} if bad: print(f"error: unknown --alert-on flag(s): {', '.join(sorted(bad))}", file=sys.stderr) return 2 + webhook = args.webhook or config.key("PARADOX_WEBHOOK") + if webhook and (problem := webhook_problem(webhook)): + print(f"error: {problem}", file=sys.stderr) + return 2 w = Watcher(min_hits=args.min_hits, rescan_after_h=args.rescan_after, alert_on=alert_on, - workers=args.workers, webhook=args.webhook or config.key("PARADOX_WEBHOOK"), as_json=args.json, max_new_per_hour=args.max_new_per_hour) + workers=args.workers, webhook=webhook, as_json=args.json, max_new_per_hour=args.max_new_per_hour) return w.run(args.log or [], from_start=args.from_start, rescan_every_h=args.rescan_every) diff --git a/paradox/env.example b/paradox/env.example index 39ba785..39cd334 100644 --- a/paradox/env.example +++ b/paradox/env.example @@ -20,6 +20,7 @@ ANTHROPIC_API_KEY= # Watcher # PARADOX_WEBHOOK=https://hooks.slack.com/services/... # where paradox watch posts alerts +# PARADOX_WEBHOOK_ALLOW_HTTP=1 # allow an unencrypted http:// webhook # Web server # PARADOX_HOST=127.0.0.1 # 0.0.0.0 to listen on all interfaces (requires PARADOX_PASSWORD) diff --git a/paradox/watch.py b/paradox/watch.py index 31d3175..a4fa378 100644 --- a/paradox/watch.py +++ b/paradox/watch.py @@ -27,8 +27,10 @@ from collections import deque from datetime import datetime, timezone from typing import Callable, Iterator, TextIO +from urllib.parse import urlsplit from . import engine, history, logscan +from .server import is_loopback DEFAULT_ALERTS = ("veneer", "paradox", "threat") DEFAULT_MAX_NEW = 15 # new IPs scanned an hour: 360 a day, inside VirusTotal's 500 with room for rescans @@ -100,6 +102,18 @@ def stream(src: TextIO, stop: threading.Event) -> Iterator[str]: yield line +def webhook_problem(url: str) -> str | None: + """Why this URL can't be used, or None. Never quotes the URL, which works like a password.""" + parts = urlsplit(url) + if parts.scheme == "https" and parts.hostname: + return None + if parts.scheme != "http" or not parts.hostname: + return "the webhook must be an https:// URL" + if is_loopback(parts.hostname) or os.environ.get("PARADOX_WEBHOOK_ALLOW_HTTP") == "1": + return None + return "the webhook is http://, which would send alerts unencrypted; use https://, or set PARADOX_WEBHOOK_ALLOW_HTTP=1" + + class Watcher: def __init__(self, *, min_hits: int = 1, rescan_after_h: float = 24, alert_on=DEFAULT_ALERTS, workers: int = logscan.DEFAULT_WORKERS, webhook: str | None = None, as_json: bool = False, diff --git a/tests/test_app.py b/tests/test_app.py index 65550dd..6a5b0ed 100644 --- a/tests/test_app.py +++ b/tests/test_app.py @@ -44,6 +44,29 @@ def test_webhook_url_comes_from_the_environment_and_the_flag_wins(self): self.assertEqual(self.watch_webhook("--webhook", "https://example.test/flag", env=env), "https://example.test/flag") self.assertIsNone(self.watch_webhook()) + def test_webhook_schemes(self): + with mock.patch.dict(os.environ): + os.environ.pop("PARADOX_WEBHOOK_ALLOW_HTTP", None) + for ok in ("https://example.test/x", "http://localhost:9/x", "http://127.0.0.1:9/x", "http://[::1]:9/x"): + self.assertIsNone(watch.webhook_problem(ok), ok) + for bad in ("http://example.test/secret", "http://127.0.0.1.example.test/secret", "file:///etc/secret", + "ftp://example.test/secret", "https:///secret", "secret"): + problem = watch.webhook_problem(bad) + self.assertTrue(problem, bad) + self.assertNotIn("secret", problem) + os.environ["PARADOX_WEBHOOK_ALLOW_HTTP"] = "1" + self.assertIsNone(watch.webhook_problem("http://example.test/x")) + self.assertTrue(watch.webhook_problem("file:///etc/secret")) # the override is for http only + + def test_watcher_wont_start_with_an_unencrypted_webhook(self): + with mock.patch.dict(os.environ, {"PARADOX_WEBHOOK": "http://example.test/secret"}), \ + mock.patch.object(watch, "Watcher") as w, mock.patch("sys.stderr", io.StringIO()) as err: + os.environ.pop("PARADOX_WEBHOOK_ALLOW_HTTP", None) + self.assertEqual(cli.main(["watch", "--log", "a"]), 2) + w.assert_not_called() + self.assertIn("unencrypted", err.getvalue()) + self.assertNotIn("secret", err.getvalue()) + def test_scan_exit_status_reflects_findings(self): def run(score): with mock.patch.object(cli, "scan", return_value={"ip": "45.1.1.1", "score": score}), \