@liberstudio/cloudflare-list 2.3.2 → 2.3.6

package/README.md

@@ -11,14 +11,18 @@ Request → 404 rilevato dal middleware
   └─ IP estratto (cf-connecting-ip / x-real-ip / x-forwarded-for)
        └─ throttle 5s per IP
             └─ log su file (se path non è silentPath)
-                 └─ ASN lookup su api.hackertarget.com
-                      ├─ range trovato → blocca intera subnet su Cloudflare
-                      └─ fallback      → blocca singolo IP /32 o /128
+                 └─ allowedIps? → skip (log only)
+                      └─ IP Cloudflare? → skip (log only)
+                           └─ ASN lookup su api.hackertarget.com
+                                ├─ range trovato → blocca intera subnet su Cloudflare
+                                └─ fallback      → blocca singolo IP /32 o /128
 ```
 
 ### Filtraggio automatico
 
 Il modulo ignora automaticamente:
+- IP nella whitelist `allowedIps` (configurazione statica)
+- IP appartenenti ai range ufficiali Cloudflare (scaricati e cachati 24h)
 - IP privati (10.x, 192.168.x, 172.16–31.x)
 - Loopback (127.0.0.1, ::1)
 - IPv4-mapped IPv6 (::ffff:x.x.x.x → convertiti in IPv4)
@@ -68,6 +72,7 @@ import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
       apiToken:  "your-cloudflare-api-token",
       comment:   "Blocked by liberstudio/cloudflare-list",
       logPath:   "/var/log/nestjs-attacks.log",
+      allowedIps:    ["1.2.3.4", "10.0.0.0/8"],
       excludedPaths: ["/api/health", "/api/webhook"],
       silentPaths:   ["/auth/me", "/auth/refresh"],
       verbose: false,
@@ -93,6 +98,7 @@ import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
         listId:    config.getOrThrow<string>("CLOUDFLARE_LIST_ID"),
         comment:   config.get<string>("CLOUDFLARE_LIST_COMMENT") || "Blocked",
         logPath:   config.get<string>("CLOUDFLARE_LIST_LOG_PATH") || "/var/log/nestjs-attacks.log",
+        allowedIps:    ["1.2.3.4", "10.0.0.0/8"],
         excludedPaths: ["/api/health", "/api/webhook", /^\/api\/public\/.*/],
         silentPaths:   ["/auth/me", "/auth/refresh"],
         verbose: false,
@@ -114,10 +120,26 @@ export class AppModule {}
 | `listId` | `string` | si | ID della IP List Cloudflare |
 | `comment` | `string` | si | Commento aggiunto ad ogni IP bloccato |
 | `logPath` | `string` | si | Percorso del file di log degli attacchi |
+| `allowedIps` | `string[]` | no | IP o CIDR mai bloccati (whitelist, supporta IPv4 e IPv6) |
 | `excludedPaths` | `(string \| RegExp)[]` | no | Path esclusi da ogni rilevamento e log |
 | `silentPaths` | `(string \| RegExp)[]` | no | Path bloccati su Cloudflare ma senza log su file |
 | `verbose` | `boolean` | no | Se `true`, il log include body, query, params e stack |
 
+### `allowedIps` — whitelist server
+
+Lista di IP o subnet CIDR che non vengono mai bloccati, indipendentemente dal comportamento. Utile per i propri server, proxy interni, CDN proprietarie. Supporta IPv4, CIDR IPv4, IPv6 e CIDR IPv6:
+
+```typescript
+allowedIps: [
+  "1.2.3.4",           // IP singolo IPv4
+  "10.0.0.0/8",        // subnet IPv4
+  "2001:db8::1",       // IP singolo IPv6
+  "2001:db8::/32",     // subnet IPv6
+]
+```
+
+> I range ufficiali Cloudflare sono esclusi automaticamente senza bisogno di aggiungerli qui.
+
 ### `excludedPaths` vs `silentPaths`
 
 - **`excludedPaths`**: il path viene ignorato completamente — nessun log, nessun blocco. Usato per path infrastrutturali (`/health`, `/webhook`).

package/dist/attacks.service.d.ts

@@ -7,7 +7,7 @@ export declare class AttacksService {
     private readonly API_URL;
     private readonly ASN_LOOKUP_URL;
     constructor(httpService: HttpService, options: CloudflareAttacksOptions);
-    blockIp(rawIp: string): Promise<CloudflareResponse>;
+    blockIp(rawIp: string): Promise<CloudflareResponse | null>;
     private lookupAsnRange;
     updateIpList(cidr: string): Promise<CloudflareResponse>;
 }

package/dist/attacks.service.js

@@ -31,6 +31,14 @@ let AttacksService = class AttacksService {
         this.ASN_LOOKUP_URL = `https://api.hackertarget.com/aslookup`;
     }
     async blockIp(rawIp) {
+        if ((0, utils_1.isAllowedIp)(rawIp, this.options.allowedIps ?? [])) {
+            this.logger.log(`IP ${rawIp} in whitelist — ban saltato`);
+            return null;
+        }
+        if (await (0, utils_1.isCloudflareIp)(rawIp)) {
+            this.logger.log(`IP ${rawIp} appartiene al range Cloudflare — ban saltato`);
+            return null;
+        }
         const asnRange = await this.lookupAsnRange(rawIp);
         if (asnRange) {
             this.logger.log(`ASN range trovato per ${rawIp}: ${asnRange} — blocco intera subnet`);

package/dist/interfaces/cloudflare-attacks.interface.d.ts

@@ -4,6 +4,7 @@ export interface CloudflareAttacksOptions {
     listId: string;
     comment: string;
     logPath: string;
+    allowedIps?: string[];
     excludedPaths?: (string | RegExp)[];
     silentPaths?: (string | RegExp)[];
     verbose?: boolean;

package/dist/utils/cloudflare-ips.util.d.ts

@@ -0,0 +1,2 @@
+export declare function isAllowedIp(ip: string, allowedIps: string[]): boolean;
+export declare function isCloudflareIp(ip: string): Promise<boolean>;

package/dist/utils/cloudflare-ips.util.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowedIp = isAllowedIp;
+exports.isCloudflareIp = isCloudflareIp;
+const axios_1 = __importDefault(require("axios"));
+const net_1 = require("net");
+const CF_IPS_V4_URL = "https://www.cloudflare.com/ips-v4/";
+const CF_IPS_V6_URL = "https://www.cloudflare.com/ips-v6/";
+const TTL_MS = 24 * 60 * 60 * 1000;
+let cache = null;
+let inFlight = null;
+async function loadCloudflareIps() {
+    if (cache && Date.now() < cache.expiresAt)
+        return cache;
+    if (inFlight)
+        return inFlight;
+    inFlight = (async () => {
+        const [v4Res, v6Res] = await Promise.all([
+            axios_1.default.get(CF_IPS_V4_URL, { responseType: "text" }),
+            axios_1.default.get(CF_IPS_V6_URL, { responseType: "text" }),
+        ]);
+        const parse = (data) => data.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+        cache = {
+            v4: parse(v4Res.data),
+            v6: parse(v6Res.data),
+            expiresAt: Date.now() + TTL_MS,
+        };
+        return cache;
+    })().finally(() => {
+        inFlight = null;
+    });
+    return inFlight;
+}
+function ipv4ToInt(ip) {
+    return ip.split(".").reduce((acc, oct) => (acc << 8) + Number(oct), 0) >>> 0;
+}
+function ipv6ToBigInt(ip) {
+    const [headStr, tailStr] = ip.includes("::") ? ip.split("::") : [ip, ""];
+    const head = headStr ? headStr.split(":") : [];
+    const tail = tailStr ? tailStr.split(":") : [];
+    const missing = 8 - head.length - tail.length;
+    const groups = [...head, ...Array(missing).fill("0"), ...tail];
+    return groups.reduce((acc, g) => (acc << 16n) + BigInt(parseInt(g || "0", 16)), 0n);
+}
+function isInCidrV4(ip, cidr) {
+    const [range, bitsStr] = cidr.split("/");
+    const bits = bitsStr === undefined ? 32 : Number(bitsStr);
+    if (bits === 0)
+        return true;
+    const mask = (0xffffffff << (32 - bits)) >>> 0;
+    return (ipv4ToInt(ip) & mask) === (ipv4ToInt(range) & mask);
+}
+function isInCidrV6(ip, cidr) {
+    const [range, bitsStr] = cidr.split("/");
+    const prefix = bitsStr === undefined ? 128 : Number(bitsStr);
+    if (prefix === 0)
+        return true;
+    const mask = ((1n << 128n) - 1n) ^ ((1n << BigInt(128 - prefix)) - 1n);
+    return (ipv6ToBigInt(ip) & mask) === (ipv6ToBigInt(range) & mask);
+}
+function isAllowedIp(ip, allowedIps) {
+    if (!ip || !allowedIps.length)
+        return false;
+    let pure = ip.includes("/") ? ip.split("/")[0] : ip;
+    pure = pure.trim();
+    if (pure.startsWith("::ffff:"))
+        pure = pure.slice("::ffff:".length);
+    const version = (0, net_1.isIP)(pure);
+    if (!version)
+        return false;
+    return allowedIps.some((entry) => {
+        let entryPure = entry.includes("/") ? entry.split("/")[0] : entry;
+        entryPure = entryPure.trim();
+        if (entryPure.startsWith("::ffff:"))
+            entryPure = entryPure.slice("::ffff:".length);
+        const entryVersion = (0, net_1.isIP)(entryPure);
+        if (!entryVersion || entryVersion !== version)
+            return false;
+        return version === 4
+            ? isInCidrV4(pure, entry)
+            : isInCidrV6(pure, entry);
+    });
+}
+async function isCloudflareIp(ip) {
+    if (!ip)
+        return false;
+    let pure = ip.includes("/") ? ip.split("/")[0] : ip;
+    pure = pure.trim();
+    if (pure.startsWith("::ffff:"))
+        pure = pure.slice("::ffff:".length);
+    const version = (0, net_1.isIP)(pure);
+    if (!version)
+        return false;
+    try {
+        const { v4, v6 } = await loadCloudflareIps();
+        return version === 4
+            ? v4.some((cidr) => isInCidrV4(pure, cidr))
+            : v6.some((cidr) => isInCidrV6(pure, cidr));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from './cloudflare.constants';
+export * from './cloudflare-ips.util';
 export * from './get-client-ip.util';
 export * from './options.validator';

package/dist/utils/index.js

@@ -15,5 +15,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./cloudflare.constants"), exports);
+__exportStar(require("./cloudflare-ips.util"), exports);
 __exportStar(require("./get-client-ip.util"), exports);
 __exportStar(require("./options.validator"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liberstudio/cloudflare-list",
-  "version": "2.3.2",
+  "version": "2.3.6",
   "description": "Modulo NestJS per gestione IP List Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",