CS StatSentry 🛡️

CS2 Anti-Cheat Detection System - Automated teammate analysis for suspicious player identification.

📑 Inhaltsverzeichnis

• ✨ Features
• 🏗️ Architecture
• 🚀 Quick Start
• 🔧 Tech Stack
• 📊 Detection System
• 📁 Project Structure
• ⚙️ Configuration
• 🧪 Development
• 🤝 Contributing
• 📄 License
• ⚠️ Disclaimer
• 📖 Documentation
• 🆘 Support

✨ Features

• 🔐 Steam OAuth Authentication - Secure login via Steam OpenID
• 🎯 Automated Match Analysis - Continuous monitoring of CS2 teammates
• 🚨 Suspicious Player Detection - Advanced scoring algorithm with multiple detection criteria
• 📊 Real-time Dashboard - Live updates and comprehensive analytics
• ⚡ Background Processing - Celery-powered asynchronous job system
• 🔄 Auto-Sync - Periodic match synchronization every 30 minutes
• 🎮 Demo Download Service - Integrated CS2 demo file download service via Steam GC

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React SPA     │    │   FastAPI       │    │  PostgreSQL     │
│   (Frontend)    │◄──►│   (Backend)     │◄──►│  (Database)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                     │                        │
         │              ┌─────────────────┐    ┌───────┴─────────┐
         │              │     Celery      │◄──►│     Redis       │
         │              │ (Background)    │    │   (Cache)       │
         │              └─────────────────┘    └─────────────────┘
         │                                             │
         └─────────────►┌─────────────────┐◄──────────┘
                        │  Demo Service   │
                        │   (Node.js)     │
                        └─────────────────┘

🚀 Quick Start

Development Setup

# Clone repository
git clone https://github.com/meinjens/cstatsentry.git
cd cstatsentry

# Start with Docker Compose
docker-compose up -d

# Or use the setup script
./scripts/start.sh

Access Points:

• Frontend: http://localhost:3000
• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Demo Service API: http://localhost:3001

Demo Service Setup

The demo service requires Steam credentials to download CS2 demo files:

# Add to your .env file
DEMO_SERVICE_STEAM_USERNAME=your_steam_username
DEMO_SERVICE_STEAM_PASSWORD=your_steam_password

# Initialize demo service database
./scripts/init-demo-db.sh

🔧 Tech Stack

Component	Technology	Purpose
Frontend	React 18 + TypeScript + Tailwind CSS + pnpm	Modern, responsive UI
Backend	FastAPI + SQLAlchemy + PostgreSQL	High-performance API
Demo Service	Node.js + Express + Prisma + Bull	CS2 demo downloads
Jobs	Celery + Redis	Background processing
Auth	Steam OpenID + JWT	Secure authentication
CI/CD	GitHub Actions	Automated testing & deployment

📊 Detection System

StatSentry uses a sophisticated scoring algorithm to identify suspicious players:

Detection Criteria

• 🆕 New Account Analysis - Recent account creation with high performance
• 🔒 Private Profile Flags - Private profiles with suspicious stats
• ⚠️ VAC History - Previous VAC bans in other games
• 🎮 Playtime Anomalies - CS2-only accounts with limited game libraries
• 📈 Performance Spikes - Sudden improvement in gameplay metrics
• 🎯 Statistical Analysis - Unnatural consistency patterns

Scoring System

• 0-30: Unlikely to cheat
• 31-60: Suspicious patterns detected
• 61-80: Highly suspicious behavior
• 81-100: Almost certainly cheating

📁 Project Structure

cstatsentry/
├── 🔙 backend/              # FastAPI backend
│   ├── app/
│   │   ├── api/             # REST API endpoints
│   │   ├── core/            # Configuration & security
│   │   ├── models/          # SQLAlchemy models
│   │   ├── schemas/         # Pydantic schemas
│   │   ├── services/        # Business logic
│   │   └── tasks/           # Celery background tasks
│   ├── alembic/             # Database migrations
│   └── tests/               # Backend tests
├── 🎨 frontend/             # React frontend
│   └── src/
│       ├── components/      # Reusable UI components
│       ├── pages/           # Application pages
│       ├── services/        # API integration
│       └── types/           # TypeScript definitions
├── 🎮 demo-service/         # CS2 Demo Download Service
│   ├── src/
│   │   ├── steam/           # Steam GC integration
│   │   ├── queue/           # Bull download queue
│   │   ├── services/        # Demo & webhook services
│   │   └── routes/          # Express API routes
│   └── prisma/              # Database schema
├── 📚 docs/                 # Documentation
├── 🛠️ scripts/              # Utility scripts
├── 🐳 .github/              # GitHub Actions workflows
└── 📋 docker-compose*.yml   # Docker configurations

⚙️ Configuration

Required Environment Variables

# Steam API (get from https://steamcommunity.com/dev/apikey)
STEAM_API_KEY=your_steam_api_key_here

# Security
SECRET_KEY=your_super_secure_jwt_secret_key

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/statsentry

# Optional: Leetify API Integration
LEETIFY_API_KEY=your_leetify_api_key_here

See SETUP.md for complete configuration guide.

🧪 Development

Running Tests

# Backend tests
cd backend && pytest

# Frontend tests
cd frontend && pnpm test

# Integration tests
docker-compose -f docker-compose.test.yml up --abort-on-container-exit

API Documentation

Interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

StatSentry is designed for educational and analytical purposes. It only accesses publicly available Steam profile data and does not interact with CS2 game files or memory. Always follow Steam's Terms of Service and use responsibly.

📖 Documentation

• 🏗️ Architecture Guide - Detailed system architecture and design patterns
• ✅ Features & TODO List - Complete feature overview and roadmap
• 🧪 TDD Guide - Test-driven development workflow
• 🔗 Integration Testing - Testing with mock services
• ⚙️ Setup Guide - Detailed configuration instructions
• 🔌 API Documentation - REST API reference

🎯 Related Projects

• Replay Hunter - CS2 Demo Download Service (formerly part of this project)

🆘 Support

• 🐛 Report Issues
• 💬 Discussions

---

Made with ❤️ for the CS2 community