/**
 * Adversary Agent - Type Definitions
 *
 * The Adversary agent is a mythos-class ethical hacker that uses real
 * LLM reasoning (Claude API) to find vulnerabilities that pattern-based
 * scanners miss. It thinks like an attacker, generates PoCs, and chains
 * vulnerabilities into attack paths.
 *
 * @module agents/adversary/types
 */
import type { Severity, FindingCategory } from "../../certification/types.js";
/**
 * Claude model for adversary analysis
 *
 * Accepts any valid Claude model ID. Configure via environment variables:
 *   ADVERSARY_SONNET_MODEL - Pro tier model
 *   ADVERSARY_OPUS_MODEL   - Enterprise tier model
 *
 * Common models:
 *   claude-sonnet-4-6 (default Pro)
 *   claude-opus-4-8 (default Enterprise)
 */
export type AdversaryModel = string;
/**
 * Aggressiveness level determines depth and risk of analysis
 */
export type AggressivenessLevel = "passive" | "active" | "aggressive";
/**
 * Focus areas for adversarial analysis
 */
export type AttackFocusArea = "web-app" | "api" | "auth" | "injection" | "llm" | "infra" | "crypto" | "data-flow" | "supply-chain";
/**
 * Configuration for the adversary agent
 */
export interface AdversaryConfig {
    /** Claude model to use (Pro gets Sonnet 4, Enterprise gets Opus 4) */
    model: AdversaryModel;
    /** Analysis aggressiveness level */
    aggressiveness: AggressivenessLevel;
    /** Attack focus areas to analyze */
    focusAreas: AttackFocusArea[];
    /** Maximum time for analysis in milliseconds */
    maxAnalysisTime: number;
    /** Whether to generate proof-of-concept exploits */
    generatePoC: boolean;
    /** Maximum files to analyze */
    maxFiles?: number;
    /** Include patterns for file selection */
    includePatterns?: string[];
    /** Exclude patterns for file selection */
    excludePatterns?: string[];
    /** Enable chain analysis to find multi-step attacks */
    enableChaining?: boolean;
    /** Existing findings to consider for chaining */
    existingFindings?: AdversaryFinding[];
}
/**
 * Exploitability assessment
 */
export type Exploitability = "trivial" | "easy" | "moderate" | "hard" | "expert";
/**
 * Attack step in a proof of concept
 */
export interface AttackStep {
    /** Step order number */
    order: number;
    /** Action identifier */
    action: string;
    /** Step description */
    description: string;
    /** Command to execute if applicable */
    command?: string;
    /** Expected outcome */
    expectedResult?: string;
    /** Payload or data if applicable */
    payload?: string;
    /** Additional notes */
    note?: string;
    /** Target URL/endpoint if applicable */
    target?: string;
    /** HTTP method if applicable */
    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
    /** Headers if applicable */
    headers?: Record<string, string>;
}
/**
 * Proof of concept for a vulnerability
 */
export interface ProofOfConcept {
    /** Unique PoC ID */
    id: string;
    /** Reference to the finding */
    findingId: string;
    /** Prerequisites before executing PoC */
    prerequisites: string[];
    /** Steps to reproduce */
    steps: AttackStep[];
    /** Exploit payload if applicable */
    payload?: string;
    /** Expected result demonstrating vulnerability */
    expectedResult: string;
    /** Instructions for safe testing */
    safeTestInstructions: string;
    /** Whether this PoC was validated */
    validated?: boolean;
}
/**
 * Adversary finding with attack narrative and PoC
 */
export interface AdversaryFinding {
    /** Unique finding ID */
    id: string;
    /** Finding title */
    title: string;
    /** Detailed description */
    description: string;
    /** Severity level */
    severity: Severity;
    /** Confidence score 0-100 */
    confidence: number;
    /** Finding category */
    category: FindingCategory;
    /** Attack focus area */
    focusArea: AttackFocusArea;
    /** Affected file */
    file: string;
    /** Line number */
    line: number;
    /** End line if multi-line */
    endLine?: number;
    /** Code snippet */
    codeSnippet: string;
    /** Step-by-step attack narrative */
    attackScenario: string;
    /** How difficult to exploit */
    exploitability: Exploitability;
    /** Proof of concept if generated */
    proofOfConcept?: ProofOfConcept;
    /** Finding IDs that can be chained with this one */
    chainPotential: string[];
    /** MITRE ATT&CK technique IDs */
    mitreAttackTechniques: string[];
    /** CWE identifiers */
    cweIds: string[];
    /** OWASP category if applicable */
    owaspCategory?: string;
    /** Remediation recommendation */
    recommendation: string;
    /** AI reasoning that led to this finding */
    aiReasoning: string;
    /** Claude model that found this (or "deterministic" for pattern-based) */
    modelUsed: AdversaryModel | "deterministic";
    /** Compliance framework mappings */
    complianceMapping?: {
        owaspLlm?: {
            id: string;
            name: string;
            description: string;
            severity: string;
        };
        mitreAtlas?: {
            technique: string;
            tactic: string;
            description: string;
        };
        mitreAttack?: {
            technique: string;
            tactic: string;
            description: string;
        };
        cwe?: {
            id: string;
            name: string;
            description: string;
        };
        soc2?: {
            criteria: string;
            control: string;
            description: string;
        };
        iso27001?: {
            control: string;
            annex: string;
            description: string;
        };
        pciDss?: {
            requirement: string;
            description: string;
        };
        gdpr?: {
            article: string;
            description: string;
        };
    };
}
/**
 * Technology detection result
 */
export interface TechnologyStack {
    framework?: string;
    language: string;
    runtime?: string;
    database?: string[];
    auth?: string[];
    cloud?: string;
    apis?: ("rest" | "graphql" | "grpc" | "websocket")[];
}
/**
 * Entry point for attack surface
 */
export interface EntryPoint {
    /** Type of entry point */
    type: "route" | "handler" | "endpoint" | "webhook" | "socket" | "cli";
    /** Path or identifier */
    path: string;
    /** HTTP methods if applicable */
    methods?: string[];
    /** File location */
    file: string;
    /** Line number */
    line: number;
    /** Authentication required */
    authRequired: boolean;
    /** Input parameters */
    inputs: {
        name: string;
        source: "query" | "body" | "header" | "path" | "cookie";
        validated: boolean;
    }[];
    /** Risk score 0-100 */
    riskScore: number;
}
/**
 * Trust boundary in the application
 */
export interface TrustBoundary {
    /** Boundary name */
    name: string;
    /** Description */
    description: string;
    /** Entry points at this boundary */
    entryPoints: string[];
    /** Data flowing across this boundary */
    dataFlow: string[];
    /** Security controls at this boundary */
    controls: string[];
}
/**
 * Reconnaissance phase result
 */
export interface ReconResult {
    /** Detected technology stack */
    techStack: TechnologyStack;
    /** Source files analyzed */
    filesAnalyzed: string[];
    /** Entry points discovered */
    entryPoints: EntryPoint[];
    /** Trust boundaries identified */
    trustBoundaries: TrustBoundary[];
    /** Third-party integrations */
    thirdParty: {
        name: string;
        type: "api" | "sdk" | "service";
        riskLevel: "low" | "medium" | "high";
    }[];
    /** Duration of recon phase */
    duration: number;
}
/**
 * Attack surface analysis result
 */
export interface AttackSurfaceResult {
    /** All entry points categorized */
    entryPoints: EntryPoint[];
    /** High-risk areas requiring deep analysis */
    highRiskAreas: {
        area: string;
        reason: string;
        files: string[];
    }[];
    /** Data flow paths (input to output) */
    dataFlows: {
        input: string;
        output: string;
        transformations: string[];
        validated: boolean;
    }[];
    /** Permission boundaries */
    permissionBoundaries: {
        role: string;
        allowedActions: string[];
        files: string[];
    }[];
    /** Duration */
    duration: number;
}
/**
 * Exploitation phase result
 */
export interface ExploitationResult {
    /** Vulnerabilities discovered */
    findings: AdversaryFinding[];
    /** Files analyzed in depth */
    filesAnalyzed: number;
    /** Token usage for this phase */
    tokensUsed: number;
    /** Duration */
    duration: number;
}
/**
 * Exploit chain analysis
 */
export interface ExploitChain {
    /** Chain ID */
    id: string;
    /** Chain name */
    name: string;
    /** Chain description */
    description: string;
    /** Finding IDs in chain order */
    findingIds: string[];
    /** Combined severity (often escalates) */
    combinedSeverity: Severity;
    /** Impact if chain is exploited */
    impact: string;
    /** MITRE ATT&CK techniques for full chain */
    mitreChain: string[];
    /** Likelihood of successful chaining */
    likelihood: "high" | "medium" | "low";
}
/**
 * Chaining phase result
 */
export interface ChainingResult {
    /** Discovered exploit chains */
    chains: ExploitChain[];
    /** Single findings that couldn't be chained */
    isolatedFindings: string[];
    /** Duration */
    duration: number;
}
/**
 * Complete adversary analysis result
 */
export interface AdversaryResult {
    /** Whether analysis succeeded */
    success: boolean;
    /** Unique analysis ID */
    analysisId: string;
    /** Project path analyzed */
    projectPath: string;
    /** Configuration used */
    config: AdversaryConfig;
    /** Reconnaissance results */
    recon?: ReconResult;
    /** Attack surface results */
    attackSurface?: AttackSurfaceResult;
    /** Exploitation results */
    exploitation?: ExploitationResult;
    /** Chaining results */
    chaining?: ChainingResult;
    /** All findings (deduplicated) */
    findings: AdversaryFinding[];
    /** All discovered chains */
    chains: ExploitChain[];
    /** Total token usage */
    totalTokensUsed: number;
    /** Total duration in milliseconds */
    totalDuration: number;
    /** Error if analysis failed */
    error?: string;
    /** Summary recommendations */
    recommendations: string[];
}
/**
 * Message for Claude API
 */
export interface ClaudeMessage {
    role: "user" | "assistant";
    content: string;
}
/**
 * Response from Claude API
 */
export interface ClaudeResponse {
    content: string;
    tokensUsed: {
        input: number;
        output: number;
    };
    model: string;
    stopReason: "end_turn" | "max_tokens" | "stop_sequence";
}
/**
 * Analysis prompt for Claude
 */
export interface AnalysisPrompt {
    /** System prompt establishing adversarial thinking */
    systemPrompt: string;
    /** Code context to analyze */
    codeContext: string;
    /** Specific analysis instructions */
    instructions: string;
    /** Expected output format */
    outputFormat: string;
}
//# sourceMappingURL=types.d.ts.map