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>
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# derp - Project
|
|
|
|
## Purpose
|
|
|
|
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
|
|
|
|
```
|
|
CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
|
|
|-> IRCConnection (async TCP/TLS)
|
|
|-> PluginRegistry (decorators, loader)
|
|
|-> plugins/*.py (hot-reloadable)
|
|
```
|
|
|
|
### Modules
|
|
|
|
| Module | Role |
|
|
|--------|------|
|
|
| `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 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`, `struct`, `ipaddress`, `hashlib`)
|
|
- **Decorator-based plugins**: `@command` and `@event` for clean registration
|
|
- **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`
|