derp

Asyncio IRC bot for Python 3.11+ with a decorator-based plugin system. Built for red team ops, OSINT, and OPSEC workflows.

Quick Start

git clone <repo> ~/git/derp && cd ~/git/derp
make install
cp config/derp.toml.example config/derp.toml
# Edit config/derp.toml with your server details
make run

Container

make build     # Build image (only after dependency changes)
make up        # Start with podman-compose
make logs      # Follow logs
make down      # Stop

Features

• Async IRC over plain TCP or TLS (SASL PLAIN auth, IRCv3 CAP negotiation)
• Microsoft Teams support via outgoing webhooks (no SDK dependency)
• Telegram support via long-polling (no SDK dependency, SOCKS5 proxied)
• Mumble support via TCP/TLS protobuf control channel (text only, SOCKS5 proxied)
• Plugin system with @command and @event decorators
• Hot-reload: load, unload, reload plugins at runtime
• Admin permission system (hostmask patterns + IRCOP detection + AAD IDs)
• Command shorthand: !h resolves to !help (unambiguous prefix matching)
• TOML configuration with sensible defaults
• Rate limiting, CTCP responses, auto reconnect
• Containerized deployment via Podman

Plugins

Plugin	Commands	Description
core	ping, help, version, uptime, whoami, admins, load, reload, unload, plugins, state	Bot management
dns	dns	Raw UDP DNS resolver (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA)
tdns	tdns	TCP DNS resolver via SOCKS5 proxy (same record types)
encode	encode, decode	Base64, hex, URL, ROT13
hash	hash, hashid	Hash generation + type identification
defang	defang, refang	IOC defanging for safe sharing
revshell	revshell	Reverse shell one-liners (11 languages)
cidr	cidr	Subnet calculator + IP membership check
crtsh	cert	Certificate transparency log lookup
whois	whois	Raw socket WHOIS (port 43)
portcheck	portcheck	Async TCP port scanner
httpcheck	httpcheck	HTTP status, redirects, response time
tlscheck	tlscheck	TLS version, cipher, cert details
blacklist	blacklist	DNSBL/RBL IP reputation check
rand	rand	Passwords, hex, UUIDs, dice rolls
timer	timer	Countdown timers with notification
geoip	geoip	GeoIP city/country lookup (MaxMind mmdb)
asn	asn	AS number + organization lookup (MaxMind mmdb)
torcheck	tor	Tor exit node check (local list)
iprep	iprep	IP reputation (Firehol/ET blocklists)
cve	cve	CVE lookup + search (local NVD mirror)
opslog	opslog	Timestamped operational notes (SQLite)
note	note	Per-channel persistent key-value store
subdomain	subdomain	Subdomain enum (crt.sh + DNS brute)
headers	headers	HTTP header fingerprinting
exploitdb	exploitdb	Exploit-DB search (local CSV)
payload	payload	SQLi/XSS/SSTI/LFI/CMDi/XXE templates
dork	dork	Google dork query builder
wayback	wayback	Wayback Machine snapshot lookup
username	username	Username enumeration across ~25 services
remind	remind	One-shot, repeating, and calendar reminders
rss	rss	RSS/Atom feed subscriptions with polling
youtube	yt	YouTube channel follow with new-video alerts
twitch	twitch	Twitch livestream notifications (public GQL)
chanmgmt	kick, ban, unban, topic, mode	Channel management (admin)
example	echo	Demo plugin

Writing Plugins

from derp.plugin import command, event

@command("greet", help="Say hello")
async def cmd_greet(bot, message):
    await bot.reply(message, f"Hello, {message.nick}!")

@event("JOIN")
async def on_join(bot, message):
    if message.nick != bot.nick:
        await bot.send(message.target, f"Welcome, {message.nick}")

Make Targets

Target	Description
make install	Create venv and install
make test	Run test suite
make lint	Lint with ruff
make run	Start the bot (bare metal)
make link	Symlink to ~/.local/bin/
make build	Build container image (only for dependency changes)
make up	Start with podman-compose
make down	Stop with podman-compose
make logs	Follow compose logs

Documentation

• Plugin API Reference
• Installation
• Usage Guide
• Cheatsheet
• Debugging

License

MIT