username/derp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add podman-compose, update all project documentation

Browse Source 
- docker-compose.yml for podman-compose deployment
- Makefile: add up/down/logs compose targets
- README: plugin table, container quickstart, make targets
- PROJECT: plugin categories, deployment matrix, design decisions
- ROADMAP: v0.1 done, v0.2 current, v0.3-v1.0 planned
- TASKS: current sprint with priorities
- TODO: full backlog organized by wave
- CHEATSHEET: reorganized by category (OSINT, Red Team, OPSEC)
- INSTALL: container deployment instructions
- DEBUG: container logs, hot-reload, DNS troubleshooting
- USAGE: all 19 commands documented

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-15 01:46:21 +01:00
parent 2e2378d3ee
commit c5b0430da8
11 changed files with 351 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
Makefile
View File

@@ -1,4 +1,4 @@
.PHONY: install dev test lint clean help build container-run container-stop container-logs
.PHONY: install dev test lint clean help build container-run container-stop container-logs up down logs
APP_NAME := derp
VENV := .venv
@@ -53,3 +53,12 @@ container-stop: ## Stop and remove container
container-logs: ## Follow container logs
podman logs -f $(APP_NAME)
up: ## Start with podman-compose (build + detach)
podman-compose up -d --build
down: ## Stop with podman-compose
podman-compose down
logs: ## Follow compose logs
podman-compose logs -f

34
PROJECT.md
View File

@@ -2,7 +2,7 @@
## Purpose
A lightweight, zero-dependency asyncio IRC bot with a clean plugin system for Python 3.11+.
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
@@ -10,7 +10,7 @@ A lightweight, zero-dependency asyncio IRC bot with a clean plugin system for Py
CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
|-> IRCConnection (async TCP/TLS)
|-> PluginRegistry (decorators, loader)
|-> plugins/*.py
|-> plugins/*.py (hot-reloadable)
```
### Modules
@@ -20,18 +20,40 @@ CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
| `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 file loader |
| `bot.py` | Orchestrator: connect, dispatch, reconnect |
| `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 | Reconnaissance and enumeration |
| Red Team | revshell, encode, hash | Offensive tooling |
| OPSEC | defang | Safe IOC handling |
| Utility | cidr, example | Network tools, demo |
### Key Design Decisions
- **Zero dependencies**: stdlib only (`asyncio`, `ssl`, `tomllib`, `importlib`)
- **Zero dependencies**: stdlib only (`asyncio`, `ssl`, `tomllib`, `struct`, `ipaddress`, `hashlib`)
- **Decorator-based plugins**: `@command` and `@event` for clean registration
- **File-based plugin loading**: drop `.py` files in `plugins/` directory
- **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`

56
README.md
View File

@@ -1,45 +1,51 @@
# derp
Asyncio IRC bot for Python 3.11+ with a decorator-based plugin system. Zero external dependencies.
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
```bash
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
```bash
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
- Built-in commands: `!ping`, `!help`, `!version`
- Containerized deployment via Podman
## Configuration
## Plugins
Edit `config/derp.toml`:
```toml
[server]
host = "irc.libera.chat"
port = 6697
tls = true
nick = "derp"
[bot]
prefix = "!"
channels = ["#test"]
plugins_dir = "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
Create a `.py` file in `plugins/`:
```python
from derp.plugin import command, event
@@ -53,15 +59,19 @@ async def on_join(bot, message):
await bot.send(message.target, f"Welcome, {message.nick}")
```
## Commands
## Make Targets
| Command | Description |
|---------|-------------|
| Target | Description |
|--------|-------------|
| `make install` | Create venv and install |
| `make test` | Run test suite |
| `make lint` | Lint with ruff |
| `make run` | Start the bot |
| `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

58
ROADMAP.md
View File

@@ -1,33 +1,67 @@
# derp - Roadmap
## v0.1.0 (current)
## v0.1.0 -- Foundation (done)
- [x] IRC protocol: connect, parse, send
- [x] TLS support
- [x] TLS support with optional verification
- [x] Plugin system with `@command` and `@event`
- [x] TOML configuration
- [x] TOML configuration with defaults merging
- [x] Built-in plugins: ping, help, version
- [x] Auto PING/PONG, nick recovery, reconnect
- [x] CLI entry point
- [x] CLI entry point with argparse
## v0.2.0
## v0.2.0 -- Operational Toolkit (current)
- [ ] Plugin hot-reload (`!reload` command)
- [ ] Per-channel plugin enable/disable
- [x] Plugin hot-reload (!load, !reload, !unload, !plugins)
- [x] Command shorthand (unambiguous prefix matching)
- [x] Plugin help (!help <plugin>)
- [x] Container support (Containerfile, podman-compose)
- [x] DNS plugin (raw UDP resolver, all record types)
- [x] Encode/decode plugin (b64, hex, url, rot13)
- [x] Hash plugin (generation + type identification)
- [x] Defang/refang plugin (IOC sanitization)
- [x] Reverse shell generator (11 languages)
- [x] CIDR calculator plugin
- [x] Bot uptime command
- [ ] SASL authentication
- [ ] Rate limiting (anti-flood)
- [ ] CTCP VERSION/TIME/PING responses
## v0.3.0
## v0.3.0 -- Wave 2 Plugins
- [ ] WHOIS plugin (raw socket, port 43)
- [ ] Port scanner plugin (async TCP connect)
- [ ] HTTP check plugin (status, redirects, timing)
- [ ] TLS check plugin (cipher, cert chain, expiry)
- [ ] DNSBL/blacklist check plugin
- [ ] Random generator plugin (passwords, UUIDs, hex)
- [ ] Timer plugin (countdown for time-boxed ops)
- [ ] Admin system (owner/admin nicks in config)
- [ ] Permissions per command
- [ ] Channel management commands (kick, ban, topic)
- [ ] Plugin state persistence (sqlite)
## v1.0.0
## v0.4.0 -- Wave 3 Plugins (Local Databases)
- [ ] GeoIP plugin (MaxMind GeoLite2-City mmdb)
- [ ] ASN plugin (GeoLite2-ASN mmdb)
- [ ] Tor exit node check (local list, daily refresh)
- [ ] IP reputation plugin (Firehol blocklist feeds)
- [ ] CVE lookup plugin (local NVD JSON feed)
- [ ] Data update cron/script for all local databases
## v0.5.0 -- Wave 4 Plugins (Advanced)
- [ ] Operational logging plugin (SQLite per-channel)
- [ ] Persistent notes plugin (per-channel key-value)
- [ ] Subdomain enumeration (crt.sh + wordlist DNS brute)
- [ ] HTTP header fingerprinting (local signature db)
- [ ] ExploitDB search (local CSV clone)
- [ ] Payload template library (SQLi, XSS, SSTI)
## v1.0.0 -- Stable
- [ ] Multi-server support
- [ ] IRCv3 capability negotiation
- [ ] Message tags support
- [ ] Stable plugin API
- [ ] Stable plugin API (versioned)
- [ ] Channel management commands (kick, ban, topic)
- [ ] Plugin state persistence (SQLite)

34
TASKS.md
View File

@@ -1,16 +1,28 @@
# derp - Tasks
## Current (2026-02-15)
## Current Sprint (2026-02-15)
| Pri | Status | Task |
|-----|--------|------|
| P0 | [x] | Core IRC protocol implementation |
| P0 | [x] | Plugin system with decorators |
| P0 | [x] | Bot orchestrator with reconnect |
| P0 | [x] | CLI entry point |
| P0 | [x] | Built-in plugins (core, example) |
| P0 | [x] | Unit tests for parser and plugins |
| P0 | [x] | Documentation |
| P1 | [ ] | Test against live IRC server |
| P1 | [x] | crt.sh CT lookup plugin (`!cert`) |
| P2 | [ ] | SASL authentication |
| P0 | [x] | Hot-reload: !load, !reload, !unload, !plugins |
| P0 | [x] | Command shorthand (prefix matching) |
| P0 | [x] | Container support (Containerfile + podman-compose) |
| P0 | [x] | Wave 1 plugins: dns, encode, hash, defang, revshell, cidr |
| P0 | [x] | Plugin help: !help <plugin> shows description + commands |
| P0 | [x] | Bot uptime command |
| P0 | [x] | Documentation update (all docs current) |
| P1 | [ ] | SASL PLAIN authentication |
| P1 | [ ] | Rate limiting for outgoing messages |
| P1 | [ ] | CTCP responses (VERSION, TIME, PING) |
| P2 | [ ] | Admin/owner permission system |
## Completed
| Date | Task |
|------|------|
| 2026-02-15 | Wave 1 plugins (dns, encode, hash, defang, revshell, cidr) |
| 2026-02-15 | Hot-reload, shorthand, plugin help |
| 2026-02-15 | Container deployment (Containerfile, compose, Makefile targets) |
| 2026-02-15 | crt.sh CT lookup plugin |
| 2026-02-15 | TLS verify option for self-signed certs |
| 2026-02-15 | Initial implementation (IRC, plugins, config, CLI) |

54
TODO.md
View File

@@ -1,23 +1,59 @@
# derp - Backlog
## Features
## Wave 2 Plugins (stdlib, next up)
- [ ] `whois` -- raw socket WHOIS client (port 43)
- [ ] `portcheck` -- async TCP connect scan
- [ ] `httpcheck` -- HTTP status, redirects, response time
- [ ] `tlscheck` -- TLS version, cipher suite, cert chain, expiry
- [ ] `blacklist` -- DNSBL/RBL IP check
- [ ] `rand` -- passwords, hex strings, UUIDs
- [ ] `timer` -- countdown/stopwatch for time-boxed ops
## Wave 3 Plugins (local databases)
- [ ] `geoip` -- GeoLite2-City mmdb (requires `maxminddb`)
- [ ] `asn` -- GeoLite2-ASN mmdb (same package)
- [ ] `torcheck` -- local Tor exit node list, daily refresh
- [ ] `iprep` -- Firehol/Emerging Threats blocklist feeds
- [ ] `cve` -- local NVD JSON feed mirror
## Wave 4 Plugins (advanced)
- [ ] `opslog` -- timestamped operational notes (SQLite)
- [ ] `note` -- per-channel persistent key-value store
- [ ] `subdomain` -- crt.sh + wordlist DNS brute force
- [ ] `headers` -- HTTP header fingerprinting with local sigs
- [ ] `exploitdb` -- local exploit-db CSV search
- [ ] `payload` -- SQLi/XSS/SSTI template library
- [ ] `username` -- cross-platform username enumeration
- [ ] `emailcheck` -- SMTP VRFY/RCPT TO verification
- [ ] `dork` -- Google dork query builder
- [ ] `wayback` -- Wayback Machine snapshot lookup
- [ ] `canary` -- canary token generator/tracker
## Bot Features
- [ ] Plugin hot-reload command
- [ ] SASL PLAIN authentication
- [ ] Admin/owner permission system
- [ ] Rate limiting for outgoing messages
- [ ] Rate limiting (anti-flood, token bucket)
- [ ] CTCP responses (VERSION, TIME, PING)
- [ ] Admin/owner permission system (hostmask-based)
- [ ] Per-channel plugin enable/disable
- [ ] Channel management commands (kick, ban, topic)
- [ ] Multi-server support
- [ ] IRCv3 capability negotiation
## Improvements
- [ ] Structured logging (JSON option)
- [ ] Plugin state persistence
- [ ] Channel-specific plugin config
- [ ] Configurable reconnect backoff
- [ ] Structured logging (JSON output option)
- [ ] Plugin state persistence (SQLite backend)
- [ ] Configurable reconnect backoff (exponential)
- [ ] Message truncation for IRC 512-byte limit
- [ ] Data update script for local databases (cron-friendly)
## Testing
- [ ] Integration tests with mock IRC server
- [ ] Bot orchestrator tests
- [ ] Bot orchestrator unit tests
- [ ] Config merge edge case tests
- [ ] Plugin command tests (encode, hash, dns, etc.)

11
docker-compose.yml Normal file
View File

@@ -0,0 +1,11 @@
services:
derp:
build:
context: .
dockerfile: Containerfile
container_name: derp
restart: unless-stopped
volumes:
- ./config/derp.toml:/app/config/derp.toml:ro,Z
- ./plugins:/app/plugins:ro,Z
command: ["--verbose"]

60
docs/CHEATSHEET.md
View File

@@ -1,17 +1,26 @@
# Cheatsheet
## Quick Commands
## Dev Commands
```bash
make install # Setup venv + install
make test # Run tests
make lint # Lint with ruff
make run # Start bot
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
```
## Container
```bash
make build # Build image
make up # Start (podman-compose)
make down # Stop
make logs # Follow logs
```
## Bot Commands
```
@@ -20,13 +29,54 @@ derp -v # Verbose/debug mode
!help <cmd> # Command help
!help <plugin> # Plugin description + commands
!version # Bot version
!uptime # Bot uptime
!echo <text> # Echo text back
!cert <domain> # CT log lookup (max 5 domains)
!h # Shorthand (any unambiguous prefix works)
```
## Plugin Management
```
!plugins # List loaded plugins
!load <plugin> # Hot-load a plugin
!reload <plugin> # Reload a changed plugin
!unload <plugin> # Remove a plugin
!plugins # List loaded plugins
!h # Shorthand (any unambiguous prefix works)
```
## OSINT
```
!dns example.com # A record lookup
!dns 1.2.3.4 # Reverse PTR lookup
!dns example.com MX # Specific type (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA)
!cert example.com # CT log lookup (max 5 domains)
```
## 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
```
## Plugin Template

55
docs/DEBUG.md
View File

@@ -3,7 +3,9 @@
## Verbose Mode
```bash
derp --verbose
derp --verbose # Bare metal
make up # Compose (--verbose in compose file)
podman run ... derp --verbose # Manual container
```
Shows all IRC traffic:
@@ -24,6 +26,15 @@ Set in `config/derp.toml`:
level = "debug" # debug, info, warning, error
```
Or override with `--verbose` flag (forces debug).
## Container Logs
```bash
make logs # podman-compose
podman logs -f derp # direct
```
## Common Issues
### Connection refused
@@ -35,10 +46,11 @@ ERROR derp.irc connection lost: [Errno 111] Connection refused
- Check `host` and `port` in config
- Verify TLS setting matches port (6697 = TLS, 6667 = plain)
- Test connectivity: `nc -zv <host> <port>`
- In container: ensure DNS resolution works (check `/etc/resolv.conf`)
### Nickname in use
The bot appends `_` to the nick and retries automatically. Check logs for:
The bot appends `_` to the nick and retries automatically:
```
<<< :server 433 * derp :Nickname is already in use
@@ -47,7 +59,12 @@ The bot appends `_` to the nick and retries automatically. Check logs for:
### TLS certificate errors
If the server uses a self-signed certificate, you may need to adjust the SSL context. Currently uses system default CA bundle.
For self-signed certificates, set `tls_verify = false` in config:
```toml
[server]
tls_verify = false
```
### Plugin load failures
@@ -55,15 +72,30 @@ If the server uses a self-signed certificate, you may need to adjust the SSL con
ERROR derp.plugin failed to load plugin: plugins/broken.py
```
- Check plugin file for syntax errors: `python -c "import plugins.broken"`
- Check plugin for syntax errors: `python -c "import py_compile; py_compile.compile('plugins/broken.py')"`
- Ensure handlers are `async def`
- Check imports (`from derp.plugin import command, event`)
- In container with mounted plugins: verify mount path and permissions
### No response to commands
- Verify `prefix` in config matches what you type
- Check that the plugin is loaded (look for "loaded plugin" in verbose output)
- Ensure the bot has joined the channel
- Check that the plugin is loaded: `!plugins`
- Ensure the bot has joined the channel (check logs for `JOIN`)
- Try `!ping` first to confirm basic connectivity
### Hot-reload issues
- `!reload <plugin>` re-reads the file from disk
- In container: plugins are mounted read-only, edit on host then `!reload`
- Core plugin cannot be unloaded (but can be reloaded)
- Check logs for `loaded plugin` / `unloaded plugin` messages
### DNS plugin timeouts
- The DNS plugin uses raw UDP to the system resolver
- In container: resolver is typically `127.0.0.11` (Podman DNS)
- Fallback: `8.8.8.8` if no resolver found in `/etc/resolv.conf`
## Testing IRC Connection
@@ -72,3 +104,14 @@ ERROR derp.plugin failed to load plugin: plugins/broken.py
openssl s_client -connect irc.libera.chat:6697
# Then type: NICK testbot / USER testbot 0 * :test
```
## Inspecting State
From IRC, use these commands:
```
!plugins # List loaded plugins + handler counts
!help <plugin> # Show plugin description + commands
!uptime # Bot uptime
!version # Running version
```

47
docs/INSTALL.md
View File

@@ -5,7 +5,11 @@
- Python 3.11+
- git
## Setup
For container deployment:
- podman
- podman-compose
## Bare Metal
```bash
cd ~/git/derp
@@ -14,7 +18,7 @@ make install
This creates a `.venv`, installs derp in editable mode, and adds dev tools.
## Symlink
### Symlink
```bash
make link
@@ -27,7 +31,7 @@ which derp
derp --version
```
## Manual Install
### Manual Install
```bash
python3 -m venv .venv
@@ -35,13 +39,34 @@ source .venv/bin/activate
pip install -e .
```
## Configuration
## Container (Podman)
Copy and edit the default config:
### With podman-compose
```bash
cp config/derp.toml ~/.config/derp/derp.toml
# Edit server, nick, channels
cp config/derp.toml.example config/derp.toml
# Edit config/derp.toml
make up
```
### Manual
```bash
podman build -t derp .
podman run -d --name derp \
-v ./config/derp.toml:/app/config/derp.toml:ro,Z \
-v ./plugins:/app/plugins:ro,Z \
derp --verbose
```
The image contains only the Python package. Config and plugins are bind-mounted at runtime, so edits on the host are picked up by `!reload` without rebuilding.
## Configuration
Copy and edit the example config:
```bash
cp config/derp.toml.example config/derp.toml
```
Config search order:
@@ -50,3 +75,11 @@ Config search order:
2. `./config/derp.toml`
3. `~/.config/derp/derp.toml`
4. Built-in defaults
## Verification
```bash
derp --version # Check install
make test # Run test suite
make lint # Lint check
```

11
docs/USAGE.md
View File

@@ -51,12 +51,23 @@ level = "info" # Logging level: debug, info, warning, error
| `!help <cmd>` | Show help for a specific command |
| `!help <plugin>` | Show plugin description and its commands |
| `!version` | Show bot version |
| `!uptime` | Show how long the bot has been running |
| `!echo <text>` | Echo back text (example plugin) |
| `!cert <domain> [...]` | Lookup CT logs for up to 5 domains |
| `!load <plugin>` | Hot-load a plugin from the plugins directory |
| `!reload <plugin>` | Reload a plugin, picking up file changes |
| `!unload <plugin>` | Unload a plugin, removing its handlers |
| `!plugins` | List loaded plugins with handler counts |
| `!dns <target> [type]` | DNS lookup (A, AAAA, MX, NS, TXT, CNAME, PTR, SOA) |
| `!encode <fmt> <text>` | Encode text (b64, hex, url, rot13) |
| `!decode <fmt> <text>` | Decode text (b64, hex, url, rot13) |
| `!hash [algo] <text>` | Generate hash digests (md5, sha1, sha256, sha512) |
| `!hashid <hash>` | Identify hash type by format |
| `!defang <ioc>` | Defang URLs/IPs/domains for safe sharing |
| `!refang <text>` | Restore defanged IOCs |
| `!revshell <type> <ip> <port>` | Generate reverse shell one-liner |
| `!cidr <network>` | Subnet info (range, hosts, mask) |
| `!cidr contains <net> <ip>` | Check if IP belongs to network |
### Command Shorthand