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 up        # Build + start with podman-compose
make logs      # Follow logs
make down      # Stop

Features

• Async IRC over plain TCP or TLS (SASL PLAIN auth)
• Plugin system with @command and @event decorators
• Hot-reload: load, unload, reload plugins at runtime
• Admin permission system (hostmask patterns + IRCOP detection)
• 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	Bot management
dns	dns	Raw UDP DNS resolver (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA)
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)
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
make up	Start with podman-compose
make down	Stop with podman-compose
make logs	Follow compose logs

Documentation

• Installation
• Usage Guide
• Cheatsheet
• Debugging

License

MIT