@liberstudio/cloudflare-list 2.3.4 → 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.js

@@ -31,6 +31,10 @@ 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;

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

@@ -1 +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

@@ -3,6 +3,7 @@ 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");
@@ -60,6 +61,29 @@ function isInCidrV6(ip, cidr) {
     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;

package/package.json

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