faultmesh 1.0.0 → 1.1.0

package/dist/redteam/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * FaultMesh — Autonomous Red Chaos Team Engine
+ * Type definitions for multi-wave adversarial campaigns and agent personas.
+ */
+export type RedTeamSpecialty = 'security' | 'silent-failure' | 'performance' | 'adversarial-gan' | 'transport';
+export interface RedTeamPersona {
+    id: string;
+    name: string;
+    callSign: string;
+    description: string;
+    model: string;
+    tools: string[];
+    specialty: RedTeamSpecialty;
+    huntTargets: string[];
+    systemPromptExcerpt: string;
+    sourceFile: string;
+}
+export type CampaignPhase = 'idle' | 'recon' | 'weaponize' | 'assault' | 'debrief' | 'complete' | 'aborted';
+export type CampaignIntensity = 'stealth' | 'sustained' | 'avalanche';
+export interface AssaultWaveToxic {
+    type: string;
+    config: Record<string, any>;
+    direction?: 'upstream' | 'downstream';
+    pathPattern?: string;
+}
+export interface AssaultWave {
+    id: string;
+    waveNumber: number;
+    name: string;
+    personaId: string;
+    personaName: string;
+    callSign: string;
+    category: 'security' | 'resilience' | 'storm';
+    targetEndpoint: string;
+    toxicsToInject: AssaultWaveToxic[];
+    probesCount: number;
+    concurrency: number;
+    description: string;
+}
+export interface BreachProof {
+    method: string;
+    url: string;
+    requestHeaders?: Record<string, string>;
+    requestBody?: any;
+    responseStatus: number;
+    responseDurationMs: number;
+    snippet: string;
+    activeToxics?: string[];
+}
+export interface BreachFinding {
+    id: string;
+    personaId: string;
+    personaName: string;
+    callSign: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    category: string;
+    title: string;
+    impact: string;
+    endpoint: string;
+    proofOfBreach: BreachProof;
+    remediation: string;
+    autoHealCheckKey: string;
+}
+export interface CampaignLog {
+    timestamp: number;
+    waveNumber: number;
+    persona: string;
+    message: string;
+    type: 'info' | 'warn' | 'breach' | 'pass';
+}
+export interface CampaignReport {
+    campaignId: string;
+    targetUrl: string;
+    intensity: CampaignIntensity;
+    phase: CampaignPhase;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    totalWaves: number;
+    completedWaves: number;
+    totalProbes: number;
+    breachesFound: BreachFinding[];
+    survivabilityScore: number;
+    survivabilityGrade: 'A' | 'B' | 'C' | 'D' | 'F';
+    activePersonas: string[];
+    logs: CampaignLog[];
+}
+export interface CampaignStatus {
+    active: boolean;
+    campaignId: string | null;
+    phase: CampaignPhase;
+    progressPercent: number;
+    currentWave: number;
+    totalWaves: number;
+    currentWaveName: string;
+    activePersona: string;
+    probesSent: number;
+    breachesCount: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+        total: number;
+    };
+    latestLog?: CampaignLog;
+}
+export interface CampaignOptions {
+    targetUrl?: string;
+    intensity?: CampaignIntensity;
+    personaIds?: string[];
+    aiConfig?: {
+        provider: string;
+        endpoint?: string;
+        apiKey?: string;
+        model?: string;
+    };
+}

package/dist/redteam/types.js

@@ -0,0 +1,5 @@
+/**
+ * FaultMesh — Autonomous Red Chaos Team Engine
+ * Type definitions for multi-wave adversarial campaigns and agent personas.
+ */
+export {};

package/dist/scorer/ResilienceScorer.d.ts

@@ -10,4 +10,9 @@ export declare class ResilienceScorer {
     private testConnectionCut;
     private testPayloadCorruption;
     private testServiceOutage;
+    private testPacketJitter;
+    private testCircuitBreakerRecovery;
+    private testSocketStarvation;
+    private testZombieConnectionLeak;
+    private testPartialTransferTruncation;
 }

package/dist/scorer/ResilienceScorer.js

@@ -10,6 +10,43 @@ export class ResilienceScorer {
         const recommendations = [];
         // Ensure clean pipeline initially
         this.pipeline.clearRules();
+        // Pre-flight check: verify upstream target is reachable through the proxy
+        let upstreamReachable = true;
+        let preflightError = '';
+        try {
+            const probe = await fetch(`${this.proxyUrl}/api/health`, { signal: AbortSignal.timeout(2500) });
+            if (probe.status === 502) {
+                upstreamReachable = false;
+                preflightError = 'Upstream target API returned HTTP 502 Bad Gateway. The configured target server is unreachable or offline.';
+            }
+        }
+        catch (err) {
+            upstreamReachable = false;
+            preflightError = `Target connection failed (${err.message}). Ensure target server is online.`;
+        }
+        if (!upstreamReachable) {
+            const failedPlaceholders = [
+                { name: 'Response Delay Handling (300ms)', description: 'Checks delay handling.', toxicUsed: 'latency', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Slow Connection Throughput (16 kbps)', description: 'Checks low bandwidth.', toxicUsed: 'bandwidth', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Abrupt Disconnection Mid-Transfer', description: 'Checks disconnection.', toxicUsed: 'cut', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Malformed JSON Handling', description: 'Checks data corruption.', toxicUsed: 'corrupt', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'HTTP 503 Service Outage Handling', description: 'Checks 503 outage.', toxicUsed: 'status', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Packet Jitter & Latency Variance', description: 'Checks latency jitter.', toxicUsed: 'jitter', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Half-Open Circuit Breaker Recovery', description: 'Checks recovery after downtime.', toxicUsed: 'circuit-breaker', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Downstream Socket Starvation & Slow Read', description: 'Checks connection pool health.', toxicUsed: 'starvation', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Zombie Connection Leak Probe', description: 'Checks client abort socket handling.', toxicUsed: 'zombie-leak', passed: false, latencyMs: 0, details: preflightError },
+                { name: 'Payload Truncation & Partial Transfer', description: 'Checks partial response handling.', toxicUsed: 'truncation', passed: false, latencyMs: 0, details: preflightError },
+            ];
+            return {
+                score: 0,
+                grade: 'F',
+                timestamp: Date.now(),
+                totalAttacks: 10,
+                passedAttacks: 0,
+                results: failedPlaceholders,
+                recommendations: ['Target server is unreachable. Check the Target API field in the header and verify your backend server is running.'],
+            };
+        }
         // 1. Test 1: Latency Spike
         const r1 = await this.testLatencySpike(profile);
         results.push(r1);
@@ -40,10 +77,40 @@ export class ResilienceScorer {
         if (!r5.passed) {
             recommendations.push('Handle 5xx server errors gracefully and display a friendly retry prompt to the user.');
         }
+        // 6. Test 6: Packet Jitter & Latency Variance
+        const r6 = await this.testPacketJitter(profile);
+        results.push(r6);
+        if (!r6.passed) {
+            recommendations.push('Configure dynamic client timeouts with jitter buffers to absorb fluctuating network delay spikes.');
+        }
+        // 7. Test 7: Half-Open Circuit Breaker Recovery
+        const r7 = await this.testCircuitBreakerRecovery(profile);
+        results.push(r7);
+        if (!r7.passed) {
+            recommendations.push('Implement a half-open state transition in your circuit breaker to allow canary probes through after transient outages.');
+        }
+        // 8. Test 8: Downstream Socket Starvation & Slow Read
+        const r8 = await this.testSocketStarvation(profile);
+        results.push(r8);
+        if (!r8.passed) {
+            recommendations.push('Tune connection pool sizes and enforce request write timeouts to prevent slow clients from exhausting worker threads.');
+        }
+        // 9. Test 9: Zombie Connection Leak Probe
+        const r9 = await this.testZombieConnectionLeak(profile);
+        results.push(r9);
+        if (!r9.passed) {
+            recommendations.push('Listen for request "close" events server-side and abort downstream database queries when clients disconnect prematurely.');
+        }
+        // 10. Test 10: Payload Truncation & Partial Transfer
+        const r10 = await this.testPartialTransferTruncation(profile);
+        results.push(r10);
+        if (!r10.passed) {
+            recommendations.push('Verify Content-Length or chunked stream terminator before parsing payloads to prevent partial data corruption.');
+        }
         // Cleanup pipeline after tests
         this.pipeline.clearRules();
-        // Calculate weighted score
-        const weights = [20, 15, 25, 20, 20];
+        // Calculate weighted score (10 checks, 10 points each = 100 points)
+        const weights = [10, 10, 10, 10, 10, 10, 10, 10, 10, 10];
         let score = 0;
         let passedCount = 0;
         results.forEach((r, idx) => {
@@ -62,7 +129,7 @@ export class ResilienceScorer {
         else if (score >= 45)
             grade = 'D';
         if (recommendations.length === 0) {
-            recommendations.push('Your application handled all 5 simulated network failure scenarios smoothly.');
+            recommendations.push('Your application handled all 10 simulated network failure and resilience scenarios smoothly.');
         }
         return {
             score,
@@ -101,7 +168,7 @@ export class ResilienceScorer {
             const res = await fetch(`${this.proxyUrl}/api/health`, { signal: controller.signal });
             clearTimeout(timeout);
             const duration = Date.now() - start;
-            const passed = res.status === 200 && duration >= 180 && duration <= 600;
+            const passed = res.status === 200 && duration >= 180 && duration <= 650;
             return {
                 name: 'Response Delay Handling (300ms)',
                 description: 'Checks whether the client handles delayed network responses without freezing or hanging.',
@@ -282,7 +349,7 @@ export class ResilienceScorer {
     async testServiceOutage(profile) {
         if (profile === 'fragile') {
             return {
-                name: 'HTTP 503 Service Unavailable Handling',
+                name: 'HTTP 503 Service Outage Handling',
                 description: 'Tests if the application properly receives and reacts to temporary server downtime.',
                 toxicUsed: 'status',
                 passed: false,
@@ -304,7 +371,7 @@ export class ResilienceScorer {
             const res = await fetch(`${this.proxyUrl}/api/data`);
             const passed = res.status === 503;
             return {
-                name: 'HTTP 503 Service Unavailable Handling',
+                name: 'HTTP 503 Service Outage Handling',
                 description: 'Tests if the application properly receives and reacts to temporary server downtime.',
                 toxicUsed: 'status',
                 passed,
@@ -314,7 +381,7 @@ export class ResilienceScorer {
         }
         catch (err) {
             return {
-                name: 'HTTP 503 Service Unavailable Handling',
+                name: 'HTTP 503 Service Outage Handling',
                 description: 'Tests if the application properly receives and reacts to temporary server downtime.',
                 toxicUsed: 'status',
                 passed: false,
@@ -327,4 +394,253 @@ export class ResilienceScorer {
             this.pipeline.removeRule('test_rule_503');
         }
     }
+    async testPacketJitter(profile) {
+        if (profile === 'fragile') {
+            return {
+                name: 'Packet Jitter & Latency Variance',
+                description: 'Injects high latency variance (100ms-350ms) to test jitter buffering.',
+                toxicUsed: 'jitter',
+                passed: false,
+                latencyMs: 380,
+                errorCaught: 'PacketOrderingException: stream arrival out of sequence',
+                details: 'Client experienced connection timeout or buffer stall under high network jitter',
+            };
+        }
+        this.pipeline.addRule({
+            id: 'test_rule_jitter',
+            name: 'Simulated High Jitter',
+            type: 'latency',
+            direction: 'downstream',
+            enabled: true,
+            config: { latencyMs: 100, jitterMs: 70 },
+        });
+        const start = Date.now();
+        try {
+            const res = await fetch(`${this.proxyUrl}/api/health`, { signal: AbortSignal.timeout(1200) });
+            const duration = Date.now() - start;
+            const passed = res.status === 200 && duration >= 30;
+            return {
+                name: 'Packet Jitter & Latency Variance',
+                description: 'Injects high latency variance (100ms-350ms) to test jitter buffering.',
+                toxicUsed: 'jitter',
+                passed,
+                latencyMs: duration,
+                details: passed ? `Handled packet jitter smoothly in ${duration}ms` : `Unstable response latency (${duration}ms)`,
+            };
+        }
+        catch (err) {
+            return {
+                name: 'Packet Jitter & Latency Variance',
+                description: 'Injects high latency variance (100ms-350ms) to test jitter buffering.',
+                toxicUsed: 'jitter',
+                passed: false,
+                latencyMs: Date.now() - start,
+                errorCaught: err.message,
+                details: `Jitter probe failed: ${err.message}`,
+            };
+        }
+        finally {
+            this.pipeline.removeRule('test_rule_jitter');
+        }
+    }
+    async testCircuitBreakerRecovery(profile) {
+        if (profile === 'fragile') {
+            return {
+                name: 'Half-Open Circuit Breaker Recovery',
+                description: 'Tests if service recovers immediately after a transient 503 outage.',
+                toxicUsed: 'circuit-breaker',
+                passed: false,
+                latencyMs: 12,
+                errorCaught: 'CircuitBreakerOpenError: service remained latched open after outage cleared',
+                details: 'Subsequent requests failed because circuit breaker failed to transition to half-open state',
+            };
+        }
+        // Step 1: inject transient 503 outage
+        this.pipeline.addRule({
+            id: 'test_rule_transient_503',
+            name: 'Transient Outage',
+            type: 'status',
+            direction: 'downstream',
+            enabled: true,
+            config: { statusCode: 503, statusMessage: 'Transient Down' },
+        });
+        const start = Date.now();
+        try {
+            await fetch(`${this.proxyUrl}/api/health`);
+            // Step 2: clear outage
+            this.pipeline.removeRule('test_rule_transient_503');
+            // Step 3: verify recovery request succeeds
+            const recoveryRes = await fetch(`${this.proxyUrl}/api/health`, { signal: AbortSignal.timeout(1500) });
+            const duration = Date.now() - start;
+            const passed = recoveryRes.status === 200;
+            return {
+                name: 'Half-Open Circuit Breaker Recovery',
+                description: 'Tests if service recovers immediately after a transient 503 outage.',
+                toxicUsed: 'circuit-breaker',
+                passed,
+                latencyMs: duration,
+                details: passed ? 'Service cleanly resumed serving traffic immediately after outage lifted' : 'Service failed to recover after transient 503',
+            };
+        }
+        catch (err) {
+            return {
+                name: 'Half-Open Circuit Breaker Recovery',
+                description: 'Tests if service recovers immediately after a transient 503 outage.',
+                toxicUsed: 'circuit-breaker',
+                passed: false,
+                latencyMs: Date.now() - start,
+                errorCaught: err.message,
+                details: `Recovery probe failed: ${err.message}`,
+            };
+        }
+        finally {
+            this.pipeline.removeRule('test_rule_transient_503');
+        }
+    }
+    async testSocketStarvation(profile) {
+        if (profile === 'fragile') {
+            return {
+                name: 'Downstream Socket Starvation & Slow Read',
+                description: 'Tests if connection pool continues serving healthy clients when one connection is throttled.',
+                toxicUsed: 'starvation',
+                passed: false,
+                latencyMs: 950,
+                errorCaught: 'ConnectionPoolExhausted: worker pool starved by slow connection',
+                details: 'Server blocked all incoming requests while servicing a single throttled downstream client',
+            };
+        }
+        this.pipeline.addRule({
+            id: 'test_rule_slow_client',
+            name: 'Throttled Downstream Client',
+            type: 'bandwidth',
+            direction: 'downstream',
+            enabled: true,
+            config: { rateKbps: 8 },
+            pathPattern: '/api/data',
+        });
+        const start = Date.now();
+        try {
+            // Start slow download in background
+            const slowPromise = fetch(`${this.proxyUrl}/api/data`).catch(() => { });
+            // Concurrent probe to /api/health should not be blocked or starved
+            const healthRes = await fetch(`${this.proxyUrl}/api/health`, { signal: AbortSignal.timeout(1200) });
+            const duration = Date.now() - start;
+            const passed = healthRes.status === 200 && duration < 800;
+            await slowPromise;
+            return {
+                name: 'Downstream Socket Starvation & Slow Read',
+                description: 'Tests if connection pool continues serving healthy clients when one connection is throttled.',
+                toxicUsed: 'starvation',
+                passed,
+                latencyMs: duration,
+                details: passed ? `Concurrent probe completed in ${duration}ms without pool starvation` : `Health probe stalled (${duration}ms)`,
+            };
+        }
+        catch (err) {
+            return {
+                name: 'Downstream Socket Starvation & Slow Read',
+                description: 'Tests if connection pool continues serving healthy clients when one connection is throttled.',
+                toxicUsed: 'starvation',
+                passed: false,
+                latencyMs: Date.now() - start,
+                errorCaught: err.message,
+                details: `Starvation test failed: ${err.message}`,
+            };
+        }
+        finally {
+            this.pipeline.removeRule('test_rule_slow_client');
+        }
+    }
+    async testZombieConnectionLeak(profile) {
+        if (profile === 'fragile') {
+            return {
+                name: 'Zombie Connection Leak Probe',
+                description: 'Tests if backend frees sockets and server resources when client aborts prematurely.',
+                toxicUsed: 'zombie-leak',
+                passed: false,
+                latencyMs: 15,
+                errorCaught: 'SocketDescriptorLeak: unreleased TCP handle retained in LISTEN queue',
+                details: 'Aborted client connections remained open as zombie handles and leaked system file descriptors',
+            };
+        }
+        const start = Date.now();
+        try {
+            // Abort connection quickly
+            const controller = new AbortController();
+            const abortedFetch = fetch(`${this.proxyUrl}/api/data`, { signal: controller.signal }).catch(() => { });
+            setTimeout(() => controller.abort(), 10);
+            await abortedFetch;
+            // Ensure target is immediately responsive for new connection
+            const checkRes = await fetch(`${this.proxyUrl}/api/health`, { signal: AbortSignal.timeout(1000) });
+            const duration = Date.now() - start;
+            const passed = checkRes.status === 200;
+            return {
+                name: 'Zombie Connection Leak Probe',
+                description: 'Tests if backend frees sockets and server resources when client aborts prematurely.',
+                toxicUsed: 'zombie-leak',
+                passed,
+                latencyMs: duration,
+                details: passed ? 'Aborted request was cleanly recycled without leaking socket resources' : 'Target unresponsive after abort',
+            };
+        }
+        catch (err) {
+            return {
+                name: 'Zombie Connection Leak Probe',
+                description: 'Tests if backend frees sockets and server resources when client aborts prematurely.',
+                toxicUsed: 'zombie-leak',
+                passed: false,
+                latencyMs: Date.now() - start,
+                errorCaught: err.message,
+                details: `Zombie leak probe failed: ${err.message}`,
+            };
+        }
+    }
+    async testPartialTransferTruncation(profile) {
+        if (profile === 'fragile') {
+            return {
+                name: 'Payload Truncation & Partial Transfer',
+                description: 'Evaluates client detection when server terminates transmission mid-body.',
+                toxicUsed: 'truncation',
+                passed: false,
+                latencyMs: 22,
+                errorCaught: 'CorruptStateError: client processed incomplete byte stream without boundary check',
+                details: 'Client accepted truncated data stream as complete response without validating payload integrity',
+            };
+        }
+        this.pipeline.addRule({
+            id: 'test_rule_partial_cut',
+            name: 'Partial Body Cut',
+            type: 'cut',
+            direction: 'downstream',
+            enabled: true,
+            config: { cutAfterBytes: 30 },
+        });
+        const start = Date.now();
+        try {
+            const res = await fetch(`${this.proxyUrl}/api/data`);
+            await res.text();
+            return {
+                name: 'Payload Truncation & Partial Transfer',
+                description: 'Evaluates client detection when server terminates transmission mid-body.',
+                toxicUsed: 'truncation',
+                passed: false,
+                latencyMs: Date.now() - start,
+                details: 'Stream did not truncate as expected',
+            };
+        }
+        catch (err) {
+            return {
+                name: 'Payload Truncation & Partial Transfer',
+                description: 'Evaluates client detection when server terminates transmission mid-body.',
+                toxicUsed: 'truncation',
+                passed: true,
+                latencyMs: Date.now() - start,
+                errorCaught: err.message,
+                details: `Partial stream termination detected safely: ${err.message}`,
+            };
+        }
+        finally {
+            this.pipeline.removeRule('test_rule_partial_cut');
+        }
+    }
 }

package/dist/scorer/SecurityAuditor.d.ts

@@ -2,6 +2,7 @@ import { SecurityScorecard } from '../types.js';
 export declare class SecurityAuditor {
     private targetUrl;
     constructor(targetUrl: string);
+    setTargetUrl(url: string): void;
     runAudit(profile?: 'secure' | 'vulnerable'): Promise<SecurityScorecard>;
     private auditDefensiveHeaders;
     private auditCorsConfiguration;
@@ -10,4 +11,11 @@ export declare class SecurityAuditor {
     private auditErrorDisclosure;
     private auditPathTraversal;
     private auditInertCanaryInjection;
+    private auditHostHeaderPoisoning;
+    private auditClientIpSpoofing;
+    private auditParameterPollution;
+    private auditCacheControlHeaders;
+    private auditBrokenAuthHeaders;
+    private auditTimingAttacks;
+    private auditMetadataLeakage;
 }