@j3r3mcdev/scoring 1.0.0

package/src/rules/ssrf.rules.ts

@@ -0,0 +1,76 @@
+import { Rule, RuleFinding, ScoringContext } from "../core/scoring-types";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  SSRF RULE — Détection simple basée sur les patterns classiques
+ *  Version minimaliste, sans callback OAST (viendra plus tard).
+ *  Compatible avec le moteur de scoring.
+ * ─────────────────────────────────────────────────────────────
+ */
+export class SsrfRule implements Rule {
+  id = "ssrf-basic";
+  name = "Basic SSRF Detection";
+  description = "Détecte les patterns SSRF classiques dans les événements normalisés.";
+
+  /**
+   * La règle s’applique si au moins un event contient un payload suspect.
+   */
+  applies(context: ScoringContext): boolean {
+    return context.events.some(
+      (evt) => typeof evt.payload === "string" && this.containsSsrf(evt.payload)
+    );
+  }
+
+  /**
+   * Retourne un ou plusieurs findings SSRF.
+   */
+  execute(context: ScoringContext): RuleFinding[] {
+    const findings: RuleFinding[] = [];
+
+    for (const evt of context.events) {
+      if (typeof evt.payload !== "string") continue;
+
+      if (this.containsSsrf(evt.payload)) {
+        findings.push({
+          ruleId: this.id,
+          vulnerability: "ssrf",
+          score: 0.9, // score brut (0 → 1)
+          severity: "critical",
+          details: `Payload SSRF détecté : ${evt.payload}`,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Détection simple de patterns SSRF.
+   */
+  private containsSsrf(input: string): boolean {
+    const patterns = [
+      // Accès aux IP internes
+      /127\.0\.0\.1/i,
+      /localhost/i,
+      /0\.0\.0\.0/i,
+      /169\.254\.169\.254/i, // AWS metadata
+      /metadata\.google\.internal/i,
+      /metadata\/v1/i,
+
+      // Protocoles dangereux
+      /file:\/\//i,
+      /gopher:\/\//i,
+      /dict:\/\//i,
+      /ftp:\/\//i,
+
+      // Bypass classiques
+      /\[::1\]/i,
+      /@localhost/i,
+      /\/\/localhost/i,
+      /\/\/127\.0\.0\.1/i,
+    ];
+
+    return patterns.some((regex) => regex.test(input));
+  }
+
+}

package/src/rules/waf.rules.ts

@@ -0,0 +1,62 @@
+import { Rule, RuleFinding, ScoringContext } from "../core/scoring-types";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  WAF RULE — Agrégation des signaux WAF
+ *  Cette règle transforme les scores WAF en findings consolidés.
+ *  Elle ne détecte rien elle-même : elle consomme les signaux
+ *  produits par ton middleware WAF.
+ * ─────────────────────────────────────────────────────────────
+ */
+export class WafRule implements Rule {
+  id = "waf-basic";
+  name = "Basic WAF Signal Aggregation";
+  description = "Transforme les signaux WAF (scores) en findings consolidés.";
+
+  /**
+   * La règle s’applique si au moins un event WAF contient un score.
+   */
+  applies(context: ScoringContext): boolean {
+    return context.events.some(
+      (evt) =>
+        evt.source === "waf" &&
+        typeof evt.metadata?.wafScore === "number" &&
+        evt.metadata.wafScore > 0,
+    );
+  }
+
+  /**
+   * Retourne un ou plusieurs findings basés sur les scores WAF.
+   */
+  execute(context: ScoringContext): RuleFinding[] {
+    const findings: RuleFinding[] = [];
+
+    for (const evt of context.events) {
+      if (evt.source !== "waf") continue;
+
+      const score =
+        typeof evt.metadata?.wafScore === "number" ? evt.metadata.wafScore : 0;
+
+      if (score <= 0) continue;
+
+      const severity =
+        score >= 0.85
+          ? "critical"
+          : score >= 0.65
+            ? "high"
+            : score >= 0.4
+              ? "medium"
+              : "low";
+
+      findings.push({
+        ruleId: this.id,
+        vulnerability: "waf",
+        score,
+        severity,
+        details: `Score WAF détecté (${score}) sur l’événement ${evt.id}`,
+      });
+    }
+
+    return findings;
+  }
+}

package/src/rules/xss.rules.ts

@@ -0,0 +1,66 @@
+import { Rule, RuleFinding, ScoringContext } from "../core/scoring-types";
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  XSS RULE — Détection simple basée sur les patterns classiques
+ *  Cette règle est volontairement minimaliste :
+ *  - pas d’heuristique lourde
+ *  - pas de normalizer
+ *  - pas de dépendance externe
+ *  - compatible avec le moteur de scoring
+ * ─────────────────────────────────────────────────────────────
+ */
+export class XssRule implements Rule {
+  id = "xss-basic";
+  name = "Basic XSS Detection";
+  description =
+    "Détecte les patterns XSS classiques dans les événements normalisés.";
+
+  /**
+   * La règle s’applique si au moins un event contient un payload exploitable.
+   */
+  applies(context: ScoringContext): boolean {
+    return context.events.some(
+      (evt) => typeof evt.payload === "string" && this.containsXss(evt.payload),
+    );
+  }
+
+  /**
+   * Retourne un ou plusieurs findings XSS.
+   */
+  execute(context: ScoringContext): RuleFinding[] {
+    const findings: RuleFinding[] = [];
+
+    for (const evt of context.events) {
+      if (typeof evt.payload !== "string") continue;
+
+      if (this.containsXss(evt.payload)) {
+        findings.push({
+          ruleId: this.id,
+          vulnerability: "xss",
+          score: 0.8, // score brut (0 → 1)
+          severity: "high",
+          details: `Payload suspect détecté : ${evt.payload}`,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Détection simple de patterns XSS.
+   */
+  private containsXss(input: string): boolean {
+    const patterns = [
+      /<script[\s>]/i,
+      /<\/script>/i,
+      /on\w+=/i, // onclick=, onerror=, onload=...
+      /javascript:/i,
+      /alert\s*\(/i,
+      /document\.cookie/i,
+    ];
+
+    return patterns.some((regex) => regex.test(input));
+  }
+}

package/src/utils/chain-utils.ts

@@ -0,0 +1,73 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  CHAIN UTILS — Version PRO
+ *  Outils avancés pour manipuler les chaînes de corrélation.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+import { CorrelationChain, NormalizedEvent } from "../core/scoring-types";
+
+/**
+ * Retourne un label lisible pour la confiance (0 → 1).
+ */
+export function chainConfidenceLabel(confidence: number): string {
+  if (confidence >= 0.9) return "very_high";
+  if (confidence >= 0.75) return "high";
+  if (confidence >= 0.5) return "medium";
+  if (confidence >= 0.25) return "low";
+  return "very_low";
+}
+
+/**
+ * Formate une chaîne en texte lisible (pour Markdown/HTML).
+ */
+export function formatChain(chain: CorrelationChain): string {
+  const events = chain.events
+    .map(
+      (e) => `${e.source.toUpperCase()}@${new Date(e.timestamp).toISOString()}`,
+    )
+    .join(" → ");
+
+  return `${chain.type.toUpperCase()} (${chainConfidenceLabel(chain.confidence)})\n${events}`;
+}
+
+/**
+ * Résumé compact d'une chaîne (pour tableaux, JSON, logs).
+ */
+export function chainSummary(chain: CorrelationChain): string {
+  const first = chain.events[0];
+  const last = chain.events[chain.events.length - 1];
+
+  return `${chain.type} | ${first.source} → ${last.source} | conf=${chain.confidence.toFixed(2)}`;
+}
+
+/**
+ * Trie les chaînes par confiance décroissante.
+ */
+export function sortChains(chains: CorrelationChain[]): CorrelationChain[] {
+  return [...chains].sort((a, b) => b.confidence - a.confidence);
+}
+
+/**
+ * Groupe les chaînes par type de vulnérabilité.
+ */
+export function groupChainsByType(
+  chains: CorrelationChain[],
+): Record<string, CorrelationChain[]> {
+  return chains.reduce(
+    (acc, chain) => {
+      if (!acc[chain.type]) acc[chain.type] = [];
+      acc[chain.type].push(chain);
+      return acc;
+    },
+    {} as Record<string, CorrelationChain[]>,
+  );
+}
+
+/**
+ * Génère une signature unique pour une chaîne (utile pour les reporters).
+ */
+export function chainSignature(chain: CorrelationChain): string {
+  const ids = chain.events.map((e: NormalizedEvent) => e.id).join("-");
+  return `${chain.type}:${ids}`;
+}

package/src/utils/date-utils.ts

@@ -0,0 +1,80 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  DATE UTILS — Version PRO
+ *  Outils avancés pour formater les dates dans les rapports.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+/**
+ * Formate un timestamp en ISO (lisible, stable, triable).
+ */
+export function formatIso(timestamp: number): string {
+  return new Date(timestamp).toISOString();
+}
+
+/**
+ * Formate une date en format humain (YYYY-MM-DD HH:mm:ss).
+ */
+export function formatHuman(timestamp: number): string {
+  const d = new Date(timestamp);
+
+  const pad = (n: number) => n.toString().padStart(2, "0");
+
+  return (
+    `${d.getFullYear()}-` +
+    `${pad(d.getMonth() + 1)}-` +
+    `${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:` +
+    `${pad(d.getMinutes())}:` +
+    `${pad(d.getSeconds())}`
+  );
+}
+
+/**
+ * Retourne la durée entre deux timestamps (ms → texte lisible).
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ${sec % 60}s`;
+
+  const h = Math.floor(min / 60);
+  if (h < 24) return `${h}h ${min % 60}m`;
+
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+/**
+ * Retourne "il y a X" (utile pour les rapports Markdown/HTML).
+ */
+export function timeAgo(timestamp: number): string {
+  const diff = Date.now() - timestamp;
+
+  const sec = Math.floor(diff / 1000);
+  if (sec < 60) return `${sec}s ago`;
+
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+
+  const h = Math.floor(min / 60);
+  if (h < 24) return `${h}h ago`;
+
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+
+/**
+ * Retourne un objet détaillé (utile pour JSON reporter).
+ */
+export function dateInfo(timestamp: number) {
+  return {
+    iso: formatIso(timestamp),
+    human: formatHuman(timestamp),
+    ago: timeAgo(timestamp),
+  };
+}

package/src/utils/finding-utils.ts

@@ -0,0 +1,97 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  FINDING UTILS — Version PRO
+ *  Outils avancés pour manipuler les findings consolidés.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+import { Finding, Severity } from "../core/scoring-types";
+
+/**
+ * Poids interne pour trier les sévérités.
+ */
+const SEVERITY_ORDER: Record<Severity, number> = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1,
+};
+
+/**
+ * Trie les findings par sévérité décroissante.
+ */
+export function sortFindingsBySeverity(findings: Finding[]): Finding[] {
+  return [...findings].sort(
+    (a, b) => SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity],
+  );
+}
+
+/**
+ * Trie les findings par score décroissant.
+ */
+export function sortFindingsByScore(findings: Finding[]): Finding[] {
+  return [...findings].sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Groupe les findings par vulnérabilité.
+ */
+export function groupFindingsByVulnerability(
+  findings: Finding[],
+): Record<string, Finding[]> {
+  return findings.reduce((acc, f) => {
+    if (!acc[f.vulnerability]) acc[f.vulnerability] = [];
+    acc[f.vulnerability].push(f);
+    return acc;
+  }, {} as Record<string, Finding[]>);
+}
+
+/**
+ * Filtre les findings par sévérité minimale.
+ */
+export function filterFindingsBySeverity(
+  findings: Finding[],
+  min: Severity,
+): Finding[] {
+  const minWeight = SEVERITY_ORDER[min];
+  return findings.filter((f) => SEVERITY_ORDER[f.severity] >= minWeight);
+}
+
+/**
+ * Génère une signature unique pour un finding.
+ * Utile pour les reporters, logs, déduplication.
+ */
+export function findingSignature(f: Finding): string {
+  return `${f.vulnerability}:${f.score}:${f.severity}`;
+}
+
+/**
+ * Résumé compact d’un finding (pour tableaux, logs, JSON).
+ */
+export function findingSummary(f: Finding): string {
+  return `${f.vulnerability.toUpperCase()} | score=${f.score} | severity=${f.severity}`;
+}
+
+/**
+ * Fusionne plusieurs findings du même type (utile si un reporter veut regrouper).
+ */
+export function mergeFindings(findings: Finding[]): Finding {
+  if (findings.length === 1) return findings[0];
+
+  const base = findings[0];
+
+  const merged: Finding = {
+    ...base,
+    score: Math.max(...findings.map((f) => f.score)),
+    severity: findings.reduce(
+      (acc, f) =>
+        SEVERITY_ORDER[f.severity] > SEVERITY_ORDER[acc] ? f.severity : acc,
+      base.severity,
+    ),
+    evidence: findings.flatMap((f) => f.evidence),
+    chains: findings.flatMap((f) => f.chains ?? []),
+    details: findings.map((f) => f.details ?? "").join("\n"),
+  };
+
+  return merged;
+}

package/src/utils/index.ts

@@ -0,0 +1,6 @@
+export * from "./string-utils";
+export * from "./date-utils";
+export * from "./score-utils";
+export * from "./finding-utils";
+export * from "./chain-utils";
+export * from "./report-utils";

package/src/utils/report-utils.ts

@@ -0,0 +1,118 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  REPORT UTILS — Version PRO
+ *  Outils avancés pour générer du Markdown, HTML et JSON propres.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+/**
+ * Échappe les caractères Markdown sensibles.
+ */
+export function escapeMarkdown(text: string): string {
+  if (!text) return "";
+  return text
+    .replace(/\\/g, "\\\\")
+    .replace(/`/g, "\\`")
+    .replace(/\*/g, "\\*")
+    .replace(/_/g, "\\_")
+    .replace(/{/g, "\\{")
+    .replace(/}/g, "\\}")
+    .replace(/\[/g, "\\[")
+    .replace(/]/g, "\\]")
+    .replace(/\(/g, "\\(")
+    .replace(/\)/g, "\\)")
+    .replace(/#/g, "\\#")
+    .replace(/\+/g, "\\+")
+    .replace(/-/g, "\\-")
+    .replace(/\!/g, "\\!");
+}
+
+/**
+ * Échappe les caractères HTML dangereux.
+ */
+export function escapeHtml(text: string): string {
+  if (!text) return "";
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Nettoie un texte pour éviter les injections dans les rapports.
+ */
+export function sanitizeText(text: string): string {
+  if (!text) return "";
+  return escapeHtml(text).trim();
+}
+
+/**
+ * Rend une liste Markdown propre.
+ */
+export function renderList(items: string[]): string {
+  if (!items || items.length === 0) return "- (empty)";
+  return items.map((i) => `- ${escapeMarkdown(i)}`).join("\n");
+}
+
+/**
+ * Rend un tableau Markdown.
+ */
+export function renderTable(headers: string[], rows: string[][]): string {
+  const escapedHeaders = headers.map(escapeMarkdown);
+  const escapedRows = rows.map((row) => row.map(escapeMarkdown));
+
+  const headerLine = `| ${escapedHeaders.join(" | ")} |`;
+  const separator = `| ${escapedHeaders.map(() => "---").join(" | ")} |`;
+  const rowLines = escapedRows.map((r) => `| ${r.join(" | ")} |`);
+
+  return [headerLine, separator, ...rowLines].join("\n");
+}
+
+/**
+ * Rend un bloc de code Markdown.
+ */
+export function renderCodeBlock(code: string, lang = ""): string {
+  return `\`\`\`${lang}\n${code}\n\`\`\``;
+}
+
+/**
+ * Rend une section Markdown avec un titre.
+ */
+export function renderSection(title: string, content: string): string {
+  return `## ${escapeMarkdown(title)}\n\n${content}`;
+}
+
+/**
+ * Rend un paragraphe HTML sécurisé.
+ */
+export function renderHtmlParagraph(text: string): string {
+  return `<p>${escapeHtml(text)}</p>`;
+}
+
+/**
+ * Rend une liste HTML sécurisée.
+ */
+export function renderHtmlList(items: string[]): string {
+  const li = items.map((i) => `<li>${escapeHtml(i)}</li>`).join("");
+  return `<ul>${li}</ul>`;
+}
+
+/**
+ * Rend un tableau HTML sécurisé.
+ */
+export function renderHtmlTable(headers: string[], rows: string[][]): string {
+  const thead = `<tr>${headers
+    .map((h) => `<th>${escapeHtml(h)}</th>`)
+    .join("")}</tr>`;
+
+  const tbody = rows
+    .map(
+      (row) =>
+        `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join("")}</tr>`,
+    )
+    .join("");
+
+  return `<table><thead>${thead}</thead><tbody>${tbody}</tbody></table>`;
+}

package/src/utils/score-utils.ts

@@ -0,0 +1,103 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ *  SCORE UTILS — Version PRO
+ *  Outils avancés pour manipuler les scores et sévérités.
+ * ─────────────────────────────────────────────────────────────
+ */
+
+import { Severity } from "../core/scoring-types";
+
+/**
+ * Normalise un score brut (0 → 1) en score final (0 → 100).
+ */
+export function normalizeScore(raw: number): number {
+  if (raw < 0) return 0;
+  if (raw > 1) return 100;
+  return Math.round(raw * 100);
+}
+
+/**
+ * Convertit un score (0–100) en sévérité standardisée.
+ */
+export function scoreToSeverity(score: number): Severity {
+  if (score >= 90) return "critical";
+  if (score >= 70) return "high";
+  if (score >= 40) return "medium";
+  return "low";
+}
+
+/**
+ * Retourne une couleur lisible pour les reporters HTML/Markdown.
+ */
+export function severityColor(severity: Severity): string {
+  switch (severity) {
+    case "critical":
+      return "#d32f2f"; // rouge fort
+    case "high":
+      return "#f57c00"; // orange
+    case "medium":
+      return "#fbc02d"; // jaune
+    case "low":
+      return "#388e3c"; // vert
+    default:
+      return "#616161"; // gris
+  }
+}
+
+/**
+ * Combine plusieurs scores bruts (0 → 1) en un score unique.
+ * Utilise la méthode "max" (la plus utilisée en sécurité).
+ */
+export function combineScoresMax(scores: number[]): number {
+  if (scores.length === 0) return 0;
+  return Math.max(...scores);
+}
+
+/**
+ * Combine plusieurs scores bruts en moyenne pondérée.
+ */
+export function combineScoresWeighted(
+  scores: number[],
+  weights: number[],
+): number {
+  if (scores.length === 0 || weights.length === 0) return 0;
+  if (scores.length !== weights.length) {
+    throw new Error("scores and weights must have the same length");
+  }
+
+  const totalWeight = weights.reduce((a, b) => a + b, 0);
+  if (totalWeight === 0) return 0;
+
+  const weighted = scores.reduce(
+    (acc, score, i) => acc + score * weights[i],
+    0,
+  );
+
+  return weighted / totalWeight;
+}
+
+/**
+ * Retourne un label lisible pour un score (utile pour les reporters).
+ */
+export function scoreLabel(score: number): string {
+  if (score >= 90) return "Critical risk";
+  if (score >= 70) return "High risk";
+  if (score >= 40) return "Medium risk";
+  return "Low risk";
+}
+
+/**
+ * Retourne un objet complet pour les reporters JSON.
+ */
+export function scoreInfo(raw: number) {
+  const normalized = normalizeScore(raw);
+  const severity = scoreToSeverity(normalized);
+
+  return {
+    raw,
+    normalized,
+    severity,
+    label: scoreLabel(normalized),
+    color: severityColor(severity),
+  };
+}