ca46042c41
Add Mumble sections to USAGE.md, CHEATSHEET.md, API.md, README.md. Mark Mumble done in ROADMAP.md and TODO.md. Update TASKS.md sprint.
119 lines
4.4 KiB
Markdown
119 lines
4.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.
|
|
|
|
## 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 build # Build image (only after dependency changes)
|
|
make up # Start with podman-compose
|
|
make logs # Follow logs
|
|
make down # Stop
|
|
```
|
|
|
|
## Features
|
|
|
|
- Async IRC over plain TCP or TLS (SASL PLAIN auth, IRCv3 CAP negotiation)
|
|
- Microsoft Teams support via outgoing webhooks (no SDK dependency)
|
|
- Telegram support via long-polling (no SDK dependency, SOCKS5 proxied)
|
|
- Mumble support via TCP/TLS protobuf control channel (text only, SOCKS5 proxied)
|
|
- Plugin system with `@command` and `@event` decorators
|
|
- Hot-reload: load, unload, reload plugins at runtime
|
|
- Admin permission system (hostmask patterns + IRCOP detection + AAD IDs)
|
|
- Command shorthand: `!h` resolves to `!help` (unambiguous prefix matching)
|
|
- TOML configuration with sensible defaults
|
|
- Rate limiting, CTCP responses, auto reconnect
|
|
- Containerized deployment via Podman
|
|
|
|
## Plugins
|
|
|
|
| Plugin | Commands | Description |
|
|
|--------|----------|-------------|
|
|
| core | ping, help, version, uptime, whoami, admins, load, reload, unload, plugins, state | Bot management |
|
|
| dns | dns | Raw UDP DNS resolver (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA) |
|
|
| tdns | tdns | TCP DNS resolver via SOCKS5 proxy (same record types) |
|
|
| 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 |
|
|
| whois | whois | Raw socket WHOIS (port 43) |
|
|
| portcheck | portcheck | Async TCP port scanner |
|
|
| httpcheck | httpcheck | HTTP status, redirects, response time |
|
|
| tlscheck | tlscheck | TLS version, cipher, cert details |
|
|
| blacklist | blacklist | DNSBL/RBL IP reputation check |
|
|
| rand | rand | Passwords, hex, UUIDs, dice rolls |
|
|
| timer | timer | Countdown timers with notification |
|
|
| geoip | geoip | GeoIP city/country lookup (MaxMind mmdb) |
|
|
| asn | asn | AS number + organization lookup (MaxMind mmdb) |
|
|
| torcheck | tor | Tor exit node check (local list) |
|
|
| iprep | iprep | IP reputation (Firehol/ET blocklists) |
|
|
| cve | cve | CVE lookup + search (local NVD mirror) |
|
|
| opslog | opslog | Timestamped operational notes (SQLite) |
|
|
| note | note | Per-channel persistent key-value store |
|
|
| subdomain | subdomain | Subdomain enum (crt.sh + DNS brute) |
|
|
| headers | headers | HTTP header fingerprinting |
|
|
| exploitdb | exploitdb | Exploit-DB search (local CSV) |
|
|
| payload | payload | SQLi/XSS/SSTI/LFI/CMDi/XXE templates |
|
|
| dork | dork | Google dork query builder |
|
|
| wayback | wayback | Wayback Machine snapshot lookup |
|
|
| username | username | Username enumeration across ~25 services |
|
|
| remind | remind | One-shot, repeating, and calendar reminders |
|
|
| rss | rss | RSS/Atom feed subscriptions with polling |
|
|
| youtube | yt | YouTube channel follow with new-video alerts |
|
|
| twitch | twitch | Twitch livestream notifications (public GQL) |
|
|
| chanmgmt | kick, ban, unban, topic, mode | Channel management (admin) |
|
|
| 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 (only for dependency changes) |
|
|
| `make up` | Start with podman-compose |
|
|
| `make down` | Stop with podman-compose |
|
|
| `make logs` | Follow compose logs |
|
|
|
|
## Documentation
|
|
|
|
- [Plugin API Reference](docs/API.md)
|
|
- [Installation](docs/INSTALL.md)
|
|
- [Usage Guide](docs/USAGE.md)
|
|
- [Cheatsheet](docs/CHEATSHEET.md)
|
|
- [Debugging](docs/DEBUG.md)
|
|
|
|
## License
|
|
|
|
MIT
|