@checkstack/healthcheck-http-backend 0.4.11 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # @checkstack/healthcheck-http-backend
 
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies [2e20792]
+- Updated dependencies [2e20792]
+  - @checkstack/backend-api@0.26.0
+  - @checkstack/healthcheck-common@1.8.1
+  - @checkstack/common@0.17.0
+
+## 0.5.0
+
+### Minor Changes
+
+- 8cad340: Fix collectors hard-failing on successful-but-non-OK application results.
+
+  A health-check collector must fail only when the TRANSPORT fails (the probe
+  could not complete: DNS/connect/TLS failure, timeout, aborted, unspawnable
+  process). A successfully-received result that is simply "not what you hoped" is
+  an assertable metric, not a collector failure - the user's assertions (or the
+  no-assertion default) decide health.
+
+  BREAKING CHANGE: checks that previously relied on a collector auto-failing on a
+  non-OK result will now report healthy unless an explicit assertion is added.
+  Affected collectors:
+
+  - HTTP request collector: a received response (including 4xx/5xx) is now a
+    successful collection. `statusCode` / `statusText` / `success` are exposed as
+    metrics; the collector no longer sets `error` on a non-2xx. Add a
+    `statusCode equals 200` assertion to fail on non-200 (or `statusCode equals
+404` for a check that wants a 404). Only a real transport failure fails the
+    collector.
+  - gRPC health collector: a completed health RPC returning `NOT_SERVING` /
+    `SERVICE_UNKNOWN` / `UNKNOWN` is now a successful collection. `serving` /
+    `status` are assertable metrics; only a real RPC transport error fails the
+    collector.
+  - Jenkins node-health collector: offline nodes are now an assertable metric
+    (`offlineNodes`); a successful all-nodes API call no longer fails the
+    collector when some nodes are offline.
+  - Script (shell) execute collector: a non-zero exit code is now an assertable
+    metric (`exitCode` / `success`); the collector no longer hard-fails on a
+    non-zero exit. A timeout or a script that could not be spawned still fails the
+    collector (those are transport failures). Add a `success is true` (or
+    `exitCode equals 0`) assertion to fail on a non-zero exit.
+
+  Other strategies (DNS, TCP, TLS, ping, ssh, mysql, postgres, redis, rcon,
+  hardware, and the inline-script collector) were audited and already failed only
+  on genuine transport failures.
+
+- 8cad340: feat(healthcheck-http): SSRF egress guard for the in-process HTTP collector
+
+  The HTTP healthcheck strategy runs in-process on the trusted core (whenever a
+  check is local or not satellite-only), so it now applies a secure-by-default
+  egress guard before connecting:
+
+  - Denies the cloud-metadata + link-local ranges by default (the same
+    `ALWAYS_BLOCKED_CIDRS` the script sandbox enforces), so a check can no longer
+    be pointed at `http://169.254.169.254/...` to read instance credentials.
+  - Keeps RFC1918 / internal probing ALLOWED by default (a monitoring tool's job).
+  - Resolves the target host to IP(s) and checks the CONNECTED IP, pinning the
+    request to the validated IP to resist DNS-rebind.
+  - Operator-extensible: the new optional `egressDenyCidrs` field on the HTTP
+    strategy config adds further CIDRs on top of the always-on block.
+
+  `@checkstack/backend-api` exports a reusable `resolveAndValidateHost` /
+  `pinUrlToIp` SSRF guard plus `DEFAULT_EGRESS_DENY_CIDRS`.
+
+- 8cad340: Add a finer per-run transport timing breakdown to health checks.
+
+  Each run now records an optional structured `metadata.timings` (DNS, connect,
+  TLS, wait/time-to-first-byte, transfer, and a `processing` catch-all for
+  non-HTTP operation time). The run-detail view renders the phases it has, in
+  transport order, and falls back to the previous Connection + Processing split
+  for older runs that lack the finer data.
+
+  For HTTP the request is issued verbatim through `fetch` (original URL, headers,
+  and body), so request behavior is identical to a plain `fetch`. The timing is
+  measured around it: `fetch` resolves at the response headers, so wait
+  (time-to-first-byte) and transfer (body) are measured exactly on the request,
+  DNS is timed at the resolve step, and connect/TLS come from a short-lived,
+  best-effort raw `net`/`tls` probe to the same already-validated IP (the request
+  socket exposes no connect/handshake events on the Bun runtime). The probe is
+  timing-only and never fails the check. The probe validates the TLS certificate
+  (against the original hostname via SNI) like the real request does - it does not
+  disable certificate validation; an unverifiable cert simply yields no TLS-phase
+  timing rather than aborting. Other transports surface the connect and operation
+  times they already measure.
+
+  The SSRF guard now validates the resolved host (rejecting cloud-metadata /
+  link-local and operator-denied ranges) as a pre-flight check and no longer pins
+  the request to the resolved IP. Pinning rewrote the URL to the IP literal and
+  moved the host to the `Host` header, which breaks HTTP/2 origins (their
+  authority comes from the URL's `:authority`, not `Host`) - that is why real
+  hosts such as `google.com` started answering 404/429 instead of 200. The
+  pre-flight validation keeps blocking static metadata/link-local targets and
+  direct denied IP literals; the only thing dropped is DNS-rebind TOCTOU
+  protection (a narrow window that pinning closed at the cost of breaking
+  legitimate HTTP/2 requests).
+
+  The run-detail "slowest" badge no longer collides with the timing bar, and a
+  genuinely sub-millisecond phase reads as "<1 ms" instead of a bare "0 ms".
+
+### Patch Changes
+
+- 8cad340: Retune anomaly-detection defaults across every health-check strategy and the
+  hardware collector for a low-noise, problem-focused out-of-the-box experience.
+
+  The detection engine already learns a per-metric baseline, debounces with a
+  confirmation window, and applies practical-significance floors. This pass tunes
+  the per-metric **defaults** so a fresh install alerts only on genuine,
+  statistically-significant, problem-mapping deviations instead of flooding on
+  every metric that wiggles. 264 metrics were reviewed:
+
+  - **Default-disabled** the high-noise and un-baselineable classes that were
+    alerting for no good reason: raw identifiers and counts (status codes, error
+    and row counts, build counts, player and executor counts), config echoes and
+    near-constants (probe packet counts, CPU core count, total/swap memory),
+    payload-size and other run-to-run-volatile values, and deterministic values
+    like certificate days-remaining (governed by the check's own static-threshold
+    health logic, not statistics). These stay chartable and can be re-enabled per
+    field.
+  - **Hardened** the signals that should alert - latency/response/execution time
+    and availability/success/saturation percentages - with confirmation windows
+    and absolute + relative floors so brief spikes and sub-threshold jitter no
+    longer flap, and prefer percentage metrics over their absolute twins.
+
+  No detection-engine or schema changes; only per-metric `x-anomaly-*` defaults.
+  Users who had opted into any now-disabled metric keep their explicit override.
+
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+  - @checkstack/backend-api@0.25.0
+  - @checkstack/healthcheck-common@1.8.0
+  - @checkstack/common@0.17.0
+
 ## 0.4.11
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-http-backend",
-  "version": "0.4.11",
+  "version": "0.5.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,16 +14,16 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.24.1",
-    "@checkstack/healthcheck-common": "1.7.1",
+    "@checkstack/backend-api": "0.26.0",
+    "@checkstack/healthcheck-common": "1.8.1",
     "jsonpath-plus": "^10.3.0",
-    "@checkstack/common": "0.16.0"
+    "@checkstack/common": "0.17.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.6.2"
+    "@checkstack/scripts": "0.6.4"
   },
   "description": "Checkstack healthcheck-http-backend plugin",
   "author": {

package/src/connect-probe.test.ts

@@ -0,0 +1,43 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import net from "node:net";
+import type { AddressInfo } from "node:net";
+import { probeConnectTiming } from "./connect-probe";
+
+describe("probeConnectTiming", () => {
+  let server: net.Server;
+  let port = 0;
+
+  beforeAll(async () => {
+    server = net.createServer((socket) => socket.end());
+    await new Promise<void>((resolve) =>
+      server.listen(0, "127.0.0.1", resolve),
+    );
+    port = (server.address() as AddressInfo).port;
+  });
+
+  afterAll(() => server.close());
+
+  it("measures TCP connect time to a listening port", async () => {
+    const result = await probeConnectTiming({
+      ip: "127.0.0.1",
+      port,
+      tls: false,
+      timeoutMs: 2000,
+    });
+    expect(result.connectMs).toBeGreaterThanOrEqual(0);
+    expect(result.tlsMs).toBeUndefined();
+  });
+
+  it("never throws on a refused connection (timing-only, best-effort)", async () => {
+    // Port the listening server is NOT on; connection is refused.
+    const result = await probeConnectTiming({
+      ip: "127.0.0.1",
+      port: port + 1,
+      tls: false,
+      timeoutMs: 1000,
+    });
+    // Resolves to an empty result rather than rejecting - it must never fail
+    // the health check.
+    expect(result.connectMs).toBeUndefined();
+  });
+});

package/src/connect-probe.ts

@@ -0,0 +1,93 @@
+import net from "node:net";
+import tls from "node:tls";
+
+/**
+ * Best-effort TCP/TLS connect timing for the HTTP timing breakdown.
+ *
+ * Why a separate probe: the actual request goes through `fetch`, whose internal
+ * socket does NOT expose connect/handshake events on the Bun runtime (Bun never
+ * emits `connect`/`secureConnect` on `node:http` sockets). Raw `node:net` /
+ * `node:tls` sockets DO emit them on Bun, so we open one short-lived connection
+ * to the SAME already-validated IP purely to measure how long TCP connect and
+ * the TLS handshake take. It is representative (same host/IP/network, run
+ * alongside the request), not the request's own socket.
+ *
+ * This is timing-only and MUST NEVER fail the check: any error / timeout
+ * resolves to whatever was measured so far (possibly nothing). The socket is
+ * destroyed as soon as the handshake completes - no application bytes are sent.
+ */
+export interface ConnectProbeResult {
+  /** TCP connect duration in ms (from probe start to the `connect` event). */
+  connectMs?: number;
+  /** TLS handshake duration in ms (`connect` -> `secureConnect`); https only. */
+  tlsMs?: number;
+}
+
+export interface ConnectProbeOptions {
+  /** The pre-validated IP literal to connect to (no DNS, no SSRF re-resolve). */
+  ip: string;
+  port: number;
+  /** Whether to perform a TLS handshake (https targets). */
+  tls: boolean;
+  /** SNI server name for the TLS handshake (the original hostname). */
+  servername?: string;
+  /** Abort the probe after this many ms. */
+  timeoutMs: number;
+  /** Monotonic clock; injectable for tests. Defaults to `performance.now`. */
+  now?: () => number;
+}
+
+export function probeConnectTiming({
+  ip,
+  port,
+  tls: useTls,
+  servername,
+  timeoutMs,
+  now = () => performance.now(),
+}: ConnectProbeOptions): Promise<ConnectProbeResult> {
+  return new Promise<ConnectProbeResult>((resolve) => {
+    const result: ConnectProbeResult = {};
+    const start = now();
+    let settled = false;
+
+    const finish = (socket: net.Socket): void => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+
+    if (useTls) {
+      // Validate the certificate (the default): it is checked against
+      // `servername` (the original hostname), not the IP we dialed, so a
+      // legitimately valid cert still verifies. We deliberately do NOT disable
+      // validation - the real `fetch` validates strictly too, so a bad cert
+      // already fails the check; matching that here is consistent and avoids the
+      // insecure `rejectUnauthorized: false`. If the handshake can't complete
+      // (invalid/self-signed cert), the `error` handler below resolves with just
+      // the TCP `connectMs` and no `tlsMs` - timing is best-effort, never fatal.
+      const socket = tls.connect({
+        host: ip,
+        port,
+        ...(servername === undefined ? {} : { servername }),
+      });
+      socket.once("connect", () => {
+        result.connectMs = Math.max(0, now() - start);
+      });
+      socket.once("secureConnect", () => {
+        const handshakeDone = now() - start;
+        result.tlsMs = Math.max(0, handshakeDone - (result.connectMs ?? 0));
+        finish(socket);
+      });
+      socket.once("error", () => finish(socket));
+      socket.setTimeout(timeoutMs, () => finish(socket));
+    } else {
+      const socket = net.connect({ host: ip, port }, () => {
+        result.connectMs = Math.max(0, now() - start);
+        finish(socket);
+      });
+      socket.once("error", () => finish(socket));
+      socket.setTimeout(timeoutMs, () => finish(socket));
+    }
+  });
+}

package/src/request-collector.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, mock } from "bun:test";
+import { evaluateAssertions } from "@checkstack/backend-api";
 import { RequestCollector, type RequestConfig } from "./request-collector";
 import type { HttpTransportClient } from "./transport-client";
 
@@ -43,7 +44,13 @@ describe("RequestCollector", () => {
       expect(result.error).toBeUndefined();
     });
 
-    it("should return error for failed requests", async () => {
+    // Regression: a received-but-non-2xx response (e.g. 500) is a SUCCESSFUL
+    // collection - the server was reached and answered. The collector must NOT
+    // set the `error` field (which the executor treats as a transport failure
+    // and uses to hard-fail the run). It records the status code as a metric
+    // and lets assertions decide health. Previously this asserted the wrong
+    // behavior (`error` contains "500"); updated to the corrected semantics.
+    it("does not hard-fail the collector on a 5xx response", async () => {
       const collector = new RequestCollector();
       const client = createMockClient({
         statusCode: 500,
@@ -61,8 +68,51 @@ describe("RequestCollector", () => {
       });
 
       expect(result.result.statusCode).toBe(500);
+      // `success` stays a metric (2xx/3xx => true); 500 => false.
       expect(result.result.success).toBe(false);
-      expect(result.error).toContain("500");
+      // The collector reports transport success: no error field is set.
+      expect(result.error).toBeUndefined();
+    });
+
+    // Regression: a 404 is a fully successful HTTP transaction. The collector
+    // must report transport success (no `error`) and expose the status code as
+    // a metric so a "statusCode equals 404" assertion can pass (GREEN), and so
+    // a check with no assertions is not auto-failed by the collector.
+    it("treats a 404 as a successful collection with the status as a metric", async () => {
+      const collector = new RequestCollector();
+      const client = createMockClient({
+        statusCode: 404,
+        statusText: "Not Found",
+      });
+
+      const result = await collector.execute({
+        config: {
+          url: "https://example.com/missing",
+          method: "GET",
+          timeout: 5000,
+        },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.statusCode).toBe(404);
+      expect(result.error).toBeUndefined();
+
+      // A "status code equals 404" assertion passes against the result, so a
+      // check that WANTS a 404 can be green.
+      const failed = evaluateAssertions(
+        [{ field: "statusCode", operator: "equals", value: 404 }],
+        result.result as Record<string, unknown>,
+      );
+      expect(failed).toBeNull();
+
+      // A "status code equals 200" assertion fails - the user, not the
+      // collector, decides this is unhealthy.
+      const failed200 = evaluateAssertions(
+        [{ field: "statusCode", operator: "equals", value: 200 }],
+        result.result as Record<string, unknown>,
+      );
+      expect(failed200).not.toBeNull();
     });
 
     it("should convert headers array to record", async () => {

package/src/request-collector.ts

@@ -81,8 +81,12 @@ const requestResultSchema = healthResultSchema({
   statusCode: healthResultNumber({
     "x-chart-type": "counter",
     "x-chart-label": "Status Code",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "dominance",
+    // Off by default: the raw status code is an identifier, not a quantity
+    // with a meaningful baseline. Legitimate shifts (200 -> 301/302 redirects,
+    // content negotiation) are not problems, while real availability loss is
+    // already captured by the `success` boolean. Charting stays available for
+    // opt-in.
+    "x-anomaly-enabled": false,
   }),
   statusText: healthResultString({
     "x-chart-type": "text",
@@ -125,6 +129,13 @@ const requestAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Latency: bias toward fewer false positives. Require several consecutive
+    // anomalous buckets, ignore small absolute jitter (tens of ms) so fast
+    // endpoints stay quiet, and require a meaningful relative jump.
+    "x-anomaly-sensitivity": 2,
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 50,
+    "x-anomaly-min-relative-delta": 0.5,
   }),
   successRate: aggregatedRate({
     "x-chart-type": "gauge",
@@ -132,6 +143,11 @@ const requestAggregatedFields = {
     "x-chart-unit": "%",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "higher-is-better",
+    // Availability percent: the canonical saturation/failure signal. Debounce
+    // transient single-bucket dips and ignore sub-percent noise so only a real,
+    // sustained drop alerts.
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 2,
   }),
 };
 
@@ -214,6 +230,14 @@ export class RequestCollector implements CollectorStrategy<
     });
 
     const responseTimeMs = Date.now() - startTime;
+    // `success` is an ASSERTABLE METRIC (2xx/3xx), not a collector-failure
+    // signal. Receiving ANY response - including a 4xx/5xx - is a successful
+    // collection: the server was reached and answered. A real transport failure
+    // (DNS, connect, TLS, timeout, aborted) throws out of `client.exec` above
+    // and the executor records it as a collector failure. We must NOT set the
+    // `error` field here for a received-but-non-2xx response, otherwise the
+    // executor hard-fails the run and assertions (e.g. "statusCode equals 404")
+    // never get a chance to decide health.
     const success = response.statusCode >= 200 && response.statusCode < 400;
 
     return {
@@ -225,9 +249,6 @@ export class RequestCollector implements CollectorStrategy<
         bodyLength: response.body?.length ?? 0,
         success,
       },
-      error: success
-        ? undefined
-        : `HTTP ${response.statusCode}: ${response.statusText}`,
     };
   }
 

package/src/strategy.test.ts

@@ -1,11 +1,83 @@
-import { describe, expect, it, spyOn, afterEach } from "bun:test";
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  it,
+} from "bun:test";
+import * as http from "node:http";
+import { AddressInfo } from "node:net";
 import { HttpHealthCheckStrategy } from "./strategy";
 
 describe("HttpHealthCheckStrategy", () => {
-  const strategy = new HttpHealthCheckStrategy();
+  // Inject a deterministic DNS resolver so the in-process SSRF guard does not
+  // depend on real network DNS in unit tests. By default every host resolves
+  // to a public IP (allowed); specific tests override with their own resolver.
+  const publicLookup = async () => [
+    { address: "93.184.216.34", family: 4 },
+  ];
+  const strategy = new HttpHealthCheckStrategy(publicLookup);
+
+  // A real local server backs the `client.exec` behaviour tests. The request is
+  // issued verbatim (no IP pinning), so the URL targets loopback directly; the
+  // SSRF guard validates the `127.0.0.1` literal (an allowed range) before the
+  // request goes out.
+  let server: http.Server;
+  let serverPort = 0;
+  const loopbackLookup = async () => [{ address: "127.0.0.1", family: 4 }];
+  const localStrategy = new HttpHealthCheckStrategy(loopbackLookup);
+  const localUrl = (path: string) => `http://127.0.0.1:${serverPort}${path}`;
+
+  beforeAll(async () => {
+    server = http.createServer((req, res) => {
+      const url = req.url ?? "/";
+      if (url === "/notfound") {
+        res.writeHead(404, { "content-type": "text/plain" });
+        res.end("missing");
+        return;
+      }
+      if (url === "/echo") {
+        const chunks: Buffer[] = [];
+        req.on("data", (c: Buffer) => chunks.push(c));
+        req.on("end", () => {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(
+            JSON.stringify({
+              method: req.method,
+              body: Buffer.concat(chunks).toString("utf8"),
+              auth: req.headers["authorization"] ?? null,
+              custom: req.headers["x-custom-header"] ?? null,
+              host: req.headers["host"] ?? null,
+            }),
+          );
+        });
+        return;
+      }
+      if (url === "/text") {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("Hello World");
+        return;
+      }
+      if (url === "/slow") {
+        // Delay the response so the server's processing time must land in the
+        // `waitMs` (time-to-first-byte) phase, not vanish.
+        setTimeout(() => {
+          res.writeHead(200, { "content-type": "text/plain" });
+          res.end("slow");
+        }, 300);
+        return;
+      }
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ status: "ok" }));
+    });
+    await new Promise<void>((resolve) =>
+      server.listen(0, "127.0.0.1", resolve),
+    );
+    serverPort = (server.address() as AddressInfo).port;
+  });
 
-  afterEach(() => {
-    spyOn(globalThis, "fetch").mockRestore();
+  afterAll(() => {
+    server.close();
   });
 
   describe("config migration (assume-v1-on-read)", () => {
@@ -57,17 +129,11 @@ describe("HttpHealthCheckStrategy", () => {
 
   describe("client.exec", () => {
     it("should return successful response for valid request", async () => {
-      spyOn(globalThis, "fetch").mockResolvedValue(
-        new Response(JSON.stringify({ status: "ok" }), {
-          status: 200,
-          statusText: "OK",
-          headers: { "Content-Type": "application/json" },
-        }),
-      );
-
-      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
       const result = await connectedClient.client.exec({
-        url: "https://example.com/api",
+        url: localUrl("/api"),
         method: "GET",
         timeout: 5000,
       });
@@ -75,40 +141,67 @@ describe("HttpHealthCheckStrategy", () => {
       expect(result.statusCode).toBe(200);
       expect(result.statusText).toBe("OK");
       expect(result.contentType).toContain("application/json");
+      // The connected client surfaces the request's transport phase timings on
+      // its holder. wait + transfer come from the fetch (always present); dns
+      // is measured at the resolve step; connect/tls are best-effort.
+      const timings = connectedClient.timings;
+      if (!timings) throw new Error("expected the HTTP client to surface timings");
+      expect(timings.waitMs).toBeGreaterThanOrEqual(0);
+      expect(timings.transferMs).toBeGreaterThanOrEqual(0);
+      expect(timings.dnsMs).toBeGreaterThanOrEqual(0);
 
       connectedClient.close();
     });
 
-    it("should return 404 status for not found", async () => {
-      spyOn(globalThis, "fetch").mockResolvedValue(
-        new Response(null, { status: 404, statusText: "Not Found" }),
-      );
+    it("attributes a slow server response to the wait phase (not lost)", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
+      await connectedClient.client.exec({
+        url: localUrl("/slow"),
+        method: "GET",
+        timeout: 5000,
+      });
 
-      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const timings = connectedClient.timings;
+      if (!timings) throw new Error("expected the HTTP client to surface timings");
+      // The 300ms server delay must surface as wait time (the bug was the
+      // dominant phase vanishing, leaving only a sub-ms transfer).
+      expect(timings.waitMs).toBeGreaterThanOrEqual(250);
+      // The breakdown must roughly account for the whole request, not <1ms.
+      const total =
+        (timings.dnsMs ?? 0) +
+        (timings.connectMs ?? 0) +
+        (timings.tlsMs ?? 0) +
+        (timings.waitMs ?? 0) +
+        (timings.transferMs ?? 0);
+      expect(total).toBeGreaterThanOrEqual(250);
+
+      connectedClient.close();
+    });
+
+    it("should return 404 status for not found (received = success)", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
       const result = await connectedClient.client.exec({
-        url: "https://example.com/notfound",
+        url: localUrl("/notfound"),
         method: "GET",
         timeout: 5000,
       });
 
       expect(result.statusCode).toBe(404);
+      expect(result.body).toBe("missing");
 
       connectedClient.close();
     });
 
     it("should send custom headers with request", async () => {
-      let capturedHeaders: Record<string, string> | undefined;
-      spyOn(globalThis, "fetch").mockImplementation((async (
-        _url: RequestInfo | URL,
-        options?: RequestInit,
-      ) => {
-        capturedHeaders = options?.headers as Record<string, string>;
-        return new Response(null, { status: 200 });
-      }) as unknown as typeof fetch);
-
-      const connectedClient = await strategy.createClient({ timeout: 5000 });
-      await connectedClient.client.exec({
-        url: "https://example.com/api",
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
         method: "GET",
         headers: {
           Authorization: "Bearer my-token",
@@ -117,45 +210,37 @@ describe("HttpHealthCheckStrategy", () => {
         timeout: 5000,
       });
 
-      expect(capturedHeaders).toBeDefined();
-      expect(capturedHeaders?.["Authorization"]).toBe("Bearer my-token");
-      expect(capturedHeaders?.["X-Custom-Header"]).toBe("custom-value");
+      const parsed = JSON.parse(result.body) as {
+        auth: string | null;
+        custom: string | null;
+      };
+      expect(parsed.auth).toBe("Bearer my-token");
+      expect(parsed.custom).toBe("custom-value");
 
       connectedClient.close();
     });
 
     it("should return JSON body as string", async () => {
-      const responseBody = { foo: "bar", count: 42 };
-      spyOn(globalThis, "fetch").mockResolvedValue(
-        new Response(JSON.stringify(responseBody), {
-          status: 200,
-          headers: { "Content-Type": "application/json" },
-        }),
-      );
-
-      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
       const result = await connectedClient.client.exec({
-        url: "https://example.com/api",
+        url: localUrl("/api"),
         method: "GET",
         timeout: 5000,
       });
 
-      expect(result.body).toBe(JSON.stringify(responseBody));
+      expect(result.body).toBe(JSON.stringify({ status: "ok" }));
 
       connectedClient.close();
     });
 
     it("should handle text body", async () => {
-      spyOn(globalThis, "fetch").mockResolvedValue(
-        new Response("Hello World", {
-          status: 200,
-          headers: { "Content-Type": "text/plain" },
-        }),
-      );
-
-      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
       const result = await connectedClient.client.exec({
-        url: "https://example.com/api",
+        url: localUrl("/text"),
         method: "GET",
         timeout: 5000,
       });
@@ -166,47 +251,123 @@ describe("HttpHealthCheckStrategy", () => {
     });
 
     it("should send POST body", async () => {
-      let capturedBody: string | undefined;
-      spyOn(globalThis, "fetch").mockImplementation((async (
-        _url: RequestInfo | URL,
-        options?: RequestInit,
-      ) => {
-        capturedBody = options?.body as string;
-        return new Response(null, { status: 201 });
-      }) as unknown as typeof fetch);
-
-      const connectedClient = await strategy.createClient({ timeout: 5000 });
-      await connectedClient.client.exec({
-        url: "https://example.com/api",
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
         method: "POST",
         body: JSON.stringify({ name: "test" }),
         timeout: 5000,
       });
 
-      expect(capturedBody).toBe('{"name":"test"}');
+      const parsed = JSON.parse(result.body) as { body: string };
+      expect(parsed.body).toBe('{"name":"test"}');
 
       connectedClient.close();
     });
 
     it("should use correct HTTP method", async () => {
-      let capturedMethod: string | undefined;
-      spyOn(globalThis, "fetch").mockImplementation((async (
-        _url: RequestInfo | URL,
-        options?: RequestInit,
-      ) => {
-        capturedMethod = options?.method;
-        return new Response(null, { status: 200 });
-      }) as unknown as typeof fetch);
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
+        method: "DELETE",
+        timeout: 5000,
+      });
+
+      const parsed = JSON.parse(result.body) as { method: string };
+      expect(parsed.method).toBe("DELETE");
+
+      connectedClient.close();
+    });
 
+    it("sends the request's Host header to the server", async () => {
+      const connectedClient = await localStrategy.createClient({
+        timeout: 5000,
+      });
+      const result = await connectedClient.client.exec({
+        url: localUrl("/echo"),
+        method: "GET",
+        timeout: 5000,
+      });
+
+      const parsed = JSON.parse(result.body) as { host: string | null };
+      // The request is issued verbatim, so the server sees the URL's authority.
+      expect(parsed.host).toBe(`127.0.0.1:${serverPort}`);
+
+      connectedClient.close();
+    });
+  });
+
+  describe("SSRF guard (in-process egress)", () => {
+    it("refuses a request whose host resolves to the cloud-metadata IP", async () => {
+      const metadataStrategy = new HttpHealthCheckStrategy(async () => [
+        { address: "169.254.169.254", family: 4 },
+      ]);
+
+      const connectedClient = await metadataStrategy.createClient({
+        timeout: 5000,
+      });
+
+      // The guard rejects in resolveTarget, BEFORE any socket is opened.
+      await expect(
+        connectedClient.client.exec({
+          url: "http://metadata.internal/latest/meta-data/",
+          method: "GET",
+          timeout: 5000,
+        }),
+      ).rejects.toThrow(/denied egress range/);
+
+      connectedClient.close();
+    });
+
+    it("refuses a direct cloud-metadata IP literal", async () => {
       const connectedClient = await strategy.createClient({ timeout: 5000 });
-      await connectedClient.client.exec({
-        url: "https://example.com/api",
-        method: "DELETE",
+
+      await expect(
+        connectedClient.client.exec({
+          url: "http://169.254.169.254/latest/meta-data/",
+          method: "GET",
+          timeout: 5000,
+        }),
+      ).rejects.toThrow(/denied egress range/);
+      connectedClient.close();
+    });
+
+    it("allows an internal RFC1918 host by default (monitoring stays allowed)", async () => {
+      // Resolve to loopback so the (allowed) request reaches the local server.
+      const internalStrategy = new HttpHealthCheckStrategy(loopbackLookup);
+      const connectedClient = await internalStrategy.createClient({
         timeout: 5000,
       });
 
-      expect(capturedMethod).toBe("DELETE");
+      const result = await connectedClient.client.exec({
+        url: localUrl("/healthz"),
+        method: "GET",
+        timeout: 5000,
+      });
+      expect(result.statusCode).toBe(200);
+      connectedClient.close();
+    });
 
+    it("honors an operator-extended denylist for an internal range", async () => {
+      const internalStrategy = new HttpHealthCheckStrategy(async () => [
+        { address: "10.5.5.5", family: 4 },
+      ]);
+      const connectedClient = await internalStrategy.createClient({
+        timeout: 5000,
+        egressDenyCidrs: ["10.0.0.0/8"],
+      });
+
+      await expect(
+        connectedClient.client.exec({
+          url: "http://internal.service.local/healthz",
+          method: "GET",
+          timeout: 5000,
+        }),
+      ).rejects.toThrow(/denied egress range/);
       connectedClient.close();
     });
   });

package/src/strategy.ts

@@ -8,13 +8,17 @@ import {
   z,
   type InferAggregatedResult,
   type ConnectedClient,
+  type TransportTimings,
   baseStrategyConfigSchema,
+  DEFAULT_EGRESS_DENY_CIDRS,
+  resolveAndValidateHost,
 } from "@checkstack/backend-api";
 import {
   healthResultString,
   healthResultSchema,
   StrategyCategory,
 } from "@checkstack/healthcheck-common";
+import { probeConnectTiming } from "./connect-probe";
 import type {
   HttpTransportClient,
   HttpRequest,
@@ -28,8 +32,25 @@ import type {
 /**
  * HTTP health check configuration schema.
  * Global defaults only - action params moved to RequestCollector.
+ *
+ * `egressDenyCidrs` extends the SSRF guard's default denylist. The collector
+ * runs in-process on the trusted core, so it always refuses to connect to
+ * cloud-metadata + link-local ranges (the secure default); operators can add
+ * further CIDRs here (e.g. to block a sensitive internal range) WITHOUT losing
+ * the metadata/link-local block. Leaving it unset keeps the secure default.
+ * RFC1918 / internal probing stays allowed by default (a monitoring tool's job).
+ *
+ * Optional + additive: existing stored configs (which lack this field) remain
+ * valid, so no schema-version bump / migration is required.
  */
-export const httpHealthCheckConfigSchema = baseStrategyConfigSchema.extend({});
+export const httpHealthCheckConfigSchema = baseStrategyConfigSchema.extend({
+  egressDenyCidrs: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Extra CIDR ranges to deny for outbound requests (added on top of the always-on cloud-metadata/link-local block).",
+    ),
+});
 
 export type HttpHealthCheckConfig = z.infer<typeof httpHealthCheckConfigSchema>;
 
@@ -64,8 +85,12 @@ const httpAggregatedFields = {
   errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "lower-is-better",
+    // Off by default: a raw per-bucket error COUNT scales with how many runs
+    // land in the bucket, so it has no stable baseline and drifts with traffic
+    // volume. The percent form of the same signal (`successRate`) is the one
+    // that alerts; this absolute twin stays chart-only to avoid duplicate,
+    // noisy alerting.
+    "x-anomaly-enabled": false,
   }),
 };
 
@@ -86,6 +111,17 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
   description = "HTTP endpoint health monitoring";
   category = StrategyCategory.NETWORKING;
 
+  /**
+   * DNS resolver used by the SSRF guard. Defaults to the system resolver
+   * (`resolveAndValidateHost`'s built-in). Injectable so tests can drive the
+   * guard deterministically without real network DNS.
+   */
+  constructor(
+    private readonly lookupFn?: (
+      hostname: string,
+    ) => Promise<Array<{ address: string; family: number }>>,
+  ) {}
+
   config: Versioned<HttpHealthCheckConfig> = new Versioned({
     version: 3, // v3 for createClient pattern with action params moved to RequestCollector
     schema: httpHealthCheckConfigSchema,
@@ -174,33 +210,118 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
   ): Promise<ConnectedClient<HttpTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
+    // SSRF secure default: deny cloud-metadata + link-local always, plus any
+    // operator-configured extra ranges. This collector runs IN-PROCESS on the
+    // trusted core, so without this guard a healthcheck author could point a
+    // check at http://169.254.169.254/... and read the response body.
+    const denyCidrs = [
+      ...DEFAULT_EGRESS_DENY_CIDRS,
+      ...(validatedConfig.egressDenyCidrs ?? []),
+    ];
+    const lookupFn = this.lookupFn;
+
+    // Mutable per-run timings holder. `exec` writes the request's transport
+    // phases here so the executor can lift them into `metadata.timings`.
+    const timings: TransportTimings = {};
+
     const client: HttpTransportClient = {
       async exec(request: HttpRequest): Promise<HttpResponse> {
         const controller = new AbortController();
-        const timeoutId = setTimeout(
-          () => controller.abort(),
-          request.timeout ?? validatedConfig.timeout,
-        );
+        const timeoutMs = request.timeout ?? validatedConfig.timeout;
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
         try {
+          // SSRF guard: resolve the host and reject any denied range (cloud
+          // metadata / link-local, plus operator extras) BEFORE issuing the
+          // request. We then `fetch` the ORIGINAL url verbatim - we do NOT pin
+          // the connection to the resolved IP. Pinning (rewriting the URL host
+          // to the IP + overriding the Host header + TLS SNI) breaks HTTP/2
+          // origins, whose authority comes from the URL's `:authority`
+          // pseudo-header, not the `Host` header - which is exactly what made
+          // real hosts like google.com answer 404/429 instead of 200. Issuing
+          // the original request keeps it byte-identical to a plain fetch.
+          //
+          // Trade-off: because `fetch` re-resolves DNS itself, this pre-flight
+          // validation has a DNS-rebind TOCTOU window (a host could resolve to
+          // an allowed IP here and a denied one at connect time). It still
+          // blocks the common cases - a host that statically resolves to a
+          // denied range, and direct denied IP literals. The resolved IP is
+          // reused only for the best-effort timing probe below.
+          const requestUrl = new URL(request.url);
+          const dnsStart = performance.now();
+          const target = await resolveAndValidateHost({
+            host: requestUrl.hostname,
+            denyCidrs,
+            ...(lookupFn === undefined ? {} : { lookupFn }),
+          });
+          const dnsMs = Math.max(0, performance.now() - dnsStart);
+          const isHttps = requestUrl.protocol === "https:";
+
+          // Connect/TLS timing comes from a short-lived raw probe to the SAME
+          // validated IP: Bun's `fetch` socket exposes no connect/handshake
+          // events, but raw net/tls sockets do. Best-effort, runs alongside the
+          // request, and never fails the check.
+          const probePromise = probeConnectTiming({
+            ip: target.ip,
+            port:
+              requestUrl.port === ""
+                ? isHttps
+                  ? 443
+                  : 80
+                : Number(requestUrl.port),
+            tls: isHttps,
+            servername: requestUrl.hostname,
+            timeoutMs,
+          });
+
+          // `fetch` resolves at the response HEADERS (time-to-first-byte);
+          // consuming the body is the transfer phase.
+          const fetchStart = performance.now();
           const response = await fetch(request.url, {
             method: request.method,
             headers: request.headers,
             body: request.body,
             signal: controller.signal,
           });
+          const ttfbMs = Math.max(0, performance.now() - fetchStart);
 
-          // Read body BEFORE clearing timeout - body streaming can also hang
+          // Read body BEFORE clearing the timeout - body streaming can also hang.
+          const transferStart = performance.now();
           const body = await response.text();
+          const transferMs = Math.max(0, performance.now() - transferStart);
 
           clearTimeout(timeoutId);
-          const headers: Record<string, string> = {};
 
-          // eslint-disable-next-line unicorn/no-array-for-each
-          response.headers.forEach((value, key) => {
+          const probe = await probePromise;
+          // Server wait = time-to-first-byte minus the connection setup we could
+          // measure. Clamped: the probe is a parallel connection, so on a warm
+          // path its setup can exceed the request's ttfb.
+          const waitMs = Math.max(
+            0,
+            ttfbMs - ((probe.connectMs ?? 0) + (probe.tlsMs ?? 0)),
+          );
+
+          // Last-request-wins: reset then write this request's phases.
+          delete timings.dnsMs;
+          delete timings.connectMs;
+          delete timings.tlsMs;
+          delete timings.waitMs;
+          delete timings.transferMs;
+          delete timings.processingMs;
+          timings.dnsMs = dnsMs;
+          if (probe.connectMs !== undefined) timings.connectMs = probe.connectMs;
+          if (probe.tlsMs !== undefined) timings.tlsMs = probe.tlsMs;
+          timings.waitMs = waitMs;
+          timings.transferMs = transferMs;
+
+          const headers: Record<string, string> = {};
+          for (const [key, value] of response.headers) {
             headers[key.toLowerCase()] = value;
-          });
+          }
 
+          // A received response - INCLUDING a 4xx/5xx - returns normally and is
+          // an assertable metric (never an error). Only a genuine transport
+          // failure (DNS, connect, TLS, timeout, abort) throws.
           return {
             statusCode: response.status,
             statusText: response.statusText,
@@ -217,6 +338,7 @@ export class HttpHealthCheckStrategy implements HealthCheckStrategy<
 
     return {
       client,
+      timings,
       close: () => {
         // HTTP is stateless, nothing to close
       },

package/src/transport-client.ts

@@ -1,4 +1,5 @@
 import type { TransportClient } from "@checkstack/common";
+import type { TransportTimings } from "@checkstack/backend-api";
 
 /**
  * HTTP request configuration.
@@ -20,6 +21,12 @@ export interface HttpResponse {
   headers: Record<string, string>;
   body: string;
   contentType?: string;
+  /**
+   * Structured transport timing breakdown for this request (DNS / connect /
+   * TLS / wait / transfer), populated by the instrumented node-http client.
+   * Absent if the request never produced socket events.
+   */
+  timings?: TransportTimings;
 }
 
 /**