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
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
6 changes: 3 additions & 3 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 |

Expand Down
5 changes: 4 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand All @@ -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

Expand Down
8 changes: 6 additions & 2 deletions paradox/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)


Expand Down
1 change: 1 addition & 0 deletions paradox/env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
14 changes: 14 additions & 0 deletions paradox/watch.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
23 changes: 23 additions & 0 deletions tests/test_app.py
Original file line number Diff line number Diff line change
Expand Up @@ -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}), \
Expand Down
Loading