xypriss 9.11.13 → 9.12.0

package/dist/src/middleware/built-in/security/HoneypotTarpit.d.ts

@@ -0,0 +1,225 @@
+export declare class HoneypotTarpit {
+    /**
+     * Maximum accepted path length (bytes).
+     * Paths exceeding this length are treated as traps to neutralize buffer-probing
+     * attacks before any string processing occurs.
+     *
+     * @internal
+     */
+    private static readonly MAX_PATH_LENGTH;
+    /**
+     * High-confidence exact paths that are **never** legitimate in any modern
+     * web application. All entries are lowercase; comparison is performed against
+     * a lowercased, normalized path.
+     *
+     * Sources: OWASP Top-10 scanner payloads, Shodan query signatures,
+     * Nuclei template library, Metasploit auxiliary scanner modules.
+     *
+     * @internal
+     */
+    private static readonly EXACT_TRAPS;
+    /**
+     * Path prefixes whose entire subtree should be considered traps.
+     * A request for `/.git/logs/HEAD` is just as dangerous as one for `/.git/config`.
+     *
+     * Rules are matched with a trailing-slash anchor to avoid collisions
+     * (e.g. `/.gitignore` must **not** match the `/.git/` prefix rule).
+     *
+     * @internal
+     */
+    private static readonly PREFIX_TRAPS;
+    /**
+     * File extensions that are exclusively associated with scanner probes or
+     * sensitive file types that should **never** be served over HTTP in any
+     * legitimate modern application.
+     *
+     * Deliberately conservative — common extensions like `.php`, `.bak`, or
+     * `.log` are excluded because they *may* be intentionally served by some
+     * apps. Only zero-ambiguity extensions are listed here.
+     *
+     * @internal
+     */
+    private static readonly SUFFIX_TRAPS;
+    /**
+     * Discrete path segments (surrounded by `/` boundaries or at string edges)
+     * that indicate well-known scanner probes regardless of their position in
+     * the path hierarchy.
+     *
+     * Each entry is matched as a full segment to prevent substring collisions
+     * (e.g. `"admin"` must not trap `/admin-panel` but must trap `/api/admin`).
+     *
+     * @internal
+     */
+    private static readonly SEGMENT_TRAPS;
+    /**
+     * Custom user-defined traps registered at runtime.
+     */
+    private static CUSTOM_EXACT_TRAPS;
+    private static CUSTOM_PREFIX_TRAPS;
+    private static CUSTOM_SUFFIX_TRAPS;
+    private static CUSTOM_SEGMENT_TRAPS;
+    /**
+     * Registers custom trap patterns to expand the honeypot surface.
+     *
+     * @param {object} custom - Object containing custom patterns to trap.
+     */
+    static registerCustomTraps(custom: {
+        exact?: string[];
+        prefixes?: string[];
+        suffixes?: string[];
+        segments?: string[];
+    }): void;
+    /**
+     * Determines whether a raw URI path matches any known honeypot trap signature.
+     *
+     * The method is intentionally **stateless and synchronous** to guarantee
+     * sub-millisecond latency even under high-volume scanner floods. It applies
+     * a four-stage pipeline internally (see module-level docs) and returns as
+     * soon as the first positive match is found.
+     *
+     * #### False-positive safeguards
+     * - Input is sanitized and validated before any rule is evaluated.
+     * - Path normalization resolves all encoding tricks before matching.
+     * - All rules are scoped to patterns that are unambiguously malicious.
+     * - Broad wildcard rules (e.g. "all `.php` files") are deliberately absent.
+     *
+     * @param {string} rawPath - The raw, un-normalized URI path from the incoming
+     *   request (e.g. `req.url` in Node.js `http.IncomingMessage`). Query strings
+     *   and fragments are accepted but stripped before evaluation.
+     * @returns {boolean} `true` if the path matches a trap and the request should
+     *   be handed to {@link handleTrap}; `false` if the path appears legitimate.
+     *
+     * @example
+     * ```typescript
+     * HoneypotTarpit.isTrap("/.env");                 // true
+     * HoneypotTarpit.isTrap("/.env%2elocal");         // true  (encoded bypass)
+     * HoneypotTarpit.isTrap("/api/v1/users");         // false
+     * HoneypotTarpit.isTrap("/assets/logo.png");      // false
+     * HoneypotTarpit.isTrap("/../.env");              // true  (traversal bypass)
+     * ```
+     */
+    static isTrap(rawPath: string): boolean;
+    private static matchesCustomPrefix;
+    private static matchesCustomSuffix;
+    private static matchesCustomSegment;
+    /**
+     * Sends a minimal HTTP 403 Forbidden response and terminates the connection.
+     *
+     * The response is intentionally bare — no body, no `Content-Type`, no
+     * application-level headers — to minimize bandwidth consumption and avoid
+     * leaking server fingerprint information to the scanner.
+     *
+     * #### Why 403 and not a socket destroy?
+     * Destroying the raw socket (`req.socket.destroy()`) is tempting but unsafe
+     * when the Node.js process sits behind a reverse proxy (nginx, Caddy, HAProxy)
+     * or uses keep-alive connection pooling, because the socket may be shared
+     * across multiple logical HTTP requests. A 403 + `res.end()` correctly closes
+     * only the current HTTP transaction without disrupting the underlying TCP
+     * connection pool.
+     *
+     * @param {object} req - The raw incoming request object. Compatible with
+     *   `http.IncomingMessage`, `Http2ServerRequest`, and Fastify/Express
+     *   request wrappers. Not used directly but accepted for API symmetry and
+     *   future extensibility (e.g. logging, rate-limiting by IP).
+     * @param {object} res - The raw outgoing response object. Must expose
+     *   `writeHead(statusCode: number): void` and `end(): void`. Compatible
+     *   with `http.ServerResponse`, `Http2ServerResponse`, and most framework
+     *   response wrappers.
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * app.use((req, res, next) => {
+     *   if (HoneypotTarpit.isTrap(req.url)) {
+     *     return HoneypotTarpit.handleTrap(req, res);
+     *   }
+     *   next();
+     * });
+     * ```
+     */
+    static handleTrap(req: {
+        socket?: unknown;
+    }, res: {
+        writeHead?: (status: number) => void;
+        end?: () => void;
+    }): void;
+    /**
+     * Validates that the raw path is a non-empty string within the accepted
+     * length budget.
+     *
+     * Paths that fail this check (wrong type, empty, or suspiciously long) are
+     * themselves indicators of malicious probing and should be treated as traps
+     * by the caller.
+     *
+     * @param {unknown} value - The raw value received from the request object.
+     * @returns {boolean} `true` if the value is a safe, processable string;
+     *   `false` if it should be rejected immediately.
+     *
+     * @internal
+     */
+    private static sanitizeInput;
+    /**
+     * Layer 1 — Exact path match.
+     *
+     * Performs an O(1) `Set` lookup against {@link EXACT_TRAPS}. This is the
+     * most performant check and handles the vast majority of scanner probes,
+     * which tend to request well-known canonical paths verbatim.
+     *
+     * @param {string} normalizedPath - The fully normalized, lowercase path.
+     * @returns {boolean} `true` if the path is an exact trap match.
+     *
+     * @internal
+     */
+    private static matchesExactTrap;
+    /**
+     * Layer 2 — Directory prefix match.
+     *
+     * Tests whether the normalized path starts with any entry from
+     * {@link PREFIX_TRAPS}. This catches requests for any sub-resource within
+     * a sensitive directory (e.g. `/.git/logs/HEAD`, `/.ssh/known_hosts`).
+     *
+     * Each prefix entry is stored with a trailing `/` to prevent false positives
+     * from partial name collisions (e.g. `/.gitignore` must not match the
+     * `/.git/` prefix).
+     *
+     * @param {string} normalizedPath - The fully normalized, lowercase path.
+     * @returns {boolean} `true` if the path falls under a trapped directory.
+     *
+     * @internal
+     */
+    private static matchesPrefixTrap;
+    /**
+     * Layer 3 — File extension (suffix) match.
+     *
+     * Extracts the file extension from the final path segment and checks it
+     * against {@link SUFFIX_TRAPS}. Only the extension of the *filename* is
+     * considered; directory components are ignored to prevent collisions like
+     * `/certs-info/page` matching `.certs`.
+     *
+     * The comparison is performed on the already-lowercased normalized path,
+     * so no additional case folding is required here.
+     *
+     * @param {string} normalizedPath - The fully normalized, lowercase path.
+     * @returns {boolean} `true` if the file extension is a known trap extension.
+     *
+     * @internal
+     */
+    private static matchesSuffixTrap;
+    /**
+     * Layer 4 — Path segment match.
+     *
+     * Splits the normalized path into discrete segments and checks each one
+     * against {@link SEGMENT_TRAPS}. This catches scanner payloads embedded
+     * at arbitrary depths (e.g. `/api/v2/actuator`, `/proxy/wp-login.php`).
+     *
+     * Matching on full segments (rather than substrings) prevents false positives
+     * such as `/administration` matching a rule for `admin`.
+     *
+     * @param {string} normalizedPath - The fully normalized, lowercase path.
+     * @returns {boolean} `true` if any path segment matches a known trap segment.
+     *
+     * @internal
+     */
+    private static matchesSegmentTrap;
+}
+//# sourceMappingURL=HoneypotTarpit.d.ts.map

package/dist/src/middleware/built-in/security/HoneypotTarpit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HoneypotTarpit.d.ts","sourceRoot":"","sources":["../../../../../src/middleware/built-in/security/HoneypotTarpit.ts"],"names":[],"mappings":"AAmEA,qBAAa,cAAc;IAKvB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAQ;IAM/C;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAmIhC;IAMH;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAejC;IAMH;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAcjC;IAMH;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAalC;IAEH;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAqB;IACtD,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAqB;IACvD,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAqB;IACvD,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqB;IAExD;;;;OAIG;WACW,mBAAmB,CAAC,MAAM,EAAE;QACtC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,GAAG,IAAI;IAWR;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;WACW,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAqB9C,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAKlC,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAMlC,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAMnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;WACW,UAAU,CACpB,GAAG,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,EACzB,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,GAChE,IAAI;IAkBP;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAY5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAShC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAUhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;CASpC"}