feat(ip): say what is blocking an address, and what its filter lets through

[Denis-hamon]

What this adds

The ip domain exposes 15 of its 81 routes. This adds the incident surface: what blocks an
address, how to release it, and how its anti-DDoS filter is configured.

ovhcloud ip blocked <ip_block>                     # anti-hack + ARP + anti-spam, one answer
ovhcloud ip unblock <ip_block> <ip> [--reason antihack|arp|spam]
ovhcloud ip spam-stats <ip_block> <ip> [--from] [--to]
ovhcloud ip phishing list|get
ovhcloud ip mitigation list|get|add|set|remove
ovhcloud ip mitigation-profile list|get|set|delete
ovhcloud ip game list|get|edit
ovhcloud ip game rule list|get|add|delete

26 routes, 22 commands. Stacked on #255; only the last commit belongs to this pull request.

What the account said

Every block of a real account, every family — 537 × 7 = 3 759 requests:

family	content
antihack	0 / 537
arp	0 / 537
spam	0 / 537
phishing	0 of the 485 that answered — 52 answered HTTP 500
mitigation	1 address
mitigationProfiles	1 profile
game	8 addresses, 31 rules

A 14-block sample taken earlier said all seven families were empty. They are not: game and
mitigation carry live configuration, and the reads below run against it. The zero came from the
sample, not from the account.

Four things only the measurement showed

time means the opposite thing on one of the three mechanisms. On antihack and arp it is
"time remaining before you can request your IP to be unblocked"; on spam it is "time while
the IP will be blocked". One is a cooldown to wait out, the other is the sentence itself. A single
column holding both under one header would be wrong on a third of its rows and look right, so
blocked turns the number into a sentence per mechanism, and unblock refuses locally while the
cooldown runs — the API refuses it with "The requested object (ipBlocked = x) does not exist",
which reads as "unknown address" when it means "not yet".

GET /ip/{ip}/phishing returns 500 for every address hosted outside Europe. Ten network
prefixes answer 500 on 100 % of their blocks — 139.99, 148.113, 149.56, 15.235, 158.69,
51.161, 51.222, 51.79, 2402:1f00, 2607:5300. The 49 other prefixes answer 200 on 100 % of
theirs. Not one prefix is mixed, with and without the state and ipOnAntiphishing filters,
and the four sibling families answer 200 on those very same blocks. The CLI cannot fix that, so it
reports the failure as a failure: an empty table there would say "no phishing reported" about a
block nobody managed to read. Worth a look by the route's owner.

The embedded schema is stale on game protocols. ip.GameMitigationRuleProtocolEnum does not
list arkSurvivalAscended, which the API reports in supportedProtocols and which rule 11266524
of a live address already uses. So game rule add checks --protocol against the address, not
against the enum shipped with the CLI — validating against the schema would refuse a protocol
already in production. The lists also differ between addresses (14 protocols on one, 20 on
another), as does maxRules (30 and 100), so there was no single right list to check against
anyway: valheim is accepted on one address of this account and refused on another, both live.

Firewall mode with no rule is a UDP blackhole. It only lets through UDP traffic matching a
rule, so turning it on with zero rules drops every UDP packet to the address — and one address of
the account measured sits in exactly that state: firewall mode off, zero rules, one flag away.
game edit --firewall-mode refuses instead, and names the command that adds a rule first.

Verified against the API

Reads, on the addresses that carry configuration:

command	measured
ip game list 145.239.23.144/32	1 address, 20 protocols, 100 rules max
ip game get	12 of 100 rules, firewall mode on
ip game rule list	the 12 rules, ports rendered as 123 or 7777-7778
ip mitigation list 87.98.233.18/32	1 address · --state removalPending narrows it to none
ip mitigation-profile list 141.94.98.55/32	1 profile, 6 h
ip phishing list on a European block	no entry
ip phishing list on a Canadian block	the 500, as an error, exit 1
ip blocked	nothing blocked — which is the answer, on 537 blocks out of 537

Eight refusals executed against the API: nothing to release, unknown --reason, the UDP
blackhole, an unsupported protocol, a reversed port range, a delay outside the five the API takes,
statistics for an address the anti-spam system does not know, and a game get on an unprotected
address.

The writes are not demonstrable and this PR does not pretend otherwise. Releasing a block
needs an address that is blocked, and none is; the mitigation and game configuration belongs to
running services. So the eight write paths are proven by --dry-run — each one printing the
method and path it would call and sending nothing — and the account state was read back afterwards
outside the CLI: 12 rules still, permanent still false, timeout still 360, firewall mode still
off. Nothing was written.

Notes

• --filter is applied after the readable columns are built, not before: filtering first makes the
  flag silently match nothing on the very columns the table shows, which reads as an answer.
• mitigation keeps its three verbs. POST enrols an address, DELETE drops it from the list,
  and PUT changes the permanent flag of a row that stays. Collapsing them into two commands
  would have made one of the three unreachable.
• mitigation-profile set reads whether a profile exists and picks POST or PUT itself. An
  operator setting a delay does not know which of the two routes applies, and should not have to.
• spam-stats defaults its mandatory window to the date the address was blocked, read from the
  sibling route, and says where the bound came from. The API makes from and to required and
  gives no default, so forwarding them as-is makes the command unusable without two values the
  operator cannot know.

---

Review round — second commit

An adversarial review of the first commit found seven defects, six real. Two would have shipped.

A spam block is a sentence, not a wait. The path that works the mechanism out itself passed the
block duration on as a release cooldown and refused, while --reason spam performed the same POST
unchanged — and the table, on the same number, printed the correct "blocked for 1d". Three readings
of one field, two of them wrong. This is the trap named at the top of this page, and the first
commit fell into it in its own code.

Deleting the last rule under firewall mode is the same UDP blackhole as enabling firewall mode
with no rule, and only the second was guarded. It was one game rule delete away, on the command
an operator runs while tidying up rather than while changing protection.

Four smaller ones: --reason swallowed a 404 and so became the way around the refusal it exists to
give; the mechanism and the address now travel in the API's spelling rather than the one typed,
because both end up in a path segment and in a comparison; the profile update treated every read
failure as "no profile yet", sending a create where an update was due and making --dry-run name
the wrong verb; and --timeout 0, one of the five accepted values, announced "stays on for no
delay" — which names the setting and describes no behaviour.

One finding was rejected and measured: averageSpamscore is spelled exactly that way in the
specification.

Seven sabotages against the fixes, seven red.