feat(scanners): subdomain takeover scanner

scanners/subdomain-takeover/.env.example

@@ -0,0 +1,7 @@
+NATS_URL=
+NATS_STREAM=
+SUBJECT_IN=
+SUBJECT_OUT=
+DURABLE_NAME=
+WORKER_COUNT=
+LOG_LEVEL=

scanners/subdomain-takeover/Dockerfile

@@ -0,0 +1,22 @@
+FROM golang:1.25-alpine AS builder
+
+WORKDIR /src
+RUN apk add --no-cache git ca-certificates
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /out/subdomain-takeover ./cmd/service
+
+# Runtime stage
+FROM alpine:3.22
+
+RUN addgroup -S scanner && adduser -S scanner -G scanner
+WORKDIR /app
+RUN apk add --no-cache ca-certificates tzdata
+
+COPY --from=builder /out/subdomain-takeover /app/subdomain-takeover
+
+USER scanner
+ENTRYPOINT ["/app/subdomain-takeover"]

scanners/subdomain-takeover/Makefile

@@ -0,0 +1,51 @@
+.PHONY: help run test test-race test-integration build fmt fmt-check vet lint tidy ci
+
+GO ?= go
+SERVICE_BIN ?= subdomain-takeover
+BUILD_DIR ?= bin
+
+help:
+	@printf "Targets:\n"
+	@printf "  make run              - Run the service\n"
+	@printf "  make test             - Run all unit tests\n"
+	@printf "  make test-race        - Run unit tests with race detector\n"
+	@printf "  make test-integration - Run integration tests (boots an in-process NATS server)\n"
+	@printf "  make build            - Build service binary\n"
+	@printf "  make fmt              - Format Go files\n"
+	@printf "  make fmt-check        - Check formatting (no changes)\n"
+	@printf "  make vet              - Run go vet\n"
+	@printf "  make lint             - Run fmt-check + vet\n"
+	@printf "  make tidy             - Tidy modules\n"
+	@printf "  make ci               - Lint, test, build\n"
+
+run:
+	$(GO) run ./cmd/service
+
+test:
+	$(GO) test ./...
+
+test-race:
+	$(GO) test -race ./...
+
+test-integration:
+	$(GO) test -tags integration ./...
+
+build:
+	mkdir -p $(BUILD_DIR)
+	CGO_ENABLED=0 $(GO) build -o $(BUILD_DIR)/$(SERVICE_BIN) ./cmd/service
+
+fmt:
+	$(GO) fmt ./...
+
+fmt-check:
+	@test -z "$$($(GO)fmt -l .)" || (printf "Unformatted files found. Run 'make fmt'.\n" && exit 1)
+
+vet:
+	$(GO) vet ./...
+
+lint: fmt-check vet
+
+tidy:
+	$(GO) mod tidy
+
+ci: lint test build

scanners/subdomain-takeover/README.md

@@ -0,0 +1,182 @@
+# subdomain-takeover-service
+
+Go microservice that consumes DNS scan results and emits normalized subdomain takeover findings.
+
+## What it does
+
+1. Consumes from `scans.dns_scanner_results` (JetStream stream: `SCANS`)
+2. Evaluates passive CNAME and NS takeover risk using provider fingerprints
+3. Assigns confidence (`suspected`, `probable`, `confirmed`)
+4. Publishes findings to `scans.findings.subdomain-takeover`
+
+Published finding event contract:
+
+```json
+{
+  "source": "subdomain-takeover",
+  "findingType": "subdomain-takeover-cname",
+  "domainKey": "12345",
+  "subject": "old-app.example.gc.ca",
+  "confidence": "probable",
+  "reasonCode": "CNAME_DANGLING_NXDOMAIN",
+  "observedAt": "2026-08-07T12:34:56Z",
+  "evidence": {
+    "target": "old-app.azurewebsites.net",
+    "recordType": "CNAME"
+  },
+  "attributes": {
+    "provider": "azure",
+    "lameType": ""
+  }
+}
+```
+
+`findingType` values emitted by this service:
+
+- `subdomain-takeover-cname`
+- `subdomain-takeover-ns`
+
+## Current detection scope
+
+Implemented today:
+
+- CNAME passive detection
+- NS passive detection (vulnerable-only emission policy)
+- Deterministic NS candidate selection when multiple providers/hosts match
+- Nil-safe evidence extraction for CNAME and NS
+- Classifier refactor to support injected fingerprint sources (`FingerprintSource`)
+
+Current NS behavior:
+
+- NS provider/host matches are evaluated and ranked
+- Findings are emitted only for exploitable NS outcomes:
+  - `NS_FULL_LAME_PROVIDER_VULNERABLE`
+  - `NS_PARTIAL_LAME_PROVIDER_VULNERABLE`
+- Non-exploitable NS matches (`NS_LAME_PROVIDER_UNKNOWN`, `NS_PROVIDER_MATCH_ONLY`) are classified but not emitted
+
+## Passive-only detection policy
+
+This service uses passive checks only.
+It does not attempt account takeover, resource claiming, or any active validation.
+
+As a result, confidence is conservative and evidence-driven:
+
+- `suspected`: weak or incomplete takeover indicators
+- `probable`: strong passive indicators with known exploitable conditions
+- `confirmed`: reserved for deterministic passive signatures only
+
+## Confidence model (current)
+
+### CNAME
+
+- `suspected`
+  - provider target matched, but required passive signal is missing
+- `probable`
+  - dangling target with NXDOMAIN where required, or
+  - provider fingerprint body match for providers that require body verification
+- `confirmed`
+  - reserved; not currently emitted by CNAME rules
+
+### NS
+
+- `confirmed`
+  - full lame delegation + exploitable provider status
+- `probable`
+  - partial lame delegation + exploitable provider status
+- `suspected`
+  - reason codes exist for weaker NS states, but these are currently not emitted
+
+## Internal package layout
+
+Detection logic was split into focused files to reduce coupling:
+
+- `internal/detect/cname_rules.go`
+- `internal/detect/ns_rules.go`
+- `internal/detect/ns_reasoning.go`
+- `internal/detect/cname_evidence.go`
+- `internal/detect/ns_evidence.go`
+- `internal/detect/fingerprint_source.go`
+
+`Classifier` now supports dependency injection via `NewClassifierWithSource(...)`, while `NewClassifier(...)` defaults to global loaded fingerprints.
+
+## Fingerprint data
+
+Provider fingerprint data is stored in:
+
+- `internal/fingerprints/data/cname_fingerprints.json`
+- `internal/fingerprints/data/ns_fingerprints.json`
+
+The service embeds and validates these files at startup (`fingerprints.Load`).
+
+For CNAME body matching:
+
+- `mode: literal` performs plain substring search
+- `mode: regex` performs regular expression matching
+- if `mode` is omitted, the loader applies backward-compatible inference
+
+## Prerequisites
+
+- Go 1.25+
+- NATS with JetStream enabled
+- `nats` CLI (optional, for local testing)
+
+## Quick start
+
+```bash
+go mod tidy
+go run ./cmd/service
+```
+
+## Local commands
+
+This service includes a local `Makefile` for common workflows:
+
+```bash
+make help      # list targets
+make run       # run the service
+make test      # run tests
+make lint      # fmt-check + vet
+make build     # build bin/subdomain-takeover
+make ci        # lint + test + build
+```
+
+Environment variables:
+
+- `NATS_URL` (default: `nats://localhost:4222`)
+- `NATS_STREAM` (default: `SCANS`)
+- `SUBJECT_IN` (default: `scans.dns_scanner_results`)
+- `SUBJECT_OUT` (default: `scans.findings.subdomain-takeover`)
+- `DURABLE_NAME` (default: `subdomain_takeover`)
+- `WORKER_COUNT` (default: `5`)
+- `LOG_LEVEL` (default: `info`)
+
+## Message ack behavior
+
+The worker uses explicit JetStream ack semantics:
+
+- decode failures -> `Term()` (drop poison message)
+- classify/publish failures -> `Nak()` (retryable)
+- successful processing -> `Ack()`
+
+## Local test flow
+
+Publish a test request:
+
+```bash
+nats pub scans.dns_scanner_results '{"domain_key":"12345","results":{"domain":"example.gc.ca","resolve_chain":[["old-app.example.gc.ca. 300 IN CNAME old-app.azurewebsites.net."]],"cname_record":"old-app.example.gc.ca. 300 IN CNAME old-app.azurewebsites.net.","ns_delegations":{"ns_hosts":["ns1.example-dns-provider.net"],"ns_checks":[],"ns_delegation":{"total_ns":1,"authoritative_ok":0,"lame_count":1,"lame_type":"full"},"error":""}}}'
+```
+
+Watch findings:
+
+```bash
+nats sub "scans.findings.subdomain-takeover"
+```
+
+## Next steps / nice-to-haves
+
+1. Add table-driven tests for NS reason mapping, ranking, and emission gating.
+2. Add classifier integration tests using injected `FingerprintSource`.
+3. Document and implement explicit policy for `edge_case` and `registration_closed` NS provider statuses.
+4. Add structured debug logs for NS matching decisions (host, provider, status, reason).
+5. Add registrar-context mismatch handling (`RegistrarMismatch`) and confidence policy.
+6. Add metrics (counts by reason code, emitted vs suppressed) for production observability.

scanners/subdomain-takeover/cloudbuild.yaml

@@ -0,0 +1,43 @@
+steps:
+  - name: "golang:1.25"
+    id: ci-checks
+    dir: scanners/subdomain-takeover
+    entrypoint: "bash"
+    args:
+      - "-c"
+      - |
+        make ci
+
+  - name: "gcr.io/cloud-builders/docker"
+    id: generate-image-name
+    entrypoint: "bash"
+    dir: scanners/subdomain-takeover
+    args:
+      - "-c"
+      - |
+        echo "northamerica-northeast1-docker.pkg.dev/track-compliance/tracker/subdomain-takeover:$(echo $BRANCH_NAME | sed 's/[^a-zA-Z0-9]/-/g')-$SHORT_SHA-$(date +%s)" > /workspace/imagename
+
+  - name: "gcr.io/cloud-builders/docker"
+    id: build-scanner
+    entrypoint: "bash"
+    dir: scanners/subdomain-takeover
+    args:
+      - "-c"
+      - |
+        image=$(cat /workspace/imagename)
+        docker build -t $image .
+
+  - name: "gcr.io/cloud-builders/docker"
+    id: push-scanner-if-master
+    entrypoint: "bash"
+    dir: scanners/subdomain-takeover
+    args:
+      - "-c"
+      - |
+        if [[ "$BRANCH_NAME" == "master" ]]
+        then
+          image=$(cat /workspace/imagename)
+          docker push $image
+        else
+          exit 0
+        fi

scanners/subdomain-takeover/cmd/service/main.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"context"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/canada-ca/tracker/scanners/subdomain-takeover/internal/app"
+	"github.com/canada-ca/tracker/scanners/subdomain-takeover/internal/bootstrap"
+	"github.com/canada-ca/tracker/scanners/subdomain-takeover/internal/config"
+	"github.com/canada-ca/tracker/scanners/subdomain-takeover/internal/detect"
+	"github.com/canada-ca/tracker/scanners/subdomain-takeover/internal/fingerprints"
+	"github.com/canada-ca/tracker/scanners/subdomain-takeover/internal/messaging"
+	"github.com/rs/zerolog"
+)
+
+func main() {
+	logger := bootstrap.NewLogger(zerolog.InfoLevel)
+
+	cfg, err := config.Load()
+	if err != nil {
+		logger.Fatal().Err(err).Msg("failed to load config")
+	}
+
+	logger = bootstrap.NewLogger(cfg.LogLevel)
+	logger.Info().
+		Str("nats_url", cfg.NATSURL).
+		Str("stream", cfg.NATSStream).
+		Str("subject_in", cfg.SubjectIn).
+		Str("subject_out", cfg.SubjectOut).
+		Str("durable", cfg.DurableName).
+		Int("worker_count", cfg.WorkerCount).
+		Str("log_level", cfg.LogLevel.String()).
+		Msg("service configuration loaded")
+
+	if err := fingerprints.Load(logger); err != nil {
+		logger.Fatal().Err(err).Msg("failed to load fingerprints")
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
+	defer signal.Stop(sig)
+
+	runtimeDeps, err := bootstrap.NewRuntimeDeps(ctx, cfg, logger)
+	if err != nil {
+		logger.Fatal().Err(err).Msg("failed to initialize runtime dependencies")
+	}
+
+	logger.Info().Msgf("Connected to NATS at %s", runtimeDeps.NC.ConnectedUrl())
+
+	pub := messaging.NewPublisher(logger, runtimeDeps.JS, cfg.SubjectOut)
+	matcher := detect.NewHTTPBodyFingerprintMatcher(5 * time.Second)
+	classifier := detect.NewClassifier(matcher, logger)
+	worker := app.NewWorker(logger, pub, classifier)
+
+	go func() {
+		<-sig
+		logger.Info().Msg("Shutdown requested...")
+		cancel()
+		runtimeDeps.Iter.Stop()
+	}()
+
+	deps := app.RunnerDeps{
+		Logger:      logger,
+		WorkerCount: cfg.WorkerCount,
+		Iter:        runtimeDeps.Iter,
+		Worker:      worker,
+		NC:          runtimeDeps.NC,
+	}
+
+	app.Run(ctx, deps)
+
+	logger.Info().Msgf("Disconnecting from NATS at %s", runtimeDeps.NC.ConnectedUrl())
+	if err := runtimeDeps.NC.Flush(); err != nil {
+		logger.Error().Err(err).Msg("failed to flush nats connection")
+	}
+	runtimeDeps.NC.Close()
+
+	if err := ctx.Err(); err != nil && err != context.Canceled {
+		logger.Error().Err(err).Msg("service exited with context error")
+	}
+}