treco-framework 1.10.0

Tactical Race Exploitation & Concurrency Orchestrator

TRECO

Tactical Race Exploitation & Concurrency Orchestrator

A specialized framework for identifying and exploiting race condition vulnerabilities in HTTP APIs with sub-microsecond precision.

Documentation | PyPI Package | Quick Start | Examples

---

🎯 Overview

TRECO enables security researchers to orchestrate highly precise concurrent HTTP attacks with sub-microsecond timing accuracy, making it possible to reliably trigger race conditions in web applications. Built for both Python 3.10+ (with GIL) and Python 3.14t (GIL-free), TRECO achieves unprecedented timing precision for race condition exploitation.

Common Vulnerabilities Tested

• 💰 Double-spending attacks - Payment processing vulnerabilities
• 🎁 Fund redemption exploits - Gift cards and coupon abuse
• 📦 Inventory manipulation - Limited stock bypasses
• 🔐 Privilege escalation - Authentication/authorization flaws
• ⚡ Rate limiting bypasses - API quota exhaustion
• 🎟️ Voucher abuse - Single-use code reuse
• 🏦 TOCTOU vulnerabilities - Time-of-Check to Time-of-Use exploits

---

✨ Key Features

• ⚡ Sub-Microsecond Precision: Race windows < 1μs with barrier synchronization
• 🔓 GIL-Free Option: Python 3.14t for true parallel execution
• 🧵 Thread Groups: Define multiple request patterns with distinct thread counts and delays
• 🔄 Flexible Synchronization: Barrier, countdown latch, and semaphore mechanisms
• 🌐 Full HTTP/HTTPS Support: HTTP/1.1 and HTTP/2 with TLS/SSL
• 🎨 Powerful Templates: Jinja2-based with TOTP, hashing, env vars, and more
• 🎯 Dynamic Input Sources: Brute-force, enumeration, and combination attacks
• 📊 Automatic Analysis: Race window calculation and vulnerability detection
• 🔌 Extensible Architecture: Plugin-based extractors and connection strategies
• ✅ JSON Schema Validation: IDE integration and real-time validation

---

📦 Quick Start

Installation

# Install from PyPI
pip install treco-framework

# Or with uv (faster)
uv pip install treco-framework

# Verify installation
treco --version

Your First Test

Create a file test.yaml:

metadata:
  name: "Race Condition Test"
  version: "1.0"
  author: "Security Researcher"
  vulnerability: "CWE-362"

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

entrypoint:
  state: race_attack
  input:
    voucher_code: "DISCOUNT50"

states:
  race_attack:
    description: "Test voucher race condition"
    race:
      threads: 20
      sync_mechanism: barrier
      connection_strategy: preconnect
    
    request: |
      POST /api/vouchers/redeem HTTP/1.1
      Host: {{ target.host }}
      Content-Type: application/json
      
      {"code": "{{ voucher_code }}"}
    
    next:
      - on_status: 200
        goto: end
  
  end:
    description: "Attack completed"

Run the test:

treco test.yaml

---

📖 Documentation

For detailed documentation, please visit treco.readthedocs.io:

• Installation Guide - Complete installation instructions for all platforms
• Quick Start Tutorial - Your first race condition test in 5 minutes
• Configuration Reference - Complete YAML configuration guide
• Thread Groups - Define multiple request patterns with distinct thread counts ✨ NEW
• Synchronization Mechanisms - Barrier, latch, and semaphore patterns
• Connection Strategies - Preconnect, pooled, lazy, and multiplexed
• Data Extractors - JSONPath, XPath, Regex, and more
• Template Engine - Jinja2 syntax and custom filters
• Examples - Real-world attack scenarios
• CLI Reference - Command-line options
• API Documentation - Python API for programmatic use
• Troubleshooting - Common issues and solutions
• Best Practices - Performance optimization and security

---

💡 Examples

Check out the examples/ directory for real-world attack scenarios:

• Thread Groups Demo - Simple demonstration of thread groups feature ✨ NEW
• PortSwigger Labs - Solutions for Web Security Academy challenges
• Racing Bank - Fund redemption attack demonstration
• Input Sources - Brute-force and enumeration examples
• JWT Analysis - JWT vulnerability testing
• Rate Limit Detection - API rate limiting bypass
• Error Detection - Error-based race conditions

---

🚀 Why Python 3.14t?

Python 3.14t removes the Global Interpreter Lock (GIL) for true parallelism:

Feature	Python 3.10-3.13 (GIL)	Python 3.14t (GIL-Free)
True Parallelism	❌ Single thread at a time	✅ Multiple threads simultaneously
Race Window	~10-100μs	< 1μs (sub-microsecond)
CPU Utilization	Limited by GIL	Full multi-core usage
Consistency	Variable timing	Highly consistent
Best for TRECO	Good	Excellent

Note: TRECO works with both Python 3.10+ and 3.14t, but achieves optimal performance with 3.14t's free-threaded build.

Install Python 3.14t:

uv python install 3.14t
uv pip install treco-framework --python 3.14t

---

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

💖 Support the Project

If you find TRECO useful, please consider supporting its development:

Your support helps maintain and improve TRECO for the security research community.

---

📄 License

TRECO is released under the MIT License. See LICENSE for details.

Responsible Use

⚠️ AUTHORIZED TESTING ONLY ⚠️

TRECO is designed for authorized security testing. You must:

• ✅ Obtain written authorization before testing
• ✅ Test only within agreed scope and boundaries
• ✅ Comply with all applicable laws and regulations
• ✅ Report vulnerabilities responsibly

Unauthorized testing may result in criminal prosecution and civil liability.

Users are solely responsible for ensuring their use complies with applicable laws, regulations, and agreements.

---

🙏 Acknowledgments

• TREM - The project that inspired TRECO
• Python Community - For Python 3.14t free-threaded build
• httpx, Jinja2, PyYAML, PyOTP - Essential libraries
• Security Community - Researchers and contributors who make this possible

---

📞 Support

• 📖 Documentation: treco.readthedocs.io
• 💬 GitHub Discussions: github.com/maycon/TRECO/discussions
• 🐛 GitHub Issues: github.com/maycon/TRECO/issues

---

⚠️ USE RESPONSIBLY - AUTHORIZED TESTING ONLY ⚠️

Made with ❤️ by security researchers, for security researchers

⭐ Star on GitHub | 📖 Documentation | 🐛 Report Bug | 💡 Request Feature