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
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
```
Expand All @@ -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.

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

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.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 |

Expand Down
4 changes: 2 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions 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, 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)


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