1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
# osterman
Channel moderation bot. Manages bans, kicks, mutes, auto-modes, content filters,
and idle tracking.
## Dependencies
No external libraries required.
## Plugins
| File | Role |
|------|------|
| `protect.py` | Setup, passive protection: flood, caps, repeat, badword, clone, join flood |
| `commands.py` | All user-facing moderation and config commands |
| `tracking.py` | SQLite event log, greeting, `!seen`, `!info`, `!log` |
| `idle.py` | Idle detection tick, `!afk`, `!idle` |
| `help.py` | Three-level help system |
## Message routing
| Output type | Delivery |
|-------------|----------|
| `!seen`, `!idle <nick>` results | Channel message |
| `!info`, `!log` results | PM to nick |
| `!ban list`, `!config`, `!filter list`, `!badword list` | PM to nick |
| All other command feedback (errors, confirmations) | IRC NOTICE to nick |
| Greetings, idle warns, bad word warn | IRC NOTICE to nick |
## Help system
```
!help list topics
!help <topic> list commands for a topic
!help <topic> <cmd> description and usage for a command
!help <cmd> description and usage (topic not required)
```
Topics: `mod`, `config`, `track`, `idle`, `admin`
## Commands
### Moderation (owner / ACL / op)
| Command | Short | Description |
|---------|-------|-------------|
| `!kick <nick> [reason]` | `!k` | Kick |
| `!ban <nick\|mask> [reason]` | `!b` | Ban + kick |
| `!ban list` | `!b list` | View channel ban list (PM) |
| `!bankick <nick\|mask> [reason]` | `!bk` | Ban + kick (explicit) |
| `!unban <nick\|mask>` | `!ub` | Remove ban |
| `!tempban <nick\|mask> <min> [reason]` | `!tb` | Timed ban (auto-lifts) |
| `!mute <nick\|mask>` | `!mu` | Quiet (+q) |
| `!unmute <nick\|mask>` | `!umu` | Unquiet (-q) |
| `!voice <nick>` | `!v` | Give voice (+v) |
| `!devoice <nick>` | `!dv` | Remove voice |
| `!op <nick>` | `!o` | Give op (+o) |
| `!deop <nick>` | `!do` | Remove op |
| `!halfop <nick>` | `!hop` | Give halfop (+h) |
| `!dehalfop <nick>` | `!dhop` | Remove halfop |
| `!lock [m\|i]` | `!lk` | Lock channel (+mi, +m, or +i) |
| `!unlock [m\|i]` | `!ulk` | Unlock channel |
### Auto-modes (owner / ACL / op, per channel)
| Command | Short | Description |
|---------|-------|-------------|
| `!autoop <add\|del\|list> [nick\|mask]` | `!ao` | Auto +o on join |
| `!autovoice <add\|del\|list> [nick\|mask]` | `!av` | Auto +v on join |
| `!autohalfop <add\|del\|list> [nick\|mask]` | `!ahop` | Auto +h on join |
### Config / lists (owner / ACL)
| Command | Short | Description |
|---------|-------|-------------|
| `!blacklist <add\|del\|list> [mask]` | `!bl` | Global ban list (all channels) |
| `!whitelist <add\|del\|list> [mask]` | `!wl` | Global bypass list |
| `!except <add\|del\|list> [mask]` | `!ex` | Per-channel bypass list |
| `!acl <add\|del\|list> [nick]` | (none) | Trusted nicks (can use mod commands) |
| `!filter <add\|del\|list> [pattern]` | `!f` | Per-channel regex content filter |
| `!badword <add\|del\|list> [word]` | `!bw` | Per-channel word block list |
| `!set <key> <value>` | `!s` | Set a config value (in channel: per-channel; in PM: global) |
| `!config [#channel]` | `!cfg` | Show channel config (PM) |
| `!idle <on\|off>` | `!id` | Toggle idle detection |
### Tracking
| Command | Auth | Description |
|---------|------|-------------|
| `!seen <nick>` | anyone | Last time nick was seen in this channel. Responds in channel. Owner/ACL may call from PM for cross-channel lookup. |
| `!info <nick>` | anyone | Nick summary scoped to this channel (PM). Owner/ACL may call from PM for global lookup. |
| `!idle <nick>` | anyone | How long nick has been idle in this channel. Responds in channel. |
| `!log <nick> [n]` | owner / ACL | Full event log for nick (PM) |
| `!afk` | anyone | Reset your idle timer |
### Admin (owner)
| Command | Short | Description |
|---------|-------|-------------|
| `!join <#channel>` | `!j` | Join a channel |
| `!part [#channel]` | `!p` | Leave a channel |
| `!chans` | `!c` | List channels |
## Configurable settings (`!set <key> <value>`)
| Key | Default | Description |
|-----|---------|-------------|
| `flood_threshold` | 5 | Messages before flood action |
| `flood_window_sec` | 10 | Flood detection window (seconds) |
| `caps_filter` | 1 | Enable caps filter (0/1) |
| `caps_percent` | 70 | Caps percentage threshold |
| `caps_min_len` | 10 | Minimum message length to check |
| `repeat_filter` | 1 | Enable repeat filter (0/1) |
| `repeat_threshold` | 3 | Repeated messages before action |
| `repeat_window_sec` | 30 | Repeat detection window (seconds) |
| `clone_limit` | 2 | Max connections from same host |
| `join_flood_filter` | 1 | Enable join flood filter (0/1) |
| `join_flood_count` | 5 | Joins before action |
| `join_flood_window` | 10 | Join flood window (seconds) |
| `nick_flood_filter` | 1 | Enable nick flood filter (0/1) |
| `nick_flood_count` | 3 | Nick changes before action |
| `nick_flood_window` | 60 | Nick flood window (seconds) |
| `badword_action` | kick | Action on badword: `kick` or `warn` |
| `tempban_max_min` | 60 | Max duration for `!tempban` (minutes) |
| `idle_warn_min` | 45 | Minutes idle before warning |
| `idle_kick_min` | 60 | Minutes idle before kick |
| `log_limit` | 6 | Default number of events shown by `!log` |
| `greet` | 1 | Send join greeting (0/1) |
## Config keys
| Key | Description |
|-----|-------------|
| `[osterman] db_path` | Path to JSON database file |
|
