---
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"]
```