1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
# abusectl
Abuse reporting for phishing mail. Parses a flagged message, extracts its
indicators, resolves who to report each one to, and files the result to a
MISP instance and to public abuse channels.
**Status: early.** The design is settled and the first part is being built.
Nothing here submits anything yet.
## What it does
```
abusectl parse msg.eml # -> case directory, IOCs offline
abusectl contacts <case> # + abuse contacts via RDAP network, read-only
abusectl report <case> # + report bodies offline
# review the bodies, by hand or in a mail client
abusectl submit <case> # MISP, then the vendors network, writes
```
Each subcommand runs on its own and is useful on its own. `parse` triages a
message with no configuration at all; `parse`, `contacts` and `report`
together produce a document you can send by hand with no API key anywhere.
State lives in a **case directory** rather than in memory, so a review can
take a week and survive a reboot.
## Two properties that are not negotiable
**Recipient identifiers are never captured.** Not the `To`, `Cc`,
`Delivered-To` or `X-Original-To` headers, not your Message-IDs, not maildir
paths or account names. They are dropped at extraction rather than stripped at
submission, so the tool cannot disclose an identifier it was never given.
Tracking tokens inside URLs count: parameter values are redacted, parameter
names and paths are kept, because the names fingerprint the kit and the values
identify you.
**Nothing remote is ever fetched while parsing.** Not the URLs, not the
redirect chains, not remote images. Following a link confirms your address is
live to the sender and fires exactly the tracker the message wanted. Redirect
chains are read from headers and link text, never by following them.
## Reversible and irreversible
`submit` writes to MISP first and stops if that fails. MISP is your own
instance and is correctable; a report to AbuseIPDB, URLhaus or VirusTotal
cannot be recalled. The reversible step gates the irreversible ones, and it is
also what answers "have I reported this infrastructure before".
Every destination carries its own status, so a retry sends only what failed. A
rate-limited vendor does not mean re-reporting to the three that accepted.
## Design
`docs/specs/2026-09-08-abusectl-design.md` is the umbrella design. Each part
gets its own spec before it is built.
## Requirements
Python 3.11 or newer. `parse` and `report` need nothing else; `contacts` needs
an HTTP client and `submit` needs PyMISP. Development runs from a venv in the
checkout.
## License
GPLv2. See `LICENSE`.
## Development Approach
This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.
|
