diff --git a/README.md b/README.md index c9e5823..2cf93ac 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # derp -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. +Asyncio IRC bot for Python 3.11+ with a decorator-based plugin system. Built for red team ops, OSINT, and OPSEC workflows. ## Quick Start @@ -22,19 +22,20 @@ make down # Stop ## Features -- Async IRC over plain TCP or TLS +- Async IRC over plain TCP or TLS (SASL PLAIN auth) - Plugin system with `@command` and `@event` decorators - Hot-reload: load, unload, reload plugins at runtime +- Admin permission system (hostmask patterns + IRCOP detection) - Command shorthand: `!h` resolves to `!help` (unambiguous prefix matching) - TOML configuration with sensible defaults -- Auto reconnect, nick recovery, PING/PONG handling +- Rate limiting, CTCP responses, auto reconnect - Containerized deployment via Podman ## Plugins | Plugin | Commands | Description | |--------|----------|-------------| -| core | ping, help, version, uptime, load, reload, unload, plugins | Bot management | +| core | ping, help, version, uptime, whoami, admins, load, reload, unload, plugins | Bot management | | dns | dns | Raw UDP DNS resolver (A/AAAA/MX/NS/TXT/CNAME/PTR/SOA) | | encode | encode, decode | Base64, hex, URL, ROT13 | | hash | hash, hashid | Hash generation + type identification | @@ -42,6 +43,13 @@ make down # Stop | 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 | | example | echo | Demo plugin | ## Writing Plugins diff --git a/ROADMAP.md b/ROADMAP.md index 8630667..4eec3a2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -10,7 +10,7 @@ - [x] Auto PING/PONG, nick recovery, reconnect - [x] CLI entry point with argparse -## v0.2.0 -- Operational Toolkit (current) +## v0.2.0 -- Operational Toolkit (done) - [x] Plugin hot-reload (!load, !reload, !unload, !plugins) - [x] Command shorthand (unambiguous prefix matching) @@ -23,30 +23,30 @@ - [x] Reverse shell generator (11 languages) - [x] CIDR calculator plugin - [x] Bot uptime command -- [ ] SASL authentication -- [ ] Rate limiting (anti-flood) -- [ ] CTCP VERSION/TIME/PING responses +- [x] SASL PLAIN authentication +- [x] Rate limiting (anti-flood, token bucket) +- [x] CTCP VERSION/TIME/PING responses -## v0.3.0 -- Wave 2 Plugins +## v0.3.0 -- Wave 2 + Admin (done) -- [ ] 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) -- [ ] Permissions per command +- [x] WHOIS plugin (raw socket, port 43) +- [x] Port scanner plugin (async TCP connect) +- [x] HTTP check plugin (status, redirects, timing) +- [x] TLS check plugin (cipher, cert chain, expiry) +- [x] DNSBL/blacklist check plugin +- [x] Random generator plugin (passwords, UUIDs, hex) +- [x] Timer plugin (countdown for time-boxed ops) +- [x] Admin/owner permission system (hostmask + IRCOP) +- [x] !whoami and !admins commands -## v0.4.0 -- Wave 3 Plugins (Local Databases) +## v0.4.0 -- Wave 3 Plugins (Local Databases) (current) - [ ] 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 +- [ ] Data update script (cron-friendly, all local DBs) ## v0.5.0 -- Wave 4 Plugins (Advanced) diff --git a/TASKS.md b/TASKS.md index df2cbf5..4612e17 100644 --- a/TASKS.md +++ b/TASKS.md @@ -1,27 +1,23 @@ # derp - Tasks -## Current Sprint (2026-02-15) +## Current Sprint -- v0.4.0 Wave 3 (2026-02-15) | Pri | Status | Task | |-----|--------|------| -| P0 | [x] | Hot-reload: !load, !reload, !unload, !plugins | -| P0 | [x] | Command shorthand (prefix matching) | -| P0 | [x] | Container support (Containerfile + podman-compose) | -| P0 | [x] | Wave 1 plugins: dns, encode, hash, defang, revshell, cidr | -| P0 | [x] | Plugin help: !help shows description + commands | -| P0 | [x] | Bot uptime command | -| P0 | [x] | Documentation update (all docs current) | -| P0 | [x] | Wave 2 plugins: whois, portcheck, httpcheck, tlscheck, blacklist, rand, timer | -| P0 | [x] | CLI --cprofile flag | -| P1 | [ ] | SASL PLAIN authentication | -| P1 | [ ] | Rate limiting for outgoing messages | -| P1 | [ ] | CTCP responses (VERSION, TIME, PING) | -| P2 | [ ] | Admin/owner permission system | +| P0 | [ ] | GeoIP plugin (GeoLite2-City mmdb) | +| P0 | [ ] | ASN plugin (GeoLite2-ASN mmdb) | +| P0 | [ ] | Tor exit node check plugin | +| P0 | [ ] | IP reputation plugin (Firehol blocklists) | +| P0 | [ ] | CVE lookup plugin (NVD JSON feed) | +| P0 | [ ] | Data update script (scripts/update-data.sh) | +| P1 | [ ] | Documentation update (all docs current) | ## Completed | Date | Task | |------|------| +| 2026-02-15 | Admin/owner permission system (hostmask + IRCOP) | +| 2026-02-15 | SASL PLAIN, rate limiting, CTCP responses | | 2026-02-15 | Wave 2 plugins (whois, portcheck, httpcheck, tlscheck, blacklist, rand, timer) | | 2026-02-15 | CLI --cprofile flag | | 2026-02-15 | Wave 1 plugins (dns, encode, hash, defang, revshell, cidr) | diff --git a/TODO.md b/TODO.md index 6186fb9..516c36d 100644 --- a/TODO.md +++ b/TODO.md @@ -1,16 +1,6 @@ # derp - Backlog -## Wave 2 Plugins (stdlib) -- DONE - -- [x] `whois` -- raw socket WHOIS client (port 43) -- [x] `portcheck` -- async TCP connect scan -- [x] `httpcheck` -- HTTP status, redirects, response time -- [x] `tlscheck` -- TLS version, cipher suite, cert chain, expiry -- [x] `blacklist` -- DNSBL/RBL IP check -- [x] `rand` -- passwords, hex strings, UUIDs -- [x] `timer` -- countdown/stopwatch for time-boxed ops - -## Wave 3 Plugins (local databases) +## Wave 3 Plugins (local databases) -- CURRENT - [ ] `geoip` -- GeoLite2-City mmdb (requires `maxminddb`) - [ ] `asn` -- GeoLite2-ASN mmdb (same package) @@ -34,10 +24,10 @@ ## Bot Features -- [ ] SASL PLAIN authentication -- [ ] Rate limiting (anti-flood, token bucket) -- [ ] CTCP responses (VERSION, TIME, PING) -- [ ] Admin/owner permission system (hostmask-based) +- [x] SASL PLAIN authentication +- [x] Rate limiting (anti-flood, token bucket) +- [x] CTCP responses (VERSION, TIME, PING) +- [x] Admin/owner permission system (hostmask-based) - [ ] Per-channel plugin enable/disable - [ ] Channel management commands (kick, ban, topic) - [ ] Multi-server support