API Security Shield - Core 🛡️

Core security engine for intelligent API protection in Node.js applications.

The core module of API Security Shield provides the foundation for protecting your APIs from automated threats, brute force attacks, and malicious traffic. Built with TypeScript and a plugin-first architecture, it enables real-time threat detection and adaptive responses.

📦 What's Included

• Threat Detection Engine: Multi-layered detection for SQL injection, XSS, and common attack patterns
• Adaptive Rate Limiting: Intelligent request throttling based on threat assessment
• Bot Detection: Advanced fingerprinting and behavioral analysis
• Event System: Real-time event bus for security events
• Extensible Architecture: Plugin system for custom detectors and analyzers
• Storage Adapters: Memory and Redis support for distributed deployments
• Middleware Integration: Express, Fastify, and NestJS compatible

🚀 Quick Start

Installation

npm install api-security-shield
# or
pnpm add api-security-shield
# or
yarn add api-security-shield

Basic Usage

import { SecurityShield } from 'api-security-shield-core';
import express from 'express';

const app = express();
const shield = new SecurityShield({
  rateLimit: {
    windowMs: 60000,      // 1 minute
    max: 100              // 100 requests per window
  },
  botDetection: {
    enabled: true,
    sensitivity: 'high'   // low | medium | high
  }
});

// Apply middleware
app.use(shield.middleware());

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

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

🔧 Configuration

Core Options

interface ShieldConfig {
  // Rate limiting
  rateLimit?: {
    windowMs: number;      // Time window in ms
    max: number;           // Max requests per window
    message?: string;      // Custom rate limit message
  };

  // Bot detection
  botDetection?: {
    enabled: boolean;
    sensitivity: 'low' | 'medium' | 'high';
    threshold?: number;    // 0-100 score threshold
  };

  // Threat detection
  threatDetection?: {
    sqlInjection: boolean;
    xss: boolean;
    customPatterns?: RegExp[];
  };

  // Storage adapter (memory or redis)
  storage?: StorageAdapter;

  // Event handlers
  onThreat?: (event: ThreatEvent) => void;
  onRateLimit?: (event: RateLimitEvent) => void;
}

📊 Event System

Listen to security events in real-time:

shield.on('threat', (event) => {
  console.log(`Threat detected: ${event.type}`, {
    source: event.ip,
    severity: event.severity,
    timestamp: event.timestamp
  });
});

shield.on('rate-limit', (event) => {
  console.log(`Rate limit exceeded for ${event.ip}`);
});

shield.on('bot', (event) => {
  console.log(`Bot detected with score: ${event.score}`);
});

🔌 Storage Adapters

Memory Adapter (Default)

import { MemoryStorageAdapter } from 'api-security-shield-core';

const shield = new SecurityShield({
  storage: new MemoryStorageAdapter()
});

Redis Adapter

import { RedisStorageAdapter } from '@api-security-shield/redis';
import Redis from 'ioredis';

const redis = new Redis({
  host: 'localhost',
  port: 6379
});

const shield = new SecurityShield({
  storage: new RedisStorageAdapter(redis)
});

🎯 Advanced Features

Custom Threat Detectors

import { CustomDetector } from 'api-security-shield-core';

class MyCustomDetector extends CustomDetector {
  detect(request) {
    // Your detection logic
    return {
      detected: false,
      score: 0,
      message: 'Custom check passed'
    };
  }
}

shield.registerDetector(new MyCustomDetector());

Threat Scoring

The shield assigns threat scores (0-100) based on multiple factors:

| Score Range | Level | Action | |------------|-------|--------| | 0-20 | Low | Allow request | | 21-50 | Medium | Monitor & log | | 51-80 | High | Rate limit | | 81-100 | Critical | Block immediately |

Request Context

Access security context in your handlers:

app.get('/api/data', (req: any, res) => {
  const shieldContext = req.shieldContext;
  
  console.log({
    threatScore: shieldContext.threatScore,
    isBot: shieldContext.isBot,
    fingerprint: shieldContext.fingerprint,
    violations: shieldContext.violations
  });

  res.json({ data: 'sensitive' });
});

🔐 Security Best Practices

1. Always validate input - Shield complements but doesn't replace input validation
2. Use HTTPS - Always run in production with TLS/SSL
3. Monitor events - Set up alerts for high threat scores
4. Update regularly - Keep Shield and dependencies updated
5. Test configuration - Thoroughly test rate limits and detection rules
6. Use Redis for distributed - In production with multiple servers, use Redis adapter

📚 Middleware Integration

Express

import express from 'express';
import { SecurityShield } from 'api-security-shield-core';

const app = express();
const shield = new SecurityShield(config);
app.use(shield.middleware());

Fastify

Install the Fastify adapter:

npm install @api-security-shield/fastify

import Fastify from 'fastify';
import { fastifyShield } from '@api-security-shield/fastify';

const fastify = Fastify();
await fastify.register(fastifyShield, config);

NestJS

Install the NestJS adapter:

npm install @api-security-shield/nestjs

import { Module } from '@nestjs/common';
import { ShieldModule } from '@api-security-shield/nestjs';

@Module({
  imports: [ShieldModule.forRoot(config)]
})
export class AppModule {}

🚨 Error Handling

shield.on('error', (error) => {
  console.error('Shield error:', error);
  // Handle errors gracefully
});

// Custom error responses
app.use((err: any, req: any, res: any, next: any) => {
  if (err.code === 'RATE_LIMIT_EXCEEDED') {
    return res.status(429).json({
      error: 'Too many requests',
      retryAfter: err.retryAfter
    });
  }

  if (err.code === 'THREAT_DETECTED') {
    return res.status(403).json({
      error: 'Request blocked',
      reason: err.reason
    });
  }

  next(err);
});

📊 Monitoring & Metrics

Access real-time metrics:

const metrics = shield.getMetrics();

console.log({
  totalRequests: metrics.totalRequests,
  blockedRequests: metrics.blockedRequests,
  threatsDetected: metrics.threatsDetected,
  averageThreatScore: metrics.averageThreatScore,
  botsDetected: metrics.botsDetected
});

🔗 Webhook Integration

Send security events to external services:

npm install @api-security-shield/webhook

import { WebhookAdapter } from '@api-security-shield/webhook';

const webhook = new WebhookAdapter({
  url: 'https://your-service.com/security-events',
  events: ['threat', 'bot', 'rate-limit'],
  retries: 3
});

shield.registerAdapter(webhook);

🧪 Testing

import { createTestShield } from 'api-security-shield-core';

const shield = createTestShield({
  rateLimit: { windowMs: 1000, max: 5 }
});

// Simulate requests
const result = await shield.check({
  ip: '192.168.1.1',
  path: '/api/test',
  method: 'POST'
});

expect(result.threatScore).toBeLessThan(50);

🐛 Debugging

Enable debug mode to see detailed logs:

const shield = new SecurityShield(config, {
  debug: true,
  logLevel: 'verbose'
});

// Or use environment variable
// DEBUG=api-security-shield:* node app.js

📖 Documentation

• Full API Reference
• Architecture Guide
• Plugin Development
• Examples

🔗 Related Packages

• @api-security-shield/express - Express integration
• @api-security-shield/fastify - Fastify integration
• @api-security-shield/redis - Redis adapter
• @api-security-shield/webhook - Webhook notifications

📜 License

MIT © Akram Hossain

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

🐛 Report Issues

Found a bug? Please report it on GitHub Issues

📞 Support

• GitHub Discussions: Discussion Board
• Email: [email protected]