# 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