adversarial-analysis

name	adversarial-analysis
description	Analyze code to identify explicit contracts, implicit usage patterns, and realistic boundary conditions. Contains concrete formulas for calculating input realism limits. Use before generating adversarial tests.
allowed-tools	Read, Grep, Glob

Adversarial Code Analysis

Purpose

Map the "Surface of Reality" for target code. Your goal is to distinguish:

• Contract Violations (invalid inputs the caller shouldn't send) → NOT testable
• Logic Bugs (valid inputs the code handles poorly) → TESTABLE

Analysis Checklist

1. Contract Extraction

Explicit Contracts:

• Type hints (int, str, Optional[T], List[T])
• assert statements and preconditions
• Docstring Args, Raises, Returns sections
• Validation code at function entry

Implicit Contracts:

• Variable names implying limits (retry_count → small positive int, buffer_size → memory-reasonable)
• Context from call sites (what values are actually passed?)
• Domain knowledge (user IDs are positive, emails contain @)

External Constraints:

• Database column limits (VARCHAR(255))
• API rate limits and timeouts
• Filesystem permissions and path length limits

2. Realism Baseline (The 3-Sigma Rule)

Use Grep to scan existing tests in tests/ and call sites in src/. Calculate boundaries:

String Inputs:

existing_lengths = [len(s) for each test string argument]
if len(existing_lengths) >= 5:
    Max_Realistic_Length = mean(existing_lengths) + 3 * std(existing_lengths)
elif len(existing_lengths) >= 1:
    Max_Realistic_Length = max(existing_lengths) * 2
else:
    Max_Realistic_Length = 256  # Zero-sample fallback

Numeric Inputs:

existing_values = [v for each numeric argument]
if len(existing_values) >= 5:
    Lower = mean(existing_values) - 3 * std(existing_values)
    Upper = mean(existing_values) + 3 * std(existing_values)
elif len(existing_values) >= 1:
    Lower = min(existing_values) - abs(min(existing_values))
    Upper = max(existing_values) + abs(max(existing_values))
else:
    Lower, Upper = -1000, 1000  # Zero-sample fallback

Special Boundaries (Always Valid):

• 0, -1, 1 for integers (if type allows)
• Empty string "" (if not explicitly forbidden)
• None only if type is Optional

Complex Objects:

• Max nesting depth: 3 levels (unless recursive data structure)
• Max fields: 20 (unless schema requires more)
• Zero-sample fallback: depth 2, fields 10

3. Vulnerability Surface Identification

High-Risk Patterns:

• Arithmetic: Division, modulo, floating-point accumulation, currency calculations
• Boundaries: Loop limits, array indices, string slicing
• State: Multi-step workflows, flag combinations, temporal dependencies
• Resources: File handles, connections, locks (cleanup on error paths)
• Parsing: User input, external data, format conversions

Output Format

For each target function, produce:

## Analysis: `function_name`

### Contracts
- Parameter X: Type, range [A, B], constraints
- Parameter Y: Type, must not be null/empty

### Realism Bounds (Calculated)
- String inputs: Max N characters (based on M samples, mean=P, std=Q)
- Numeric inputs: Range [X, Y]
- Objects: Max depth D, max fields F

### Realistic Edge Cases (TESTABLE)
1. [Specific input] - [Why it's realistic] - [What might break]
2. ...

### Excluded Scenarios (NOT TESTABLE - Contract Violations)
1. [Input] - [Why it violates contract]
2. ...

### Vulnerability Hypothesis
- Primary risk: [e.g., "off-by-one in loop boundary"]
- Secondary risk: [e.g., "floating point precision in total calculation"]