docs: add podman-compose, update all project documentation

- 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>
2026-02-15 01:46:21 +01:00
parent 2e2378d3ee
commit c5b0430da8
11 changed files with 351 additions and 80 deletions
--- a/docs/CHEATSHEET.md
+++ b/docs/CHEATSHEET.md
@@ -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
--- a/docs/DEBUG.md
+++ b/docs/DEBUG.md
@@ -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
+```
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -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
+```
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -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