diff --git a/.claude/rules/lookups.md b/.claude/rules/lookups.md index 4247a6f..b6b9eee 100644 --- a/.claude/rules/lookups.md +++ b/.claude/rules/lookups.md @@ -134,7 +134,9 @@ client that does not use those transports is a bug. ## Error text `sanitizeErr()` strips internals before anything reaches a response. `safenet.BlockedError` -gets a specific friendly message; others are truncated to the final colon-space segment. The +gets a specific friendly message and is an *expected* error (logged with the host, never +alerted on: the name is the caller's choice); others are truncated to the final colon-space +segment. The full error chain is logged server-side for diagnosis — the error, never the request payload, response body, or any credential it may have carried. diff --git a/docs/decisions.md b/docs/decisions.md index 6b38435..a99b7a6 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -328,6 +328,25 @@ hostname and connecting to it. **Instead of.** Validating the URL or hostname before the request. A name that resolves to a private address passes that check and connects anyway. +### 2026-11-16 — A refused private address is logged, not alerted on + +**Decision.** `safenet.BlockedError` is an expected error in `IsExpectedError`. The +refusal is returned to the caller and logged at warn level with the host; it does not +count toward the throttle or spike alerts. + +**Why.** It was unexpected on purpose, as a possible SSRF probe worth a look. But an +alert carries a lookup name and a count, never the host or the customer, so the alert +could not be investigated; the log line can. Meanwhile the trigger is a hostname the +caller chooses, and names that point at private addresses are common in public DNS +(internal hosts published by mistake, `localhost.` records, split-DNS leftovers). A +customer checking a list of someone's subdomains would raise alerts by accident, and +anyone could raise them on purpose. The encryption endpoint made this sharper, because +all three of its lookups resolve the host and so fail together. + +**Instead of.** Keeping the page as an attack signal. If that signal is wanted, a counter +of blocked dials in `internal/metrics` is the place for it: it can be graphed and alerted +on at a threshold that means something, without tying it to the pager. + ### The 404 page never echoes the requested path **Decision.** `Handler.NotFound` renders a static page. Paths under `/v1` or `/billing` get diff --git a/internal/domain/errors.go b/internal/domain/errors.go index b2b87b3..21e1653 100644 --- a/internal/domain/errors.go +++ b/internal/domain/errors.go @@ -10,6 +10,7 @@ import ( "github.com/likexian/whois" whoisparser "github.com/likexian/whois-parser" + "github.com/security-accelerated/intelligence-api/internal/safenet" ) // expectedWhoisErrors are conditions the WHOIS libraries report about the @@ -84,6 +85,19 @@ func IsExpectedError(err error) bool { return true } + // The target's name resolves to a private or reserved address and safenet + // refused to connect. The guard did its job, and where a name points is a + // fact about the name the caller chose. It used to count toward alerts as + // a possible SSRF probe, but an alert names a lookup and a count, not the + // host or the customer, so it could not be investigated from the alert; + // the refusal is logged with the host, and that is where to look. Counting + // it also meant a caller could raise alerts at will by submitting such + // names, which are common in public DNS without any ill intent. + var blocked *safenet.BlockedError + if errors.As(err, &blocked) { + return true + } + // TLS handshake failures below the certificate layer — a target that is not // speaking TLS on 443, or speaking it badly. That is a finding about them. var recordErr tls.RecordHeaderError diff --git a/internal/domain/errors_test.go b/internal/domain/errors_test.go index 1a9e314..a760eef 100644 --- a/internal/domain/errors_test.go +++ b/internal/domain/errors_test.go @@ -7,12 +7,14 @@ import ( "errors" "fmt" "net" + "net/netip" "net/url" "syscall" "testing" "github.com/likexian/whois" whoisparser "github.com/likexian/whois-parser" + "github.com/security-accelerated/intelligence-api/internal/safenet" ) func TestIsExpectedError_Expected(t *testing.T) { @@ -48,6 +50,11 @@ func TestIsExpectedError_Expected(t *testing.T) { {"tls record header", tls.RecordHeaderError{Msg: "first record does not look like a TLS handshake"}}, {"encryption probe refused on every offer", ErrNoHandshake}, + + // A caller-chosen name that points at a private address. Refused by + // safenet, logged with the host, and not an incident. + {"private address refused before dialing", &safenet.BlockedError{IP: netip.MustParseAddr("10.0.0.5")}}, + {"private address refused at dial time", fmt.Errorf("tls connect: %w", &net.OpError{Op: "dial", Net: "tcp", Err: &safenet.BlockedError{IP: netip.MustParseAddr("127.0.0.1")}})}, } for _, tt := range tests { diff --git a/internal/handler/changelog.yaml b/internal/handler/changelog.yaml index fc1ce27..a15562c 100644 --- a/internal/handler/changelog.yaml +++ b/internal/handler/changelog.yaml @@ -31,6 +31,8 @@ audience: internal - text: "`sactl lookup encryption HOST` and an Encryption posture entry in the interactive lookup menu; `sactl usage` prints the host total" audience: internal + - text: "A lookup refused because its target resolves to a private or reserved address no longer counts toward alerting, on any endpoint. The caller still gets the same error and the refusal is still logged with the host. Where a name points is the caller's choice, so it should not be able to raise alerts" + audience: internal - version: v1.2.0 date: 2026-11-16 diff --git a/internal/service/encryption_test.go b/internal/service/encryption_test.go index feadbf2..0470c19 100644 --- a/internal/service/encryption_test.go +++ b/internal/service/encryption_test.go @@ -4,12 +4,14 @@ import ( "context" "errors" "fmt" + "net/netip" "sync" "testing" "time" "github.com/security-accelerated/intelligence-api/internal/cache" "github.com/security-accelerated/intelligence-api/internal/domain" + "github.com/security-accelerated/intelligence-api/internal/safenet" ) const testHost = "example.com" @@ -165,6 +167,26 @@ func TestEncryptionLookup_PanicBecomesInternalError(t *testing.T) { } } +// A host that resolves only to private addresses is refused by all three +// lookups at once. The caller is told why, and no alert is recorded: otherwise +// a handful of requests naming such a host would page, with nothing in the +// alert to say who sent them. +func TestEncryptionLookup_PrivateAddressHostDoesNotAlert(t *testing.T) { + rec := &countingRecorder{} + blocked := fmt.Errorf("resolve: %w", &safenet.BlockedError{IP: netip.MustParseAddr("10.0.0.5")}) + svc := newTestEncryptionService(newMockCache(), &encryptionStubs{protocolErr: blocked}) + svc.alerter = rec + + resp, _ := svc.Lookup(context.Background(), "intranet.example.com", encryptionOpts(domain.LookupProtocolsName)) + + if len(resp.Errors) != 1 || resp.Errors[0].Message != "domain resolves to a private/reserved IP address" { + t.Fatalf("errors = %+v, want the refusal reported to the caller", resp.Errors) + } + if rec.count.Load() != 0 { + t.Errorf("recorded %d alerts, want 0 for a host that resolves to a private address", rec.count.Load()) + } +} + // Every encryption lookup talks only to the target, so a host that refuses // every handshake is a finding about that host. If it counted toward alerting, // one customer scanning hosts with nothing on 443 would page. diff --git a/internal/service/sanitize_err_test.go b/internal/service/sanitize_err_test.go index 08b6110..cdd46d8 100644 --- a/internal/service/sanitize_err_test.go +++ b/internal/service/sanitize_err_test.go @@ -173,11 +173,14 @@ func TestIsExpectedError_InfraError_NotExpected(t *testing.T) { } } -func TestIsExpectedError_BlockedError_NotExpected(t *testing.T) { - // SSRF blocks are unexpected — they indicate a domain resolved to a private IP, - // which may warrant investigation. +// A name that resolves to a private address is refused and logged, and it is +// not an incident. This was the other way round until the encryption endpoint +// made the consequence plain: a caller could raise alerts at will by +// submitting such names, and the alert could not say which host or customer. +// See docs/decisions.md before flipping it back. +func TestIsExpectedError_BlockedError_Expected(t *testing.T) { err := &safenet.BlockedError{IP: netip.MustParseAddr("127.0.0.1")} - if isExpectedError(err) { - t.Error("safenet.BlockedError should NOT be expected") + if !isExpectedError(err) { + t.Error("safenet.BlockedError should be expected: it must not count toward alerting") } }