c5b0430da8
- 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>
86 lines
2.4 KiB
Markdown
86 lines
2.4 KiB
Markdown
# derp
|
|
|
|
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
|
|
- Containerized deployment via Podman
|
|
|
|
## 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
|
|
|
|
```python
|
|
from derp.plugin import command, event
|
|
|
|
@command("greet", help="Say hello")
|
|
async def cmd_greet(bot, message):
|
|
await bot.reply(message, f"Hello, {message.nick}!")
|
|
|
|
@event("JOIN")
|
|
async def on_join(bot, message):
|
|
if message.nick != bot.nick:
|
|
await bot.send(message.target, f"Welcome, {message.nick}")
|
|
```
|
|
|
|
## Make Targets
|
|
|
|
| Target | Description |
|
|
|--------|-------------|
|
|
| `make install` | Create venv and install |
|
|
| `make test` | Run test suite |
|
|
| `make lint` | Lint with ruff |
|
|
| `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
|
|
|
|
- [Installation](docs/INSTALL.md)
|
|
- [Usage Guide](docs/USAGE.md)
|
|
- [Cheatsheet](docs/CHEATSHEET.md)
|
|
- [Debugging](docs/DEBUG.md)
|
|
|
|
## License
|
|
|
|
MIT
|