K9Shield

K9Shield is a comprehensive security middleware for Node.js applications, providing robust protection against various web security threats. It offers advanced features like DDoS protection, rate limiting, IP management, and security headers management.

Updates

Data Protection Enhancements (January 2025)

• Added advanced data loss prevention module
• Implemented sensitive data detection and masking
• Integrated k9crypt for secure data encryption
• Added custom pattern support for sensitive data
• Enhanced data protection with regex-based detection
• Implemented async encryption and decryption methods
• Added comprehensive data masking techniques for various sensitive information types

Usage Example

1const shield = new K9Shield();
2
3// Optional: Scan for sensitive data
4const sensitiveDataResult = shield.scanForSensitiveData('Credit Card: 4111-1111-1111-1111');
5console.log(sensitiveDataResult);
6// Output: { hasSensitiveData: true, detectedData: { creditCard: ['4111-1111-1111-1111'] } }
7
8// Optional: Mask sensitive data
9const maskedData = shield.maskSensitiveData('Email: john.doe@example.com');
10console.log(maskedData);
11// Output: 'Email: jo****@example.com'
12
13// Optional: Encrypt sensitive data
14const encryptedData = await shield.encryptSensitiveData('Secret Information');
15const decryptedData = await shield.decryptSensitiveData(encryptedData);
16
17// Optional: Add custom sensitive pattern
18shield.addCustomSensitivePattern('customId', /\bCUST-\d{6}\b/);

Module Status

• Completely Optional: The data loss prevention module is not mandatory
• Can be Disabled: No impact on core security features
• Modular Design: Use only the features you need
• Performance Overhead: Minimal additional processing
• Recommended for: Applications handling sensitive personal or financial data

Note: While optional, this module provides an additional layer of data protection for applications requiring advanced data handling.

Table of Contents

• Features
• Installation
• Quick Start
• Core Components
• Configuration
• Security Features
• API Reference
• Testing
• Examples
• Contributing
• License

Features

Core Security Features

• DDoS Protection

  • Progressive penalty system
  • Connection tracking
  • Burst detection
  • Path-based rate limiting
  • Configurable thresholds and block durations

• Rate Limiting

  • Route-specific limits
  • Flexible time windows
  • Throttling support
  • Ban duration management
  • Distributed system support

• IP Management

  • CIDR notation support
  • IPv6 support with IPv4 mapping
  • Private IP detection
  • Whitelist/Blacklist functionality
  • Proxy support

• Request Validation

  • Method validation
  • Payload size limits
  • Header validation
  • Pattern detection (SQL Injection, XSS, Path Traversal)
  • User Agent and Referer filtering

Advanced Security

• Security Headers

  • Content Security Policy (CSP)
  • Permissions Policy
  • HSTS support
  • XSS protection
  • Frame options
  • Content type options

• Pattern Detection

  • SQL Injection patterns
  • XSS patterns
  • Path traversal attempts
  • Custom pattern support
  • Regular expression based detection

Monitoring & Logging

• Logging System

  • Multiple log levels
  • Automatic rotation
  • Archive management
  • Performance metrics
  • Security event tracking

• Request Tracking

  • IP tracking
  • Request duration
  • Path monitoring
  • Error logging
  • Detailed request information

Installation

1npm install k9shield

Quick Start

Basic Express Integration

1const express = require('express');
2const K9Shield = require('k9shield');
3
4const app = express();
5const shield = new K9Shield();
6
7// Protect all routes
8app.use(shield.protect());
9
10app.get('/', (req, res) => {
11    res.json({ message: 'A secure endpoint' });
12});
13
14app.listen(3000, () => {
15    console.log('Server running securely');
16});

Detailed Security Configuration

1const shield = new K9Shield({
2    rateLimiting: {
3        enabled: true,
4        default: {
5            maxRequests: 10,     // 10 requests per minute
6            timeWindow: 60000,   // 1 minute
7            banDuration: 300000  // 5 minutes ban
8        },
9        routes: {
10            '/api/sensitive-endpoint': {
11                'POST': { 
12                    maxRequests: 3,      // Stricter control for sensitive endpoint
13                    timeWindow: 60000,   // 1 minute
14                    banDuration: 600000  // 10 minutes ban
15                }
16            }
17        }
18    },
19    security: {
20        maxBodySize: 1024 * 100,  // 100KB payload limit
21        allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
22        userAgentBlacklist: ['bad-bot', 'malicious-crawler']
23    },
24    ddosProtection: {
25        enabled: true,
26        config: {
27            maxConnections: 50,
28            blockDuration: 300,
29            requestThreshold: 30,
30            rateLimitByPath: {
31                '/api/*': 20,    // Special limit for API routes
32                '*': 50           // General limit for all routes
33            }
34        }
35    }
36});

IP Management Examples

1// Block a specific IP
2shield.blockIP('192.168.1.100');
3
4// Whitelist an IP
5shield.whitelistIP('10.0.0.1');
6
7// Unblock a previously blocked IP
8shield.unblockIP('192.168.1.100');
9
10// Remove an IP from whitelist
11shield.unwhitelistIP('10.0.0.1');

Adding Custom Security Patterns

1// Custom patterns for SQL Injection and XSS
2shield.addSuspiciousPattern(/SELECT.*FROM/i);
3shield.addSuspiciousPattern(/<script>|javascript:/i);

Advanced Error Handling

1const shield = new K9Shield({
2    errorHandling: {
3        includeErrorDetails: true,
4        customHandlers: {
5            // Custom response for rate limit exceeded
6            'rateLimitExceeded': (res, data) => {
7                res.status(429).json({
8                    message: 'Too many requests',
9                    retryAfter: data.retryAfter,
10                    limit: data.limit
11                });
12            },
13            // Custom response for DDoS attack
14            'ddosAttack': (res) => {
15                res.status(403).json({
16                    message: 'Suspicious traffic detected',
17                    action: 'Access denied'
18                });
19            }
20        }
21    }
22});

Logging and Monitoring

1// Get all log records
2const logs = shield.getLogs();
3
4// Get archived log records
5const archivedLogs = shield.getArchivedLogs();
6
7// Reset all settings and statistics
8shield.reset();

Test Environment Configuration

1// More flexible settings for development environment
2process.env.NODE_ENV = 'development';
3
4const shield = new K9Shield({
5    rateLimiting: { enabled: false },  // Rate limit disabled in development
6    ddosProtection: { enabled: false } // DDoS protection disabled
7});

Production Environment Configuration

1// Strict security settings for production
2process.env.NODE_ENV = 'production';
3
4const shield = new K9Shield({
5    rateLimiting: {
6        enabled: true,
7        default: { maxRequests: 100, timeWindow: 60000 }
8    },
9    security: {
10        maxBodySize: 1024 * 1024,  // 1MB
11        allowPrivateIPs: false
12    },
13    ddosProtection: {
14        enabled: true,
15        config: {
16            maxConnections: 200,
17            blockDuration: 1800000  // 30 minutes block
18        }
19    },
20    logging: {
21        level: 'warning',  // Log only critical warnings
22        maxLogSize: 10000  // More log storage
23    }
24});

Core Components

1. K9Shield Class (src/k9shield.js)

The main class that orchestrates all security features:

1const shield = new K9Shield({
2    security: {
3        trustProxy: true,
4        allowPrivateIPs: false,
5        maxBodySize: 1024 * 1024 // 1MB
6    }
7});

2. IP Utils (src/utils/ip.js)

Handles IP address management and validation:

1// IP management examples
2shield.blockIP('192.168.1.100');
3shield.whitelistIP('10.0.0.1');
4shield.unblockIP('192.168.1.100');
5shield.unwhitelistIP('10.0.0.1');

3. Security Module (src/core/security.js)

Manages security patterns and request validation:

1// Add custom security patterns
2shield.addSuspiciousPattern(/eval\(/i);
3shield.addSuspiciousPattern(/(document|window)\./i);

4. Rate Limiter (src/core/rateLimiter.js)

Controls request rates and implements throttling:

1const config = {
2    rateLimiting: {
3        enabled: true,
4        default: {
5            maxRequests: 100,
6            timeWindow: 60000, // 1 minute
7            banDuration: 3600000 // 1 hour
8        },
9        routes: {
10            '/api/data': {
11                'POST': { maxRequests: 5, timeWindow: 30000 }
12            }
13        }
14    }
15};

5. DDoS Protection (src/core/ddos.js)

Provides DDoS attack prevention:

1const config = {
2    ddosProtection: {
3        enabled: true,
4        config: {
5            maxConnections: 200,
6            timeWindow: 60000,
7            blockDuration: 1800000,
8            requestThreshold: 500,
9            burstThreshold: 50
10        }
11    }
12};

Configuration

Complete Configuration Example

1const shield = new K9Shield({
2    security: {
3        trustProxy: true,
4        allowPrivateIPs: false,
5        maxBodySize: 1024 * 1024,
6        allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
7        userAgentBlacklist: ['bad-bot', 'malicious-crawler'],
8        refererBlacklist: ['malicious.com'],
9        securityHeaders: {
10            'X-Content-Type-Options': 'nosniff',
11            'X-Frame-Options': 'DENY',
12            'X-XSS-Protection': '1; mode=block',
13            'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'
14        },
15        csp: {
16            'default-src': ["'self'"],
17            'script-src': ["'self'", "'unsafe-inline'"],
18            'style-src': ["'self'", "'unsafe-inline'"],
19            'img-src': ["'self'", 'data:', 'https:']
20        },
21        permissions: {
22            'geolocation': '()',
23            'camera': '()',
24            'microphone': '()'
25        }
26    },
27    rateLimiting: {
28        enabled: true,
29        default: {
30            maxRequests: 100,
31            timeWindow: 60000,
32            banDuration: 3600000,
33            throttleDuration: 60000,
34            throttleDelay: 1000
35        },
36        routes: {
37            '/api/data': {
38                'POST': { maxRequests: 5, timeWindow: 30000 }
39            }
40        }
41    },
42    ddosProtection: {
43        enabled: true,
44        config: {
45            maxConnections: 200,
46            timeWindow: 60000,
47            blockDuration: 1800000,
48            requestThreshold: 500,
49            burstThreshold: 50,
50            slowRequestThreshold: 10,
51            rateLimitByPath: {
52                '/api/*': 100,
53                '/auth/*': 20,
54                '*': 500
55            }
56        }
57    },
58    logging: {
59        enable: true,
60        level: 'info',
61        maxLogSize: 5000,
62        archiveLimit: 5
63    },
64    errorHandling: {
65        includeErrorDetails: true,
66        customHandlers: {
67            'rateLimitExceeded': (res, data) => {
68                res.status(429).json({
69                    message: 'Too many requests',
70                    retryAfter: data.retryAfter,
71                    limit: data.limit,
72                    windowMs: data.windowMs
73                });
74            }
75        }
76    },
77    bypassRoutes: ['/health', '/metrics']
78});

Security Features

1. Rate Limiting

• Global Limits: Set default limits for all routes
• Route-Specific Limits: Configure different limits for specific routes
• Throttling: Progressive slowdown of requests
• Ban System: Temporary IP bans for limit violations

2. DDoS Protection

• Connection Tracking: Monitor connection counts
• Burst Detection: Identify sudden request spikes
• Progressive Penalties: Increasing restrictions for violations
• Path-Based Limits: Different limits for different paths

3. Security Headers

• CSP: Content Security Policy configuration
• HSTS: HTTP Strict Transport Security
• XSS Protection: Cross-site scripting prevention
• Frame Options: Clickjacking prevention

4. Pattern Detection

• SQL Injection: Detect SQL injection attempts
• XSS: Cross-site scripting pattern detection
• Path Traversal: Directory traversal prevention
• Custom Patterns: Add your own detection patterns

API Reference

Shield Methods

1// IP Management
2shield.blockIP(ip)
3shield.unblockIP(ip)
4shield.whitelistIP(ip)
5shield.unwhitelistIP(ip)
6
7// Pattern Management
8shield.addSuspiciousPattern(pattern)
9
10// Configuration
11shield.setConfig(config)
12
13// Logging
14shield.getLogs()
15shield.getArchivedLogs()
16
17// Reset
18shield.reset()

Testing

Run the test server:

1node test.js

Test Commands

1. Basic Request Test

1curl http://localhost:3000/

2. Rate Limit Test

1for i in $(seq 1 10); do 
2    curl http://localhost:3000/api/test
3    echo ""
4    sleep 1
5done

3. SQL Injection Test

1curl -X POST http://localhost:3000/search \
2     -H "Content-Type: application/json" \
3     -d '{"query": "1 UNION SELECT * FROM users"}'

4. XSS Test

1curl -X POST http://localhost:3000/comment \
2     -H "Content-Type: application/json" \
3     -d '{"comment": "<script>alert(\"XSS\")</script>"}'

5. IP Information

1curl http://localhost:3000/ip

6. Bypass Routes Test

1curl http://localhost:3000/health
2curl http://localhost:3000/metrics

7. DDoS Test

1for i in $(seq 1 100); do 
2    curl http://localhost:3000/ & 
3done

8. Large Payload Test

1curl -X POST http://localhost:3000/comment \
2     -H "Content-Type: application/json" \
3     -d '{"comment": "A...(100KB+)..."}'

Error Handling

K9Shield provides detailed error responses:

• 403: Access Denied / Suspicious Request
• 405: Method Not Allowed
• 413: Payload Too Large
• 429: Too Many Requests
• 500: Internal Server Error

Each error includes:

• Error message
• Error code
• Timestamp
• Additional details (when enabled)

Best Practices

1. Rate Limiting

   • Set appropriate limits based on your application needs
   • Use route-specific limits for sensitive endpoints
   • Implement proper retry-after headers

2. DDoS Protection

   • Configure thresholds based on your server capacity
   • Monitor and adjust settings based on traffic patterns
   • Use bypass routes for critical endpoints

3. Security Headers

   • Implement strict CSP policies
   • Enable HSTS in production
   • Configure appropriate frame options

4. Logging

   • Set appropriate log levels
   • Implement log rotation
   • Monitor security events regularly

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

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