@grc-claw/drift-detector 1.0.0

package/dist/DriftDetector.d.ts

@@ -0,0 +1,37 @@
+import type { BaselineSnapshot, ControlEvaluator, DriftAlert, DriftDetectionResult, DriftDetectorConfig, DriftEvent, DriftEventType, DriftSeverity } from './types.js';
+export declare class DriftDetector {
+    private config;
+    private evaluator;
+    private baselineHistory;
+    private currentBaseline;
+    private driftHistory;
+    private alertHistory;
+    private pollTimer;
+    constructor(config: DriftDetectorConfig, evaluator: ControlEvaluator);
+    /** Capture a baseline snapshot of all controls across configured frameworks */
+    captureBaseline(): Promise<BaselineSnapshot>;
+    /** Run a single drift detection cycle against the current baseline */
+    detectDrift(): Promise<DriftDetectionResult>;
+    /** Start continuous polling at the configured interval */
+    startPolling(): void;
+    /** Stop continuous polling */
+    stopPolling(): void;
+    /** Get the drift history */
+    getDriftHistory(): DriftEvent[];
+    /** Get the alert history */
+    getAlertHistory(): DriftAlert[];
+    /** Get the current baseline */
+    getCurrentBaseline(): BaselineSnapshot | null;
+    /** Get baseline history */
+    getBaselineHistory(): BaselineSnapshot[];
+    /** Compute a summary of drift events by severity */
+    getDriftSummary(): {
+        totalEvents: number;
+        bySeverity: Record<DriftSeverity, number>;
+        byType: Record<DriftEventType, number>;
+        byFramework: Record<string, number>;
+        overallScoreDelta: number;
+    };
+    private buildAlerts;
+    private computeHash;
+}

package/dist/DriftDetector.js

@@ -0,0 +1,284 @@
+import { createHash, randomUUID } from 'node:crypto';
+// ─── Status Severity Ranking ────────────────────────────────────────
+const STATUS_SEVERITY = {
+    compliant: 4,
+    partial: 3,
+    non_compliant: 1,
+    unknown: 0,
+};
+function severityFromDelta(delta) {
+    const absDelta = Math.abs(delta);
+    if (absDelta >= 3)
+        return 'critical';
+    if (absDelta >= 2)
+        return 'high';
+    if (absDelta >= 1)
+        return 'medium';
+    return 'low';
+}
+function priorityFromSeverity(severity) {
+    switch (severity) {
+        case 'critical': return 'p1';
+        case 'high': return 'p2';
+        case 'medium': return 'p3';
+        case 'low': return 'p4';
+    }
+}
+function classifyDriftEvent(prev, curr) {
+    const prevStatusRank = STATUS_SEVERITY[prev.status];
+    const currStatusRank = STATUS_SEVERITY[curr.status];
+    if (currStatusRank < prevStatusRank) {
+        const evType = prev.evidenceCount > curr.evidenceCount
+            ? 'evidence_revoked'
+            : curr.status === 'unknown'
+                ? 'control_downgraded'
+                : 'status_change';
+        return {
+            eventType: evType,
+            description: `${prev.controlId}: status ${prev.status} → ${curr.status} (evidence ${prev.evidenceCount} → ${curr.evidenceCount})`,
+        };
+    }
+    if (curr.evidenceCount < prev.evidenceCount) {
+        return {
+            eventType: 'evidence_expired',
+            description: `${prev.controlId}: evidence count decreased ${prev.evidenceCount} → ${curr.evidenceCount}`,
+        };
+    }
+    if (curr.complianceScore < prev.complianceScore) {
+        return {
+            eventType: 'score_degradation',
+            description: `${prev.controlId}: score decreased ${prev.complianceScore} → ${curr.complianceScore}`,
+        };
+    }
+    if (prev.status === 'unknown' && curr.status !== 'unknown') {
+        return {
+            eventType: 'new_gap',
+            description: `${prev.controlId}: status changed from unknown to ${curr.status}`,
+        };
+    }
+    return null;
+}
+// ─── Drift Detector ─────────────────────────────────────────────────
+export class DriftDetector {
+    config;
+    evaluator;
+    baselineHistory = [];
+    currentBaseline = null;
+    driftHistory = [];
+    alertHistory = [];
+    pollTimer = null;
+    constructor(config, evaluator) {
+        this.config = {
+            driftThresholdPercent: config.driftThresholdPercent ?? 5,
+            scoreDeltaAlertThreshold: config.scoreDeltaAlertThreshold ?? 10,
+            pollIntervalMs: config.pollIntervalMs ?? 60_000,
+            maxBaselineHistory: config.maxBaselineHistory ?? 50,
+            onDrift: config.onDrift ?? (() => { }),
+            onAlert: config.onAlert ?? (() => { }),
+            tenantId: config.tenantId,
+            frameworks: config.frameworks,
+        };
+        this.evaluator = evaluator;
+    }
+    /** Capture a baseline snapshot of all controls across configured frameworks */
+    async captureBaseline() {
+        const allControls = [];
+        let totalScore = 0;
+        let compliantCount = 0;
+        for (const framework of this.config.frameworks) {
+            const definitions = await this.evaluator.listControls(framework);
+            for (const def of definitions) {
+                const snapshot = await this.evaluator.evaluateControl(def.controlId, framework);
+                allControls.push(snapshot);
+                totalScore += snapshot.complianceScore;
+                if (snapshot.status === 'compliant')
+                    compliantCount++;
+            }
+        }
+        const overallScore = allControls.length > 0
+            ? Math.round((totalScore / allControls.length) * 100) / 100
+            : 0;
+        const frameworkScores = {};
+        for (const fw of this.config.frameworks) {
+            const fwControls = allControls.filter(c => c.framework === fw);
+            frameworkScores[fw] = fwControls.length > 0
+                ? Math.round((fwControls.reduce((s, c) => s + c.complianceScore, 0) / fwControls.length) * 100) / 100
+                : 0;
+        }
+        const baseline = {
+            id: randomUUID(),
+            capturedAt: new Date().toISOString(),
+            controls: allControls,
+            overallScore,
+            frameworkScores,
+            controlCount: allControls.length,
+            compliantCount,
+            hash: this.computeHash(allControls),
+        };
+        this.currentBaseline = baseline;
+        this.baselineHistory.push(baseline);
+        if (this.baselineHistory.length > this.config.maxBaselineHistory) {
+            this.baselineHistory.shift();
+        }
+        return baseline;
+    }
+    /** Run a single drift detection cycle against the current baseline */
+    async detectDrift() {
+        if (!this.currentBaseline) {
+            throw new Error('No baseline captured. Call captureBaseline() first.');
+        }
+        const baseline = this.currentBaseline;
+        const currentControls = [];
+        let totalScore = 0;
+        for (const framework of this.config.frameworks) {
+            const definitions = await this.evaluator.listControls(framework);
+            for (const def of definitions) {
+                const snapshot = await this.evaluator.evaluateControl(def.controlId, framework);
+                currentControls.push(snapshot);
+                totalScore += snapshot.complianceScore;
+            }
+        }
+        const currentScore = currentControls.length > 0
+            ? Math.round((totalScore / currentControls.length) * 100) / 100
+            : 0;
+        const baselineMap = new Map(baseline.controls.map(c => [`${c.controlId}:${c.framework}`, c]));
+        const driftEvents = [];
+        for (const curr of currentControls) {
+            const key = `${curr.controlId}:${curr.framework}`;
+            const prev = baselineMap.get(key);
+            if (!prev)
+                continue;
+            const classification = classifyDriftEvent(prev, curr);
+            if (!classification)
+                continue;
+            const statusDelta = STATUS_SEVERITY[prev.status] - STATUS_SEVERITY[curr.status];
+            const scoreDelta = prev.complianceScore - curr.complianceScore;
+            const severity = severityFromDelta(Math.max(statusDelta, scoreDelta));
+            driftEvents.push({
+                id: randomUUID(),
+                timestamp: new Date().toISOString(),
+                controlId: curr.controlId,
+                framework: curr.framework,
+                eventType: classification.eventType,
+                previousStatus: prev.status,
+                currentStatus: curr.status,
+                previousEvidenceCount: prev.evidenceCount,
+                currentEvidenceCount: curr.evidenceCount,
+                previousScore: prev.complianceScore,
+                currentScore: curr.complianceScore,
+                delta: scoreDelta,
+                severity,
+                description: classification.description,
+            });
+        }
+        const overallScoreDelta = baseline.overallScore - currentScore;
+        const driftDetected = driftEvents.length > 0 ||
+            Math.abs(overallScoreDelta) >= this.config.driftThresholdPercent;
+        if (driftDetected) {
+            this.driftHistory.push(...driftEvents);
+            this.config.onDrift(driftEvents);
+        }
+        const alerts = this.buildAlerts(driftEvents, overallScoreDelta);
+        for (const alert of alerts) {
+            this.alertHistory.push(alert);
+            this.config.onAlert(alert);
+        }
+        return {
+            snapshotId: randomUUID(),
+            baselineId: baseline.id,
+            detectedAt: new Date().toISOString(),
+            driftEvents,
+            driftDetected,
+            overallScoreDelta: Math.round(overallScoreDelta * 100) / 100,
+            currentScore,
+            baselineScore: baseline.overallScore,
+            alerts,
+        };
+    }
+    /** Start continuous polling at the configured interval */
+    startPolling() {
+        if (this.pollTimer)
+            return;
+        this.pollTimer = setInterval(() => {
+            this.detectDrift().catch(err => {
+                console.error('[DriftDetector] polling error:', err instanceof Error ? err.message : err);
+            });
+        }, this.config.pollIntervalMs);
+    }
+    /** Stop continuous polling */
+    stopPolling() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    /** Get the drift history */
+    getDriftHistory() {
+        return [...this.driftHistory];
+    }
+    /** Get the alert history */
+    getAlertHistory() {
+        return [...this.alertHistory];
+    }
+    /** Get the current baseline */
+    getCurrentBaseline() {
+        return this.currentBaseline;
+    }
+    /** Get baseline history */
+    getBaselineHistory() {
+        return [...this.baselineHistory];
+    }
+    /** Compute a summary of drift events by severity */
+    getDriftSummary() {
+        const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+        const byType = {
+            evidence_revoked: 0,
+            control_downgraded: 0,
+            evidence_expired: 0,
+            new_gap: 0,
+            score_degradation: 0,
+            status_change: 0,
+        };
+        const byFramework = {};
+        for (const event of this.driftHistory) {
+            bySeverity[event.severity]++;
+            byType[event.eventType]++;
+            byFramework[event.framework] = (byFramework[event.framework] ?? 0) + 1;
+        }
+        const overallScoreDelta = this.baselineHistory.length >= 2
+            ? this.baselineHistory[0].overallScore - this.baselineHistory[this.baselineHistory.length - 1].overallScore
+            : 0;
+        return {
+            totalEvents: this.driftHistory.length,
+            bySeverity,
+            byType,
+            byFramework,
+            overallScoreDelta: Math.round(overallScoreDelta * 100) / 100,
+        };
+    }
+    buildAlerts(events, overallDelta) {
+        if (events.length === 0 && Math.abs(overallDelta) < this.config.scoreDeltaAlertThreshold) {
+            return [];
+        }
+        const alerts = [];
+        const severityOrder = ['critical', 'high', 'medium', 'low'];
+        const maxSeverity = severityOrder.find(s => events.some(e => e.severity === s)) ?? 'low';
+        const affectedFrameworks = [...new Set(events.map(e => e.framework))];
+        alerts.push({
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            priority: priorityFromSeverity(maxSeverity),
+            driftEvents: events,
+            summary: `${events.length} drift event(s) detected across ${affectedFrameworks.length} framework(s). Score delta: ${overallDelta > 0 ? '-' : '+'}${Math.abs(overallDelta).toFixed(1)}%`,
+            affectedFrameworks,
+            affectedControlCount: new Set(events.map(e => e.controlId)).size,
+            maxSeverity,
+            overallScoreDelta: Math.round(overallDelta * 100) / 100,
+        });
+        return alerts;
+    }
+    computeHash(controls) {
+        const payload = JSON.stringify(controls.map(c => `${c.controlId}:${c.status}:${c.evidenceCount}:${c.complianceScore}`).sort());
+        return createHash('sha256').update(payload).digest('hex');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DriftDetector } from './DriftDetector.js';
+export type { AlertPriority, BaselineSnapshot, ControlEvaluator, ControlSnapshot, ControlStatus, DriftAlert, DriftDetectionResult, DriftDetectorConfig, DriftEvent, DriftEventType, DriftSeverity, } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { DriftDetector } from './DriftDetector.js';

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,155 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { DriftDetector } from './DriftDetector.js';
+// ─── Mock Evaluator ─────────────────────────────────────────────────
+function makeMockEvaluator(controls) {
+    return {
+        async evaluateControl(controlId, framework) {
+            const key = `${controlId}:${framework}`;
+            const snap = controls.get(key);
+            if (!snap) {
+                return {
+                    controlId,
+                    framework,
+                    status: 'unknown',
+                    evidenceHashes: [],
+                    evidenceCount: 0,
+                    complianceScore: 0,
+                    lastCheckedAt: new Date().toISOString(),
+                };
+            }
+            return { ...snap, lastCheckedAt: new Date().toISOString() };
+        },
+        async listControls(framework) {
+            const defs = [];
+            for (const [key, snap] of controls) {
+                if (snap.framework === framework) {
+                    defs.push({ controlId: snap.controlId, title: snap.controlId });
+                }
+            }
+            return defs;
+        },
+    };
+}
+function makeControl(controlId, framework, status, evidenceCount, score) {
+    return {
+        controlId,
+        framework,
+        status,
+        evidenceHashes: Array.from({ length: evidenceCount }, (_, i) => `hash-${i}`),
+        evidenceCount,
+        complianceScore: score,
+        lastCheckedAt: new Date().toISOString(),
+    };
+}
+// ─── Tests ──────────────────────────────────────────────────────────
+describe('DriftDetector', () => {
+    let controls;
+    let evaluator;
+    let config;
+    beforeEach(() => {
+        controls = new Map();
+        controls.set('A.5.1:iso27001', makeControl('A.5.1', 'iso27001', 'compliant', 3, 100));
+        controls.set('A.5.2:iso27001', makeControl('A.5.2', 'iso27001', 'compliant', 2, 100));
+        controls.set('A.8.1:iso27001', makeControl('A.8.1', 'iso27001', 'partial', 1, 50));
+        evaluator = makeMockEvaluator(controls);
+        config = {
+            tenantId: 1,
+            frameworks: ['iso27001'],
+            driftThresholdPercent: 5,
+            scoreDeltaAlertThreshold: 10,
+        };
+    });
+    it('should capture a baseline snapshot', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        const baseline = await detector.captureBaseline();
+        assert.equal(baseline.controlCount, 3);
+        assert.equal(baseline.compliantCount, 2);
+        assert.ok(baseline.hash.length > 0);
+        assert.ok(baseline.id.length > 0);
+    });
+    it('should detect no drift when controls are unchanged', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        const result = await detector.detectDrift();
+        assert.equal(result.driftDetected, false);
+        assert.equal(result.driftEvents.length, 0);
+        assert.equal(result.overallScoreDelta, 0);
+    });
+    it('should detect status downgrade drift', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        controls.set('A.5.1:iso27001', makeControl('A.5.1', 'iso27001', 'non_compliant', 0, 0));
+        const result = await detector.detectDrift();
+        assert.equal(result.driftDetected, true);
+        assert.ok(result.driftEvents.length > 0);
+        const event = result.driftEvents.find(e => e.controlId === 'A.5.1');
+        assert.ok(event);
+        assert.equal(event.previousStatus, 'compliant');
+        assert.equal(event.currentStatus, 'non_compliant');
+        assert.equal(event.eventType, 'evidence_revoked');
+    });
+    it('should detect evidence revocation', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        controls.set('A.5.1:iso27001', makeControl('A.5.1', 'iso27001', 'compliant', 0, 100));
+        const result = await detector.detectDrift();
+        const event = result.driftEvents.find(e => e.controlId === 'A.5.1');
+        assert.ok(event);
+        assert.equal(event.eventType, 'evidence_expired');
+        assert.equal(event.previousEvidenceCount, 3);
+        assert.equal(event.currentEvidenceCount, 0);
+    });
+    it('should detect score degradation', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        controls.set('A.8.1:iso27001', makeControl('A.8.1', 'iso27001', 'partial', 1, 25));
+        const result = await detector.detectDrift();
+        const event = result.driftEvents.find(e => e.controlId === 'A.8.1');
+        assert.ok(event);
+        assert.equal(event.eventType, 'score_degradation');
+        assert.equal(event.delta, 25);
+    });
+    it('should generate alerts when drift exceeds threshold', async () => {
+        let alertReceived = false;
+        config.onAlert = () => { alertReceived = true; };
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        controls.set('A.5.1:iso27001', makeControl('A.5.1', 'iso27001', 'non_compliant', 0, 0));
+        await detector.detectDrift();
+        assert.equal(alertReceived, true);
+        const alerts = detector.getAlertHistory();
+        assert.ok(alerts.length > 0);
+        assert.equal(alerts[0].priority, 'p1');
+    });
+    it('should track drift history across multiple cycles', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        controls.set('A.5.1:iso27001', makeControl('A.5.1', 'iso27001', 'non_compliant', 0, 0));
+        await detector.detectDrift();
+        controls.set('A.5.2:iso27001', makeControl('A.5.2', 'iso27001', 'non_compliant', 0, 0));
+        await detector.detectDrift();
+        const history = detector.getDriftHistory();
+        assert.ok(history.length >= 2);
+    });
+    it('should compute drift summary correctly', async () => {
+        const detector = new DriftDetector(config, evaluator);
+        await detector.captureBaseline();
+        controls.set('A.5.1:iso27001', makeControl('A.5.1', 'iso27001', 'non_compliant', 0, 0));
+        controls.set('A.5.2:iso27001', makeControl('A.5.2', 'iso27001', 'partial', 1, 50));
+        await detector.detectDrift();
+        const summary = detector.getDriftSummary();
+        assert.ok(summary.totalEvents >= 2);
+        assert.ok(summary.bySeverity.critical > 0 || summary.bySeverity.high > 0);
+        assert.ok(summary.byFramework.iso27001 >= 2);
+    });
+    it('should maintain baseline history within limits', async () => {
+        const limitedConfig = { ...config, maxBaselineHistory: 3 };
+        const detector = new DriftDetector(limitedConfig, evaluator);
+        for (let i = 0; i < 5; i++) {
+            await detector.captureBaseline();
+        }
+        const history = detector.getBaselineHistory();
+        assert.equal(history.length, 3);
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+export type ControlStatus = 'compliant' | 'non_compliant' | 'partial' | 'unknown';
+export type DriftSeverity = 'critical' | 'high' | 'medium' | 'low';
+export type DriftEventType = 'evidence_revoked' | 'control_downgraded' | 'evidence_expired' | 'new_gap' | 'score_degradation' | 'status_change';
+export type AlertPriority = 'p1' | 'p2' | 'p3' | 'p4';
+export interface ControlSnapshot {
+    controlId: string;
+    framework: string;
+    status: ControlStatus;
+    evidenceHashes: string[];
+    evidenceCount: number;
+    complianceScore: number;
+    lastCheckedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DriftEvent {
+    id: string;
+    timestamp: string;
+    controlId: string;
+    framework: string;
+    eventType: DriftEventType;
+    previousStatus: ControlStatus;
+    currentStatus: ControlStatus;
+    previousEvidenceCount: number;
+    currentEvidenceCount: number;
+    previousScore: number;
+    currentScore: number;
+    delta: number;
+    severity: DriftSeverity;
+    description: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DriftAlert {
+    id: string;
+    timestamp: string;
+    priority: AlertPriority;
+    driftEvents: DriftEvent[];
+    summary: string;
+    affectedFrameworks: string[];
+    affectedControlCount: number;
+    maxSeverity: DriftSeverity;
+    overallScoreDelta: number;
+}
+export interface BaselineSnapshot {
+    id: string;
+    capturedAt: string;
+    controls: ControlSnapshot[];
+    overallScore: number;
+    frameworkScores: Record<string, number>;
+    controlCount: number;
+    compliantCount: number;
+    hash: string;
+}
+export interface DriftDetectionResult {
+    snapshotId: string;
+    baselineId: string;
+    detectedAt: string;
+    driftEvents: DriftEvent[];
+    driftDetected: boolean;
+    overallScoreDelta: number;
+    currentScore: number;
+    baselineScore: number;
+    alerts: DriftAlert[];
+}
+export interface DriftDetectorConfig {
+    tenantId: number;
+    frameworks: string[];
+    driftThresholdPercent?: number;
+    scoreDeltaAlertThreshold?: number;
+    pollIntervalMs?: number;
+    maxBaselineHistory?: number;
+    onDrift?: (events: DriftEvent[]) => void;
+    onAlert?: (alert: DriftAlert) => void;
+}
+export interface ControlEvaluator {
+    evaluateControl(controlId: string, framework: string): Promise<ControlSnapshot>;
+    listControls(framework: string): Promise<Array<{
+        controlId: string;
+        title: string;
+    }>>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@grc-claw/drift-detector",
+  "version": "1.0.0",
+  "description": "Real-time compliance drift detection — monitors control posture changes, detects evidence gaps, and broadcasts drift alerts",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/**/*.test.js 2>/dev/null || true"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}