RatRace

---

What Problem It Solves

Race conditions represent one of the highest-impact security vulnerabilities in modern applications, yet they remain poorly covered by automated scanners. While tools like Nuclei, ffuf, and sqlmap excel at finding static vulnerabilities, they are fundamentally blind to concurrency-based issues.

Pentesters today face a choice: manually write throwaway scripts for each engagement, or skip race condition testing entirely. Neither option is scalable or professional.

RatRace solves this by providing a polished, repeatable workflow for race condition testing—transforming what was once ad-hoc scripting into a systematic process that integrates with CI/CD pipelines and generates professional reports.

Real-World Impact

Race condition vulnerabilities frequently appear in high-impact areas:

• E-commerce: Duplicate orders, inventory overselling, discount stacking
• Fintech: Double transfers, race-based privilege escalation, transaction replay
• Authentication: Token draining, session fixation, concurrent password resets
• Rate Limiting: Bypass via concurrent requests, distributed abuse

These bugs consistently earn the highest bounties in bug bounty programs because they directly threaten business revenue and customer trust.

---

Core Capabilities

Template-Driven Testing

Define race scenarios once in YAML, reuse across projects. Format mirrors Nuclei templates for familiarity:

id: checkout-race
info:
  name: Checkout Duplicate Order Race
  severity: critical
race:
  mode: burst
  concurrency: 20
  request:
    method: POST
    path: /api/v1/checkout
    headers:
      Authorization: "Bearer {{session}}"
    body: '{"item_id": "SKU-001"}'
validate:
  follow_up:
    method: GET
    path: /api/v1/orders?user={{user_id}}
  expect:
    json_field: "orders.length"
    condition: equals
    value: 1

Multiple Attack Modes

Burst Mode — Goroutine-based parallel requests with precise synchronization (stable, production-ready)

• Launches N goroutines that synchronize at microsecond precision
• Ideal for most applications with >5ms race windows

Last-Byte Sync — HTTP/1.1 TCP-level attack (implementation ready, testing phase)

• Holds all connections at request body's final byte
• Release via close() broadcast for sub-millisecond windows
• Effective against load-balanced and rate-limited targets

Single-Packet — HTTP/2 frame-based attack (implementation ready, testing phase)

• Sends all requests in a single TCP segment
• Leverages multiplexing for near-simultaneous server reception
• Bypasses some rate limiting mechanisms

Intelligent Validation

RatRace automatically:

• Fingerprints responses by status code + body hash to detect anomalies
• Clusters results to identify statistically significant differences
• Calculates confidence scores based on anomaly frequency and magnitude
• Executes follow-up requests to confirm state changes (e.g., "was the item really purchased twice?")
• Supports conditional validation with operators: equals, not_equals, greater_than, contains

Workflow Integration

Import existing requests:

# From curl commands
ratrace import --curl 'curl -X POST https://api.example.com/checkout ...' -o template.yaml

# From Burp exported HAR files
ratrace import --har session.har -o template.yaml

CI/CD automation:

ratrace race -u $TARGET -t template.yaml --silent
echo $?  # Exit code 10 = race found, 0 = clean

Professional reporting:

# JSON for automation
ratrace race -u $TARGET -t template.yaml -o results/

# HTML reports (planned V2)
ratrace report --input results.json --format html

---

Installation

From Source

git clone https://github.com/bogdanticu88/ratrace.git
cd ratrace
go build ./cmd/ratrace
./ratrace --help

Requirements: Go 1.24+

Docker

docker build -t ratrace:latest .
docker run --rm -it ratrace:latest race -u https://api.example.com -t template.yaml

---

Usage

Quick Start: Run a Race Test

# 1. Import from curl or use existing template
ratrace import --curl 'curl -X POST https://api.example.com/checkout ...' -o checkout.yaml

# 2. Execute the race
ratrace race -u https://api.example.com -t checkout.yaml -m burst -c 20

# 3. Review findings
# Output shows:
# 🔴 [CRITICAL] Checkout Duplicate Order Race
#     Anomaly Rate: 91.7%
#     Confidence:   84%

Example: E-Commerce Checkout Race

ratrace race \
  -u https://shop.example.com \
  -t examples/templates/checkout-race.yaml \
  -m burst \
  -c 25 \
  --output results/

Example: Silent Mode (for CI/CD)

# Runs without verbose logs, exits with semantic code
ratrace race -u https://api.example.com -t template.yaml --silent

# Check exit code
if [ $? -eq 10 ]; then
  echo "Race condition found!"
  exit 1
fi

---

Command Reference

race — Execute Race Attack

ratrace race -u <url> -t <template> [options]

Options:
  -m, --mode string          burst|lastbyte|singlepacket (default from template)
  -c, --concurrency int      Goroutine count (default 20)
  -H, --header strings       Custom headers (repeatable)
  -x, --proxy string         Proxy URL for requests
  -o, --output string        Output directory for results
  --timeout duration         Request timeout (default 10s)
  --insecure                 Skip TLS certificate verification
  --dry-run                  Parse template and exit
  --silent                   Suppress logs, show findings only

import — Convert Requests to Templates

ratrace import [--curl <command> | --har <file>] -o <output.yaml>

Converts existing requests (curl commands or HAR exports) into RatRace templates.
Useful for integrating with existing workflows.

report — Generate Reports

ratrace report --input results.json --format [html|json] --output report.html

Generates human-readable reports from race test results.

ratelimit — Test Rate Limit Bypass

ratrace ratelimit -u <url> -c <concurrency>

Tests if endpoints are vulnerable to concurrent rate limit bypass.

---

Template Format

Templates are YAML files that define a race scenario. Full reference:

id: unique-identifier
info:
  name: "Human-readable name"
  severity: critical|high|medium|low|info
  tags: [tag1, tag2]

race:
  mode: burst|lastbyte|singlepacket
  concurrency: 20
  request:
    method: POST|GET|PUT|DELETE|PATCH
    path: /api/endpoint
    headers:
      Authorization: "Bearer {{token}}"
      Custom-Header: "value"
    body: '{"json": "body", "user": "{{user_id}}"}'

validate:
  follow_up:
    method: GET
    path: /api/orders?user={{user_id}}
  expect:
    json_field: "orders.length"
    condition: equals|greater_than|contains|not_equals
    value: 1

Variables (use {{name}} placeholders):

• Substituted via command-line headers or hardcoded in template
• Example: ratrace race ... -H "Authorization: Bearer {{session_token}}"

---

Output

Terminal Output

Clean, color-coded logging shows test progress: