🦎 Chameleon Security Middleware

Advanced security middleware with ML-powered request analysis, adaptive response generation, and intelligent traffic routing for Express and Next.js applications.

✨ Features

• 🧠 ML-Powered Classification - Real-time request analysis using machine learning
• 🎭 Adaptive Responses - Context-aware response generation
• ⚡ High Performance - Built-in caching and optimized processing
• 🔄 Intelligent Routing - Smart traffic management
• 📊 Optional Logging - Firebase integration for analytics
• 🌐 Site Replication - Optional website mirroring capabilities
• 🛡️ Fail-Safe - Graceful degradation when services unavailable

📦 Installation

npm install chameleon-security-middleware

Optional Features

Install optional dependencies for advanced features:

# For site replication
npm install puppeteer

# For Firebase logging
npm install firebase-admin

🚀 Quick Start

Basic Setup (Express)

import express from 'express';
import { ChameleonDefense } from 'chameleon-security-middleware';

const app = express();
app.use(express.json());

const defense = new ChameleonDefense({
  mlApiUrl: 'https://chameleon-api-umen.onrender.com/analyze',
  confidenceThreshold: 0.7
});

app.use(defense.middleware());

app.get('/api/data', (req, res) => {
  res.json({ message: 'Protected endpoint' });
});

app.listen(3000, () => {
  console.log('Server running with Chameleon protection');
});

Advanced Setup (All Features)

import { ChameleonDefense } from 'chameleon-security-middleware';

const defense = new ChameleonDefense({
  // ML Configuration
  mlApiUrl: 'https://your-ml-api.com/analyze',
  confidenceThreshold: 0.7,
  timeout: 10000,
  retries: 2,
  
  // Adaptive Response Configuration
  responseMode: 'adaptive', // 'adaptive', 'block', or 'monitor'
  delayEnabled: true,
  
  // Site Replication (requires puppeteer)
  replicateTarget: 'https://your-production-site.com',
  simulationPath: '/simulation',
  cacheDir: './simulation-cache',
  
  // Firebase Logging (requires firebase-admin)
  firebaseConfig: {
    projectId: 'your-project',
    privateKey: process.env.FIREBASE_PRIVATE_KEY,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL
  },
  geminiApiKey: process.env.GEMINI_API_KEY,
  
  // Monitoring
  monitorAll: false // Set true to log all requests
});

// Pre-replicate site at startup (if enabled)
await defense.preReplicate();

app.use(defense.middleware());

Next.js Integration

// middleware.js
import { ChameleonDefense } from 'chameleon-security-middleware';

const defense = new ChameleonDefense({
  confidenceThreshold: 0.8
});

export async function middleware(request) {
  // Implement Next.js middleware logic using Chameleon components
  const mlConnector = defense.mlConnector;
  // ... your logic
}

export const config = {
  matcher: '/api/:path*'
};

⚙️ Configuration Options

Core Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | mlApiUrl | string | Chameleon API | ML classification API endpoint | | confidenceThreshold | number | 0.7 | Minimum confidence to take action (0-1) | | timeout | number | 10000 | API timeout in milliseconds | | retries | number | 2 | Number of retry attempts |

Response Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | responseMode | string | 'adaptive' | Response strategy: 'adaptive', 'block', 'monitor' | | delayEnabled | boolean | true | Enable progressive delay |

Replication Options (Requires puppeteer)

| Option | Type | Default | Description | |--------|------|---------|-------------| | replicateTarget | string | null | URL to replicate | | simulationPath | string | '/simulation' | Path for simulated site | | cacheDir | string | './simulation-cache' | Cache directory | | replicateInterval | number | 86400000 | Re-replicate interval (ms) |

Logging Options (Requires firebase-admin)

| Option | Type | Default | Description | |--------|------|---------|-------------| | firebaseConfig | object | null | Firebase credentials | | geminiApiKey | string | null | Gemini API key for AI analysis | | monitorAll | boolean | false | Log all requests (not just suspicious) |

📊 Statistics & Monitoring

const stats = await defense.getStats();
console.log(stats);
/*
{
  ml: { size: 45, maxAge: 60000 },
  requests: {
    totalRequests: 1234,
    classificationTypes: { 'SQLi': 45, 'XSS': 23, ... },
    topCountries: { 'US': 567, 'GB': 234, ... },
    recentRequests: [...]
  },
  features: {
    mlClassification: true,
    adaptiveResponses: true,
    siteReplication: true,
    firebaseLogging: true
  }
}
*/

🔧 Component Usage

Use Individual Components

import { 
  MLConnector,
  AdaptiveEngine,
  SiteReplicator,
  RequestLogger 
} from 'chameleon-security-middleware';

// Use ML classification only
const ml = new MLConnector({
  mlApiUrl: 'https://your-api.com',
  confidenceThreshold: 0.7
});

const result = await ml.classify('SELECT * FROM users', '192.168.1.1');
console.log(result.classification); // 'SQLi' | 'XSS' | 'Benign' | etc.

// Generate adaptive responses
const adaptive = new AdaptiveEngine({
  responseMode: 'adaptive',
  delayEnabled: true
});

const response = adaptive.generateResponse('SQLi', { path: '/api/users' });

// Site replication (requires puppeteer)
const replicator = new SiteReplicator({
  replicateTarget: 'https://example.com'
});

await replicator.replicate();

// Firebase logging (requires firebase-admin)
const logger = new RequestLogger({
  firebaseConfig: {...}
});

await logger.logRequest({
  payload: 'suspicious input',
  classification: 'SQLi',
  confidence: 0.95,
  clientIp: '192.168.1.1'
});

🎯 Use Cases

1. Basic WAF Protection

const defense = new ChameleonDefense({
  confidenceThreshold: 0.8
});
app.use(defense.middleware());

2. Research & Analysis

const defense = new ChameleonDefense({
  responseMode: 'monitor',
  monitorAll: true,
  firebaseConfig: {...}
});

3. Simulation Environment

const defense = new ChameleonDefense({
  replicateTarget: 'https://production.com',
  simulationPath: '/simulation',
  delayEnabled: true
});

await defense.preReplicate();

🛡️ Security Best Practices

1. Environment Variables: Store API keys and credentials securely
2. Confidence Threshold: Adjust based on your risk tolerance
3. Monitoring: Enable logging in production for insights
4. Fail-Safe: Middleware fails open (allows traffic) if ML API is unavailable
5. Rate Limiting: Combine with rate limiting for comprehensive protection

📄 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR on GitHub.

🔗 Links

• GitHub Repository
• NPM Package
• Documentation

Made with ❤️ by The Outliers Team @ SPIT