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

11
Makefile
View File

@@ -1,4 +1,4 @@
.PHONY: install dev test lint clean help build container-run container-stop container-logs .PHONY: install dev test lint clean help build container-run container-stop container-logs up down logs
APP_NAME := derp APP_NAME := derp
VENV := .venv VENV := .venv
@@ -53,3 +53,12 @@ container-stop: ## Stop and remove container
container-logs: ## Follow container logs container-logs: ## Follow container logs
podman logs -f $(APP_NAME) podman logs -f $(APP_NAME)
up: ## Start with podman-compose (build + detach)
podman-compose up -d --build
down: ## Stop with podman-compose
podman-compose down
logs: ## Follow compose logs
podman-compose logs -f

34
PROJECT.md
View File

@@ -2,7 +2,7 @@
## Purpose ## 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 ## 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) CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
|-> IRCConnection (async TCP/TLS) |-> IRCConnection (async TCP/TLS)
|-> PluginRegistry (decorators, loader) |-> PluginRegistry (decorators, loader)
|-> plugins/*.py |-> plugins/*.py (hot-reloadable)
``` ```
### Modules ### Modules
@@ -20,18 +20,40 @@ CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
| `cli.py` | Argument parsing, logging setup, entry point | | `cli.py` | Argument parsing, logging setup, entry point |
| `config.py` | TOML loader with defaults merging | | `config.py` | TOML loader with defaults merging |
| `irc.py` | IRC protocol: message parsing, formatting, async connection | | `irc.py` | IRC protocol: message parsing, formatting, async connection |
| `plugin.py` | Decorator-based plugin system with file loader | | `plugin.py` | Decorator-based plugin system with hot-reload |
| `bot.py` | Orchestrator: connect, dispatch, reconnect | | `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 ### 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 - **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` - **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 ## Dependencies
- Python 3.11+ (for `tomllib`) - Python 3.11+ (for `tomllib`)
- No external packages required at runtime - No external packages required at runtime
- Dev: `pytest`, `ruff` - Dev: `pytest`, `ruff`
- Container: `podman`, `podman-compose`

56
README.md
View File

@@ -1,45 +1,51 @@
# derp # 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 ## Quick Start
```bash ```bash
git clone <repo> ~/git/derp && cd ~/git/derp git clone <repo> ~/git/derp && cd ~/git/derp
make install make install
cp config/derp.toml.example config/derp.toml
# Edit config/derp.toml with your server details # Edit config/derp.toml with your server details
make run make run
``` ```
### Container
```bash
make up # Build + start with podman-compose
make logs # Follow logs
make down # Stop
```
## Features ## Features
- Async IRC over plain TCP or TLS - Async IRC over plain TCP or TLS
- Plugin system with `@command` and `@event` decorators - 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 - TOML configuration with sensible defaults
- Auto reconnect, nick recovery, PING/PONG handling - Auto reconnect, nick recovery, PING/PONG handling
- Built-in commands: `!ping`, `!help`, `!version` - Containerized deployment via Podman
## Configuration ## Plugins
Edit `config/derp.toml`: | Plugin | Commands | Description |
|--------|----------|-------------|
```toml | core | ping, help, version, uptime, load, reload, unload, plugins | Bot management |
[server] | dns | dns | Raw UDP DNS resolver (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA) |
host = "irc.libera.chat" | encode | encode, decode | Base64, hex, URL, ROT13 |
port = 6697 | hash | hash, hashid | Hash generation + type identification |
tls = true | defang | defang, refang | IOC defanging for safe sharing |
nick = "derp" | revshell | revshell | Reverse shell one-liners (11 languages) |
| cidr | cidr | Subnet calculator + IP membership check |
[bot] | crtsh | cert | Certificate transparency log lookup |
prefix = "!" | example | echo | Demo plugin |
channels = ["#test"]
plugins_dir = "plugins"
```
## Writing Plugins ## Writing Plugins
Create a `.py` file in `plugins/`:
```python ```python
from derp.plugin import command, event 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}") await bot.send(message.target, f"Welcome, {message.nick}")
``` ```
## Commands ## Make Targets
| Command | Description | | Target | Description |
|---------|-------------| |--------|-------------|
| `make install` | Create venv and install | | `make install` | Create venv and install |
| `make test` | Run test suite | | `make test` | Run test suite |
| `make lint` | Lint with ruff | | `make lint` | Lint with ruff |
| `make run` | Start the bot | | `make run` | Start the bot (bare metal) |
| `make link` | Symlink to `~/.local/bin/` | | `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 ## Documentation

58
ROADMAP.md
View File

@@ -1,33 +1,67 @@
# derp - Roadmap # derp - Roadmap
## v0.1.0 (current) ## v0.1.0 -- Foundation (done)
- [x] IRC protocol: connect, parse, send - [x] IRC protocol: connect, parse, send
- [x] TLS support - [x] TLS support with optional verification
- [x] Plugin system with `@command` and `@event` - [x] Plugin system with `@command` and `@event`
- [x] TOML configuration - [x] TOML configuration with defaults merging
- [x] Built-in plugins: ping, help, version - [x] Built-in plugins: ping, help, version
- [x] Auto PING/PONG, nick recovery, reconnect - [x] Auto PING/PONG, nick recovery, reconnect
- [x] CLI entry point - [x] CLI entry point with argparse
## v0.2.0 ## v0.2.0 -- Operational Toolkit (current)
- [ ] Plugin hot-reload (`!reload` command) - [x] Plugin hot-reload (!load, !reload, !unload, !plugins)
- [ ] Per-channel plugin enable/disable - [x] Command shorthand (unambiguous prefix matching)
- [x] Plugin help (!help <plugin>)
- [x] Container support (Containerfile, podman-compose)
- [x] DNS plugin (raw UDP resolver, all record types)
- [x] Encode/decode plugin (b64, hex, url, rot13)
- [x] Hash plugin (generation + type identification)
- [x] Defang/refang plugin (IOC sanitization)
- [x] Reverse shell generator (11 languages)
- [x] CIDR calculator plugin
- [x] Bot uptime command
- [ ] SASL authentication - [ ] SASL authentication
- [ ] Rate limiting (anti-flood) - [ ] Rate limiting (anti-flood)
- [ ] CTCP VERSION/TIME/PING responses - [ ] CTCP VERSION/TIME/PING responses
## v0.3.0 ## v0.3.0 -- Wave 2 Plugins
- [ ] WHOIS plugin (raw socket, port 43)
- [ ] Port scanner plugin (async TCP connect)
- [ ] HTTP check plugin (status, redirects, timing)
- [ ] TLS check plugin (cipher, cert chain, expiry)
- [ ] DNSBL/blacklist check plugin
- [ ] Random generator plugin (passwords, UUIDs, hex)
- [ ] Timer plugin (countdown for time-boxed ops)
- [ ] Admin system (owner/admin nicks in config) - [ ] Admin system (owner/admin nicks in config)
- [ ] Permissions per command - [ ] Permissions per command
- [ ] Channel management commands (kick, ban, topic)
- [ ] Plugin state persistence (sqlite)
## v1.0.0 ## v0.4.0 -- Wave 3 Plugins (Local Databases)
- [ ] GeoIP plugin (MaxMind GeoLite2-City mmdb)
- [ ] ASN plugin (GeoLite2-ASN mmdb)
- [ ] Tor exit node check (local list, daily refresh)
- [ ] IP reputation plugin (Firehol blocklist feeds)
- [ ] CVE lookup plugin (local NVD JSON feed)
- [ ] Data update cron/script for all local databases
## v0.5.0 -- Wave 4 Plugins (Advanced)
- [ ] Operational logging plugin (SQLite per-channel)
- [ ] Persistent notes plugin (per-channel key-value)
- [ ] Subdomain enumeration (crt.sh + wordlist DNS brute)
- [ ] HTTP header fingerprinting (local signature db)
- [ ] ExploitDB search (local CSV clone)
- [ ] Payload template library (SQLi, XSS, SSTI)
## v1.0.0 -- Stable
- [ ] Multi-server support - [ ] Multi-server support
- [ ] IRCv3 capability negotiation - [ ] IRCv3 capability negotiation
- [ ] Message tags support - [ ] Message tags support
- [ ] Stable plugin API - [ ] Stable plugin API (versioned)
- [ ] Channel management commands (kick, ban, topic)
- [ ] Plugin state persistence (SQLite)

34
TASKS.md
View File

@@ -1,16 +1,28 @@
# derp - Tasks # derp - Tasks
## Current (2026-02-15) ## Current Sprint (2026-02-15)
| Pri | Status | Task | | Pri | Status | Task |
|-----|--------|------| |-----|--------|------|
| P0 | [x] | Core IRC protocol implementation | | P0 | [x] | Hot-reload: !load, !reload, !unload, !plugins |
| P0 | [x] | Plugin system with decorators | | P0 | [x] | Command shorthand (prefix matching) |
| P0 | [x] | Bot orchestrator with reconnect | | P0 | [x] | Container support (Containerfile + podman-compose) |
| P0 | [x] | CLI entry point | | P0 | [x] | Wave 1 plugins: dns, encode, hash, defang, revshell, cidr |
| P0 | [x] | Built-in plugins (core, example) | | P0 | [x] | Plugin help: !help <plugin> shows description + commands |
| P0 | [x] | Unit tests for parser and plugins | | P0 | [x] | Bot uptime command |
| P0 | [x] | Documentation | | P0 | [x] | Documentation update (all docs current) |
| P1 | [ ] | Test against live IRC server | | P1 | [ ] | SASL PLAIN authentication |
| P1 | [x] | crt.sh CT lookup plugin (`!cert`) | | P1 | [ ] | Rate limiting for outgoing messages |
| P2 | [ ] | SASL authentication | | P1 | [ ] | CTCP responses (VERSION, TIME, PING) |
| P2 | [ ] | Admin/owner permission system |
## Completed
| Date | Task |
|------|------|
| 2026-02-15 | Wave 1 plugins (dns, encode, hash, defang, revshell, cidr) |
| 2026-02-15 | Hot-reload, shorthand, plugin help |
| 2026-02-15 | Container deployment (Containerfile, compose, Makefile targets) |
| 2026-02-15 | crt.sh CT lookup plugin |
| 2026-02-15 | TLS verify option for self-signed certs |
| 2026-02-15 | Initial implementation (IRC, plugins, config, CLI) |

54
TODO.md
View File

@@ -1,23 +1,59 @@
# derp - Backlog # derp - Backlog
## Features ## Wave 2 Plugins (stdlib, next up)
- [ ] `whois` -- raw socket WHOIS client (port 43)
- [ ] `portcheck` -- async TCP connect scan
- [ ] `httpcheck` -- HTTP status, redirects, response time
- [ ] `tlscheck` -- TLS version, cipher suite, cert chain, expiry
- [ ] `blacklist` -- DNSBL/RBL IP check
- [ ] `rand` -- passwords, hex strings, UUIDs
- [ ] `timer` -- countdown/stopwatch for time-boxed ops
## Wave 3 Plugins (local databases)
- [ ] `geoip` -- GeoLite2-City mmdb (requires `maxminddb`)
- [ ] `asn` -- GeoLite2-ASN mmdb (same package)
- [ ] `torcheck` -- local Tor exit node list, daily refresh
- [ ] `iprep` -- Firehol/Emerging Threats blocklist feeds
- [ ] `cve` -- local NVD JSON feed mirror
## Wave 4 Plugins (advanced)
- [ ] `opslog` -- timestamped operational notes (SQLite)
- [ ] `note` -- per-channel persistent key-value store
- [ ] `subdomain` -- crt.sh + wordlist DNS brute force
- [ ] `headers` -- HTTP header fingerprinting with local sigs
- [ ] `exploitdb` -- local exploit-db CSV search
- [ ] `payload` -- SQLi/XSS/SSTI template library
- [ ] `username` -- cross-platform username enumeration
- [ ] `emailcheck` -- SMTP VRFY/RCPT TO verification
- [ ] `dork` -- Google dork query builder
- [ ] `wayback` -- Wayback Machine snapshot lookup
- [ ] `canary` -- canary token generator/tracker
## Bot Features
- [ ] Plugin hot-reload command
- [ ] SASL PLAIN authentication - [ ] SASL PLAIN authentication
- [ ] Admin/owner permission system - [ ] Rate limiting (anti-flood, token bucket)
- [ ] Rate limiting for outgoing messages
- [ ] CTCP responses (VERSION, TIME, PING) - [ ] CTCP responses (VERSION, TIME, PING)
- [ ] Admin/owner permission system (hostmask-based)
- [ ] Per-channel plugin enable/disable
- [ ] Channel management commands (kick, ban, topic)
- [ ] Multi-server support - [ ] Multi-server support
- [ ] IRCv3 capability negotiation
## Improvements ## Improvements
- [ ] Structured logging (JSON option) - [ ] Structured logging (JSON output option)
- [ ] Plugin state persistence - [ ] Plugin state persistence (SQLite backend)
- [ ] Channel-specific plugin config - [ ] Configurable reconnect backoff (exponential)
- [ ] Configurable reconnect backoff - [ ] Message truncation for IRC 512-byte limit
- [ ] Data update script for local databases (cron-friendly)
## Testing ## Testing
- [ ] Integration tests with mock IRC server - [ ] Integration tests with mock IRC server
- [ ] Bot orchestrator tests - [ ] Bot orchestrator unit tests
- [ ] Config merge edge case tests - [ ] Config merge edge case tests
- [ ] Plugin command tests (encode, hash, dns, etc.)

11
docker-compose.yml Normal file
View File

@@ -0,0 +1,11 @@
services:
derp:
build:
context: .
dockerfile: Containerfile
container_name: derp
restart: unless-stopped
volumes:
- ./config/derp.toml:/app/config/derp.toml:ro,Z
- ./plugins:/app/plugins:ro,Z
command: ["--verbose"]

60
docs/CHEATSHEET.md
View File

@@ -1,17 +1,26 @@
# Cheatsheet # Cheatsheet
## Quick Commands ## Dev Commands
```bash ```bash
make install # Setup venv + install make install # Setup venv + install
make test # Run tests make test # Run tests
make lint # Lint with ruff make lint # Lint with ruff
make run # Start bot make run # Start bot (bare metal)
make link # Symlink to ~/.local/bin make link # Symlink to ~/.local/bin
derp -c config.toml # Run with custom config derp -c config.toml # Run with custom config
derp -v # Verbose/debug mode derp -v # Verbose/debug mode
``` ```
## Container
```bash
make build # Build image
make up # Start (podman-compose)
make down # Stop
make logs # Follow logs
```
## Bot Commands ## Bot Commands
``` ```
@@ -20,13 +29,54 @@ derp -v # Verbose/debug mode
!help <cmd> # Command help !help <cmd> # Command help
!help <plugin> # Plugin description + commands !help <plugin> # Plugin description + commands
!version # Bot version !version # Bot version
!uptime # Bot uptime
!echo <text> # Echo text back !echo <text> # Echo text back
!cert <domain> # CT log lookup (max 5 domains) !h # Shorthand (any unambiguous prefix works)
```
## Plugin Management
```
!plugins # List loaded plugins
!load <plugin> # Hot-load a plugin !load <plugin> # Hot-load a plugin
!reload <plugin> # Reload a changed plugin !reload <plugin> # Reload a changed plugin
!unload <plugin> # Remove a plugin !unload <plugin> # Remove a plugin
!plugins # List loaded plugins ```
!h # Shorthand (any unambiguous prefix works)
## OSINT
```
!dns example.com # A record lookup
!dns 1.2.3.4 # Reverse PTR lookup
!dns example.com MX # Specific type (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA)
!cert example.com # CT log lookup (max 5 domains)
```
## Red Team
```
!revshell bash 10.0.0.1 4444 # Reverse shell one-liner
!revshell list # List types (bash/sh/nc/nce/python/perl/php/ruby/socat/lua/ps)
!encode b64 hello # Base64 encode
!decode hex 68656c6c6f # Hex decode
!encode rot13 hello # ROT13
!hash hello # MD5 + SHA1 + SHA256
!hash sha512 hello # Specific algorithm
!hashid <hash> # Identify hash type
```
## OPSEC
```
!defang https://evil.com # Defang IOC
!refang hxxps[://]evil[.]com # Refang IOC
```
## Network
```
!cidr 10.0.0.0/24 # Subnet info
!cidr contains 10.0.0.0/8 10.1.2.3 # Membership check
``` ```
## Plugin Template ## Plugin Template

55
docs/DEBUG.md
View File

@@ -3,7 +3,9 @@
## Verbose Mode ## Verbose Mode
```bash ```bash
derp --verbose derp --verbose # Bare metal
make up # Compose (--verbose in compose file)
podman run ... derp --verbose # Manual container
``` ```
Shows all IRC traffic: Shows all IRC traffic:
@@ -24,6 +26,15 @@ Set in `config/derp.toml`:
level = "debug" # debug, info, warning, error level = "debug" # debug, info, warning, error
``` ```
Or override with `--verbose` flag (forces debug).
## Container Logs
```bash
make logs # podman-compose
podman logs -f derp # direct
```
## Common Issues ## Common Issues
### Connection refused ### Connection refused
@@ -35,10 +46,11 @@ ERROR derp.irc connection lost: [Errno 111] Connection refused
- Check `host` and `port` in config - Check `host` and `port` in config
- Verify TLS setting matches port (6697 = TLS, 6667 = plain) - Verify TLS setting matches port (6697 = TLS, 6667 = plain)
- Test connectivity: `nc -zv <host> <port>` - Test connectivity: `nc -zv <host> <port>`
- In container: ensure DNS resolution works (check `/etc/resolv.conf`)
### Nickname in use ### Nickname in use
The bot appends `_` to the nick and retries automatically. Check logs for: The bot appends `_` to the nick and retries automatically:
``` ```
<<< :server 433 * derp :Nickname is already in use <<< :server 433 * derp :Nickname is already in use
@@ -47,7 +59,12 @@ The bot appends `_` to the nick and retries automatically. Check logs for:
### TLS certificate errors ### TLS certificate errors
If the server uses a self-signed certificate, you may need to adjust the SSL context. Currently uses system default CA bundle. For self-signed certificates, set `tls_verify = false` in config:
```toml
[server]
tls_verify = false
```
### Plugin load failures ### Plugin load failures
@@ -55,15 +72,30 @@ If the server uses a self-signed certificate, you may need to adjust the SSL con
ERROR derp.plugin failed to load plugin: plugins/broken.py ERROR derp.plugin failed to load plugin: plugins/broken.py
``` ```
- Check plugin file for syntax errors: `python -c "import plugins.broken"` - Check plugin for syntax errors: `python -c "import py_compile; py_compile.compile('plugins/broken.py')"`
- Ensure handlers are `async def` - Ensure handlers are `async def`
- Check imports (`from derp.plugin import command, event`) - Check imports (`from derp.plugin import command, event`)
- In container with mounted plugins: verify mount path and permissions
### No response to commands ### No response to commands
- Verify `prefix` in config matches what you type - Verify `prefix` in config matches what you type
- Check that the plugin is loaded (look for "loaded plugin" in verbose output) - Check that the plugin is loaded: `!plugins`
- Ensure the bot has joined the channel - Ensure the bot has joined the channel (check logs for `JOIN`)
- Try `!ping` first to confirm basic connectivity
### Hot-reload issues
- `!reload <plugin>` re-reads the file from disk
- In container: plugins are mounted read-only, edit on host then `!reload`
- Core plugin cannot be unloaded (but can be reloaded)
- Check logs for `loaded plugin` / `unloaded plugin` messages
### DNS plugin timeouts
- The DNS plugin uses raw UDP to the system resolver
- In container: resolver is typically `127.0.0.11` (Podman DNS)
- Fallback: `8.8.8.8` if no resolver found in `/etc/resolv.conf`
## Testing IRC Connection ## Testing IRC Connection
@@ -72,3 +104,14 @@ ERROR derp.plugin failed to load plugin: plugins/broken.py
openssl s_client -connect irc.libera.chat:6697 openssl s_client -connect irc.libera.chat:6697
# Then type: NICK testbot / USER testbot 0 * :test # Then type: NICK testbot / USER testbot 0 * :test
``` ```
## Inspecting State
From IRC, use these commands:
```
!plugins # List loaded plugins + handler counts
!help <plugin> # Show plugin description + commands
!uptime # Bot uptime
!version # Running version
```

47
docs/INSTALL.md
View File

@@ -5,7 +5,11 @@
- Python 3.11+ - Python 3.11+
- git - git
## Setup For container deployment:
- podman
- podman-compose
## Bare Metal
```bash ```bash
cd ~/git/derp cd ~/git/derp
@@ -14,7 +18,7 @@ make install
This creates a `.venv`, installs derp in editable mode, and adds dev tools. This creates a `.venv`, installs derp in editable mode, and adds dev tools.
## Symlink ### Symlink
```bash ```bash
make link make link
@@ -27,7 +31,7 @@ which derp
derp --version derp --version
``` ```
## Manual Install ### Manual Install
```bash ```bash
python3 -m venv .venv python3 -m venv .venv
@@ -35,13 +39,34 @@ source .venv/bin/activate
pip install -e . pip install -e .
``` ```
## Configuration ## Container (Podman)
Copy and edit the default config: ### With podman-compose
```bash ```bash
cp config/derp.toml ~/.config/derp/derp.toml cp config/derp.toml.example config/derp.toml
# Edit server, nick, channels # Edit config/derp.toml
make up
```
### Manual
```bash
podman build -t derp .
podman run -d --name derp \
-v ./config/derp.toml:/app/config/derp.toml:ro,Z \
-v ./plugins:/app/plugins:ro,Z \
derp --verbose
```
The image contains only the Python package. Config and plugins are bind-mounted at runtime, so edits on the host are picked up by `!reload` without rebuilding.
## Configuration
Copy and edit the example config:
```bash
cp config/derp.toml.example config/derp.toml
``` ```
Config search order: Config search order:
@@ -50,3 +75,11 @@ Config search order:
2. `./config/derp.toml` 2. `./config/derp.toml`
3. `~/.config/derp/derp.toml` 3. `~/.config/derp/derp.toml`
4. Built-in defaults 4. Built-in defaults
## Verification
```bash
derp --version # Check install
make test # Run test suite
make lint # Lint check
```

11
docs/USAGE.md
View File

@@ -51,12 +51,23 @@ level = "info" # Logging level: debug, info, warning, error
| `!help <cmd>` | Show help for a specific command | | `!help <cmd>` | Show help for a specific command |
| `!help <plugin>` | Show plugin description and its commands | | `!help <plugin>` | Show plugin description and its commands |
| `!version` | Show bot version | | `!version` | Show bot version |
| `!uptime` | Show how long the bot has been running |
| `!echo <text>` | Echo back text (example plugin) | | `!echo <text>` | Echo back text (example plugin) |
| `!cert <domain> [...]` | Lookup CT logs for up to 5 domains | | `!cert <domain> [...]` | Lookup CT logs for up to 5 domains |
| `!load <plugin>` | Hot-load a plugin from the plugins directory | | `!load <plugin>` | Hot-load a plugin from the plugins directory |
| `!reload <plugin>` | Reload a plugin, picking up file changes | | `!reload <plugin>` | Reload a plugin, picking up file changes |
| `!unload <plugin>` | Unload a plugin, removing its handlers | | `!unload <plugin>` | Unload a plugin, removing its handlers |
| `!plugins` | List loaded plugins with handler counts | | `!plugins` | List loaded plugins with handler counts |
| `!dns <target> [type]` | DNS lookup (A, AAAA, MX, NS, TXT, CNAME, PTR, SOA) |
| `!encode <fmt> <text>` | Encode text (b64, hex, url, rot13) |
| `!decode <fmt> <text>` | Decode text (b64, hex, url, rot13) |
| `!hash [algo] <text>` | Generate hash digests (md5, sha1, sha256, sha512) |
| `!hashid <hash>` | Identify hash type by format |
| `!defang <ioc>` | Defang URLs/IPs/domains for safe sharing |
| `!refang <text>` | Restore defanged IOCs |
| `!revshell <type> <ip> <port>` | Generate reverse shell one-liner |
| `!cidr <network>` | Subnet info (range, hosts, mask) |
| `!cidr contains <net> <ip>` | Check if IP belongs to network |
### Command Shorthand ### Command Shorthand