username/derp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add podman-compose, update all project documentation

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

34
PROJECT.md
View File

@@ -2,7 +2,7 @@
## Purpose
A lightweight, zero-dependency asyncio IRC bot with a clean plugin system for Python 3.11+.
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
@@ -10,7 +10,7 @@ A lightweight, zero-dependency asyncio IRC bot with a clean plugin system for Py
CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
|-> IRCConnection (async TCP/TLS)
|-> PluginRegistry (decorators, loader)
|-> plugins/*.py
|-> plugins/*.py (hot-reloadable)
```
### Modules
@@ -20,18 +20,40 @@ CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
| `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 file loader |
| `bot.py` | Orchestrator: connect, dispatch, reconnect |
| `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`, `importlib`)
- **Zero dependencies**: stdlib only (`asyncio`, `ssl`, `tomllib`, `struct`, `ipaddress`, `hashlib`)
- **Decorator-based plugins**: `@command` and `@event` for clean registration
- **File-based plugin loading**: drop `.py` files in `plugins/` directory
- **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`