Command-Line Interface

TRECO provides a command-line interface for running race condition attacks.

Basic Usage

treco [OPTIONS] CONFIG_FILE

Arguments:

  • CONFIG_FILE - Path to the YAML configuration file (required)

Options

Authentication Options

--user USERNAME       Username for authentication
--password PASSWORD   Password for authentication (prefer env var)
--seed SEED          TOTP seed for 2FA generation

Example:

treco attack.yaml --user alice --password secret123
treco attack.yaml --user admin --seed JBSWY3DPEHPK3PXP

Target Options

--host HOST          Override target hostname
--port PORT          Override target port

Example:

treco attack.yaml --host api.staging.example.com --port 8443

Execution Options

--threads COUNT      Override thread count for race attacks

Example:

treco attack.yaml --threads 50

Output Options

--verbose, -v        Enable verbose/debug output

Example:

treco attack.yaml --verbose
treco attack.yaml -v

Information Options

--version            Show version number
--help               Show help message

Example:

treco --version
treco --help

Using uv

When running with uv, prefix commands with uv run:

# Basic usage
uv run treco attack.yaml

# With options
uv run treco attack.yaml --user alice --threads 20

# Verbose mode
uv run treco attack.yaml -v

Or activate the virtual environment first:

source .venv/bin/activate
treco attack.yaml --user alice

Environment Variables

TRECO can read sensitive data from environment variables using the env() filter in YAML:

# Set environment variables
export USERNAME='testuser'
export PASSWORD='secretpassword'
export API_KEY='abc123xyz'
export TOTP_SEED='JBSWY3DPEHPK3PXP'

# Run attack
treco attack.yaml

Reference in YAML:

entrypoint:
  state: login
   input:
   username: "{{ env('USERNAME') }}"
   password: "{{ env('PASSWORD') }}"
   api_key: "{{ env('API_KEY', 'default_key') }}"

Complete Examples

Basic Attack

treco configs/simple-attack.yaml

With Authentication

treco configs/auth-attack.yaml --user admin --password admin123

With 2FA

export TOTP_SEED='JBSWY3DPEHPK3PXP'
treco configs/2fa-attack.yaml --user admin

Custom Target

treco configs/attack.yaml --host staging.example.com --port 8443

High Thread Count

treco configs/race-attack.yaml --threads 100

Full Example with All Options

export PASSWORD='secret'
uv run treco configs/full-attack.yaml \
  --user alice \
  --host api.staging.example.com \
  --port 443 \
  --threads 30 \
  --seed JBSWY3DPEHPK3PXP \
  --verbose

Exit Codes

TRECO uses standard exit codes:

Code

Meaning

0

Success - attack completed normally

1

Error - attack failed

130

Interrupted - user pressed Ctrl+C

Output Format

TRECO outputs detailed information during execution:

======================================================================
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...
...

======================================================================
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!
======================================================================

======================================================================
Attack Completed Successfully
======================================================================

✓ Attack completed successfully
  Total states executed: 4

Tips and Best Practices

Security

  1. Never pass passwords on command line - Use environment variables instead

  2. Use –seed for TOTP - Only when the seed is not sensitive

  3. Store configs securely - Don’t commit sensitive data to version control

Debugging

  1. Start with –verbose - See detailed execution flow

  2. Use fewer threads first - Start with 5-10 threads

  3. Check network connectivity - Verify target is reachable

Performance

  1. Adjust thread count - Usually 10-30 is optimal

  2. Test on same network - Lower latency = better race precision

  3. Monitor system resources - Too many threads can hurt performance

See Also