Files

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

2026-02-15 01:46:21 +01:00

2.2 KiB

Raw Blame History

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

2.2 KiB Raw Blame History