Add hook to monitor outbound requests

Author: hansott

docs/outbound-requests.md

@@ -0,0 +1,21 @@
+# Monitoring Outbound Requests
+
+To monitor outbound HTTP/HTTPS requests made by your application, you can use the `onOutboundRequest` function. This is useful when you want to track external API calls, log outbound traffic, or analyze what domains your application connects to.
+
+## Basic Usage
+
+```js
+const { onOutboundRequest } = require("@aikidosec/firewall");
+
+onOutboundRequest(({ url, port, method }) => {
+  // url is a URL object: https://nodejs.org/api/url.html#class-url
+  console.log(`${new Date().toISOString()} - ${method} ${url.href}`);
+});
+```
+
+## Important Notes
+
+- You can register multiple callbacks by calling `onOutboundRequest` multiple times.
+- Callbacks are triggered for all HTTP/HTTPS requests made through Node.js built-in modules (`http`, `https`), builtin fetch function, undici and anything that uses that.
+- Callbacks are called when the connection is initiated, before knowing if Zen will block the request.
+- Errors thrown in callbacks (both sync and async) are silently caught and not logged to prevent breaking your application.

library/agent/Agent.ts

@@ -27,6 +27,7 @@ import { wrapInstalledPackages } from "./wrapInstalledPackages";
 import { Wrapper } from "./Wrapper";
 import { isAikidoCI } from "../helpers/isAikidoCI";
 import { AttackLogger } from "./AttackLogger";
+import { triggerOutboundRequestHooks } from "./hooks/outboundRequest";
 import { Packages } from "./Packages";
 import { AIStatistics } from "./AIStatistics";
 import { isNewInstrumentationUnitTest } from "../helpers/isNewInstrumentationUnitTest";
@@ -564,8 +565,12 @@ export class Agent {
     }
   }
 
-  onConnectHostname(hostname: string, port: number) {
-    this.hostnames.add(hostname, port);
+  onConnectHostname(url: URL, port: number) {
+    this.hostnames.add(url.hostname, port);
+  }
+
+  onConnectHTTP(url: URL, port: number, method: string) {
+    triggerOutboundRequestHooks({ url, port, method });
   }
 
   onRouteExecute(context: Context) {

library/agent/hooks/outboundRequest.ts

@@ -0,0 +1,41 @@
+export type OutboundRequestInfo = {
+  url: URL;
+  port: number;
+  method: string;
+};
+
+type OutboundRequestCallback = (
+  request: OutboundRequestInfo
+) => void | Promise<void>;
+
+const outboundRequestCallbacks = new Set<OutboundRequestCallback>();
+
+export function onOutboundRequest(callback: OutboundRequestCallback): void {
+  if (typeof callback !== "function") {
+    throw new TypeError("Callback must be a function");
+  }
+
+  outboundRequestCallbacks.add(callback);
+}
+
+export function triggerOutboundRequestHooks(
+  request: OutboundRequestInfo
+): void {
+  if (outboundRequestCallbacks.size === 0) {
+    return;
+  }
+
+  outboundRequestCallbacks.forEach((callback) => {
+    try {
+      const result = callback(request);
+      // If it returns a promise, catch any errors but don't wait
+      if (result instanceof Promise) {
+        result.catch(() => {
+          // Silently ignore errors from user hooks
+        });
+      }
+    } catch {
+      // Silently ignore errors from user hooks
+    }
+  });
+}

library/index.ts

@@ -15,6 +15,7 @@ import { isESM } from "./helpers/isESM";
 import { checkIndexImportGuard } from "./helpers/indexImportGuard";
 import { setRateLimitGroup } from "./ratelimiting/group";
 import { isLibBundled } from "./helpers/isLibBundled";
+import { onOutboundRequest } from "./agent/hooks/outboundRequest";
 
 // Prevent logging twice / trying to start agent twice
 if (!isNewHookSystemUsed()) {
@@ -51,6 +52,7 @@ export {
   addKoaMiddleware,
   addRestifyMiddleware,
   setRateLimitGroup,
+  onOutboundRequest,
 };
 
 // Required for ESM / TypeScript default export support
@@ -67,4 +69,5 @@ export default {
   addKoaMiddleware,
   addRestifyMiddleware,
   setRateLimitGroup,
+  onOutboundRequest,
 };

library/sinks/Fetch.ts

@@ -16,13 +16,15 @@ export class Fetch implements Wrapper {
 
   private inspectHostname(
     agent: Agent,
-    hostname: string,
-    port: number | undefined
+    url: URL,
+    port: number | undefined,
+    method: string
   ): InterceptorResult {
     // Let the agent know that we are connecting to this hostname
     // This is to build a list of all hostnames that the application is connecting to
     if (typeof port === "number" && port > 0) {
-      agent.onConnectHostname(hostname, port);
+      agent.onConnectHostname(url, port);
+      agent.onConnectHTTP(url, port, method);
     }
     const context = getContext();
 
@@ -31,7 +33,7 @@ export class Fetch implements Wrapper {
     }
 
     return checkContextForSSRF({
-      hostname: hostname,
+      hostname: url.hostname,
       operation: "fetch",
       context: context,
       port: port,
@@ -40,15 +42,22 @@ export class Fetch implements Wrapper {
 
   inspectFetch(args: unknown[], agent: Agent): InterceptorResult {
     if (args.length > 0) {
+      // Extract method from options or Request object
+      let method = "GET";
+      if (args[0] instanceof Request) {
+        method = args[0].method.toUpperCase();
+      } else if (args.length > 1 && args[1] && typeof args[1] === "object") {
+        const options = args[1] as { method?: string };
+        if (options.method) {
+          method = options.method.toUpperCase();
+        }
+      }
+
       // URL string
       if (typeof args[0] === "string" && args[0].length > 0) {
         const url = tryParseURL(args[0]);
         if (url) {
-          const attack = this.inspectHostname(
-            agent,
-            url.hostname,
-            getPortFromURL(url)
-          );
+          const attack = this.inspectHostname(agent, url, getPortFromURL(url), method);
           if (attack) {
             return attack;
           }
@@ -62,11 +71,7 @@ export class Fetch implements Wrapper {
       if (Array.isArray(args[0])) {
         const url = tryParseURL(args[0].toString());
         if (url) {
-          const attack = this.inspectHostname(
-            agent,
-            url.hostname,
-            getPortFromURL(url)
-          );
+          const attack = this.inspectHostname(agent, url, getPortFromURL(url), method);
           if (attack) {
             return attack;
           }
@@ -77,8 +82,9 @@ export class Fetch implements Wrapper {
       if (args[0] instanceof URL && args[0].hostname.length > 0) {
         const attack = this.inspectHostname(
           agent,
-          args[0].hostname,
-          getPortFromURL(args[0])
+          args[0],
+          getPortFromURL(args[0]),
+          method
         );
         if (attack) {
           return attack;
@@ -89,11 +95,7 @@ export class Fetch implements Wrapper {
       if (args[0] instanceof Request) {
         const url = tryParseURL(args[0].url);
         if (url) {
-          const attack = this.inspectHostname(
-            agent,
-            url.hostname,
-            getPortFromURL(url)
-          );
+          const attack = this.inspectHostname(agent, url, getPortFromURL(url), method);
           if (attack) {
             return attack;
           }

library/sinks/HTTPRequest.ts

@@ -19,12 +19,14 @@ export class HTTPRequest implements Wrapper {
     agent: Agent,
     url: URL,
     port: number | undefined,
-    module: "http" | "https"
+    module: "http" | "https",
+    method: string
   ): InterceptorResult {
     // Let the agent know that we are connecting to this hostname
     // This is to build a list of all hostnames that the application is connecting to
     if (typeof port === "number" && port > 0) {
-      agent.onConnectHostname(url.hostname, port);
+      agent.onConnectHostname(url, port);
+      agent.onConnectHTTP(url, port, method);
     }
     const context = getContext();
 
@@ -74,11 +76,21 @@ export class HTTPRequest implements Wrapper {
     }
 
     if (url.hostname.length > 0) {
+      // Extract method from options object
+      let method = "GET";
+      const optionObj = args.find((arg): arg is RequestOptions =>
+        isOptionsObject(arg)
+      );
+      if (optionObj && optionObj.method) {
+        method = optionObj.method.toUpperCase();
+      }
+
       const attack = this.inspectHostname(
         agent,
         url,
         getPortFromURL(url),
-        module
+        module,
+        method
       );
       if (attack) {
         return attack;

library/sinks/Undici.ts

@@ -26,14 +26,14 @@ const methods = [
 export class Undici implements Wrapper {
   private inspectHostname(
     agent: Agent,
-    hostname: string,
+    url: URL,
     port: number | undefined,
     method: string
   ): InterceptorResult {
     // Let the agent know that we are connecting to this hostname
     // This is to build a list of all hostnames that the application is connecting to
     if (typeof port === "number" && port > 0) {
-      agent.onConnectHostname(hostname, port);
+      agent.onConnectHostname(url, port);
     }
     const context = getContext();
 
@@ -42,7 +42,7 @@ export class Undici implements Wrapper {
     }
 
     return checkContextForSSRF({
-      hostname: hostname,
+      hostname: url.hostname,
       operation: `undici.${method}`,
       context,
       port,