Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 36 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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 |

Expand Down
5 changes: 3 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion paradox/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)


Expand Down Expand Up @@ -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")
Expand Down
39 changes: 35 additions & 4 deletions paradox/watch.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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


Expand Down Expand Up @@ -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
Expand All @@ -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 -------------------------------------------------------------
Expand All @@ -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)
Expand Down Expand Up @@ -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:
Expand Down
29 changes: 29 additions & 0 deletions tests/test_app.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading