diff --git a/README.md b/README.md index 86b8fc4..c39b5d1 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,10 @@ journalctl -fu sshd | paradox watch --log - paradox watch --rescan-every 6 # no logs: keep tracked IPs fresh (replaces cron) ``` +At most 15 new IPs an hour get scanned (`--max-new-per-hour`, `0` for no limit), because forged addresses in a log +would otherwise spend the day's VirusTotal lookups. An IP over the limit waits until it's seen again after that, so a +flood can delay or hide a real attacker that appears only once. The limit resets when the watcher restarts. + 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 diff --git a/ROADMAP.md b/ROADMAP.md index 07c9e6f..2bca401 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -393,6 +393,41 @@ It doubles as class material. four gaps with no story yet: `paradox watch` has no cap on new IPs, webhooks send the raw log line in the JSON `alert`, the webhook URL sits on the command line, and `.env` isn't checked for loose permissions. +### 4.6 Cap new-IP scans in `paradox watch` · S · ✅ shipped + +- [x] **PDX-33: Cap new-IP scans.** Done when: a test floods the watcher with 100 forged IPs and only the cap's worth get queued, a rescan isn't counted or blocked, an IP over the cap gets its turn when seen again after the hour, and the README states the cap and its downside. + +Found while writing the threat model. `paradox watch` scans each new public IP it sees, so forged source addresses +in a log could spend the day's VirusTotal lookups. + +*Shipped:* 15 new IPs an hour by default (`--max-new-per-hour`), which is 360 a day and leaves room inside +VirusTotal's 500 for rescans. + +*Downside:* a flood can delay a real attacker, and one that appears only once may never be scanned. The count resets +on restart. Not measured against a real log, so 15 may be too low for a busy one; the watcher warns on stderr when it +hits the limit, once per stretch at the limit. + +### 4.7 Keep raw log lines out of webhook posts · S + +- [ ] **PDX-34: Webhooks don't send log lines.** Done when: a test shows a webhook POST contains no `sample` and none of the log line's text, stdout's `--json` output is unchanged, and the README and `SECURITY.md` say so. + +The JSON `alert` includes the raw log line, which can hold usernames, internal hostnames or tokens, and it goes to a +third party. + +### 4.8 Webhook URL out of the command line · S + +- [ ] **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. + +### 4.9 Refuse unencrypted webhooks · S + +- [ ] **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 + +- [ ] **PDX-37: Warn about `.env` permissions.** Done when: loading a `.env` readable by group or others prints one warning to stderr without the file's contents, a mode 600 file prints none, a test covers both, and platforms without POSIX modes are handled. + ### 4.5 Limit which files `scan_log` can read · S · ✅ shipped - [x] **PDX-29: Limit `scan_log`'s file access.** Done when: `scan_log`'s `path` argument reads only files inside an allowed set stated plainly in the README, symlinks and `..` can't escape it, a test shows a path outside the set is refused without its contents or existence being revealed, and the `text` argument still works without any configuration. @@ -514,7 +549,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.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.7, 4.8, 4.9, 4.10, ~~4.6, 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 5360953..005da17 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -31,13 +31,14 @@ an IP's paradox can rise. reuse of good answers. The count is shared by processes on one machine. - The web server limits scans and summaries per client (`PARADOX_RATE_LIMIT`, default 20 a minute) and runs at most 2 log scans at once, each up to 50 IPs and 5 MB. +- `paradox watch` scans at most 15 new IPs an hour (`--max-new-per-hour`). A flood can still delay or hide a real + attacker that appears only once, and the limit resets when the watcher restarts. - A report lists each beacon that gave no reading, why, and what that costs, so a thin result says so. **Open:** - Only VirusTotal has a budget. The other beacons rely on their providers' own limits. -- `paradox watch` has no cap on new IPs, so a log flooded with addresses can use up the day's VirusTotal lookups and - leave later IPs without them. +- Rescans of tracked IPs aren't capped, so a long tracked list can still reach VirusTotal's daily limit. - The rate limit is in memory and per client, so it resets on restart and many clients get many allowances. With `PARADOX_TRUST_PROXY=1` it trusts `X-Forwarded-For`, which is only safe when a proxy sets that header. - Lookups made with the same key on another machine aren't counted. diff --git a/paradox/cli.py b/paradox/cli.py index 3c9bd99..52cfae4 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) + workers=args.workers, webhook=args.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) @@ -297,6 +297,8 @@ def add(name, func, help): 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("--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)") p.add_argument("--json", action="store_true", help="one JSON object per alert on stdout") p = add("history", cmd_history, "recorded scans and beacon lag for an IP") diff --git a/paradox/watch.py b/paradox/watch.py index b4c8e91..86c7220 100644 --- a/paradox/watch.py +++ b/paradox/watch.py @@ -5,7 +5,9 @@ paradox watch --rescan-every 6 # no logs: just keep tracked IPs fresh Each public IP is scanned once it reaches --min-hits, then again only after ---rescan-after hours, so a busy log doesn't hammer the beacons. An alert is +--rescan-after hours, so a busy log doesn't hammer the beacons. --max-new-per-hour +caps how many new IPs get scanned, so a log full of forged addresses can't spend +the day's quota. An alert is emitted when an IP's flag (veneer, paradox, threat, watch) enters the alert set or changes, as a line on stdout (JSON with --json) and, optionally, a POST to --webhook. The payload's "text" field makes Slack/Mattermost incoming webhooks @@ -22,12 +24,14 @@ import threading import time import urllib.request +from collections import deque from datetime import datetime, timezone from typing import Callable, Iterator, TextIO from . import engine, history, logscan 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 QUEUE_LIMIT = 1000 @@ -99,7 +103,7 @@ def stream(src: TextIO, stop: threading.Event) -> Iterator[str]: 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, - out: TextIO = sys.stdout, scanner: Callable[..., dict] | None = None): + max_new_per_hour: int = DEFAULT_MAX_NEW, out: TextIO = sys.stdout, scanner: Callable[..., dict] | None = None): self.min_hits, self.rescan_after = min_hits, rescan_after_h * 3600 self.alert_on, self.webhook, self.as_json, self.out = set(alert_on), webhook, as_json, out self.scanner = scanner or engine.scan @@ -110,7 +114,10 @@ def __init__(self, *, min_hits: int = 1, rescan_after_h: float = 24, alert_on=DE self.pending: set[str] = set() self.q: queue.Queue[str] = queue.Queue(QUEUE_LIMIT) self.lock = threading.Lock() - self.stats = {"lines": 0, "scans": 0, "alerts": 0, "dropped": 0, "errors": 0} + self.max_new = max_new_per_hour + self.new_scans: deque[float] = deque() + self.warned_capped = False + self.stats = {"lines": 0, "scans": 0, "alerts": 0, "dropped": 0, "errors": 0, "capped": 0} self.workers = [threading.Thread(target=self._work, daemon=True) for _ in range(max(1, workers))] # -- input ------------------------------------------------------------- @@ -127,11 +134,34 @@ def feed(self, line: str, source: str) -> None: info["sample"] = line.strip()[:300] due = (info["hits"] >= self.min_hits and ip not in self.pending and time.time() - self.last_scan.get(ip, 0) >= self.rescan_after) + capped = due and ip not in self.last_scan and not self._new_scan_allowed() + if capped: + due = False + self.stats["capped"] += 1 + warn = capped and not self.warned_capped + if warn: + self.warned_capped = True if due: self.pending.add(ip) + if warn: + print(f"watch: {self.max_new} new IPs scanned this hour, the limit; others wait until they're seen " + "again after that. Forged addresses in a log can cause this.", file=sys.stderr) if due: self._enqueue(ip) + def _new_scan_allowed(self) -> bool: + """A log can name endless addresses, and each scan spends quota. Call with the lock held.""" + if self.max_new <= 0: + return True + now = time.time() + while self.new_scans and now - self.new_scans[0] >= 3600: + self.new_scans.popleft() + self.warned_capped = False + if len(self.new_scans) >= self.max_new: + return False + self.new_scans.append(now) + return True + def _enqueue(self, ip: str) -> None: try: self.q.put_nowait(ip) @@ -237,7 +267,8 @@ def run(self, logs: list[str], from_start: bool = False, rescan_every_h: float = s = self.stats print(f"watch: stopped. {s['lines']} lines, {len(self.seen)} public IPs, {s['scans']} scans, " f"{s['alerts']} alerts" + (f", {s['errors']} errors" if s["errors"] else "") - + (f", {s['dropped']} dropped" if s["dropped"] else ""), file=sys.stderr) + + (f", {s['dropped']} dropped" if s["dropped"] else "") + + (f", {s['capped']} sightings over the new-IP limit" if s["capped"] else ""), file=sys.stderr) return 1 if s["alerts"] else 0 def _pump(self, lines: Iterator[str], source: str) -> None: diff --git a/tests/test_app.py b/tests/test_app.py index c94cd49..8465085 100644 --- a/tests/test_app.py +++ b/tests/test_app.py @@ -109,6 +109,35 @@ def test_scans_once_and_alerts_on_flagged_ips_only(self): self.assertIn("PARADOX 45.1.1.1", alerts[0]["text"]) self.assertEqual(w.seen["45.1.1.1"]["hits"], 3) + def test_new_ip_cap_stops_a_flood_and_recovers(self): + w, _, _ = self.watcher({}, max_new_per_hour=3) + with mock.patch("paradox.watch.time.time", return_value=1_800_000_000.0) as clock, \ + mock.patch("sys.stderr", io.StringIO()) as err: + for i in range(1, 101): + w.feed(f"forged 45.1.1.{i}", "x") + self.assertEqual(w.q.qsize(), 3) + self.assertEqual(w.stats["capped"], 97) + self.assertEqual(err.getvalue().count("the limit"), 1) + clock.return_value = 1_800_000_000.0 + 3599 + w.feed("real 45.1.1.50", "x") + self.assertEqual(w.q.qsize(), 3) # still inside the hour + clock.return_value = 1_800_000_000.0 + 3600 + w.feed("real 45.1.1.50", "x") # seen again later: gets its turn + self.assertEqual(w.q.qsize(), 4) + self.assertIn("45.1.1.50", w.pending) + + def test_new_ip_cap_doesnt_count_or_block_rescans(self): + w, _, _ = self.watcher({}, max_new_per_hour=1, rescan_after_h=0) + w.last_scan.update({"45.1.1.1": 0.0, "45.1.1.2": 0.0}) + w.feed("45.1.1.1 45.1.1.2", "x") + self.assertEqual((w.q.qsize(), w.stats["capped"], len(w.new_scans)), (2, 0, 0)) + + def test_new_ip_cap_of_zero_is_off(self): + w, _, _ = self.watcher({}, max_new_per_hour=0) + for i in range(1, 51): + w.feed(f"45.1.1.{i}", "x") + self.assertEqual((w.q.qsize(), w.stats["capped"]), (50, 0)) + def test_min_hits_and_flag_change_alerts(self): scores = {"45.1.1.1": fake_score(paradox=50, threat=0.5)} w, calls, out = self.watcher(scores, min_hits=2)