diff --git a/README.md b/README.md index e5a6a64..d157404 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ so a busy log doesn't hammer the beacons. ```bash paradox watch --log /var/log/auth.log --log /var/log/nginx/access.log -paradox watch --log /var/log/auth.log --json --webhook https://hooks.slack.com/services/... +PARADOX_WEBHOOK=https://hooks.slack.com/services/... paradox watch --log /var/log/auth.log --json journalctl -fu sshd | paradox watch --log - paradox watch --rescan-every 6 # no logs: keep tracked IPs fresh (replaces cron) ``` @@ -83,7 +83,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 `--webhook`, are POSTed as JSON. The payload's `text` field works +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 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 1a0bffb..82a7291 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -416,9 +416,9 @@ third party. *Downside:* a receiver that read `alert.sample` no longer gets it. `--json` stdout still has it for local use. -### 4.8 Webhook URL out of the command line · S +### 4.8 Webhook URL out of the command line · S · ✅ shipped -- [ ] **PDX-35: Read the webhook URL from the environment.** Done when: `PARADOX_WEBHOOK` sets the URL, a test shows it's used without `--webhook`, and the README's examples use it and say why. +- [x] **PDX-35: Read the webhook URL from the environment.** Done when: `PARADOX_WEBHOOK` sets the URL, a test shows it's used without `--webhook`, and the README's examples use it and say why. The URL works like a password for its channel, and on the command line it shows up in process listings and shell history. @@ -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.8, 4.9, 4.10, ~~4.6, 4.7, 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.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 | | 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 0d1d35d..763cca2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -108,8 +108,8 @@ more than people expect. - A post still says which IPs were seen, how often, and the log's path (`source`), and the receiver can store all of it. - `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 passed on the command line, so it's visible in process listings and shell history. It's effectively a - password for that channel. +- 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. ## `.env` handling diff --git a/docker-compose.yml b/docker-compose.yml index 06cfe9a..229ff9b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -13,7 +13,7 @@ services: # Headless sensor sharing the same history. It rescans tracked IPs every # 6 hours. To follow host logs too, mount them and add --log, e.g. # volumes: [/var/log/auth.log:/logs/auth.log:ro] - # command: [paradox, watch, --rescan-every, "6", --log, /logs/auth.log, --webhook, https://...] + # command: [paradox, watch, --rescan-every, "6", --log, /logs/auth.log] # set PARADOX_WEBHOOK in .env for alerts watch: build: . env_file: .env diff --git a/paradox/cli.py b/paradox/cli.py index 52cfae4..77496ee 100644 --- a/paradox/cli.py +++ b/paradox/cli.py @@ -186,7 +186,7 @@ def cmd_watch(args) -> int: print(f"error: unknown --alert-on flag(s): {', '.join(sorted(bad))}", 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, as_json=args.json, max_new_per_hour=args.max_new_per_hour) + workers=args.workers, webhook=args.webhook or config.key("PARADOX_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) @@ -295,7 +295,8 @@ def add(name, func, help): help="also rescan every tracked IP on this interval (0 = off)") p.add_argument("--alert-on", default=",".join(ALERT_FLAGS), help="comma-separated flags that alert (default veneer,paradox,threat; add watch)") - p.add_argument("--webhook", metavar="URL", help="POST each alert as JSON (Slack-compatible 'text')") + p.add_argument("--webhook", metavar="URL", help="POST each alert as JSON (Slack-compatible 'text'); prefer PARADOX_WEBHOOK, " + "since a URL here shows in process listings and shell history") p.add_argument("--workers", type=int, default=2, help="concurrent scans (default 2)") p.add_argument("--max-new-per-hour", type=int, default=15, metavar="N", help="scan at most this many new IPs an hour; the rest wait until seen again (default 15, 0 = off)") diff --git a/paradox/env.example b/paradox/env.example index 703d92f..39ba785 100644 --- a/paradox/env.example +++ b/paradox/env.example @@ -18,6 +18,9 @@ ANTHROPIC_API_KEY= # MCP server # PARADOX_LOG_DIRS=/var/log # folders scan_log's path may read, separated by : (; on Windows) +# Watcher +# PARADOX_WEBHOOK=https://hooks.slack.com/services/... # where paradox watch posts alerts + # Web server # PARADOX_HOST=127.0.0.1 # 0.0.0.0 to listen on all interfaces (requires PARADOX_PASSWORD) # PARADOX_PORT=8787 diff --git a/tests/test_app.py b/tests/test_app.py index 343140e..65550dd 100644 --- a/tests/test_app.py +++ b/tests/test_app.py @@ -31,6 +31,19 @@ def test_every_command_parses(self): ["beacons"], ["init"], ["where"]): self.assertTrue(callable(p.parse_args(argv).func), argv) + def watch_webhook(self, *argv, env=None): + with mock.patch.dict(os.environ, env or {}), mock.patch.object(watch, "Watcher") as w: + os.environ.pop("PARADOX_WEBHOOK", None) if env is None else None + w.return_value.run.return_value = 0 + cli.main(["watch", "--log", "a", *argv]) + return w.call_args.kwargs["webhook"] + + def test_webhook_url_comes_from_the_environment_and_the_flag_wins(self): + env = {"PARADOX_WEBHOOK": "https://example.test/env"} + self.assertEqual(self.watch_webhook(env=env), "https://example.test/env") + self.assertEqual(self.watch_webhook("--webhook", "https://example.test/flag", env=env), "https://example.test/flag") + self.assertIsNone(self.watch_webhook()) + 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}), \