race-conditions

What this skill does

# Race Conditions (RACE)

Analyze source code for race condition vulnerabilities including time-of-check
to time-of-use (TOCTOU), double-spend, check-then-act without locking, file
system race conditions, shared state across async boundaries, and non-atomic
counter operations. Race conditions are among the hardest bugs to detect through
testing because they depend on timing, making static analysis essential.

## Supported Flags

Read `../../shared/schemas/flags.md` for the full flag specification. This skill
supports all cross-cutting flags. Key flags for this skill:

- `--scope` determines which files to analyze (default: `changed`)
- `--depth standard` reads code and checks for common race patterns
- `--depth deep` traces shared state across call graphs and async boundaries
- `--severity` filters output (race conditions are often `high` or `critical`)

## Framework Context

Key CWEs in scope:
- CWE-362: Concurrent Execution Using Shared Resource with Improper Synchronization
- CWE-367: Time-of-Check Time-of-Use (TOCTOU) Race Condition
- CWE-820: Missing Synchronization
- CWE-821: Incorrect Synchronization
- CWE-829: Inclusion of Functionality from Untrusted Control Sphere

## Detection Patterns

Read `references/detection-patterns.md` for the full catalog of code patterns,
search heuristics, language-specific examples, and false positive guidance.

## Workflow

### 1. Determine Scope

Parse flags and resolve the file list per `../../shared/schemas/flags.md`.
Filter to files likely to contain race-prone logic:

- Database transaction handlers (`**/services/**`, `**/handlers/**`, `**/models/**`)
- Payment and financial logic (`**/payments/**`, `**/billing/**`, `**/wallet/**`)
- File system operations (`**/storage/**`, `**/upload/**`, `**/fs/**`)
- Async/concurrent code (`**/workers/**`, `**/tasks/**`, `**/jobs/**`)
- Counter and state management (`**/counters/**`, `**/state/**`, `**/cache/**`)

### 2. Check for Available Scanners

Detect scanners per `../../shared/schemas/scanners.md`:

1. `semgrep` -- primary scanner for concurrency patterns
2. `go vet` -- Go-specific race detection heuristics
3. `bandit` -- Python threading and synchronization issues

Record which scanners are available and which are missing.

### 3. Run Scanners (If Available)

If semgrep is available, run with rules targeting concurrency:
```
semgrep scan --config auto --json --quiet <target>
```
Filter results to rules matching race condition, TOCTOU, and concurrency
patterns. Normalize output to the findings schema.

### 4. Claude Code Analysis

Regardless of scanner availability, perform manual code analysis:

1. **Check-then-act audit**: Find patterns where a condition is checked and then
   acted on without atomic guarantees (e.g., check balance then debit).
2. **File TOCTOU**: Find file existence checks followed by file operations
   without locking or atomic alternatives.
3. **Shared state across await**: Identify mutable state read before an await
   point and used after it without re-validation.
4. **Non-atomic counters**: Find counter increments (read-modify-write) without
   locking or atomic operations.
5. **Database transactions**: Verify financial and state-changing operations
   use proper isolation levels and row-level locking.
6. **Async/parallel iteration**: Find shared mutable state accessed in parallel
   loops, goroutines, or thread pools.

When `--depth deep`, additionally trace:
- Full data flow of shared variables across async boundaries
- Database isolation level configuration
- Lock acquisition ordering (deadlock potential)

### 5. Report Findings

Format output per `../../shared/schemas/findings.md` using the `RACE` prefix
(e.g., `RACE-001`, `RACE-002`).

Include for each finding:
- Severity and confidence
- Exact file location with code snippet
- The race window (what happens between check and act)
- Exploit scenario describing how timing can be abused
- Concrete fix with diff when possible
- CWE references

## What to Look For

These are the high-signal patterns specific to race conditions. Each maps
to a detection pattern in `references/detection-patterns.md`.

1. **TOCTOU in file operations** -- Checking file existence or permissions
   then operating on the file in a separate call.

2. **Double-spend / check-then-debit** -- Reading a balance, comparing it,
   then debiting in separate non-atomic steps.

3. **Check-then-act without lock** -- Any pattern where a condition is checked
   and the result is assumed to hold when the action executes.

4. **Shared state across await** -- Reading mutable state, yielding execution
   (await/yield), then using the stale value.

5. **Non-atomic read-modify-write** -- Counter increments, sequence generators,
   or flag toggles without synchronization.

6. **Missing database transaction isolation** -- Financial operations using
   default (READ COMMITTED) isolation when SERIALIZABLE is needed.

7. **Parallel iteration over shared collection** -- Modifying a shared list,
   map, or set from concurrent goroutines, threads, or async tasks.

## Scanner Integration

| Scanner | Coverage | Command |
|---------|----------|---------|
| semgrep | TOCTOU file ops, non-atomic patterns | `semgrep scan --config auto --json --quiet <target>` |
| go vet | Go race condition heuristics | `go vet -race ./...` |
| bandit | Python threading issues | `bandit -r <target> -f json -q` |

**Fallback (no scanner)**: Use Grep with patterns from `references/detection-patterns.md`
to find check-then-act patterns, file stat calls, counter operations, and
async state access. Report findings with `confidence: medium`.

## Output Format

Use the findings schema from `../../shared/schemas/findings.md`.

- **ID prefix**: `RACE` (e.g., `RACE-001`)
- **metadata.tool**: `race-conditions`
- **metadata.framework**: `specialized`
- **metadata.category**: `RACE`
- **references.cwe**: `CWE-362`, `CWE-367`
- **references.stride**: `T` (Tampering) or `E` (Elevation of Privilege)

Severity guidance for this category:
- **critical**: Double-spend in financial operations, authentication bypass via race
- **high**: TOCTOU in security-sensitive file operations, check-then-act on authorization
- **medium**: Non-atomic counters affecting business logic, shared state across await
- **low**: Theoretical races with no clear exploit path, cosmetic counter inaccuracies