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**
   ```bash
   git clone https://git.caileb.com/Caileb/Checkpoint.git
   cd Checkpoint
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Set up configuration files**
   ```bash
   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**
   ```bash
   npm run dev
   ```

6. **Production mode**
   ```bash
   npm start
   ```

7. **Daemonize with PM2**
   ```bash
   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

```plaintext
.
├── 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

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

### Docker Compose (Synology)

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

### PM2 Process Manager

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

## 🧪 Testing

```bash
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