diff options
| author | Danilo M. <danix@danix.xyz> | 2026-09-09 18:07:46 +0200 |
|---|---|---|
| committer | Danilo M. <danix@danix.xyz> | 2026-09-09 18:07:46 +0200 |
| commit | 426d93d09e8b9ebe5b3bfdfc217472af469f2815 (patch) | |
| tree | 491a02e3858a49c42610225c4803b00ba2d8595f /docs/specs/2026-09-09-contacts.md | |
| parent | 688151c4b5ad3ff7f927fec8efde92c2154e2cd3 (diff) | |
| download | abusectl-426d93d09e8b9ebe5b3bfdfc217472af469f2815.tar.gz abusectl-426d93d09e8b9ebe5b3bfdfc217472af469f2815.zip | |
docs: document the queried key, mark server as unbuilt
The contacts spec's manifest example carried a "server" field that no code
ever wrote, while resolve() writes a "queried" key the spec never defined.
They are not the same fact under two names: "queried" is what was asked
about, the name the label walk landed on, and "server" is who was asked,
the RDAP endpoint the bootstrap selected.
Document "queried" as shipped, and record "server" as specified but not
built, with the condition that would earn it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xj1ayFRSUQ2u7cwb3S4axE
Diffstat (limited to 'docs/specs/2026-09-09-contacts.md')
| -rw-r--r-- | docs/specs/2026-09-09-contacts.md | 25 |
1 files changed, 21 insertions, 4 deletions
diff --git a/docs/specs/2026-09-09-contacts.md b/docs/specs/2026-09-09-contacts.md index c751bcb..d45cf83 100644 --- a/docs/specs/2026-09-09-contacts.md +++ b/docs/specs/2026-09-09-contacts.md @@ -234,19 +234,36 @@ resolved. The indicator still reaches MISP and the vendor feeds. "contacts": [ { "iocs": ["ioc-1"], "query": "198.51.100.7", "abuse": ["abuse@example.invalid"], - "source": "rdap", "handle": "AS64496", - "server": "rdap.example.invalid" }, - { "iocs": ["ioc-3", "ioc-7"], "query": "example.invalid", + "source": "rdap", "handle": "AS64496" }, + { "iocs": ["ioc-3", "ioc-7"], "query": "a.b.c.example.invalid", + "queried": "example.invalid", "abuse": [], "source": "rdap", "error": "no abuse role published" } ] ``` -Two departures from the sketch in the umbrella design, both deliberate: +Three departures from the sketch in the umbrella design, all deliberate: - **`iocs` is a list**, because hosts fold and one contact can serve several indicators. - **`abuse` is a list**, because multiple desks are real. +- **`queried` is present only when the label walk shortened the name.** It + records WHAT was asked about, not what the message contained: a contact + found for `a.b.c.example.invalid` at `example.invalid` belongs to the + registered domain rather than the exact host. Absent when the query and + the answer are the same name, and never present on an IP, which is always + asked as itself. + +**`server` is specified but NOT built.** An earlier draft of this example +carried it and nothing ever wrote it. It records WHO was asked, the RDAP +endpoint the bootstrap selected, which is a different fact from `queried` +and independent of it: one server answers thousands of names, and the same +name would move to another server if the bootstrap changed. Unlike `queried` +it is meaningful on the IP branch too, where longest-prefix selection picks +an endpoint. It is worth building when a desk disputes a report and the +answer is "this is the registry that published the address"; until `report` +needs that, the bootstrap cache on disk makes the mapping reproducible and +the field is dead weight. `query` records what was actually asked. Review can then see that a URL indicator was resolved by its host, which is the fourth property made visible |
