TRECO
Getting Started
About TRECO
What is TRECO?
The Problem: Race Conditions in Web Applications
Why Race Conditions Are Hard to Test
The TRECO Solution
Key Features
Core Capabilities
Advanced Features
Technical Architecture
Components
Execution Flow
Design Philosophy
Use Cases
Penetration Testing
Bug Bounty Hunting
Security Research
Quality Assurance
Common Vulnerability Patterns
Time-of-Check to Time-of-Use (TOCTOU)
Double-Spending
Resource Exhaustion
Limitations
Requirements
Project Status
Contributing
License
Security and Ethics
Acknowledgments
Support
Citation
About TRECO
What is TRECO?
The Problem: Race Conditions in Web Applications
Why Race Conditions Are Hard to Test
The TRECO Solution
Key Features
Core Capabilities
Advanced Features
Technical Architecture
Components
Execution Flow
Design Philosophy
Use Cases
Penetration Testing
Bug Bounty Hunting
Security Research
Quality Assurance
Common Vulnerability Patterns
Time-of-Check to Time-of-Use (TOCTOU)
Double-Spending
Resource Exhaustion
Limitations
Requirements
Project Status
Contributing
License
Security and Ethics
Acknowledgments
Support
Citation
Quick Start
Your First Attack
1. Create Attack Configuration
2. Run the Attack
3. Analyze the Results
Understanding the Output
Race Window
Vulnerability Assessment
Common CLI Options
Override Configuration
Verbose Output
Using Environment Variables
Example Configurations
Basic Authentication Test
API with TOTP 2FA
What’s Next?
Testing Your Own API
Troubleshooting
Attack Not Working?
Poor Race Window?
Connection Errors?
Template Errors?
Extractor Errors?
User Guide
Configuration Reference
YAML Structure Overview
Metadata Section
Target Section
TLS Configuration
HTTP Configuration
Proxy Configuration
Entrypoint Section
States Section
Basic State
State Options
State-Level Input
Race Configuration
Synchronization Mechanisms
Connection Strategies
Thread Propagation
Logger Configuration
Transitions
Complete Example
Best Practices
Configuration Tips
Security Tips
Performance Tips
See Also
Input Sources
Overview
Input Modes
distribute
product
random
same
Input Sources
Inline Lists
File Sources
Built-in Wordlists
Generator Expressions
Numeric Ranges
Examples
Password Brute-Force
Credential Stuffing
ID Enumeration
User Agent Rotation
Best Practices
Thread Count vs Input Size
Rate Limiting Considerations
Memory Usage
Performance Tips
Common Patterns
Multi-Factor Testing
Sequential Testing
Random Fuzzing
Troubleshooting
Thread Count Mismatch
File Not Found
Product Mode Too Large
See Also
Data Extractors
Overview
Basic Syntax
Available Extractors
JSONPath (jpath)
XPath (xpath)
Regex (regex)
Boundary (boundary)
Header (header)
Cookie (cookie)
JWT (jwt)
Extractor Summary
Using Extracted Variables
Variable Naming
Accessing Variables
Creating Custom Extractors
Best Practices
Troubleshooting
See Also
Template Engine
Overview
Basic Syntax
Variables
Variable Sources
Built-in Filters
TOTP (totp)
MD5 (md5)
SHA1 (sha1)
SHA256 (sha256)
Environment Variables (env)
CLI Arguments (argv)
Average (average)
Control Structures
Conditionals
Loops
Filters
Request Templates
HTTP Request Format
Dynamic Headers
Dynamic Body
Logger Templates
State Logging
Thread Logging
Analysis Logging
Special Variables
Thread Context
Config Access
State Results
Best Practices
Security
Readability
Performance
Troubleshooting
See Also
When Blocks
Overview
Basic Syntax
Condition Types
Status Code Matching
Jinja2 Expressions
Body Content Matching
Header Checks
Response Time Analysis
Combining Conditions
Complex Examples
Role-Based Routing
Error Detection
Race Condition Detection
Performance-Based Routing
Best Practices
Common Patterns
Authentication Flow
API Error Handling
See Also
Synchronization Mechanisms
Overview
Barrier (Recommended)
How It Works
Timing Characteristics
Visual Representation
Use Cases
Performance Tips
Countdown Latch
How It Works
Timing Characteristics
Visual Representation
Use Cases
Comparison with Barrier
Semaphore
How It Works
Timing Characteristics
Visual Representation
Use Cases
When to Use Semaphore
Comparison Table
Choosing the Right Mechanism
Decision Tree
Quick Reference
Performance Optimization
Achieving Sub-Microsecond Timing
Thread Count Guidelines
Common Issues
Issue: Race Window Too Large
Issue: Inconsistent Results
Issue: Connection Failures
Examples
Example 1: Optimal Race Configuration
Example 2: Rate Limiting Test
Example 3: Multi-Stage Coordinated Attack
Best Practices
General Guidelines
Configuration Checklist
Monitoring and Tuning
See Also
Connection Strategies
Overview
Preconnect Strategy (Recommended)
How It Works
Performance Characteristics
Visual Representation
Advantages
Disadvantages
Use Cases
Configuration Tips
Lazy Strategy
How It Works
Performance Characteristics
Visual Representation
Advantages
Disadvantages
Use Cases
When to Use
Pooled Strategy
How It Works
Performance Characteristics
Visual Representation
Advantages
Disadvantages
Use Cases
When to Use
Multiplexed Strategy
How It Works
Performance Characteristics
Visual Representation
Advantages
Disadvantages
Use Cases
When to Use
Comparison Table
Choosing the Right Strategy
Decision Tree
Quick Reference
Performance Optimization
Achieving Optimal Timing
Troubleshooting Connection Issues
Examples
Example 1: Optimal Configuration
Example 2: HTTP/2 Testing
Example 3: Connection Reuse
Best Practices
General Guidelines
Configuration Checklist
Common Mistakes to Avoid
See Also
Advanced Features
mTLS (Mutual TLS) Support
Why mTLS?
Configuration
Template Support
Example
Proxy Support
Configuration
Use Cases
Example with Burp Suite
Proxy Bypass Per-State
HTTP/2 Support
Configuration
Benefits
Limitations
Example
Connection Reuse
Configuration
Strategies
When to Disable Reuse
Example
Redirect Handling
Configuration
Use Cases
Example
When Blocks
Basic Syntax
Supported Conditions
Boolean Operators
Example
Timeout Configuration
Global Timeout
Per-State Timeout
Race Timeout
Connection Timeout
Best Practices
Example
Schema Validation
IDE Integration
Pre-commit Hook
Command Line
Benefits
See Also
Attack Examples
Double-Spending Attack
Coupon Redemption Race
Inventory Race Attack
Authentication Rate Limit Bypass
2FA TOTP Verification
CSRF Token Extraction and Form Submission
Running the Examples
See Also
Reference
Command-Line Interface
Basic Usage
Options
Authentication Options
Target Options
Execution Options
Output Options
Information Options
Using uv
Environment Variables
Complete Examples
Basic Attack
With Authentication
With 2FA
Custom Target
High Thread Count
Full Example with All Options
Exit Codes
Output Format
Tips and Best Practices
Security
Debugging
Performance
See Also
Python API Reference
Quick Start
Core Classes
RaceCoordinator
Configuration Models
Config
ServerConfig
State
RaceConfig
Template Engine
TemplateEngine
Extractors
BaseExtractor
Available Extractors
Creating Custom Extractors
Synchronization
SyncMechanism
Connection Strategies
ConnectionStrategy
HTTP Client
HTTPClient
HTTPParser
State Machine
StateMachine
ExecutionContext
Complete Example
See Also
Troubleshooting
Quick Diagnostic Checklist
Installation Issues
Issue: “treco: command not found”
Issue: Wrong Python Version
Issue: Dependency Installation Fails
Configuration Issues
Issue: YAML Syntax Error
Issue: Template Rendering Error
Issue: Invalid Configuration Value
Connection Issues
Issue: Connection Timeout
Issue: SSL Certificate Error
Issue: Too Many Open Files
Issue: Connection Refused
Proxy Issues
Issue: Proxy Authentication Failed
Issue: Proxy Connection Failed
Issue: Slow Performance with Proxy
Race Condition Issues
Issue: Poor Race Window (> 100ms)
Issue: No Successful Race Attacks
Issue: Inconsistent Results
Extractor Issues
Issue: Extractor Returns Nothing
Issue: JSONPath Pattern Not Working
Issue: Regex Pattern Not Matching
Issue: XPath Pattern Not Working
Performance Issues
Issue: Slow Execution
Issue: High Memory Usage
Logging Issues
Issue: No Log Output
Issue: Template Syntax Error in Logger
Template Issues
Issue: TOTP Code Always Invalid
Issue: Environment Variable Not Found
Common Error Messages
“Rate limit exceeded”
“Authentication failed”
“Invalid JSON”
Getting More Help
Debug Mode
Check Logs
Test Connectivity
Minimal Reproduction
Report Issue
See Also
Best Practices
Performance Optimization
Achieving Optimal Race Windows
Thread Count Optimization
Connection Management
Security Best Practices
Authorization and Scope
Credential Management
SSL/TLS Configuration
Data Handling
Responsible Testing
Configuration Best Practices
File Organization
Naming Conventions
Documentation in Configuration
Version Control
Testing Best Practices
Progressive Testing Approach
Test Multiple Scenarios
Reproducibility
Logging and Monitoring
Effective Logging
Monitoring Race Quality
Reporting and Documentation
Vulnerability Reports
Test Documentation
Code Quality
Configuration Validation
Reusable Components
Continuous Improvement
Regular Reviews
Learning from Results
See Also
Additional Resources
Configuration Reference
YAML Structure Overview
Metadata Section
Config Section
Basic Configuration
TLS/SSL Configuration
HTTP Configuration
Proxy Configuration
Complete Config Example
Entrypoint Section
States Section
Basic State
Race Configuration
Synchronization Mechanisms
Connection Strategies
Thread Propagation
Data Extraction
Logger Configuration
Transitions
Complete Example
Best Practices
Configuration Tips
Security Tips
Performance Tips
Troubleshooting
See Also
License
MIT License
What This Means
You Can
You Must
You Cannot
Important Notes
Legal Use Requirements
Authorization Required
Warranty Disclaimer
No Warranty Means
Third-Party Dependencies
Dependencies and Their Licenses
Contributing
Commercial Use
You Can
Requirements
Example Attribution
Patent Rights
Trademark
Acceptable Use
Not Acceptable
License History
Questions About License
Common Questions
Getting Legal Advice
Full License Text
External Resources
Learn More About MIT License
Open Source Initiative
See Also
TRECO
Index
Index