@liberstudio/cloudflare-list 2.2.9 → 2.3.1

package/README.md

@@ -1,16 +1,49 @@
-# Modulo NestJS per la gestione IP List Cloudflare
+# @liberstudio/cloudflare-list
 
-## Prima di iniziare
+Modulo NestJS per il rilevamento e blocco automatico di attacchi tramite Cloudflare IP List.
+
+Ogni richiesta che produce un `404` viene considerata sospetta (tipicamente bot, scanner, enumeratori). L'IP viene risolto tramite ASN lookup per ottenere l'intero range di subnet e bloccarlo direttamente sulla lista Cloudflare WAF. Se il lookup fallisce, viene bloccato il singolo IP.
+
+## Come funziona
+
+```
+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
+```
+
+### Filtraggio automatico
+
+Il modulo ignora automaticamente:
+- 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)
+
+### Gestione errori e log
+
+- `AllExceptionsFilter` globale cattura tutte le eccezioni non gestite e le logga a console con IP, metodo, path e status code
+- Con `verbose: true` il log include anche body, query, params e stack trace
+
+---
+
+## Prima di iniziare su Cloudflare
 
 1. Creare un account Cloudflare
-2. Scegliere il Dominio da utilizzare
-3. Manage Account > Configuration > List > Create List
-4. Account API tokens > Create Token > Create Custom Token (Permission: Account > Account WAF > Edit, Account > Account Filter List > Edit)
-5. Salvare il token API senza scadenza
-6. Domains > Scegliere il dominio da utilizzare
-7. Andare nella categoria Security > Security Rules > Create rule > Custom Rules
-8. Nome: <Name>, Field: <IP Source Address , is in, scegli la lista creata prima>, Action: Block
-9. Salvare la regola
+2. Scegliere il dominio da utilizzare
+3. **Manage Account > Configuration > Lists > Create List** (tipo: IP)
+4. **Account API tokens > Create Token > Create Custom Token**
+   - Permission: `Account > Account WAF > Edit`
+   - Permission: `Account > Account Filter Lists > Edit`
+5. **Security > WAF > Custom Rules > Create Rule**
+   - Field: `IP Source Address` — `is in` — scegli la lista creata
+   - Action: `Block`
+6. Salvare la regola
+
+---
 
 ## Installazione
 
@@ -18,11 +51,11 @@
 npm install @liberstudio/cloudflare-list
 ```
 
-## Utilizzo
+---
 
-### Configurazione
+## Configurazione
 
-Nel file di configurazione del progetto, aggiungere il modulo all'import della configurazione:
+### Statica (`forRoot`)
 
 ```typescript
 import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
@@ -30,21 +63,21 @@ import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
 @Module({
   imports: [
     CloudflareAttacksModule.forRoot({
-      accountId: "<account_id>",
-      listId: "<list_id>",
-      apiToken: "<api_token>",
-      comment: "<comment>",
-      logPath: "<logPath>",
-      excludedPaths: "<excludedList>",
-      silentPaths: "<silentList>",
-      verbose: false, // default: false — log solo riga breve; true = log completo con body, query, stack
+      accountId: "abc123",
+      listId:    "def456",
+      apiToken:  "your-cloudflare-api-token",
+      comment:   "Blocked by liberstudio/cloudflare-list",
+      logPath:   "/var/log/nestjs-attacks.log",
+      excludedPaths: ["/api/health", "/api/webhook"],
+      silentPaths:   ["/auth/me", "/auth/refresh"],
+      verbose: false,
     }),
   ],
 })
 export class AppModule {}
 ```
 
-## Versione Asincrona con ConfigModule
+### Asincrona (`forRootAsync`) con `ConfigModule`
 
 ```typescript
 import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
@@ -53,16 +86,16 @@ import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
   imports: [
     CloudflareAttacksModule.forRootAsync({
       imports: [ConfigModule],
-      inject: [ConfigService],
+      inject:  [ConfigService],
       useFactory: (config: ConfigService) => ({
-        apiToken: config.getOrThrow<string>("CLOUDFLARE_API_TOKEN"),
+        apiToken:  config.getOrThrow<string>("CLOUDFLARE_API_TOKEN"),
         accountId: config.getOrThrow<string>("CLOUDFLARE_ACCOUNT_ID"),
-        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",
+        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",
         excludedPaths: ["/api/health", "/api/webhook", /^\/api\/public\/.*/],
-        silentPaths: ["/auth/me", "/auth/refresh"],
-        verbose: false, // default: false — log solo riga breve; true = log completo con body, query, stack
+        silentPaths:   ["/auth/me", "/auth/refresh"],
+        verbose: false,
       }),
     }),
   ],
@@ -70,6 +103,28 @@ import { CloudflareAttacksModule } from "@liberstudio/cloudflare-list";
 export class AppModule {}
 ```
 
+---
+
+## Opzioni di configurazione
+
+| Opzione | Tipo | Obbligatorio | Descrizione |
+|---|---|---|---|
+| `apiToken` | `string` | si | Token API Cloudflare |
+| `accountId` | `string` | si | ID account Cloudflare |
+| `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 |
+| `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 |
+
+### `excludedPaths` vs `silentPaths`
+
+- **`excludedPaths`**: il path viene ignorato completamente — nessun log, nessun blocco. Usato per path infrastrutturali (`/health`, `/webhook`).
+- **`silentPaths`**: il path viene bloccato su Cloudflare ma non viene scritto sul file di log. Usato per path che generano 404 legittimi frequenti (`/auth/me`, `/auth/refresh`).
+
+---
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/attacks.service.d.ts

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

package/dist/attacks.service.js

@@ -28,13 +28,33 @@ let AttacksService = class AttacksService {
         this.options = options;
         this.logger = new common_1.Logger("AttackLogger");
         this.API_URL = `https://api.cloudflare.com/client/v4/accounts`;
+        this.ASN_LOOKUP_URL = `https://api.hackertarget.com/aslookup`;
     }
-    async updateIpList(ip) {
+    async blockIp(rawIp) {
+        const asnRange = await this.lookupAsnRange(rawIp);
+        if (asnRange) {
+            this.logger.log(`ASN range trovato per ${rawIp}: ${asnRange} — blocco intera subnet`);
+            return this.updateIpList(asnRange);
+        }
+        const cidr = (0, utils_1.normalizeIp)(rawIp);
+        if (!cidr)
+            throw new Error(`IP non valido: ${rawIp}`);
+        return this.updateIpList(cidr);
+    }
+    async lookupAsnRange(ip) {
+        try {
+            const response = await (0, rxjs_1.firstValueFrom)(this.httpService.get(`${this.ASN_LOOKUP_URL}/?q=${ip}&output=json`));
+            return response.data?.asn_range ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async updateIpList(cidr) {
         const { accountId, listId, apiToken, comment } = this.options;
         const url = `${this.API_URL}/${accountId}/rules/lists/${listId}/items`;
-        this.logger.error(`Aggiungo IP ${ip} alla lista Cloudflare`);
-        const formattedIp = ip.includes("/") ? ip : `${ip}/32`;
-        const body = [{ ip: formattedIp, comment }];
+        this.logger.log(`Aggiungo ${cidr} alla lista Cloudflare`);
+        const body = [{ ip: cidr, comment }];
         try {
             const response = await (0, rxjs_1.firstValueFrom)(this.httpService.post(url, body, {
                 headers: {

package/dist/filters/all-exceptions.filter.js

@@ -50,10 +50,10 @@ let AllExceptionsFilter = AllExceptionsFilter_1 = class AllExceptionsFilter {
         if (!isSilentPath) {
             const verbose = this.options?.verbose === true;
             if (status >= 500) {
-                this.logger.error(`[${ip}] [${request.method}] ${request.url} → ${status}`, verbose ? JSON.stringify(errorLog, null, 2) : undefined);
+                this.logger.error(`[${ip}] [${request.method}] ${request.url} → ${status}`, verbose ? JSON.stringify(errorLog, null, 2) : message);
             }
             else {
-                this.logger.warn(`[${ip}] [${request.method}] ${request.url} → ${status}`, verbose ? JSON.stringify(errorLog, null, 2) : undefined);
+                this.logger.warn(`[${ip}] [${request.method}] ${request.url} → ${status}`, verbose ? JSON.stringify(errorLog, null, 2) : message);
             }
         }
         response.status(status).json({

package/dist/interfaces/asn-lookup.interface.d.ts

@@ -0,0 +1,6 @@
+export interface AsnLookupResponse {
+    asn: string;
+    asn_name: string;
+    asn_range: string;
+    ip: string;
+}

package/dist/interfaces/asn-lookup.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/index.d.ts

@@ -1,2 +1,3 @@
+export * from './asn-lookup.interface';
 export * from './cloudflare-attacks.interface';
 export * from './cloudflare-response.interface';

package/dist/interfaces/index.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./asn-lookup.interface"), exports);
 __exportStar(require("./cloudflare-attacks.interface"), exports);
 __exportStar(require("./cloudflare-response.interface"), exports);

package/dist/middleware/attack-logger.middleware.d.ts

@@ -16,5 +16,6 @@ export declare class AttackLoggerMiddleware implements NestMiddleware, OnModuleD
     private sanitize;
     private ensureDirectoryExists;
     private isExcluded;
+    private isSilent;
     onModuleDestroy(): void;
 }

package/dist/middleware/attack-logger.middleware.js

@@ -52,25 +52,32 @@ let AttackLoggerMiddleware = AttackLoggerMiddleware_1 = class AttackLoggerMiddle
         const ip = (0, utils_1.getClientIp)(req);
         if (!ip || this.isThrottled(ip))
             return;
-        const entry = {
-            timestamp: new Date().toISOString(),
-            type: "ATTACK",
-            ip,
-            method: req.method,
-            url: this.sanitize(req.url),
-        };
-        const line = JSON.stringify(entry) + "\n";
-        if (!this.stream.write(line)) {
-            this.stream.once("drain", () => {
-                this.logger.debug("Stream del log degli attacchi svuotato");
-            });
+        const silent = this.isSilent(req.url);
+        if (!silent) {
+            const entry = {
+                timestamp: new Date().toISOString(),
+                type: "ATTACK",
+                ip,
+                method: req.method,
+                url: this.sanitize(req.url),
+                ...(this.options.verbose && {
+                    query: req.query,
+                    body: req.body,
+                }),
+            };
+            const line = JSON.stringify(entry) + "\n";
+            if (!this.stream.write(line)) {
+                this.stream.once("drain", () => {
+                    this.logger.debug("Stream del log degli attacchi svuotato");
+                });
+            }
         }
         const cidr = (0, utils_1.normalizeIp)(ip);
         if (!cidr) {
             this.logger.warn(`IP non valido: ${ip}`);
             return;
         }
-        this.attSrv.updateIpList(cidr).catch((err) => {
+        this.attSrv.blockIp(ip).catch((err) => {
             const msg = err instanceof Error ? err.message : "Errore sconosciuto";
             this.logger.error(`Aggiornamento Cloudflare fallito: ${msg}`);
         });
@@ -98,6 +105,9 @@ let AttackLoggerMiddleware = AttackLoggerMiddleware_1 = class AttackLoggerMiddle
         const excluded = this.options.excludedPaths ?? [];
         return excluded.some((p) => (p instanceof RegExp ? p.test(url) : url.startsWith(p)));
     }
+    isSilent(url) {
+        return (this.options.silentPaths ?? []).some((p) => p instanceof RegExp ? p.test(url) : url.startsWith(p));
+    }
     onModuleDestroy() {
         this.stream.end();
         for (const timeout of this.recentIps.values()) {

package/package.json

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