@securecode-ai/mcp 0.5.5 → 0.5.6

package/dist/attack/investigationState.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Structured investigation state — tracks what the agent has already
+ * investigated so it doesn't waste steps re-reading the same code and
+ * can see which required checks remain incomplete.
+ *
+ * The Synara scan exposed two problems this module addresses:
+ *
+ * 1. The agent read `http.ts` 12 times with different line ranges, many
+ *    overlapping. The exact-range dedup blocked identical ranges but
+ *    not overlapping ones. This module tracks merged coverage so a read
+ *    that substantially overlaps an already-read range is caught.
+ *
+ * 2. The agent called `finish` without completing the required
+ *    investigation protocol (configuration inspection, threat-model
+ *    establishment, cross-file ownership tracing). The checklist makes
+ *    the missing steps visible to the agent AND to the controller.
+ */
+export interface LineRange {
+    start: number;
+    end: number;
+}
+export type InvestigationTaskStatus = 'pending' | 'investigated' | 'verified' | 'refuted' | 'unproven' | 'blocked';
+export interface InvestigationTask {
+    id: string;
+    targetFiles: string[];
+    claim: string;
+    requiredTools: string[];
+    requiredEvidence: string[];
+    status: InvestigationTaskStatus;
+    entryFiles?: string[];
+    relatedFiles?: string[];
+    sourceSymbols?: string[];
+    sinkSymbols?: string[];
+    requiredProofDimensions?: string[];
+}
+export interface FileCoverage {
+    filePath: string;
+    ranges: LineRange[];
+    totalLines?: number;
+    readCount: number;
+    blockedReadCount: number;
+}
+export type FlowVerificationStatus = 'confirmed' | 'refuted' | 'inconclusive' | 'blocked';
+export interface FlowVerification {
+    filePath: string;
+    tool: string;
+    status: FlowVerificationStatus;
+    flowCount: number;
+    reason: string;
+    timestamp: number;
+    riskId?: string;
+    candidateId?: string;
+    source?: {
+        filePath: string;
+        symbol?: string;
+        line?: number;
+    };
+    sink?: {
+        filePath: string;
+        symbol?: string;
+        line?: number;
+    };
+    hops?: Array<{
+        filePath: string;
+        symbol?: string;
+        line?: number;
+        description?: string;
+    }>;
+    truncated?: boolean;
+    error?: string;
+}
+export type ReadValueClassification = 'new-coverage' | 'partial-new-coverage' | 'duplicate' | 'high-overlap' | 'invalid' | 'function-map';
+export interface ReadValueResult {
+    classification: ReadValueClassification;
+    overlapFraction: number;
+    newLines: number;
+    coverageAfter: LineRange[];
+    nextUnreadRange: LineRange | null;
+}
+export type InvestigationStep = 'initial-read' | 'route-discovery' | 'policy-check' | 'auth-symbol-search' | 'cross-file-flow' | 'config-inspection' | 'ownership-analysis' | 'tests-found' | 'architecture-risks-addressed' | 'all-handlers-reviewed' | 'candidates-verified';
+export interface InvestigationChecklist {
+    completed: Set<InvestigationStep>;
+    required: Set<InvestigationStep>;
+    requiredForFindingType: Map<string, Set<InvestigationStep>>;
+}
+export declare class InvestigationState {
+    private fileCoverages;
+    private checklist;
+    private toolsUsed;
+    private filesRead;
+    private symbolsSearched;
+    private rootCauses;
+    private duplicateReadKeys;
+    private tasks;
+    private flowVerifications;
+    constructor();
+    static normalizePath(p: string): string;
+    static parseRange(startLine?: number, endLine?: number, totalLines?: number): LineRange;
+    static rangesOverlap(a: LineRange, b: LineRange): boolean;
+    static mergeRanges(ranges: LineRange[]): LineRange[];
+    static overlapFraction(a: LineRange, b: LineRange): number;
+    /**
+     * Check if a read would be blocked (duplicate or overlapping) WITHOUT
+     * recording it. This lets the loop decide before committing coverage.
+     */
+    checkRead(filePath: string, startLine?: number, endLine?: number, totalLines?: number): {
+        isExactDuplicate: boolean;
+        overlapping: boolean;
+        overlapFraction: number;
+        coverageAfter: LineRange[];
+    };
+    classifyRead(filePath: string, startLine?: number, endLine?: number, totalLines?: number): ReadValueResult;
+    /**
+     * Record a blocked read attempt — increments the blocked counter
+     * without merging ranges or counting it as a successful read.
+     */
+    recordBlockedRead(filePath: string): void;
+    recordRead(filePath: string, startLine?: number, endLine?: number, totalLines?: number): {
+        overlapping: boolean;
+        overlapFraction: number;
+        coverageAfter: LineRange[];
+    };
+    /**
+     * Record a read using the ACTUAL delivered range (not the requested range).
+     *
+     * Use this when the executor returns structured metadata telling you
+     * exactly which lines were delivered. A large-file read that returns a
+     * function map (truncated=true, actualStart=0, actualEnd=0) does NOT
+     * record any content coverage — the agent must still read specific
+     * line ranges.
+     */
+    recordActualRead(filePath: string, actualStart: number, actualEnd: number, totalLines: number, truncated: boolean): {
+        overlapping: boolean;
+        overlapFraction: number;
+        coverageAfter: LineRange[];
+    };
+    getCoverage(filePath: string): FileCoverage | undefined;
+    isCovered(filePath: string, startLine?: number, endLine?: number): boolean;
+    /**
+     * Return the gaps in coverage for a file — the line ranges that have NOT
+     * been read yet. Returns [] if the file is fully covered or not tracked.
+     */
+    getUncoveredRanges(filePath: string): LineRange[];
+    /**
+     * Return the next unread chunk for a file, using a chunk-size policy
+     * based on file size:
+     *   < 300 lines       full-file read (chunk = totalLines)
+     *   300-1,000 lines   250-line chunks
+     *   1,000-5,000       300-line chunks
+     *   > 5,000 lines     400-line chunks
+     *
+     * Returns null if the file is fully covered or not tracked.
+     */
+    getNextUnreadRange(filePath: string, chunkSize?: number): LineRange | null;
+    getPrioritizedUnreadRange(filePath: string, fileContent: string, chunkSize?: number, candidateLocations?: LineRange[], functionBoundaries?: {
+        name: string;
+        startLine: number;
+        endLine: number;
+    }[]): LineRange | null;
+    private snapToFunctionBoundary;
+    /**
+     * Return coverage percentage for a file (0-100). Returns 0 if the file
+     * is not tracked or has no totalLines.
+     */
+    getCoveragePercent(filePath: string): number;
+    static chunkSizeForLines(totalLines: number): number;
+    recordToolUse(toolType: string): void;
+    recordFlowVerification(filePath: string, tool: string, status: FlowVerificationStatus, flowCount: number, reason: string, structured?: {
+        riskId?: string;
+        candidateId?: string;
+        source?: {
+            filePath: string;
+            symbol?: string;
+            line?: number;
+        };
+        sink?: {
+            filePath: string;
+            symbol?: string;
+            line?: number;
+        };
+        hops?: Array<{
+            filePath: string;
+            symbol?: string;
+            line?: number;
+            description?: string;
+        }>;
+        truncated?: boolean;
+        error?: string;
+    }): void;
+    getFlowVerifications(): FlowVerification[];
+    hasClassifiedFlow(): boolean;
+    hasResolvedFlow(riskId?: string): boolean;
+    recordSymbolSearch(symbol: string): void;
+    markStepComplete(step: InvestigationStep): void;
+    markAllHandlersReviewed(): void;
+    markCandidatesVerified(): void;
+    markArchitectureRisksAddressed(): void;
+    /**
+     * Replace the required checklist with a specific set of steps.
+     * Used by target-specific investigation profiles.
+     */
+    setRequiredSteps(steps: InvestigationStep[]): void;
+    addInvestigationTasks(tasks: InvestigationTask[]): void;
+    updateTaskStatus(taskId: string, status: InvestigationTaskStatus): void;
+    getPendingTasks(): InvestigationTask[];
+    getUnresolvedTasks(): InvestigationTask[];
+    getAllTasks(): InvestigationTask[];
+    getIncompleteSteps(): InvestigationStep[];
+    getCompletedSteps(): InvestigationStep[];
+    getToolsUsed(): string[];
+    getFilesRead(): string[];
+    getReadCount(filePath: string): number;
+    getCoverageSummary(filePath: string): {
+        totalLines: number;
+        coveredLines: number;
+        coveragePercentage: number;
+        uncoveredRangeCount: number;
+        largestUncoveredRange: LineRange | null;
+        readCount: number;
+        blockedReadCount: number;
+    };
+    registerRootCause(rootCauseId: string, description: string): void;
+    getRootCauses(): Map<string, string>;
+    getRecommendedRecoveryAction(): string | null;
+    formatChecklistForPrompt(): string;
+    private stepDescription;
+}