ad12843e75
- USAGE.md: music discovery (!similar, !tags), autoplay discovery config, Mumble admin (!mu) command reference - CHEATSHEET.md: music discovery and Mumble admin quick reference - ROADMAP.md: mark v2.4.0 as done, add MB fallback + !mu + autoplay - TODO.md: mark music discovery and performance items as done - PROJECT.md: update plugin categories table - TASKS.md: close open doc items Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
63 lines
2.4 KiB
Markdown
63 lines
2.4 KiB
Markdown
# derp - Project
|
|
|
|
## Purpose
|
|
|
|
A lightweight, zero-dependency asyncio IRC bot with a clean plugin system for Python 3.11+. Designed as an operational toolkit for red team engagements, OSINT reconnaissance, and OPSEC workflows -- accessible from any IRC client.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
|
|
|-> IRCConnection (async TCP/TLS)
|
|
|-> PluginRegistry (decorators, loader)
|
|
|-> plugins/*.py (hot-reloadable)
|
|
```
|
|
|
|
### Modules
|
|
|
|
| Module | Role |
|
|
|--------|------|
|
|
| `cli.py` | Argument parsing, logging setup, entry point |
|
|
| `config.py` | TOML loader with defaults merging |
|
|
| `irc.py` | IRC protocol: message parsing, formatting, async connection |
|
|
| `plugin.py` | Decorator-based plugin system with hot-reload |
|
|
| `bot.py` | Orchestrator: connect, dispatch, reconnect, plugin management |
|
|
|
|
### Plugin Categories
|
|
|
|
| Category | Plugins | Purpose |
|
|
|----------|---------|---------|
|
|
| Core | core | Bot management, help, plugin lifecycle |
|
|
| OSINT | dns, crtsh, internetdb | Reconnaissance and enumeration |
|
|
| Red Team | revshell, encode, hash | Offensive tooling |
|
|
| OPSEC | defang | Safe IOC handling |
|
|
| Utility | cidr, rand, timer, remind | Network tools, scheduling |
|
|
| Music | music, lastfm | Mumble playback, discovery (Last.fm/MB) |
|
|
| Voice | voice, mumble_admin | STT/TTS, server admin |
|
|
| Subscriptions | rss, yt, twitch, alert | Feed monitoring, keyword alerts |
|
|
|
|
### Key Design Decisions
|
|
|
|
- **Zero dependencies**: stdlib only (`asyncio`, `ssl`, `tomllib`, `struct`, `ipaddress`, `hashlib`)
|
|
- **Decorator-based plugins**: `@command` and `@event` for clean registration
|
|
- **Hot-reload**: load, unload, reload plugins without restart
|
|
- **Command shorthand**: unambiguous prefix matching (`!h` -> `!help`)
|
|
- **Raw DNS resolver**: pure stdlib UDP, no external DNS library
|
|
- **Container-first**: Podman with bind-mounted plugins for live editing
|
|
- **Async throughout**: all handlers are `async def`
|
|
|
|
### Deployment
|
|
|
|
| Method | Command | Notes |
|
|
|--------|---------|-------|
|
|
| Bare metal | `make run` | Direct Python, editable install |
|
|
| Container | `make up` | podman-compose, plugins mounted |
|
|
| Symlink | `make link` | Installs `derp` to `~/.local/bin/` |
|
|
|
|
## Dependencies
|
|
|
|
- Python 3.11+ (for `tomllib`)
|
|
- No external packages required at runtime
|
|
- Dev: `pytest`, `ruff`
|
|
- Container: `podman`, `podman-compose`
|