A tool for parsing traffic on the jetstream and applying a moderation workstream based on regexp based rules
skywatch.blue
1# skywatch-automod
2
3Automated moderation tooling for the Bluesky independent labeler skywatch.blue. Monitors the Bluesky firehose and applies labels based on configured moderation rules.
4
5## Setup
6
7Configure environment:
8
9```bash
10cp .env.example .env
11# Edit .env with your credentials and configuration
12```
13
14Required environment variables:
15- `BSKY_HANDLE` - Bluesky account handle
16- `BSKY_PASSWORD` - Account password
17- `DID` - Moderator DID
18- `OZONE_URL` - Ozone service URL
19- `OZONE_PDS` - Ozone PDS hostname
20
21Optional environment variables:
22- `FIREHOSE_URL` - Jetstream firehose URL (default: `wss://jetstream.atproto.tools/subscribe`)
23- `REDIS_URL` - Redis connection URL (default: `redis://redis:6379`)
24- `HOST` - Metrics server bind address (default: `0.0.0.0`)
25- `METRICS_PORT` - Metrics server port (default: `4101`)
26- `PLC_URL` - PLC directory hostname (default: `plc.directory`)
27- `CURSOR_UPDATE_INTERVAL` - Cursor save interval in ms (default: `60000`)
28- `LABEL_LIMIT` - Rate limit for label operations
29- `LABEL_LIMIT_WAIT` - Wait time for rate limiter
30
31Create cursor file (optional but recommended):
32
33```bash
34touch cursor.txt
35```
36
37## Running
38
39Production:
40
41```bash
42docker compose up -d
43```
44
45Development mode with auto-reload:
46
47```bash
48docker compose -f compose.yaml -f compose.dev.yaml up
49```
50
51The service runs on port 4101 (metrics endpoint). Redis and Prometheus are included in the compose stack.
52
53## Authentication
54
55The application authenticates with Bluesky on startup and retries up to 3 times on failure. If all attempts fail, the application exits. Sessions are cached in `.session` (gitignored).
56
57## Testing
58
59```bash
60bun test # Watch mode
61bun test:run # Single run
62bun test:coverage # With coverage
63```
64
65## How It Works
66
67Monitors the Bluesky firehose via Jetstream and analyzes:
68- **Posts** - Text content and embedded URLs
69- **Profiles** - Display names and descriptions
70- **Handles** - Username patterns
71- **Starter packs** - Creation activity
72
73When criteria are met, applies appropriate labels or creates moderation reports.
74
75### Threshold Systems
76
77Beyond pattern matching, the automod supports account-level threshold enforcement:
78
79- **Account threshold** - Labels accounts that accumulate multiple post-level violations within a rolling time window
80- **Starter pack threshold** - Labels accounts that create too many starter packs within a time window (useful for detecting follow-farming)
81
82Both systems use Redis for time-windowed tracking and support configurable actions (label, report, comment).
83
84For developing custom checks, see [developing_checks.md](./rules/developing_checks.md).