Checkpoint/README.md

Checkpoint Security Gateway

High-performance, TypeScript-based security gateway with advanced threat detection, behavioral analysis, and adaptive protection.

Features:

• 🔐 Checkpoint Security: Proof-of-work (PoW) and proof-of-space-time (PoST) challenges for suspicious traffic
• 🛡️ Web Application Firewall: Advanced pattern matching against SQL injection, XSS, command injection, and more
• 🌎 IP & Geo-Filtering: Block or allow traffic based on country, continent, or ASN using MaxMind GeoIP2
• 🔀 Reverse Proxy: High-performance request forwarding with WebSocket support
• 🧠 Behavioral Detection: ML-inspired pattern recognition with adaptive scoring
• 📊 Threat Scoring: Real-time risk assessment with configurable thresholds
• 🤖 Bot Verification: Identifies and handles good bots vs malicious automation
• 🧩 Plugin Architecture: Modular design for easy extension and customization
• 📂 Data Persistence: Secure token storage with LevelDB + TTL and HMAC protection

🚀 Quick Start

1. Clone the repository

   git clone https://git.caileb.com/Caileb/Checkpoint.git
   cd Checkpoint
   

2. Install dependencies

   npm install
   

3. Set up configuration files

   cp config/*.toml.example config/*.toml
   

4. Configure your settings

   • Edit TOML files in config/ directory
   • Set proxy mappings in proxy.toml
   • Configure security rules in waf.toml
   • Adjust thresholds in threat-scoring.toml

5. Development mode

   npm run dev
   

6. Production mode

   npm start
   

7. Daemonize with PM2

   npm run daemon     # Start in background
   npm run stop       # Stop daemon
   npm run restart    # Restart daemon
   npm run logs       # View logs
   

⚙️ Configuration

All settings are stored in TOML files within the config/ directory:

• checkpoint.toml — Proof-of-work parameters, token storage, exclusion rules
• waf.toml — Web Application Firewall rules, scoring, and bot verification
• behavioral-detection.toml — Pattern detection rules and correlations
• proxy.toml — Hostname-to-backend mappings, timeouts, and body size limits
• ipfilter.toml — Geographic and network filtering with MaxMind integration
• threat-scoring.toml — Advanced scoring thresholds and feature weights

Environment Variables

• PORT — Server port (default: 3000)
• NODE_ENV — Environment mode (production/development)
• MAXMIND_ACCOUNT_ID — MaxMind account ID for GeoIP databases
• MAXMIND_LICENSE_KEY — MaxMind license key
• MAX_BODY_SIZE — Request body size limit (default: 10mb)
• MAX_BODY_SIZE_MB — WAF body size limit in MB (default: 10)

📂 Project Structure

.
├── config/                # TOML configuration files
├── data/                  # Runtime data (secrets, downloads)
├── db/                    # LevelDB token stores
├── pages/                 # Static assets and UI templates
│   ├── interstitial/      # Proof-of-work challenge pages
│   ├── ipfilter/          # Custom geo-block pages
│   └── dashboard/         # Admin dashboard (if enabled)
├── src/                   # TypeScript source code
│   ├── plugins/           # Plugin modules
│   │   ├── ipfilter.ts    # Geographic filtering
│   │   └── waf.ts         # Web Application Firewall
│   ├── utils/             # Utility modules
│   │   ├── behavioral-detection.ts
│   │   ├── behavioral-middleware.ts
│   │   ├── bot-verification.ts
│   │   ├── cache-utils.ts
│   │   ├── logs.ts
│   │   ├── network.ts
│   │   ├── performance.ts
│   │   ├── plugins.ts
│   │   ├── proof.ts
│   │   ├── threat-scoring/
│   │   └── time.ts
│   ├── checkpoint.ts      # Checkpoint security middleware
│   ├── index.ts           # Main application entry
│   └── proxy.ts           # Reverse proxy implementation
├── dist/                  # Compiled JavaScript (generated)
├── .tests/                # Test files
├── docker-compose-synology.yml
├── Dockerfile
├── jest.config.cjs
├── package.json
├── tsconfig.json
└── README.md

🏗️ Architecture

The gateway processes requests through a layered security pipeline:

1. Pre-filtering — Request exclusion rules
2. IP Filter — Geographic and ASN-based blocking
3. WAF — Pattern matching and attack detection
4. Behavioral Detection — Cross-request pattern analysis
5. Threat Scoring — Aggregate risk assessment
6. Checkpoint — Challenge suspicious requests
7. Proxy — Forward legitimate traffic to backends

🔒 Security Features

Web Application Firewall

• SQL injection detection with evasion handling
• XSS prevention across multiple vectors
• Command injection blocking
• Path traversal protection
• XXE and SSRF prevention
• Bot detection and verification

Behavioral Analysis

• Request pattern tracking
• Rate limit enforcement
• Geo-velocity detection
• User agent consistency checks
• Automated attack pattern recognition

Threat Scoring Engine

• Real-time risk calculation
• Adaptive thresholds
• Feature extraction from multiple sources
• Configurable scoring weights
• Automatic severity classification

📊 Default Security Thresholds

Critical Threats (Immediate Block):

• javascript: URLs — Score: 100+
• <script> tags — Score: 80+
• Command injection — Score: 90+
• SQL injection — Score: 70+

Action Thresholds:

• Allow: 0-15 (normal traffic)
• Challenge: 16-80 (suspicious)
• Block: 80+ (malicious)

🚢 Deployment

Docker

docker build -t Checkpoint .
docker run -d -p 3000:3000 -v $(pwd)/config:/app/config Checkpoint

Docker Compose (Synology)

docker-compose -f docker-compose-synology.yml up -d

PM2 Process Manager

npm run daemon       # Start with PM2
pm2 save            # Save process list
pm2 startup         # Generate startup script

🧪 Testing

npm test            # Run all tests
npm run test:watch  # Watch mode
npm run test:coverage # Coverage report

📈 Performance

• Handles 10,000+ requests/second
• Sub-millisecond security decisions
• Efficient caching and connection pooling
• WebSocket support with proper cleanup