derp

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

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
• Plugin system with @command and @event decorators
• Hot-reload: load, unload, reload plugins at runtime
• Command shorthand: !h resolves to !help (unambiguous prefix matching)
• TOML configuration with sensible defaults
• Auto reconnect, nick recovery, PING/PONG handling
• Containerized deployment via Podman

Plugins

Plugin	Commands	Description
core	ping, help, version, uptime, 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
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