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:
56
README.md
56
README.md
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user