Massive v2 rewrite
This commit is contained in:
parent
1025f3b523
commit
5f1328f626
77 changed files with 28105 additions and 3542 deletions
204
README.md
204
README.md
|
|
@ -1,17 +1,18 @@
|
|||
# Checkpoint
|
||||
# Checkpoint Security Gateway
|
||||
|
||||
> Secure, extensible, high-performance Node.js middleware server for proof-of-work security, IP filtering, reverse proxying, and real-time analytics.
|
||||
> High-performance, TypeScript-based security gateway with advanced threat detection, behavioral analysis, and adaptive protection.
|
||||
|
||||
**Features:**
|
||||
|
||||
- 🔐 **Checkpoint Security:** Enforce proof-of-work (PoW) and proof-of-space-time (PoST) challenges before granting access.
|
||||
- 🌎 **IP & Geo-Blocking:** Block or allow traffic based on country, continent, or ASN using MaxMind GeoIP2.
|
||||
- 🔀 **Reverse Proxy:** Route incoming requests to backend services based on hostname mappings.
|
||||
- 📊 **Real-time Stats:** Collect detailed metrics and browse via built-in web UI or API.
|
||||
- 🧩 **Plugin Architecture:** Easily extend and customize via modular plugins.
|
||||
- 🛠️ **Flexible Configuration:** Manage settings in TOML files and via environment variables.
|
||||
- ⚙️ **Daemon & PM2 Support:** Run as a background service with built-in daemon mode or PM2.
|
||||
- 📂 **Data Persistence:** Secure token storage with LevelDB + TTL and HMAC protection.
|
||||
- 🔐 **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
|
||||
|
||||
|
|
@ -20,63 +21,184 @@
|
|||
git clone https://git.caileb.com/Caileb/Checkpoint.git
|
||||
cd Checkpoint
|
||||
```
|
||||
|
||||
2. **Install dependencies**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
3. **Set up environment variables** (optional)
|
||||
Create a `.env` file in the project root:
|
||||
```ini
|
||||
MAXMIND_ACCOUNT_ID=your_account_id
|
||||
MAXMIND_LICENSE_KEY=your_license_key
|
||||
PORT=8080 # Default: 3000
|
||||
|
||||
3. **Set up configuration files**
|
||||
```bash
|
||||
cp config/*.toml.example config/*.toml
|
||||
```
|
||||
4. **Development mode**
|
||||
|
||||
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
|
||||
```
|
||||
5. **Start the server**
|
||||
|
||||
6. **Production mode**
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
6. **Daemonize**
|
||||
|
||||
7. **Daemonize with PM2**
|
||||
```bash
|
||||
npm run daemon # Start in background
|
||||
npm run stop # Stop daemon
|
||||
npm run restart # Restart daemon
|
||||
npm run logs # Show logs
|
||||
```
|
||||
Or use PM2 directly:
|
||||
```bash
|
||||
pm2 start index.js --name checkpoint
|
||||
npm run logs # View logs
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
All core settings are stored in the `config/` directory as TOML files:
|
||||
All settings are stored in TOML files within the `config/` directory:
|
||||
|
||||
- `checkpoint.toml` — PoW/PoST parameters, tokens, exclusions, interstitial templates.
|
||||
- `ipfilter.toml` — Country, continent, ASN filtering rules and custom block pages.
|
||||
- `proxy.toml` — Hostname-to-backend mappings and timeouts.
|
||||
- `stats.toml` — Metrics TTL and paths for UI/API.
|
||||
- `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
|
||||
|
||||
Override any setting via environment variables or by editing these files directly.
|
||||
### Environment Variables
|
||||
|
||||
## 📂 Directory Structure
|
||||
- `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, snapshots)
|
||||
├── data/ # Runtime data (secrets, downloads)
|
||||
├── db/ # LevelDB token stores
|
||||
├── plugins/ # Plugin modules (checkpoint, ipfilter, proxy, stats)
|
||||
├── pages/ # Static assets and UI templates
|
||||
│ ├── interstitial/ # Proof-of-work challenge pages
|
||||
│ ├── ipfilter/ # Custom block pages
|
||||
│ └── stats/ # Statistics web UI
|
||||
├── utils/ # Internal utilities (logging, network, proof, time)
|
||||
├── index.js # Core server & plugin loader
|
||||
├── checkpoint.js # Checkpoint security middleware
|
||||
├── package.json # Project metadata & scripts
|
||||
└── README.md # This file
|
||||
```
|
||||
│ ├── 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue