username/derp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add jwt, mac, abuseipdb, virustotal, and emailcheck plugins

Browse Source 
v2.0.0 sprint 1 -- five standalone plugins requiring no core changes:

- jwt: decode JWT header/payload, flag alg=none/expired/nbf issues
- mac: IEEE OUI vendor lookup, random MAC generation, OUI download
- abuseipdb: IP reputation check + abuse reporting (admin) via API
- virustotal: hash/IP/domain/URL lookup via VT APIv3, 4/min rate limit
- emailcheck: SMTP RCPT TO verification via MX + SOCKS proxy (admin)

Also adds update_oui() to update-data.sh and documents all five
plugins in USAGE.md and CHEATSHEET.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-16 21:04:43 +01:00
parent 75c6ab1e62
commit eb37fef730
8 changed files with 980 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/CHEATSHEET.md
View File

@@ -250,12 +250,33 @@ Categories: sqli, xss, ssti, lfi, cmdi, xxe
!cve search apache rce # Search CVE descriptions
!cve update # Download NVD feed (slow)
!cve stats # Show index size
!mac AA:BB:CC:DD:EE:FF # MAC OUI vendor lookup
!mac random # Generate random MAC
!mac update # Download IEEE OUI database
```
## Security Intelligence (API)
```
!abuse 8.8.8.8 # AbuseIPDB reputation check
!abuse 8.8.8.8 1.1.1.1 # Batch check (max 5)
!abuse 8.8.8.8 report 14 Spam # Report IP (admin)
!vt <hash> # VirusTotal file hash lookup
!vt 8.8.8.8 # VirusTotal IP lookup
!vt example.com # VirusTotal domain lookup
!vt https://evil.com # VirusTotal URL lookup
!jwt eyJhbG... # Decode JWT token
!emailcheck user@example.com # SMTP verification (admin)
```
API keys: set `ABUSEIPDB_API_KEY` / `VIRUSTOTAL_API_KEY` env vars or
configure in `config/derp.toml` under `[abuseipdb]` / `[virustotal]`.
VT rate limit: 4 req/min. Email check: max 5, admin only.
### Data Setup
```bash
./scripts/update-data.sh # Update tor + iprep
./scripts/update-data.sh # Update tor + iprep + oui
MAXMIND_LICENSE_KEY=xxx ./scripts/update-data.sh # + GeoLite2
```

119
docs/USAGE.md
View File

@@ -125,6 +125,12 @@ format = "text" # Log format: "text" (default) or "json"
| `!username list` | Show available services by category |
| `!alert <add\|del\|list\|check\|info\|history>` | Keyword alert subscriptions across platforms |
| `!searx <query>` | Search SearXNG and show top results |
| `!jwt <token>` | Decode JWT header, claims, and flag issues |
| `!mac <address\|random\|update>` | MAC OUI vendor lookup / random MAC |
| `!abuse <ip> [ip2 ...]` | AbuseIPDB reputation check |
| `!abuse <ip> report <cats> <comment>` | Report IP to AbuseIPDB (admin) |
| `!vt <hash\|ip\|domain\|url>` | VirusTotal lookup |
| `!emailcheck <email> [email2 ...]` | SMTP email verification (admin) |
### Command Shorthand
@@ -726,3 +732,116 @@ Polling and announcements:
- `list` shows error status indicators next to each alert
- `check` forces an immediate poll across all platforms
- `history` queries stored results, most recent first
### `!jwt` -- JWT Decoder
Decode JSON Web Token header and payload, flag common issues.
```
!jwt eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIn0.sig
```
Output format:
```
Header: alg=RS256 typ=JWT | sig=43 bytes
sub=user123
WARN: expired (2026-03-01 12:00 UTC)
```
Issues detected:
- `alg=none` (unsigned token)
- Expired tokens (`exp` in the past)
- Not-yet-valid tokens (`nbf` in the future)
No external dependencies -- pure base64/JSON decoding.
### `!mac` -- MAC Address Lookup
OUI vendor lookup from IEEE database, random MAC generation.
```
!mac AA:BB:CC:DD:EE:FF Vendor lookup
!mac AABB.CCDD.EEFF Cisco-style format also accepted
!mac random Generate random locally-administered MAC
!mac update Download IEEE OUI database
```
Output format:
```
AA:BB:CC:DD:EE:FF -- Cisco Systems, Inc (OUI: AA:BB:CC)
Random MAC: 02:4A:F7:3C:91:E2 (locally administered)
```
- Accepts any common MAC format (colon, dash, dot, no separator)
- Random MACs have the locally-administered bit set and multicast bit cleared
- OUI database stored at `data/oui.txt`, also downloadable via `scripts/update-data.sh`
### `!abuse` -- AbuseIPDB
Check IP reputation or report abuse via the AbuseIPDB API.
```
!abuse 8.8.8.8 Check single IP
!abuse 8.8.8.8 1.1.1.1 Check multiple (max 5)
!abuse 8.8.8.8 report 14,22 Brute force Report IP (admin)
```
Output format:
```
8.8.8.8 -- Abuse: 0% (0 reports) | ISP: Google LLC | Usage: Data Center | Country: US
```
- API key: set `ABUSEIPDB_API_KEY` env var or `api_key` under `[abuseipdb]` in config
- Private/loopback IPs are rejected
- Reporting requires admin privileges
- Categories are comma-separated numbers per AbuseIPDB docs
### `!vt` -- VirusTotal
Query VirusTotal API v3 for file hashes, IPs, domains, or URLs.
```
!vt 44d88612fea8a8f36de82e12... File hash (MD5/SHA1/SHA256)
!vt 8.8.8.8 IP address
!vt example.com Domain
!vt https://example.com/page URL
```
Output format:
```
44d88612fea8a8... -- 62/72 detected | trojan, malware | first seen: 2024-01-15
8.8.8.8 -- 0/94 | AS15169 GOOGLE | Country: US | Reputation: 0
example.com -- 0/94 | Registrar: Example Inc | Reputation: 0
```
- API key: set `VIRUSTOTAL_API_KEY` env var or `api_key` under `[virustotal]` in config
- Auto-detects input type from format (hash length, URL scheme, IP, domain)
- Rate limited to 4 requests per minute (VT free tier)
- URL IDs are base64url-encoded per VT API spec
### `!emailcheck` -- SMTP Email Verification (admin)
Verify email deliverability via MX resolution and raw SMTP RCPT TO conversation
through the SOCKS5 proxy.
```
!emailcheck user@example.com Single check
!emailcheck user@example.com user2@test.org Batch (max 5)
```
Output format:
```
user@example.com -- SMTP 250 OK (mx: mail.example.com)
bad@example.com -- SMTP 550 User unknown (mx: mail.example.com)
```
- Admin only (prevents enumeration abuse)
- Resolves MX records via Tor DNS, falls back to A record
- Raw SMTP via SOCKS5 proxy: EHLO, MAIL FROM:<>, RCPT TO, QUIT
- 15-second timeout per connection
- Max 5 emails per invocation