test: pin the SNMPv3 request engine against a fake authoritative agent

[ilyam8]

Summary

Second safety net for the request engine: what it does with an SNMPv3 agent, known bugs included, so the decomposition of sendOneRequest/send/v3.go and the later port of the REPORT resynchronization change are measured against it. Test files only, no library change.

• engine_v3_agent_test.go: fakeV3Agent, an authoritative SNMPv3 engine on the harness of the previous PR. It reads requests with its own parser, drops what RFC 3412 discards (another version or security model, a msgID or msgMaxSize out of range, privacy without authentication, a scoped PDU that does not decode, so a wrong privacy passphrase gets no answer as with net-snmp's snmpd, and Reports to unreadable requests that are not reportable), and checks the rest with the library's digests and ciphers in RFC 3414 section 3.2 order: the digest over the message as received, decryption when the privacy flag is set. It answers with a GetResponse at the request's security level and in its context, or with a Report at the RFC's level in the default context. Its engine time follows the test clock; it can reboot, change its engine ID and script any answer.
• engine_v3_test.go -> testdata/engine/v3.golden (90 scenarios): discovery at every security level (no answer, another Report, the unknownUserNames device workaround, preset context engine ID, context name, Reports with another model, another or no context engine ID, an empty msgFlags), a known engine ID, reboots, engine-ID changes (noAuth, authNoPriv and authPriv users, replies from the new engine), the 150 s time window, older engine time and lower boots, resynchronizations that fail again, wrong authentication and privacy passphrases, a privacy protocol mismatch, unknown users, unsupported levels, every Report counter unauthenticated and authenticated, Reports after discovery, forged Reports, and mismatched answers (stale msgID or request ID, unauthenticated, unencrypted, encrypted with another key or to an authNoPriv request, another context, user or security model, an empty msgFlags, Reports with two varbinds).
• The transcripts show every field a change to the engine can affect: msgID, flags, salts, context, USM parameters, a non-default security model or msgMaxSize, and the engine ID the client's keys are localized to after each scenario.

Known bugs pinned with known bug: notes include: unauthenticated Reports (unknownEngineID, wrongDigest, unknownUserName, unsupportedSecLevel) discarded under an authenticated session, so the caller never sees those errors; a notInTimeWindow or unknownEngineID Report that repeats after the retransmission returned with a nil error; retransmission errors replaced by ErrNotInTimeWindow/ErrUnknownEngineID; the engine time of the last message sent instead of the current one (RFC 3414 section 3.1 step 6 a); the reply's msgID, context, user, security level and engine ID not compared with the request's (RFC 3412 section 7.2 step 12); the context engine ID kept after an engine-ID change; the engine time of an authenticated error Report not stored; an older engine time or lower boots adopted (RFC 3414 section 3.2 step 7 b); replies and Reports with another security model or an empty msgFlags acted on instead of discarded; a Report with two varbinds returned as a success.

Testing

• go test ./... on darwin/arm64 and GOARCH=386; -race; -shuffle=on; 100 consecutive runs and -cpu 1,8,64 identical; golangci-lint v2.14.0: 0 issues.
• Two independent review rounds with two reviewers each: one side compared the agent with RFC 3412/3414 and a real net-snmp 5.9.3 snmpd (discovery, Report levels and fields, the time window boundary, reboots, every privacy protocol; 51 crafted requests in the second round), the other ran mutants and a scratch port of the REPORT resynchronization change. Their findings are fixed in the second and third commits.
• Mutation probes (overlay, whole root package): the author's list 23 of 24 caught (the 24th does not compile, its variant is caught), including the three engine mutants earlier steps could not catch (no re-keying after an engine-ID change, the context engine ID from discovery, response vs connection parameters for the digest check); the reviewers' lists 122 of 130 caught, 2 do not compile (their variants are caught), 6 equivalent.
• The scratch port of the REPORT resynchronization change flips 37 of the 90 scenarios, each of its changes alone flips specific ones, and variants of the port (skipping the digest for every Report, accepting unauthenticated Reports for some counters only, reusing a salt, storing other Reports) are each visible.
• Coverage of the root package against the previous PR: sendOneRequest 91.1% -> 99.4%, send 64.0% -> 92.0%, negotiateInitialSecurityParameters 71.4% -> 85.7%, storeSecurityParameters 71.4% -> 85.7%; package 85.2% -> 87.1%.