@j3r3mcdev/scoring 1.0.0

package/src/core/scoring-result.ts

@@ -0,0 +1,15 @@
+import { ScoringResult } from "./scoring-types";
+
+/**
+ * Helper pour créer un résultat vide (utile pour les tests).
+ */
+export function createEmptyResult(): ScoringResult {
+  return {
+    score: 0,
+    severity: "low",
+    findings: [],
+    chains: [],
+    timestamp: Date.now(),
+    metadata: {},
+  };
+}

package/src/core/scoring-types.ts

@@ -0,0 +1,125 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  SCORING TYPES — Version avancée et stable
+ *  Source de vérité unique pour tout le moteur.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+//
+// 1. Vulnérabilités supportées
+//
+export type Vulnerability =
+  | "ssrf"
+  | "xss"
+  | "sqli"
+  | "dns"
+  | "http"
+  | "waf"
+  | "rce"
+  | "lfi"
+  | "path_traversal";
+
+//
+// 2. Sévérité standardisée
+//
+export type Severity = "low" | "medium" | "high" | "critical";
+
+//
+// 3. Source d’un événement normalisé
+//
+export type EventSource = "http" | "dns" | "waf" | "scan" | "oast";
+
+//
+// 4. Événement normalisé (format unique pour tout le moteur)
+//
+export interface NormalizedEvent {
+  id: string; // UUID
+  source: EventSource;
+  protocol?: string; // http, dns, smtp, websocket, etc.
+  timestamp: number;
+
+  // Payload brut ou transformé
+  payload?: string;
+
+  // Données additionnelles (headers, body, metadata…)
+  metadata: Record<string, any>;
+}
+
+//
+// 5. Résultat d’une règle individuelle
+//
+export interface RuleFinding {
+  ruleId: string;
+  vulnerability: Vulnerability;
+  score: number; // score brut (0 → 1)
+  severity: Severity;
+  details?: string;
+}
+
+//
+// 6. Chaîne de corrélation (ex : DNS → HTTP = SSRF)
+//
+export interface CorrelationChain {
+  id: string;
+  type: Vulnerability;
+  events: NormalizedEvent[];
+  confidence: number; // 0 → 1
+}
+
+//
+// 7. Résultat final d’une vulnérabilité consolidée
+//
+export interface Finding {
+  id: string;
+  vulnerability: Vulnerability;
+  severity: Severity;
+  score: number; // score final pondéré
+  evidence: NormalizedEvent[];
+  chains?: CorrelationChain[];
+  details?: string;
+}
+
+//
+// 8. Interface de base pour toutes les règles
+//
+export interface Rule {
+  id: string;
+  name: string;
+  description?: string;
+
+  /**
+   * Vérifie si la règle doit s’appliquer au contexte.
+   */
+  applies(context: ScoringContext): boolean;
+
+  /**
+   * Retourne un ou plusieurs findings bruts.
+   */
+  execute(context: ScoringContext): RuleFinding[];
+}
+
+//
+// 9. Contexte minimal pour les règles et le moteur
+//
+export interface ScoringContext {
+  events: NormalizedEvent[];
+  chains: CorrelationChain[];
+  metadata?: Record<string, any>;
+}
+
+//
+// 10. Résultat final du moteur de scoring
+//
+export interface ScoringResult {
+  score: number; // score global (0–100)
+  severity: Severity;
+  findings: Finding[];
+  chains: CorrelationChain[];
+  timestamp: number;
+
+  /**
+   * Métadonnées additionnelles (optionnelles).
+   * Ex : cible, IP, user-agent, contexte d'analyse…
+   */
+  metadata?: Record<string, any>;
+}

package/src/correlation/__tests__/chain-detector.test.ts

@@ -0,0 +1,76 @@
+import { ChainDetector } from "../chain-detector";
+import { NormalizedEvent } from "../../core/scoring-types";
+
+const evt = (partial: Partial<NormalizedEvent>): NormalizedEvent => ({
+  id: partial.id ?? "id",
+  source: partial.source ?? "http",
+  timestamp: partial.timestamp ?? Date.now(),
+  payload: partial.payload ?? "",
+  metadata: partial.metadata ?? {},
+});
+
+describe("ChainDetector (PRO)", () => {
+  it("détecte une chaîne SSRF (HTTP + DNS)", () => {
+    const events = [
+      evt({ source: "http", timestamp: 1 }),
+      evt({ source: "dns", timestamp: 2 }),
+    ];
+
+    const chains = ChainDetector.detect(events);
+
+    expect(chains.length).toBe(1);
+    expect(chains[0].chain).toBe("ssrf_chain");
+    expect(chains[0].events.length).toBe(2);
+  });
+
+  it("détecte une chaîne XSS (HTTP + WAF)", () => {
+    const events = [
+      evt({ source: "http", timestamp: 1 }),
+      evt({
+        source: "waf",
+        timestamp: 2,
+        metadata: { triggeredRules: ["xss"] },
+      }),
+    ];
+
+    const chains = ChainDetector.detect(events);
+
+    expect(chains.some((c) => c.chain === "xss_chain")).toBe(true);
+  });
+
+  it("détecte une chaîne SQLi", () => {
+    const events = [
+      evt({ source: "http", timestamp: 1 }),
+      evt({
+        source: "waf",
+        timestamp: 2,
+        metadata: { triggeredRules: ["sqli"] },
+      }),
+    ];
+
+    const chains = ChainDetector.detect(events);
+
+    expect(chains.some((c) => c.chain === "sqli_chain")).toBe(true);
+  });
+
+  it("détecte une chaîne WAF confirmée (score >= 0.9)", () => {
+    const events = [
+      evt({
+        source: "waf",
+        metadata: { wafScore: 0.95 },
+      }),
+    ];
+
+    const chains = ChainDetector.detect(events);
+
+    expect(chains.some((c) => c.chain === "waf_confirmed_chain")).toBe(true);
+  });
+
+  it("ne détecte rien si aucun pattern n'est présent", () => {
+    const events = [evt({ source: "http" }), evt({ source: "http" })];
+
+    const chains = ChainDetector.detect(events);
+
+    expect(chains.length).toBe(0);
+  });
+});

package/src/correlation/__tests__/correlator.test.ts

@@ -0,0 +1,49 @@
+import { Correlator } from "../correlator";
+import { NormalizedEvent } from "../../core/scoring-types";
+
+const evt = (partial: Partial<NormalizedEvent>): NormalizedEvent => ({
+  id: partial.id ?? "id",
+  source: partial.source ?? "http",
+  timestamp: partial.timestamp ?? Date.now(),
+  payload: partial.payload ?? "",
+  metadata: partial.metadata ?? {},
+});
+
+describe("Correlator (PRO)", () => {
+  it("retourne des groupes et des chaînes", () => {
+    const events = [
+      evt({ source: "http", timestamp: 1, metadata: { ip: "1.1.1.1" } }),
+      evt({ source: "dns", timestamp: 2, metadata: { ip: "1.1.1.1" } }),
+    ];
+
+    const result = Correlator.correlate(events);
+
+    expect(result.groups.length).toBe(1);
+    expect(result.chains.length).toBe(1);
+    expect(result.chains[0].chain).toBe("ssrf_chain");
+  });
+
+  it("gère plusieurs groupes distincts", () => {
+    const events = [
+      evt({ metadata: { ip: "A" } }),
+      evt({ metadata: { ip: "B" } }),
+    ];
+
+    const result = Correlator.correlate(events);
+
+    expect(result.groups.length).toBe(2);
+  });
+
+  it("lance une erreur si l'entrée n'est pas un tableau", () => {
+    // @ts-expect-error test volontaire
+    expect(() => Correlator.correlate(null)).toThrow();
+  });
+
+  it("ne détecte aucune chaîne si aucun pattern n'est présent", () => {
+    const events = [evt({ source: "http" }), evt({ source: "http" })];
+
+    const result = Correlator.correlate(events);
+
+    expect(result.chains.length).toBe(0);
+  });
+});

package/src/correlation/__tests__/event-grouper.test.ts

@@ -0,0 +1,62 @@
+import { EventGrouper } from "../event-grouper";
+import { NormalizedEvent } from "../../core/scoring-types";
+
+const evt = (partial: Partial<NormalizedEvent>): NormalizedEvent => ({
+  id: partial.id ?? "id",
+  source: partial.source ?? "http",
+  timestamp: partial.timestamp ?? Date.now(),
+  payload: partial.payload ?? "",
+  metadata: partial.metadata ?? {},
+});
+
+describe("EventGrouper (PRO)", () => {
+  it("groupe les événements par IP (par défaut)", () => {
+    const events = [
+      evt({ metadata: { ip: "1.1.1.1" } }),
+      evt({ metadata: { ip: "1.1.1.1" } }),
+      evt({ metadata: { ip: "2.2.2.2" } }),
+    ];
+
+    const groups = EventGrouper.groupBy(events);
+
+    expect(groups.length).toBe(2);
+    expect(groups.find((g) => g.key === "1.1.1.1")!.events.length).toBe(2);
+    expect(groups.find((g) => g.key === "2.2.2.2")!.events.length).toBe(1);
+  });
+
+  it("groupe selon un sélecteur personnalisé", () => {
+    const events = [
+      evt({ metadata: { sessionId: "A" } }),
+      evt({ metadata: { sessionId: "B" } }),
+      evt({ metadata: { sessionId: "A" } }),
+    ];
+
+    const groups = EventGrouper.groupBy(events, (e) => e.metadata.sessionId);
+
+    expect(groups.length).toBe(2);
+    expect(groups.find((g) => g.key === "A")!.events.length).toBe(2);
+  });
+
+  it("gère les événements sans clé (fallback 'unknown')", () => {
+    const events = [evt({ metadata: {} }), evt({ metadata: {} })];
+
+    const groups = EventGrouper.groupBy(events);
+
+    expect(groups.length).toBe(1);
+    expect(groups[0].key).toBe("unknown");
+    expect(groups[0].events.length).toBe(2);
+  });
+
+  it("tri les événements dans chaque groupe", () => {
+    const events = [
+      evt({ timestamp: 3, metadata: { ip: "1.1.1.1" } }),
+      evt({ timestamp: 1, metadata: { ip: "1.1.1.1" } }),
+      evt({ timestamp: 2, metadata: { ip: "1.1.1.1" } }),
+    ];
+
+    const groups = EventGrouper.groupBy(events);
+    const timestamps = groups[0].events.map((e) => e.timestamp);
+
+    expect(timestamps).toEqual([1, 2, 3]);
+  });
+});

package/src/correlation/chain-detector.ts

@@ -0,0 +1,99 @@
+import { NormalizedEvent } from "../core/scoring-types";
+
+export type AttackChain =
+  | "ssrf_chain"
+  | "xss_chain"
+  | "sqli_chain"
+  | "lfi_chain"
+  | "path_traversal_chain"
+  | "waf_confirmed_chain";
+
+export interface ChainDetectionResult {
+  chain: AttackChain;
+  events: NormalizedEvent[];
+}
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  CHAIN DETECTOR — Détecte les chaînes d’attaque multi‑événements
+ *  Exemple : HTTP suspect → DNS interne → WAF → SSRF confirmé
+ * ─────────────────────────────────────────────────────────────
+ */
+export class ChainDetector {
+  /**
+   * Analyse une liste d'événements normalisés et détecte
+   * les chaînes d’attaque connues.
+   */
+  static detect(events: NormalizedEvent[]): ChainDetectionResult[] {
+    const results: ChainDetectionResult[] = [];
+
+    // Tri chronologique (important pour les chaînes)
+    const sorted = [...events].sort((a, b) => a.timestamp - b.timestamp);
+
+    // ─────────────────────────────────────────────────────────────
+    // 1. Chaîne SSRF : HTTP → DNS → WAF
+    // ─────────────────────────────────────────────────────────────
+    const http = sorted.find((e) => e.source === "http");
+    const dns = sorted.find((e) => e.source === "dns");
+    const waf = sorted.find((e) => e.source === "waf");
+
+    if (http && dns) {
+      results.push({
+        chain: "ssrf_chain",
+        events: [http, dns, ...(waf ? [waf] : [])],
+      });
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // 2. Chaîne XSS : HTTP → WAF
+    // ─────────────────────────────────────────────────────────────
+    if (http && waf && waf.metadata.triggeredRules?.includes("xss")) {
+      results.push({
+        chain: "xss_chain",
+        events: [http, waf],
+      });
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // 3. Chaîne SQLi : HTTP → WAF
+    // ─────────────────────────────────────────────────────────────
+    if (http && waf && waf.metadata.triggeredRules?.includes("sqli")) {
+      results.push({
+        chain: "sqli_chain",
+        events: [http, waf],
+      });
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // 4. Chaîne LFI : HTTP → WAF
+    // ─────────────────────────────────────────────────────────────
+    if (http && waf && waf.metadata.triggeredRules?.includes("lfi")) {
+      results.push({
+        chain: "lfi_chain",
+        events: [http, waf],
+      });
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // 5. Chaîne Path Traversal : HTTP → WAF
+    // ─────────────────────────────────────────────────────────────
+    if (http && waf && waf.metadata.triggeredRules?.includes("path")) {
+      results.push({
+        chain: "path_traversal_chain",
+        events: [http, waf],
+      });
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // 6. Chaîne WAF Confirmed : WAF seul
+    // ─────────────────────────────────────────────────────────────
+    if (waf && waf.metadata.wafScore >= 0.9) {
+      results.push({
+        chain: "waf_confirmed_chain",
+        events: [waf],
+      });
+    }
+
+    return results;
+  }
+}

package/src/correlation/correlator.ts

@@ -0,0 +1,39 @@
+import { NormalizedEvent } from "../core/scoring-types";
+import { EventGrouper, EventGroup } from "./event-grouper";
+import { ChainDetector, ChainDetectionResult } from "./chain-detector";
+
+export interface CorrelationResult {
+  groups: EventGroup[];
+  chains: ChainDetectionResult[];
+}
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  CORRELATOR — Orchestrateur de la corrélation
+ *  1. Regroupe les événements (EventGrouper)
+ *  2. Détecte les chaînes d’attaque (ChainDetector)
+ * ─────────────────────────────────────────────────────────────
+ */
+export class Correlator {
+  static correlate(events: NormalizedEvent[]): CorrelationResult {
+    if (!Array.isArray(events)) {
+      throw new Error("Correlator: events must be an array");
+    }
+
+    // 1. Groupement logique (par IP par défaut)
+    const groups = EventGrouper.groupBy(events);
+
+    // 2. Détection des chaînes dans chaque groupe
+    const chains: ChainDetectionResult[] = [];
+
+    for (const group of groups) {
+      const detected = ChainDetector.detect(group.events);
+      chains.push(...detected);
+    }
+
+    return {
+      groups,
+      chains,
+    };
+  }
+}

package/src/correlation/event-grouper.ts

@@ -0,0 +1,47 @@
+import { NormalizedEvent } from "../core/scoring-types";
+
+export interface EventGroup {
+  key: string;
+  events: NormalizedEvent[];
+}
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  EVENT GROUPER — Regroupe les événements par contexte
+ *  (IP, sessionId, requestId, etc.)
+ * ─────────────────────────────────────────────────────────────
+ */
+export class EventGrouper {
+  /**
+   * Regroupe les événements selon une clé dynamique.
+   * Par défaut : groupement par IP.
+   */
+  static groupBy(
+    events: NormalizedEvent[],
+    selector: (evt: NormalizedEvent) => string = EventGrouper.defaultSelector,
+  ): EventGroup[] {
+    const map = new Map<string, NormalizedEvent[]>();
+
+    for (const evt of events) {
+      const key = selector(evt) || "unknown";
+
+      if (!map.has(key)) {
+        map.set(key, []);
+      }
+
+      map.get(key)!.push(evt);
+    }
+
+    return Array.from(map.entries()).map(([key, events]) => ({
+      key,
+      events: events.sort((a, b) => a.timestamp - b.timestamp),
+    }));
+  }
+
+  /**
+   * Sélecteur par défaut : groupement par IP.
+   */
+  private static defaultSelector(evt: NormalizedEvent): string {
+    return evt.metadata?.ip ?? "unknown";
+  }
+}

package/src/correlation/index.ts

@@ -0,0 +1,3 @@
+export * from "./chain-detector";
+export * from "./event-grouper";
+export * from "./correlator";

package/src/index.ts

@@ -0,0 +1,21 @@
+// ─────────────────────────────────────────────────────────────
+//  CORE (scoring complet)
+// ─────────────────────────────────────────────────────────────
+export * from "./core";
+
+// ─────────────────────────────────────────────────────────────
+//  RULES
+// ─────────────────────────────────────────────────────────────
+export * from "./rules";
+export * from "./rules/rule-registry";
+
+// ─────────────────────────────────────────────────────────────
+//  NORMALIZERS
+// ─────────────────────────────────────────────────────────────
+export * from "./normalizers";
+export { Normalizers, normalizeEvent } from "./normalizers";
+
+// ─────────────────────────────────────────────────────────────
+//  CORRELATION
+// ─────────────────────────────────────────────────────────────
+export * from "./correlation";

package/src/normalizers/__tests__/dns.normalizer.test.ts

@@ -0,0 +1,40 @@
+import { DnsNormalizer } from "../dns.normalizer";
+
+describe("DnsNormalizer (PRO)", () => {
+  it("normalise un événement DNS complet", () => {
+    const raw = {
+      ip: "10.0.0.5",
+      query: "internal.service.local",
+      type: "A",
+      raw: { packet: true },
+    };
+
+    const evt = DnsNormalizer.normalize(raw);
+
+    expect(evt.source).toBe("dns");
+    expect(evt.payload).toBe("internal.service.local");
+    expect(evt.metadata.ip).toBe("10.0.0.5");
+    expect(evt.metadata.recordType).toBe("A");
+  });
+
+  it("gère un événement DNS minimal", () => {
+    const raw = { query: "example.com" };
+    const evt = DnsNormalizer.normalize(raw);
+
+    expect(evt.metadata.ip).toBe("unknown");
+    expect(evt.metadata.recordType).toBe("A");
+  });
+
+  it("gère un événement DNS sans query", () => {
+    const evt = DnsNormalizer.normalize({});
+    expect(evt.payload).toBe("");
+    expect(evt.metadata.query).toBe("");
+  });
+
+  it("gère un événement DNS avec type inconnu", () => {
+    const raw = { query: "test", type: "AAAAA" };
+    const evt = DnsNormalizer.normalize(raw);
+
+    expect(evt.metadata.recordType).toBe("AAAAA");
+  });
+});

package/src/normalizers/__tests__/http.normalizer.test.ts

@@ -0,0 +1,55 @@
+import { HttpNormalizer } from "../http.normalizer";
+
+describe("HttpNormalizer (PRO)", () => {
+  it("normalise correctement une requête HTTP complète", () => {
+    const raw = {
+      method: "POST",
+      url: "/login",
+      headers: { "x-forwarded-for": "1.2.3.4", host: "example.com" },
+      query: { user: "admin" },
+      body: { pass: "123" },
+      socket: { remoteAddress: "5.6.7.8" },
+    };
+
+    const evt = HttpNormalizer.normalize(raw);
+
+    expect(evt.source).toBe("http");
+    expect(typeof evt.id).toBe("string");
+    expect(typeof evt.timestamp).toBe("number");
+
+    expect(evt.payload).toContain("POST /login");
+    expect(evt.metadata.method).toBe("POST");
+    expect(evt.metadata.path).toBe("/login");
+    expect(evt.metadata.headers.host).toBe("example.com");
+    expect(evt.metadata.ip).toBe("1.2.3.4");
+  });
+
+  it("gère une requête sans headers ni body", () => {
+    const raw = { method: "GET", url: "/test" };
+    const evt = HttpNormalizer.normalize(raw);
+
+    expect(evt.metadata.headers).toEqual({});
+    expect(evt.metadata.body).toBe(null);
+  });
+
+  it("gère une requête avec body string", () => {
+    const raw = { method: "POST", url: "/x", body: "raw-body" };
+    const evt = HttpNormalizer.normalize(raw);
+
+    expect(evt.payload).toContain("raw-body");
+  });
+
+  it("fallback IP si aucune info n'est fournie", () => {
+    const raw = { method: "GET", url: "/" };
+    const evt = HttpNormalizer.normalize(raw);
+
+    expect(evt.metadata.ip).toBe("unknown");
+  });
+
+  it("gère un input vide sans planter", () => {
+    const evt = HttpNormalizer.normalize({});
+    expect(evt.source).toBe("http");
+    expect(evt.metadata.method).toBe("UNKNOWN");
+    expect(evt.metadata.path).toBe("/");
+  });
+});