race-condition git:20260913.4c35c60A

Immutable. This exact content never changes and is served at /api/v1/blob/882053bc6c6bc23c.

---
name: race-condition
description: Classify race condition evidence — TOCTOU (access→fopen), shared-state (lock→unlock→mutate), and classic shared-variable data races in pthread code. Maps to CWE-362.
license: MIT
compatibility: opencode,claude code,DSH
metadata:
  cwe: CWE-362
  severity: HIGH
  domain: concurrency
---

## Race Condition Analysis (CWE-362)

### Evidence Patterns

#### TOCTOU: Filesystem (CWE-362)
- **RACE_CONDITION event** with category `toctou`
- Pattern: `access(path, ...)` check followed by `fopen(path, ...)` / `open(path, ...)`
- Time-of-check to time-of-use window allows symlink attack or file swap

#### TOCTOU: Shared State (CWE-362)
- **RACE_CONDITION event** with category `toctou_shared_state`
- Pattern: `mutex_lock` → `check` → `mutex_unlock` → `mutate`
- Check and mutation not atomic; another thread can change state between unlock and mutate

#### Classic Data Race (CWE-362)
- **RACE_CONDITION event** with category `shared_data_race`
- Pattern: a file-scope variable accessed by two or more `pthread_create` thread functions, with at least one write, and no `pthread_mutex_lock`/`unlock` scope around the access
- Examples: `g_shared_counter++` in two threads, writer/reader pairs on `g_flag`/`g_data`
- The event carries `thread_functions`, `thread_instances` and `write_line` properties

### Safe Patterns (P0 Exclusion)

| Safe Pattern | Why Safe |
|---------------|----------|
| `fopen(path, "r")` directly, check result | No check-then-use window |
| `open(path, O_RDONLY | O_NOFOLLOW)` | Rejects symlinks atomically |
| `fstat(fd, &st)` after `open` | Check on the fd, not the path |
| Lock held through both check and mutation | Atomic check-then-act |

### Classification Rules

| Condition | Classification |
|-----------|---------------|
| `access()` + `fopen()` on same path, no atomicity | **confirmed** |
| `access()` + `open()` with `O_NOFOLLOW` | **false-positive** |
| Mutate a shared/global variable after releasing a lock | **suspected** (a TOCTOU only if the same variable was READ inside the lock — verify the check-then-act pair) |
| Lock held through check + mutate | **false-positive** |
| `access()` + `fopen()` in same function, path is local | **suspected** (may be safe if path not attacker-controlled) |
| Check-then-act with no shared state | **false-positive** |
| Shared variable, >= 2 pthread threads, >= 1 write, no lock | **confirmed** |
| Shared variable, all accesses inside lock scope | **false-positive** |
| Shared variable accessed by only one thread function | **false-positive** (no concurrent access) |

### Fix Suggestions
- Replace `access()` + `fopen()` with direct `fopen()` and error check
- Use `open()` with `O_NOFOLLOW` to reject symlinks
- Hold the mutex through both check and mutation (don't unlock between)
- Use `fstat()` on the fd instead of `stat()` on the path
- For file locking, use `flock()` or `fcntl(F_SETLK)` for atomic lock+check
- Consider single-threaded design for simple cases