derp/docs/CHEATSHEET.md

Cheatsheet

Dev Commands

make install          # Setup venv + install
make test             # Run tests
make lint             # Lint with ruff
make run              # Start bot (bare metal)
make link             # Symlink to ~/.local/bin
derp -c config.toml   # Run with custom config
derp -v               # Verbose/debug mode
derp --cprofile       # Profile to derp.prof

SASL Authentication

# In config/derp.toml
[server]
sasl_user = "account"
sasl_pass = "password"

Rate Limiting

# In config/derp.toml (defaults shown)
[bot]
rate_limit = 2.0     # Messages per second
rate_burst = 5       # Burst capacity

Per-Channel Plugin Control

# Only allow specific plugins in a channel
[channels."#public"]
plugins = ["core", "dns", "cidr", "encode"]

# Omit section entirely to allow all plugins

core always active. PMs unrestricted. Denied commands silently ignored.

Structured Logging

[logging]
format = "json"    # JSONL output (default: "text")

Container

make build            # Build image (only for dep changes)
make up               # Start (podman-compose)
make down             # Stop
make logs             # Follow logs

Code, plugins, config, and data are bind-mounted. No rebuild needed for code changes -- restart the container or use !reload for plugins.

Bot Commands

!ping              # Pong
!help              # List commands
!help <cmd>        # Command help
!help <plugin>     # Plugin description + commands
!version           # Bot version
!uptime            # Bot uptime
!echo <text>       # Echo text back
!h                 # Shorthand (any unambiguous prefix works)

Admin

!whoami            # Show your hostmask + admin status
!admins            # Show admin patterns + detected opers (admin)

# config/derp.toml
[bot]
admins = ["*!~user@trusted.host", "ops!*@*.ops.net"]

IRC operators are auto-detected via WHO on connect and on user JOIN (debounced 2s to handle netsplit floods). Hostmask patterns use fnmatch.

Channel Management (admin)

!kick nick reason          # Kick user from channel
!ban *!*@bad.host          # Ban hostmask
!unban *!*@bad.host        # Remove ban
!topic New topic text      # Set channel topic
!topic                     # Query current topic
!mode +m                   # Set channel mode
!mode +o nick              # Give ops

Auto-joins channels when invited by an admin/ircop. Persists across restarts. Removed from auto-rejoin list if bot is kicked.

State Store (admin)

!state list myplugin       # List keys
!state get myplugin key    # Get value
!state del myplugin key    # Delete key
!state clear myplugin      # Clear all keys

IRCv3 Capabilities

# config/derp.toml
[server]
ircv3_caps = ["multi-prefix", "away-notify", "server-time"]

SASL auto-added when sasl_user/sasl_pass configured.

Plugin Management (admin)

!plugins           # List loaded plugins
!load <plugin>     # Hot-load a plugin (admin)
!reload <plugin>   # Reload a changed plugin (admin)
!unload <plugin>   # Remove a plugin (admin)

Recon

!dork list                    # List dork categories
!dork admin example.com       # Admin/login panel dorks
!dork files example.com       # Exposed document dorks
!wayback example.com          # Wayback Machine snapshot
!wayback example.com 20240101 # Snapshot near date

Categories: admin, backup, cloud, config, creds, dirs, errors, exposed, files, login.

OSINT

!username list                 # List services by category
!username john                 # Full scan (~25 services)
!username john github          # Check single service
!dns example.com        # A record lookup (UDP, local resolver)
!dns 1.2.3.4            # Reverse PTR lookup
!dns example.com MX     # Specific type (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA)
!tdns example.com       # A record lookup (TCP via SOCKS5 proxy)
!tdns example.com MX @8.8.8.8  # Explicit type + custom server
!cert example.com       # CT log lookup (max 5 domains)
!whois example.com      # WHOIS domain lookup
!whois 8.8.8.8          # WHOIS IP lookup
!subdomain example.com        # CT log subdomain enum
!subdomain example.com brute  # + DNS wordlist brute
!headers example.com          # HTTP fingerprint (tech + security)

Ops

!opslog add Compromised target  # Add timestamped entry
!opslog list                    # Show last 5 entries
!opslog list 10                 # Show last 10
!opslog search pivot            # Search entries
!opslog del 3                   # Delete entry by ID
!opslog clear                   # Clear channel log (admin)
!note set target 10.0.0.1      # Store a note
!note get target                # Retrieve a note
!note del target                # Delete a note
!note list                      # List all keys
!note clear                     # Clear all notes (admin)

Exploit-DB

!exploitdb search apache        # Search by keyword
!exploitdb 12345                # Lookup by EDB ID
!exploitdb cve CVE-2024-1234    # Search by CVE
!exploitdb update               # Download latest CSV
!exploitdb stats                # Show index size

Payloads

!payload list                   # List categories
!payload sqli                   # Show SQLi payloads
!payload xss 3                  # Show XSS payload #3
!payload ssti jinja             # Search SSTI for 'jinja'
!payload lfi all                # Show all LFI payloads

Categories: sqli, xss, ssti, lfi, cmdi, xxe

Red Team

!revshell bash 10.0.0.1 4444   # Reverse shell one-liner
!revshell list                 # List types (bash/sh/nc/nce/python/perl/php/ruby/socat/lua/ps)
!encode b64 hello              # Base64 encode
!decode hex 68656c6c6f         # Hex decode
!encode rot13 hello            # ROT13
!hash hello                    # MD5 + SHA1 + SHA256
!hash sha512 hello             # Specific algorithm
!hashid <hash>                 # Identify hash type

OPSEC

!defang https://evil.com       # Defang IOC
!refang hxxps[://]evil[.]com   # Refang IOC

Network

!cidr 10.0.0.0/24              # Subnet info
!cidr contains 10.0.0.0/8 10.1.2.3  # Membership check
!portcheck 10.0.0.1            # Scan common ports
!portcheck 10.0.0.1 22,80,443  # Scan specific ports
!httpcheck https://example.com  # HTTP status + timing
!tlscheck example.com          # TLS/cert inspection
!tlscheck 10.0.0.1 8443        # Custom port
!blacklist 1.2.3.4             # DNSBL reputation check

Intelligence (local databases)

!geoip 8.8.8.8                # GeoIP: city, country, coords, tz
!asn 8.8.8.8                  # ASN: number + organization
!tor 1.2.3.4                  # Check Tor exit node
!tor update                   # Download exit list
!iprep 1.2.3.4                # Firehol/ET blocklist check
!iprep update                 # Download blocklist feeds
!cve CVE-2024-1234            # Lookup specific CVE
!cve search apache rce         # Search CVE descriptions
!cve update                   # Download NVD feed (slow)
!cve stats                    # Show index size

Data Setup

./scripts/update-data.sh                        # Update tor + iprep
MAXMIND_LICENSE_KEY=xxx ./scripts/update-data.sh # + GeoLite2

Random

!rand password             # 16-char random password
!rand password 32 all      # 32-char, full charset
!rand hex 64               # Random hex string
!rand uuid                 # UUID4
!rand bytes 32             # Random bytes (hex)
!rand int 100              # Random 0..99
!rand coin                 # Heads or tails
!rand dice 2d20            # Roll 2x d20

Timer

!timer 5m                  # 5-minute countdown
!timer 1h30m deploy        # Named timer
!timer 90                  # 90 seconds
!timer list                # Show active timers
!timer cancel deploy       # Cancel a timer

Remind

!remind 5m check oven            # One-shot (in-memory)
!remind every 1h hydrate         # Repeating (in-memory)
!remind at 2027-06-15 deploy     # Calendar one-shot (persisted)
!remind at 2027-06-15 14:30 go   # With explicit time
!remind yearly 02-14 valentines  # Yearly recurring (persisted)
!remind yearly 12-25 09:00 xmas  # Yearly with time
!remind list                     # Show active reminders
!remind cancel abc123            # Cancel by ID

Default time: 12:00. Timezone: bot.timezone config (default UTC).

RSS

!rss add <url> [name]      # Subscribe feed (admin)
!rss del <name>            # Unsubscribe feed (admin)
!rss list                  # List channel feeds
!rss check <name>          # Force-poll now

Names: lowercase alphanumeric + hyphens, 1-20 chars. Max 20 feeds/channel. Polls every 10min. Announces max 5 new items per cycle. Persists across restarts.

YouTube

!yt follow <url> [name]    # Follow YouTube channel (admin)
!yt unfollow <name>        # Unfollow channel (admin)
!yt list                   # List followed channels
!yt check <name>           # Force-poll now

Accepts any YouTube URL: video, channel, handle, shorts, embed. Names: lowercase alphanumeric + hyphens, 1-20 chars. Max 20 channels/channel. Polls every 10min. Announces max 5 new videos per cycle. Persists across restarts.

Twitch

!twitch follow <user> [name]   # Follow streamer (admin)
!twitch unfollow <name>        # Unfollow streamer (admin)
!twitch list                   # List followed streamers
!twitch check <name>           # Force-poll now

Names: lowercase alphanumeric + hyphens, 1-20 chars. Max 20 streamers/channel. Polls every 2min. Announces offline->live transitions. Persists across restarts. No API credentials needed (uses public GQL endpoint).

Alert

!alert add <name> <keyword...>   # Add keyword alert (admin)
!alert del <name>                # Remove alert (admin)
!alert list                      # List alerts
!alert check <name>              # Force-poll now
!alert info <id>                 # Show full result details
!alert history <name> [n]        # Show recent results (default 5)

Searches keywords across 16 backends: YouTube (yt), Twitch (tw), SearXNG (sx), Reddit (rd), Mastodon (ft), DuckDuckGo (dg), Google News (gn), Kick (kk), Dailymotion (dm), PeerTube (pt), Bluesky (bs), Lemmy (ly), Odysee (od), Archive.org (ia), Hacker News (hn), GitHub (gh). Names: lowercase alphanumeric + hyphens, 1-20 chars. Keywords: 1-100 chars. Max 20 alerts/channel. Polls every 5min. Format: [name/yt/a8k2m] Title -- URL. Use !alert info <id> to see full details. No API credentials needed. Persists across restarts. History stored in data/alert_history.db.

SearX

!searx <query>               # Search SearXNG

Shows top 3 results as Title -- URL. Channel only. Max query length: 200 chars.

Plugin Template

from derp.plugin import command, event

@command("name", help="Description")
async def cmd_name(bot, message):
    text = message.text.split(None, 1)
    await bot.reply(message, "response")

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

Message Object

msg.nick        # Sender nick
msg.target      # Channel or nick
msg.text        # Message body
msg.is_channel  # True if channel
msg.prefix      # nick!user@host
msg.command     # PRIVMSG, JOIN, etc.
msg.params      # All params list
msg.tags        # IRCv3 tags dict

Config Locations

1. --config PATH              # CLI flag
2. ./config/derp.toml         # Project dir
3. ~/.config/derp/derp.toml   # User config
4. Built-in defaults          # Fallback