Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .claude/rules/lookups.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
19 changes: 19 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 14 additions & 0 deletions internal/domain/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions internal/domain/errors_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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 {
Expand Down
2 changes: 2 additions & 0 deletions internal/handler/changelog.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions internal/service/encryption_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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.
Expand Down
13 changes: 8 additions & 5 deletions internal/service/sanitize_err_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
}
Loading