@securecode-ai/mcp 0.5.5 → 0.5.7

package/dist/attack/qualityMetrics.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Scan quality metrics — tracks measurable quality indicators throughout
+ * the agent scan so the final result includes a structured quality scorecard.
+ *
+ * Metrics are tracked locally in the MCP loop and included in the scan
+ * result/audit. They are NOT sent to the API — they are for the MCP and
+ * the caller to evaluate scan quality.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QualityMetricsTracker = void 0;
+exports.createQualityMetrics = createQualityMetrics;
+function createQualityMetrics() {
+    return {
+        reads: {
+            total: 0,
+            successful: 0,
+            duplicate: 0,
+            highOverlap: 0,
+            partialNew: 0,
+            newCoverage: 0,
+            blocked: 0,
+            truncated: 0,
+            invalid: 0,
+        },
+        coverage: {
+            totalLines: 0,
+            coveredLines: 0,
+            coveragePercentage: 0,
+            uncoveredRangeCount: 0,
+            largestUncoveredRange: null,
+        },
+        tools: {
+            totalActions: 0,
+            analysisToolCount: 0,
+            distinctToolsUsed: [],
+            readCount: 0,
+            searchCount: 0,
+            traceFlowCount: 0,
+            checkGuardCount: 0,
+            checkPolicyCount: 0,
+            getEndpointsCount: 0,
+            readConfigCount: 0,
+            findTestsCount: 0,
+            callGraphCount: 0,
+        },
+        candidates: {
+            total: 0,
+            discovered: 0,
+            investigating: 0,
+            supported: 0,
+            verified: 0,
+            unproven: 0,
+            inconclusive: 0,
+            rejected: 0,
+            merged: 0,
+            blocked: 0,
+        },
+        finish: {
+            attempts: 0,
+            rejections: 0,
+            forcedTermination: false,
+            terminationReason: '',
+            critiqueFired: 0,
+            finishGateFired: 0,
+        },
+        output: {
+            malformedOutputCount: 0,
+            sanitizedFindings: 0,
+            downgradedFindings: 0,
+        },
+        proof: {
+            requiredEvidenceChainRate: 0,
+            rootCauseCorrelationRate: 0,
+            resolvedArchitectureRiskRate: 0,
+            structuredCrossFileFlowRate: 0,
+            highPriorityGapCount: 0,
+            unsupportedFindingCount: 0,
+        },
+        budget: {
+            stepsUsed: 0,
+            stepsGranted: 0,
+            extensionsGranted: 0,
+            costSpentUsd: 0,
+            costCapUsd: 0,
+            wallClockMs: 0,
+            elapsedMs: 0,
+        },
+    };
+}
+const ANALYSIS_TOOLS = new Set([
+    'trace_flow', 'trace_flow_cross_file', 'check_guard', 'check_policy',
+    'call_graph', 'find_definition', 'find_references', 'find_tests',
+    'run_tests', 'search_code', 'read_config', 'get_endpoints',
+]);
+class QualityMetricsTracker {
+    metrics;
+    constructor() {
+        this.metrics = createQualityMetrics();
+    }
+    recordRead(classification, truncated) {
+        this.metrics.reads.total++;
+        switch (classification) {
+            case 'new-coverage':
+                this.metrics.reads.newCoverage++;
+                this.metrics.reads.successful++;
+                break;
+            case 'partial-new-coverage':
+                this.metrics.reads.partialNew++;
+                this.metrics.reads.successful++;
+                break;
+            case 'duplicate':
+                this.metrics.reads.duplicate++;
+                this.metrics.reads.blocked++;
+                break;
+            case 'high-overlap':
+                this.metrics.reads.highOverlap++;
+                this.metrics.reads.blocked++;
+                break;
+            case 'invalid':
+                this.metrics.reads.invalid++;
+                this.metrics.reads.blocked++;
+                break;
+            default: break;
+        }
+        if (truncated)
+            this.metrics.reads.truncated++;
+    }
+    recordToolUse(toolType) {
+        this.metrics.tools.totalActions++;
+        if (!this.metrics.tools.distinctToolsUsed.includes(toolType)) {
+            this.metrics.tools.distinctToolsUsed.push(toolType);
+        }
+        if (ANALYSIS_TOOLS.has(toolType)) {
+            this.metrics.tools.analysisToolCount++;
+        }
+        switch (toolType) {
+            case 'read_file':
+                this.metrics.tools.readCount++;
+                break;
+            case 'search_code':
+                this.metrics.tools.searchCount++;
+                break;
+            case 'trace_flow':
+            case 'trace_flow_cross_file':
+                this.metrics.tools.traceFlowCount++;
+                break;
+            case 'check_guard':
+                this.metrics.tools.checkGuardCount++;
+                break;
+            case 'check_policy':
+                this.metrics.tools.checkPolicyCount++;
+                break;
+            case 'get_endpoints':
+                this.metrics.tools.getEndpointsCount++;
+                break;
+            case 'read_config':
+                this.metrics.tools.readConfigCount++;
+                break;
+            case 'find_tests':
+                this.metrics.tools.findTestsCount++;
+                break;
+            case 'call_graph':
+                this.metrics.tools.callGraphCount++;
+                break;
+        }
+    }
+    recordCoverage(totalLines, coveredLines, uncoveredRangeCount, largestUncovered) {
+        this.metrics.coverage.totalLines = totalLines;
+        this.metrics.coverage.coveredLines = coveredLines;
+        this.metrics.coverage.coveragePercentage = totalLines > 0 ? Math.round(100 * coveredLines / totalLines) : 0;
+        this.metrics.coverage.uncoveredRangeCount = uncoveredRangeCount;
+        this.metrics.coverage.largestUncoveredRange = largestUncovered;
+    }
+    recordCandidateSnapshot(snapshot) {
+        this.metrics.candidates = { ...snapshot };
+    }
+    recordFinishAttempt() {
+        this.metrics.finish.attempts++;
+    }
+    recordFinishRejection() {
+        this.metrics.finish.rejections++;
+    }
+    recordCritique() {
+        this.metrics.finish.critiqueFired++;
+    }
+    recordFinishGate() {
+        this.metrics.finish.finishGateFired++;
+    }
+    recordForcedTermination(reason) {
+        this.metrics.finish.forcedTermination = true;
+        this.metrics.finish.terminationReason = reason;
+    }
+    recordTermination(reason) {
+        this.metrics.finish.terminationReason = reason;
+    }
+    recordMalformedOutput() {
+        this.metrics.output.malformedOutputCount++;
+    }
+    recordSanitizedFinding() {
+        this.metrics.output.sanitizedFindings++;
+    }
+    recordDowngradedFinding() {
+        this.metrics.output.downgradedFindings++;
+    }
+    recordBudget(stepsUsed, stepsGranted, extensionsGranted, costSpentUsd, costCapUsd, wallClockMs, elapsedMs) {
+        this.metrics.budget = { stepsUsed, stepsGranted, extensionsGranted, costSpentUsd, costCapUsd, wallClockMs, elapsedMs };
+    }
+    recordProofMetrics(input) {
+        this.metrics.proof.requiredEvidenceChainRate = input.totalFindings > 0
+            ? Math.round(100 * input.supportedFindings / input.totalFindings) : 100;
+        this.metrics.proof.rootCauseCorrelationRate = input.totalCandidates > 0
+            ? Math.round(100 * input.rootCauseGroups / input.totalCandidates) : 100;
+        this.metrics.proof.resolvedArchitectureRiskRate = input.totalRisks > 0
+            ? Math.round(100 * input.resolvedRisks / input.totalRisks) : 100;
+        this.metrics.proof.structuredCrossFileFlowRate = input.totalFlows > 0
+            ? Math.round(100 * input.structuredFlows / input.totalFlows) : 100;
+        this.metrics.proof.highPriorityGapCount = input.highPriorityGaps;
+        this.metrics.proof.unsupportedFindingCount = input.unsupportedFindings;
+    }
+    getMetrics() {
+        return { ...this.metrics };
+    }
+}
+exports.QualityMetricsTracker = QualityMetricsTracker;
+//# sourceMappingURL=qualityMetrics.js.map

package/dist/attack/qualityMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualityMetrics.js","sourceRoot":"","sources":["../../src/attack/qualityMetrics.ts"],"names":[],"mappings":"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"}

package/dist/attack/scanScheduler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Deterministic scan scheduler — chooses the next useful action when the
+ * model is blocked, repeats itself, or requests finish too early.
+ *
+ * The scheduler acts on generic state, not project names. It uses the
+ * evidence ledger, work item queue, handler inventory, and candidate
+ * store to determine what work remains and what action should execute next.
+ *
+ * Priority order:
+ *   1. Candidate missing critical evidence
+ *   2. Unresolved critical/high architecture task
+ *   3. Contract/interface target requiring implementation resolution
+ *   4. Unreviewed security-sensitive handler or RPC method
+ *   5. Missing authentication/authorization/ownership evidence
+ *   6. Missing cross-file flow
+ *   7. Missing configuration evidence
+ *   8. Missing related tests
+ *   9. Next unread critical range
+ *   10. Lower-priority pending task
+ *   11. Finish when no executable work remains
+ */
+import type { AgentScanAction, AgentScanTarget, AgentActionConstraint } from './agentScanProtocol';
+import type { ScanRunState } from './scanState';
+import type { EvidenceLedger } from './evidenceLedger';
+import type { WorkItemQueue } from './workItem';
+import type { HandlerInventory } from '../project-map/handlerInventory';
+import type { CandidateStore } from './candidateStore';
+import type { InvestigationState } from './investigationState';
+export type ScheduleDecisionKind = 'model' | 'deterministic-action' | 'finish-ready' | 'blocked';
+export interface ScheduleDecision {
+    kind: ScheduleDecisionKind;
+    action?: AgentScanAction;
+    constraint?: AgentActionConstraint;
+    workItemId?: string;
+    reason: string;
+}
+export interface SchedulerInput {
+    state: ScanRunState;
+    evidence: EvidenceLedger;
+    workItems: WorkItemQueue;
+    handlers: HandlerInventory;
+    candidates: CandidateStore;
+    investigation: InvestigationState;
+    target: AgentScanTarget;
+    functionBoundaries?: {
+        name: string;
+        startLine: number;
+        endLine: number;
+    }[];
+}
+export declare function schedule(input: SchedulerInput): ScheduleDecision;
+export declare function buildRecoveryConstraint(state: ScanRunState, investigation: InvestigationState): AgentActionConstraint | undefined;

package/dist/attack/scanScheduler.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * Deterministic scan scheduler — chooses the next useful action when the
+ * model is blocked, repeats itself, or requests finish too early.
+ *
+ * The scheduler acts on generic state, not project names. It uses the
+ * evidence ledger, work item queue, handler inventory, and candidate
+ * store to determine what work remains and what action should execute next.
+ *
+ * Priority order:
+ *   1. Candidate missing critical evidence
+ *   2. Unresolved critical/high architecture task
+ *   3. Contract/interface target requiring implementation resolution
+ *   4. Unreviewed security-sensitive handler or RPC method
+ *   5. Missing authentication/authorization/ownership evidence
+ *   6. Missing cross-file flow
+ *   7. Missing configuration evidence
+ *   8. Missing related tests
+ *   9. Next unread critical range
+ *   10. Lower-priority pending task
+ *   11. Finish when no executable work remains
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedule = schedule;
+exports.buildRecoveryConstraint = buildRecoveryConstraint;
+function schedule(input) {
+    const { state, evidence, workItems, handlers, candidates, investigation, target } = input;
+    // If no budget remains, finish is the only option
+    if (!canExecute(input)) {
+        return { kind: 'finish-ready', reason: 'No budget or wall-clock remaining' };
+    }
+    // 1. Active high/critical candidate missing critical evidence
+    const activeCandidates = candidates.getActive();
+    for (const candidate of activeCandidates) {
+        if (candidate.severity === 'critical' || candidate.severity === 'high') {
+            const action = actionForCandidateEvidence(candidate, target);
+            if (action) {
+                return {
+                    kind: 'deterministic-action',
+                    action,
+                    workItemId: candidate.id,
+                    reason: `Critical/high candidate "${candidate.claim}" needs evidence`,
+                };
+            }
+        }
+    }
+    // 2. Unresolved critical/high architecture work items with unsatisfied
+    // proof requirements — raised above unread ranges because cross-file
+    // proof is the highest-value security work. Without tracing the path
+    // to the sink, the agent cannot determine whether the risk is real.
+    const topWorkItem = workItems.highestPriority();
+    if (topWorkItem && (topWorkItem.priority === 'critical' || topWorkItem.priority === 'high')) {
+        if (topWorkItem.status === 'pending' || topWorkItem.status === 'active') {
+            const action = actionForWorkItem(topWorkItem, target, workItems);
+            if (action) {
+                return {
+                    kind: 'deterministic-action',
+                    action,
+                    workItemId: topWorkItem.id,
+                    reason: `Unresolved ${topWorkItem.priority} proof work item: ${topWorkItem.title}`,
+                };
+            }
+        }
+    }
+    // 3. Next unread critical range — source coverage is the foundation
+    // for all analysis. Uses security-keyword prioritization to read the
+    // most security-relevant uncovered range first.
+    const candidateLocations = candidates.getAll().flatMap(c => c.locations.map(l => ({ start: l.line, end: l.line })));
+    const nextRange = target.fileContent
+        ? investigation.getPrioritizedUnreadRange(target.filePath, target.fileContent, undefined, candidateLocations, input.functionBoundaries)
+        : investigation.getNextUnreadRange(target.filePath);
+    if (nextRange) {
+        const coverage = investigation.getCoverage(target.filePath);
+        const totalLines = coverage?.totalLines ?? 0;
+        const coveredLines = (coverage?.ranges ?? []).reduce((sum, r) => sum + (r.end - r.start + 1), 0);
+        const pct = totalLines > 0 ? Math.round(100 * coveredLines / totalLines) : 0;
+        return {
+            kind: 'deterministic-action',
+            action: {
+                type: 'read_file',
+                path: target.filePath,
+                startLine: nextRange.start,
+                endLine: nextRange.end,
+                rationale: `Read next unread range (coverage: ${pct}% of ${totalLines} lines)`,
+            },
+            reason: `Unread range ${nextRange.start}-${nextRange.end} in target file (${pct}% covered)`,
+        };
+    }
+    // 4. Contract/interface target requiring implementation resolution
+    const implRequirement = evidence.getUnsatisfiedRequirements().find(r => r.acceptedKinds.includes('implementation-resolution'));
+    if (implRequirement) {
+        return {
+            kind: 'deterministic-action',
+            action: {
+                type: 'search_code',
+                pattern: target.filePath.replace(/\.ts$/, '').replace(/.*\//, ''),
+                rationale: 'Resolve implementation for interface target',
+            },
+            reason: 'Interface target needs implementation resolution',
+        };
+    }
+    // 5. Unreviewed security-sensitive handler
+    const unreviewedHandlers = handlers.getUnreviewed();
+    const sensitiveUnreviewed = unreviewedHandlers.filter(h => h.securitySensitive);
+    if (sensitiveUnreviewed.length > 0) {
+        const first = sensitiveUnreviewed[0];
+        const range = handlers.getNextUnreviewedRange();
+        if (range) {
+            return {
+                kind: 'deterministic-action',
+                action: {
+                    type: 'read_file',
+                    path: first.filePath,
+                    startLine: range.start,
+                    endLine: Math.min(range.start + 50, range.end + 50),
+                    rationale: `Review unreviewed handler: ${first.symbol || 'unknown'}`,
+                },
+                workItemId: first.id,
+                reason: `${sensitiveUnreviewed.length} security-sensitive handler(s) unreviewed`,
+            };
+        }
+    }
+    // 6-8. Missing evidence from unsatisfied requirements
+    const unsatisfied = evidence.getUnsatisfiedRequirements();
+    if (unsatisfied.length > 0) {
+        const action = actionForRequirement(unsatisfied[0], target);
+        if (action) {
+            return {
+                kind: 'deterministic-action',
+                action,
+                reason: `Missing evidence: ${unsatisfied[0].description}`,
+            };
+        }
+    }
+    // 9. Lower-priority pending work items
+    const pending = workItems.getPending();
+    if (pending.length > 0) {
+        const action = actionForWorkItem(pending[0], target, workItems);
+        if (action) {
+            return {
+                kind: 'deterministic-action',
+                action,
+                workItemId: pending[0].id,
+                reason: `Lower-priority pending task: ${pending[0].title}`,
+            };
+        }
+    }
+    // 10. No executable work remains — finish is ready
+    if (candidates.allTerminal() && workItems.getExecutable().length === 0) {
+        return { kind: 'finish-ready', reason: 'All candidates terminal and no executable work items remain' };
+    }
+    // Default: let the model decide
+    return { kind: 'model', reason: 'No deterministic action determined, let model decide' };
+}
+function buildRecoveryConstraint(state, investigation) {
+    const blocked = state.recovery.consecutiveBlockedActions;
+    if (blocked < 2)
+        return undefined;
+    const recoveryAction = investigation.getRecommendedRecoveryAction();
+    return {
+        mode: 'recovery',
+        forbiddenActions: blocked >= 2 ? ['read_file'] : undefined,
+        requiredAction: recoveryAction || undefined,
+        reason: `Recovery mode: ${blocked} consecutive blocked actions`,
+    };
+}
+function canExecute(input) {
+    return input.state.budget.stepsRemaining > 0 &&
+        input.state.budget.costSpentUsd < input.state.budget.costCapUsd;
+}
+function actionForCandidateEvidence(candidate, target) {
+    if (candidate.requiredEvidence && candidate.requiredEvidence.length > 0) {
+        const req = candidate.requiredEvidence[0];
+        return actionForRequirement(req, target);
+    }
+    // Default: trace flow to gather more evidence
+    return {
+        type: 'trace_flow_cross_file',
+        filePath: candidate.locations[0]?.filePath || target.filePath,
+        rationale: `Gather evidence for candidate: ${candidate.claim}`,
+    };
+}
+function actionForWorkItem(item, target, queue) {
+    if (item.kind === 'implementation-review') {
+        const symbol = item.title.replace('Resolve implementation for: ', '');
+        return {
+            type: 'search_code',
+            pattern: `make${symbol}|Layer\\.effect.*${symbol}`,
+            rationale: item.title,
+        };
+    }
+    if (item.requirements.length === 0)
+        return null;
+    const unsatisfied = queue ? queue.getUnsatisfiedRequirements(item.id) : item.requirements;
+    if (unsatisfied.length === 0)
+        return null;
+    const req = unsatisfied[0];
+    const targetFile = req.targetFiles?.[0] || item.targetFiles[0] || target.filePath;
+    return actionForRequirement(req, target, targetFile);
+}
+function actionForRequirement(req, target, explicitTargetFile) {
+    const tool = req.requiredTools?.[0];
+    if (!tool)
+        return null;
+    const targetFile = explicitTargetFile || req.targetFiles?.[0] || target.filePath;
+    switch (tool) {
+        case 'read_file':
+            return {
+                type: 'read_file',
+                path: targetFile,
+                rationale: req.description,
+            };
+        case 'search_code':
+            return {
+                type: 'search_code',
+                pattern: 'auth|require|guard|permission|owner',
+                rationale: req.description,
+            };
+        case 'check_policy':
+            return {
+                type: 'check_policy',
+                filePath: targetFile,
+                rationale: req.description,
+            };
+        case 'check_guard':
+            return {
+                type: 'check_guard',
+                filePath: targetFile,
+                guardName: 'auth',
+                attackType: 'broken_access_control',
+                rationale: req.description,
+            };
+        case 'get_endpoints':
+            return {
+                type: 'get_endpoints',
+                rationale: req.description,
+            };
+        case 'trace_flow':
+        case 'trace_flow_cross_file':
+            return {
+                type: 'trace_flow_cross_file',
+                filePath: targetFile,
+                rationale: req.description,
+            };
+        case 'read_config':
+            return {
+                type: 'read_config',
+                configKind: 'all',
+                rationale: req.description,
+            };
+        case 'find_tests':
+            return {
+                type: 'find_tests',
+                filePath: targetFile,
+                rationale: req.description,
+            };
+        case 'find_definition':
+            return null;
+        case 'find_references':
+            return null;
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=scanScheduler.js.map

package/dist/attack/scanScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanScheduler.js","sourceRoot":"","sources":["../../src/attack/scanScheduler.ts"],"names":[],"mappings":"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"}

package/dist/attack/scanState.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Authoritative scan state — the single source of truth for a scan run's
+ * phase, budget, recovery, and lifecycle.
+ *
+ * The MCP owns this state. The model proposes actions; the MCP validates
+ * them against this state and owns all transitions.
+ *
+ * This replaces scattered booleans, counters, and checklist sets with a
+ * serializable state object that can be snapshotted for tracing and audit.
+ */
+import type { AgentScanTarget, AgentScanTranscriptStep, AgentScanBudget } from './agentScanProtocol';
+export type ScanPhase = 'planning' | 'surveying' | 'tracing' | 'candidate_investigation' | 'finish_review' | 'verifying' | 'evidence_recovery' | 'finalizing' | 'completed' | 'terminated';
+export type ScanTerminationReason = 'agent_finish' | 'forced_incomplete' | 'cost_cap' | 'budget_exhausted' | 'wall_clock' | 'cancelled' | 'api_error' | 'blocked_read_recovery';
+export interface ScanTermination {
+    reason: ScanTerminationReason;
+    phase: ScanPhase;
+    timestamp: number;
+    summary?: string;
+}
+export interface AgentScanBudgetState {
+    stepsUsed: number;
+    stepsRemaining: number;
+    stepsGranted: number;
+    hardMaxSteps: number;
+    extensionsGranted: number;
+    costSpentUsd: number;
+    costCapUsd: number;
+    startedAt: number;
+    wallClockMs: number;
+}
+export interface RecoveryState {
+    consecutiveBlockedActions: number;
+    totalBlockedActions: number;
+    lastBlockedAction?: string;
+    lastRecoveryAction?: string;
+    recoveryAttempts: number;
+    meaningfulProgressSinceRecovery: boolean;
+}
+export interface ScanRunState {
+    runId: string;
+    phase: ScanPhase;
+    target: AgentScanTarget;
+    transcript: AgentScanTranscriptStep[];
+    budget: AgentScanBudgetState;
+    recovery: RecoveryState;
+    finishAttempts: number;
+    verificationCycles: number;
+    termination?: ScanTermination;
+    profileId?: string;
+}
+export declare function createScanRunState(runId: string, target: AgentScanTarget, budget: AgentScanBudget): ScanRunState;
+export declare function transitionScanPhase(state: ScanRunState, next: ScanPhase, reason: string): void;
+export declare function terminateScan(state: ScanRunState, reason: ScanTerminationReason, summary?: string): void;
+export declare function isScanTerminal(state: ScanRunState): boolean;
+export declare function hasBudgetRemaining(state: ScanRunState): boolean;
+export declare function hasWallClockRemaining(state: ScanRunState): boolean;
+export declare function canExecuteWork(state: ScanRunState): boolean;
+export declare function snapshotState(state: ScanRunState): string;