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>
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

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