@j3r3mcdev/scoring 1.0.0

package/src/normalizers/__tests__/normalizer-registry.test.ts

@@ -0,0 +1,89 @@
+import { normalizeEvent, Normalizers } from "../index";
+import { HttpNormalizer } from "../http.normalizer";
+import { DnsNormalizer } from "../dns.normalizer";
+import { WafNormalizer } from "../waf.normalizer";
+
+describe("NormalizerRegistry (PRO)", () => {
+  // ─────────────────────────────────────────────────────────────
+  //  Vérifie que le registry expose bien les normalizers
+  // ─────────────────────────────────────────────────────────────
+  it("expose correctement les normalizers", () => {
+    expect(Normalizers.http).toBe(HttpNormalizer);
+    expect(Normalizers.dns).toBe(DnsNormalizer);
+    expect(Normalizers.waf).toBe(WafNormalizer);
+  });
+
+  // ─────────────────────────────────────────────────────────────
+  //  Vérifie le dispatch dynamique pour HTTP
+  // ─────────────────────────────────────────────────────────────
+  it("normalizeEvent('http') utilise HttpNormalizer", () => {
+    const spy = jest.spyOn(HttpNormalizer, "normalize").mockReturnValue({
+      id: "123",
+      source: "http",
+      timestamp: 1,
+      payload: "test",
+      metadata: {},
+    });
+
+    const raw = { method: "GET", url: "/test" };
+    const evt = normalizeEvent("http", raw);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(raw);
+    expect(evt.source).toBe("http");
+
+    spy.mockRestore();
+  });
+
+  // ─────────────────────────────────────────────────────────────
+  //  Vérifie le dispatch dynamique pour DNS
+  // ─────────────────────────────────────────────────────────────
+  it("normalizeEvent('dns') utilise DnsNormalizer", () => {
+    const spy = jest.spyOn(DnsNormalizer, "normalize").mockReturnValue({
+      id: "456",
+      source: "dns",
+      timestamp: 1,
+      payload: "example.com",
+      metadata: {},
+    });
+
+    const raw = { query: "example.com" };
+    const evt = normalizeEvent("dns", raw);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(raw);
+    expect(evt.source).toBe("dns");
+
+    spy.mockRestore();
+  });
+
+  // ─────────────────────────────────────────────────────────────
+  //  Vérifie le dispatch dynamique pour WAF
+  // ─────────────────────────────────────────────────────────────
+  it("normalizeEvent('waf') utilise WafNormalizer", () => {
+    const spy = jest.spyOn(WafNormalizer, "normalize").mockReturnValue({
+      id: "789",
+      source: "waf",
+      timestamp: 1,
+      payload: "WAF score: 0.9",
+      metadata: {},
+    });
+
+    const raw = { score: 0.9 };
+    const evt = normalizeEvent("waf", raw);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(raw);
+    expect(evt.source).toBe("waf");
+
+    spy.mockRestore();
+  });
+
+  // ─────────────────────────────────────────────────────────────
+  //  Vérifie qu'une source inconnue provoque une erreur claire
+  // ─────────────────────────────────────────────────────────────
+  it("lance une erreur si la source est inconnue", () => {
+    // @ts-expect-error volontaire : test d'erreur runtime
+    expect(() => normalizeEvent("unknown", {})).toThrow();
+  });
+});

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

@@ -0,0 +1,45 @@
+import { WafNormalizer } from "../waf.normalizer";
+
+describe("WafNormalizer (PRO)", () => {
+  it("normalise un signal WAF complet", () => {
+    const raw = {
+      score: 0.92,
+      triggeredRules: ["xss", "sqli"],
+      ip: "8.8.8.8",
+      path: "/admin",
+      method: "GET",
+      message: "Suspicious activity detected",
+    };
+
+    const evt = WafNormalizer.normalize(raw);
+
+    expect(evt.source).toBe("waf");
+    expect(evt.payload).toBe("Suspicious activity detected");
+    expect(evt.metadata.wafScore).toBe(0.92);
+    expect(evt.metadata.triggeredRules).toContain("xss");
+    expect(evt.metadata.ip).toBe("8.8.8.8");
+  });
+
+  it("fallback payload si aucun message n'est fourni", () => {
+    const raw = { score: 0.5 };
+    const evt = WafNormalizer.normalize(raw);
+
+    expect(evt.payload).toBe("WAF score: 0.5");
+  });
+
+  it("gère un signal WAF minimal", () => {
+    const evt = WafNormalizer.normalize({});
+    expect(evt.metadata.wafScore).toBe(0);
+    expect(evt.payload).toBe("WAF event");
+  });
+
+  it("gère triggeredRules non fournis", () => {
+    const evt = WafNormalizer.normalize({ score: 0.7 });
+    expect(evt.metadata.triggeredRules).toEqual([]);
+  });
+
+  it("gère un score non numérique", () => {
+    const evt = WafNormalizer.normalize({ score: "invalid" });
+    expect(evt.metadata.wafScore).toBe("invalid");
+  });
+});

package/src/normalizers/dns.normalizer.ts

@@ -0,0 +1,28 @@
+import { NormalizedEvent } from "../core/scoring-types";
+import crypto from "crypto";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  DNS NORMALIZER — Transforme un événement DNS brut
+ *  en NormalizedEvent standardisé pour le moteur de scoring.
+ * ─────────────────────────────────────────────────────────────
+ */
+export class DnsNormalizer {
+  static normalize(raw: any): NormalizedEvent {
+    return {
+      id: crypto.randomUUID(),
+      source: "dns",
+      timestamp: Date.now(),
+
+      // Payload utile pour les règles DNS / SSRF / Correlation
+      payload: raw.query ?? "",
+
+      metadata: {
+        ip: raw.ip ?? "unknown",
+        query: raw.query ?? "",
+        recordType: raw.type ?? "A",
+        raw: raw.raw ?? null,
+      },
+    };
+  }
+}

package/src/normalizers/http.normalizer.ts

@@ -0,0 +1,53 @@
+import { NormalizedEvent } from "../core/scoring-types";
+import crypto from "crypto";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  HTTP NORMALIZER — Transforme une requête HTTP brute
+ *  en NormalizedEvent standardisé pour le moteur de scoring.
+ * ─────────────────────────────────────────────────────────────
+ */
+export class HttpNormalizer {
+  static normalize(req: any): NormalizedEvent {
+    return {
+      id: crypto.randomUUID(),
+      source: "http",
+      timestamp: Date.now(),
+
+      payload: HttpNormalizer.extractPayload(req),
+
+      metadata: {
+        method: req.method ?? "UNKNOWN",
+        path: req.url ?? "/",
+        headers: req.headers ?? {},
+        ip: HttpNormalizer.extractIp(req),
+        query: req.query ?? {},
+        body: req.body ?? null,
+      },
+    };
+  }
+
+  /**
+   * Extraction du payload utile pour les règles (RCE, LFI, SSRF…)
+   */
+  private static extractPayload(req: any): string {
+    const body =
+      typeof req.body === "string" ? req.body : JSON.stringify(req.body ?? "");
+
+    const query =
+      typeof req.query === "string"
+        ? req.query
+        : JSON.stringify(req.query ?? "");
+
+    return `${req.method} ${req.url} | query=${query} | body=${body}`;
+  }
+
+  /**
+   * Extraction IP (X-Forwarded-For > socket)
+   */
+  private static extractIp(req: any): string {
+    return (
+      req.headers?.["x-forwarded-for"] || req.socket?.remoteAddress || "unknown"
+    );
+  }
+}

package/src/normalizers/index.ts

@@ -0,0 +1,34 @@
+import { NormalizedEvent } from "../core/scoring-types";
+import { HttpNormalizer } from "./http.normalizer";
+import { DnsNormalizer } from "./dns.normalizer";
+import { WafNormalizer } from "./waf.normalizer";
+
+/**
+ * Type générique pour un normalizer.
+ * Tous les normalizers doivent exposer une méthode static normalize().
+ */
+export type Normalizer = {
+  normalize: (raw: any) => NormalizedEvent;
+};
+
+/**
+ * Registry simple des normalizers disponibles.
+ * Peut être étendu plus tard (scan, oast, smtp…)
+ */
+export const Normalizers = {
+  http: HttpNormalizer,
+  dns: DnsNormalizer,
+  waf: WafNormalizer,
+} as const;
+
+/**
+ * Helper : normalisation dynamique selon la source.
+ */
+export function normalizeEvent(
+  source: keyof typeof Normalizers,
+  raw: any,
+): NormalizedEvent {
+  return Normalizers[source].normalize(raw);
+}
+
+export { HttpNormalizer, DnsNormalizer, WafNormalizer };

package/src/normalizers/waf.normalizer.ts

@@ -0,0 +1,39 @@
+import { NormalizedEvent } from "../core/scoring-types";
+import crypto from "crypto";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  WAF NORMALIZER — Transforme un signal WAF brut
+ *  en NormalizedEvent standardisé pour le moteur de scoring.
+ * ─────────────────────────────────────────────────────────────
+ */
+export class WafNormalizer {
+  static normalize(raw: any): NormalizedEvent {
+    return {
+      id: crypto.randomUUID(),
+      source: "waf",
+      timestamp: Date.now(),
+
+      // Le payload est volontairement simple : le score ou le message
+      payload: WafNormalizer.extractPayload(raw),
+
+      metadata: {
+        wafScore: raw.score ?? 0,
+        triggeredRules: raw.triggeredRules ?? [],
+        ip: raw.ip ?? "unknown",
+        path: raw.path ?? null,
+        method: raw.method ?? null,
+        raw: raw,
+      },
+    };
+  }
+
+  /**
+   * Le payload doit être une string exploitable par les règles.
+   */
+  private static extractPayload(raw: any): string {
+    if (typeof raw.message === "string") return raw.message;
+    if (typeof raw.score === "number") return `WAF score: ${raw.score}`;
+    return "WAF event";
+  }
+}

package/src/reporters/__tests__/html-reporter.test.ts

@@ -0,0 +1,51 @@
+import { HTMLReporter } from "../html/HTMLReporter";
+import { Finding, CorrelationChain } from "../../core/scoring-types";
+
+describe("HTMLReporter", () => {
+  const reporter = new HTMLReporter();
+
+  const findings: Finding[] = [
+    {
+      id: "f1",
+      vulnerability: "xss",
+      severity: "medium",
+      score: 55,
+      details: "<b>HTML</b> injection",
+      evidence: ["<script>alert(1)</script>"] as any[],
+      chains: [],
+    },
+  ];
+
+  const chains: CorrelationChain[] = [
+    {
+      id: "c1",
+      type: "xss",
+      confidence: 0.8,
+      events: [{ id: "e1", source: "path", timestamp: 123 }] as any[],
+    },
+  ];
+
+  it("génère un HTML valide", () => {
+    const out = reporter.generate(findings, chains);
+
+    expect(out.mime).toBe("text/html");
+    expect(out.content).toContain("<html");
+    expect(out.content).toContain("<h1>");
+    expect(out.content).toContain("Findings");
+    expect(out.content).toContain("Correlation Chains");
+  });
+
+  it("échappe correctement le HTML dangereux", () => {
+    const out = reporter.generate(findings, []);
+
+    expect(out.content).toContain("&lt;b&gt;HTML&lt;/b&gt;");
+    expect(out.content).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+  });
+
+  it("gère un rapport vide", () => {
+    const out = reporter.generate([], []);
+
+    expect(out.content).toContain("_No findings detected._");
+    expect(out.content).toContain("_No chains detected._");
+  });
+});

package/src/reporters/__tests__/json-reporter.test.ts

@@ -0,0 +1,50 @@
+import { JSONReporter } from "../json/JSONReporter";
+import { Finding, CorrelationChain } from "../../core/scoring-types";
+
+describe("JSONReporter", () => {
+  const reporter = new JSONReporter();
+
+  const findings: Finding[] = [
+    {
+      id: "f1",
+      vulnerability: "xss",
+      severity: "high",
+      score: 80,
+      details: "Reflected XSS detected",
+      evidence: [{ id: "ev1", source: "payload", timestamp: 789 }] as any[],
+      chains: [],
+    },
+  ];
+
+  const chains: CorrelationChain[] = [
+    {
+      id: "c1",
+      type: "xss",
+      confidence: 0.9,
+      events: [
+        { id: "e1", source: "path", timestamp: 123 },
+        { id: "e2", source: "path", timestamp: 456 },
+      ] as any[],
+    },
+  ];
+
+  it("génère un JSON valide", () => {
+    const out = reporter.generate(findings, chains);
+
+    expect(out.mime).toBe("application/json");
+
+    const parsed = JSON.parse(out.content);
+
+    expect(parsed.format).toBe("json");
+    expect(parsed.summary.totalFindings).toBe(1);
+    expect(parsed.summary.totalChains).toBe(1);
+  });
+
+  it("gère un rapport vide", () => {
+    const out = reporter.generate([], []);
+    const parsed = JSON.parse(out.content);
+
+    expect(parsed.summary.totalFindings).toBe(0);
+    expect(parsed.summary.totalChains).toBe(0);
+  });
+});

package/src/reporters/__tests__/markdown-reporter.test.ts

@@ -0,0 +1,75 @@
+import { MarkdownReporter } from "../markdown/MarkdownReporter";
+import { Finding, CorrelationChain } from "../../core/scoring-types";
+
+describe("MarkdownReporter", () => {
+  const reporter = new MarkdownReporter();
+
+  const findings: Finding[] = [
+    {
+      id: "f1",
+      vulnerability: "sqli",
+      severity: "critical",
+      score: 95,
+      details: "SQL injection detected",
+      evidence: [
+        { id: "ev1", source: "payload", timestamp: 111 },
+        { id: "ev2", source: "db", timestamp: 222 },
+      ] as any[],
+      chains: [],
+    },
+  ];
+
+  const chains: CorrelationChain[] = [
+    {
+      id: "c1",
+      type: "sqli",
+      confidence: 0.85,
+      events: [
+        { id: "e1", source: "path", timestamp: 123 },
+        { id: "e2", source: "query", timestamp: 456 },
+      ] as any[],
+    },
+  ];
+
+  it("génère un markdown avec les sections obligatoires", () => {
+    const out = reporter.generate(findings, chains);
+
+    expect(out.mime).toBe("text/markdown");
+
+    expect(out.content).toContain("# Security Scan Report");
+    expect(out.content).toContain("## Summary");
+    expect(out.content).toContain("## Findings");
+    expect(out.content).toContain("## Correlation Chains");
+
+    // Vérifie que la vulnérabilité apparaît bien
+    expect(out.content).toContain("SQLI");
+  });
+
+  it("échappe correctement le markdown dangereux", () => {
+    const out = reporter.generate(
+      [
+        {
+          id: "f2",
+          vulnerability: "xss",
+          severity: "high",
+          score: 80,
+          details: "`code` *bold* _italic_",
+          evidence: [],
+          chains: [],
+        },
+      ],
+      [],
+    );
+
+    expect(out.content).toContain("\\`code\\`");
+    expect(out.content).toContain("\\*bold\\*");
+    expect(out.content).toContain("\\_italic\\_");
+  });
+
+  it("gère un rapport vide", () => {
+    const out = reporter.generate([], []);
+
+    expect(out.content).toContain("_No findings detected._");
+    expect(out.content).toContain("_No chains detected._");
+  });
+});

package/src/reporters/__tests__/reporter-factory.test.ts

@@ -0,0 +1,25 @@
+import { createReporter } from "../reporter-factory";
+import { JSONReporter } from "../json/JSONReporter";
+import { MarkdownReporter } from "../markdown/MarkdownReporter";
+import { HTMLReporter } from "../html/HTMLReporter";
+
+describe("ReporterFactory", () => {
+  it("retourne un JSONReporter", () => {
+    const r = createReporter("json");
+    expect(r).toBeInstanceOf(JSONReporter);
+  });
+
+  it("retourne un MarkdownReporter", () => {
+    const r = createReporter("markdown");
+    expect(r).toBeInstanceOf(MarkdownReporter);
+  });
+
+  it("retourne un HTMLReporter", () => {
+    const r = createReporter("html");
+    expect(r).toBeInstanceOf(HTMLReporter);
+  });
+
+  it("lève une erreur pour un format inconnu", () => {
+    expect(() => createReporter("unknown" as any)).toThrow();
+  });
+});

package/src/reporters/__tests__/reporters-integration.test.ts

@@ -0,0 +1,46 @@
+import { createReporter } from "../reporter-factory";
+import { Finding, CorrelationChain } from "../../core/scoring-types";
+
+describe("Reporters Integration", () => {
+  const findings: Finding[] = [
+    {
+      id: "f1",
+      vulnerability: "sqli",
+      severity: "high",
+      score: 75,
+      details: "SQL injection",
+      evidence: [{ id: "ev1", source: "payload", timestamp: 111 }] as any[],
+      chains: [],
+    },
+  ];
+
+  const chains: CorrelationChain[] = [
+    {
+      id: "c1",
+      type: "sqli",
+      confidence: 0.9,
+      events: [{ id: "e1", source: "path", timestamp: 123 }] as any[],
+    },
+  ];
+
+  const formats = ["json", "markdown", "html"] as const;
+
+  for (const format of formats) {
+    it(`génère un rapport complet en ${format}`, () => {
+      const reporter = createReporter(format);
+      const out = reporter.generate(findings, chains);
+
+      expect(out.filename).toContain(
+        format === "markdown" ? ".md" : `.${format}`,
+      );
+      expect(out.content.length).toBeGreaterThan(50);
+      expect(out.mime).toBe(
+        format === "json"
+          ? "application/json"
+          : format === "markdown"
+            ? "text/markdown"
+            : "text/html",
+      );
+    });
+  }
+});

package/src/reporters/base/BaseReporter.ts

@@ -0,0 +1,56 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  BASE REPORTER — Version PRO
+ *  Classe abstraite pour tous les reporters (JSON, MD, HTML)
+ * ─────────────────────────────────────────────────────────────
+ */
+
+import { Finding, CorrelationChain } from "../../core/scoring-types";
+import { ReporterMetadata, ReporterOutput } from "./ReporterTypes";
+
+export abstract class BaseReporter {
+  /**
+   * Nom du reporter (ex: "json", "markdown", "html").
+   */
+  abstract getName(): string;
+
+  /**
+   * Extension du fichier généré (ex: ".json", ".md", ".html").
+   */
+  abstract getExtension(): string;
+
+  /**
+   * Génère le rapport final.
+   */
+  abstract generate(
+    findings: Finding[],
+    chains: CorrelationChain[],
+    metadata?: ReporterMetadata,
+  ): ReporterOutput;
+
+  /**
+   * Vérifie que les données d'entrée sont valides.
+   */
+  protected validateInput(
+    findings: Finding[],
+    chains: CorrelationChain[],
+  ): void {
+    if (!Array.isArray(findings)) {
+      throw new Error("findings must be an array");
+    }
+    if (!Array.isArray(chains)) {
+      throw new Error("chains must be an array");
+    }
+  }
+
+  /**
+   * Prépare les données avant génération (tri, normalisation…).
+   * Peut être overridé par les reporters avancés.
+   */
+  protected prepareData(
+    findings: Finding[],
+    chains: CorrelationChain[],
+  ): { findings: Finding[]; chains: CorrelationChain[] } {
+    return { findings, chains };
+  }
+}

package/src/reporters/base/ReporterTypes.ts

@@ -0,0 +1,21 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  REPORTER TYPES — Version PRO
+ *  Types communs à tous les reporters
+ * ─────────────────────────────────────────────────────────────
+ */
+
+export interface ReporterMetadata {
+  generatedAt?: number; // timestamp
+  title?: string;
+  target?: string; // service, app, env…
+  version?: string; // version du moteur
+}
+
+export interface ReporterOutput {
+  filename: string;
+  content: string;
+  mime: string;
+}
+
+export type ReporterFormat = "json" | "markdown" | "html";