Quick Start

This guide will help you run your first race condition test with TRECO in 5 minutes.

Your First Attack

Let’s test a simple double-redemption vulnerability.

1. Create Attack Configuration

Create a file called attack.yaml:

metadata:
  name: "Double Redemption Test"
  version: "1.0"
  author: "Security Researcher"
  vulnerability: "CWE-362"

target:
  host: "api.example.com"
  port: 443
  tls:
    enabled: true
    verify_cert: true

entrypoint:
  state: login
  input:
    username: "testuser"
    password: "testpass"

states:
  login:
    description: "Authenticate and get token"
    request: |
      POST /api/login HTTP/1.1
      Host: {{ config.host }}
      Content-Type: application/json

      {"username": "{{ username }}", "password": "{{ password }}"}

    extract:
      token:
        type: jpath
        pattern: "$.access_token"

    next:
      - on_status: 200
        goto: race_attack

  race_attack:
    description: "Concurrent redemption attack"
    request: |
      POST /api/redeem HTTP/1.1
      Host: {{ config.host }}
      Authorization: Bearer {{ login.token }}
      Content-Type: application/json

      {"amount": 100}

    race:
      threads: 20
      sync_mechanism: barrier
      connection_strategy: preconnect
      thread_propagation: single

    next:
      - on_status: 200
        goto: end

  end:
    description: "Attack complete"

2. Run the Attack

# Using uv run
uv run treco attack.yaml

# Or activate the environment first
source .venv/bin/activate
treco attack.yaml

3. Analyze the Results

TRECO will output detailed results:

======================================================================
Treco - Race Condition PoC Framework
======================================================================
Attack: Double Redemption Test
Version: 1.0
Vulnerability: CWE-362
Target: https://api.example.com:443
======================================================================

Executing state: login
[State] Status: 200
Extracted: {'token': 'eyJhbGciOiJIUzI1NiIs...'}

======================================================================
RACE ATTACK: race_attack
======================================================================
Threads: 20
Sync Mechanism: barrier
Connection Strategy: preconnect
Thread Propagation: single
======================================================================

[Thread 0] Ready, waiting at sync point...
[Thread 1] Ready, waiting at sync point...
...
[Thread 0] Status: 200, Time: 45.2ms
[Thread 1] Status: 200, Time: 45.8ms
...

======================================================================
RACE ATTACK RESULTS
======================================================================
Total threads: 20
Successful: 18
Failed: 2

Timing Analysis:
  Average response time: 46.5ms
  Fastest response: 45.2ms
  Slowest response: 48.7ms
  Race window: 3.5ms
  ✓ EXCELLENT race window (< 1ms)

Vulnerability Assessment:
  ⚠ VULNERABLE: Multiple requests succeeded (18)
  ⚠ Potential race condition detected!
======================================================================

Understanding the Output

Race Window

The race window is the time difference between the fastest and slowest response:

< 1ms: Excellent - true race condition achievable
1-100ms: Good - sufficient precision for most tests
> 100ms: Poor - timing too imprecise

Vulnerability Assessment

Multiple successes: Indicates race condition vulnerability
Single success: Normal behavior (only first should succeed)
All failures: No vulnerability detected

Common CLI Options

Override Configuration

# Override credentials
treco attack.yaml --user alice --password secret

# Override target
treco attack.yaml --host api.example.com --port 443

# Override thread count
treco attack.yaml --threads 50

# Pass TOTP seed
treco attack.yaml --seed JBSWY3DPEHPK3PXP

Verbose Output

# Show detailed debug information
treco attack.yaml --verbose

Using Environment Variables

# Set sensitive data as environment variables
export PASSWORD='mysecretpassword'
export API_KEY='abc123'

# Reference in YAML with env filter
# password: "{{ env('PASSWORD') }}"
treco attack.yaml

Example Configurations

Basic Authentication Test

metadata:
  name: "Auth Race Test"
  version: "1.0"
  author: "Tester"
  vulnerability: "CWE-362"

target:
  host: "localhost"
  port: 8080
  tls:
    enabled: false

entrypoint:
  state: race_login
  input:
    username: "admin"
    password: "password123"

states:
  race_login:
    description: "Race login attempts"
    request: |
      POST /login HTTP/1.1
      Host: {{ config.host }}
      Content-Type: application/json

      {"username": "{{ username }}", "password": "{{ password }}"}

    race:
      threads: 10
      sync_mechanism: barrier
      connection_strategy: preconnect

    next:
      - on_status: 200
        goto: end

  end:
    description: "Done"

API with TOTP 2FA

metadata:
  name: "2FA Race Test"
  version: "1.0"
  author: "Tester"
  vulnerability: "CWE-362"

target:
  host: "api.example.com"
  port: 443
  tls:
    enabled: true

entrypoint:
  state: login
  input:
    username: "{{ argv('user', 'testuser') }}"
    totp_seed: "{{ argv('seed', 'JBSWY3DPEHPK3PXP') }}"

states:
  login:
    description: "Login with 2FA"
    request: |
      POST /api/login HTTP/1.1
      Host: {{ config.host }}
      Content-Type: application/json

      {"username": "{{ username }}", "totp": "{{ totp(totp_seed) }}"}

    extract:
      token:
        type: jpath
        pattern: "$.token"

    next:
      - on_status: 200
        goto: race_action

  race_action:
    description: "Race condition attack"
    request: |
      POST /api/action HTTP/1.1
      Authorization: Bearer {{ login.token }}

    race:
      threads: 20
      sync_mechanism: barrier
      connection_strategy: preconnect

    next:
      - on_status: 200
        goto: end

  end:
    description: "Complete"

What’s Next?

Configuration Reference - Complete YAML configuration reference
Data Extractors - All available data extractors
Template Engine - Template syntax and filters
Attack Examples - More real-world attack examples
GitHub Repository - More examples and source code
GitHub Issues - Report bugs or request features

Testing Your Own API

To test your own API:

Replace api.example.com with your target
Update the authentication endpoint and credentials
Replace the attack endpoint (/api/redeem)
Adjust the threads count (10-30 is usually optimal)
Run the attack and analyze the results

Warning

Only test APIs you have written authorization to test. Unauthorized testing is illegal and unethical.

Troubleshooting

Attack Not Working?

Check authentication: Ensure login returns a valid token
Verify endpoint: Use a tool like curl or Postman to test the endpoint manually
Adjust timing: Try different sync_mechanism values
Reduce threads: Start with 5-10 threads and increase gradually

Poor Race Window?

Use preconnect: Ensure connection_strategy: preconnect
Use barrier: Set sync_mechanism: barrier
Check network: Test on the same network as the target
Reduce threads: Too many threads can increase variance

Connection Errors?

SSL/TLS: Try verify_cert: false for self-signed certificates
Timeout: Increase timeout in configuration
Firewall: Ensure target allows your connections
Rate limiting: Reduce thread count if being rate limited

Template Errors?

Check variable names: Ensure extracted variables are correctly named
Check syntax: Jinja2 uses {{ variable }} not ${variable}
Use verbose mode: Run with --verbose for detailed error messages

Extractor Errors?

Check pattern: Ensure your JSONPath/XPath/regex pattern is correct
Check response: Verify the response contains the expected data
Try different extractor: JSONPath for JSON, XPath for HTML, regex for text