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