Native Shield Guard 🛡️🦀

The Next-Generation Behavioral Protection Engine for Node.js
Sub-millisecond threat detection powered by Rust + Predictive Intelligence

🎯 What is Native Shield Guard?

Native Shield Guard is not a traditional firewall. It's a Behavioral Protection Engine that learns from legitimate traffic patterns and detects sophisticated attacks in real-time:

• 🤖 Detects Botnets: Identifies mechanical request rhythms (devices attack with precision; humans attack randomly)
• 🔄 Defeats Polymorphic Attacks: Catches payloads with changing values but identical structure
• 🍯 Honeypot System: Traps & bans scanners automatically
• ⚡ 99.9% Non-Intrusive: <1μs overhead per request
• 🧠 Learns Continuously: Persists threat patterns to oxide.brain

Real-World Protection

| Attack Type | Detection Rate | Response Time | |---|---|---| | SQL Injection (7 variants) | ✅ 100% | <0.1ms | | XSS Payloads (11 variants) | ✅ 100% | <0.1ms | | DDoS Botnets | ✅ 95%+ | <0.5ms | | Zero-Day Patterns | ✅ 80%+ | Real-time |

🚀 Quick Start

Installation

npm install native-shield-guard

Express.js Integration (30 seconds)

const express = require('express');
const { initFirewall, recordEvent, predictThreat, checkMaliciousInput } = require('native-shield-guard');

const app = express();

// 1. Initialize on startup
initFirewall();

// 2. Global security middleware
app.use((req, res, next) => {
  const ip = req.ip;
  const fingerprint = req.headers['user-agent'] || 'unknown';
  
  // Record request for rhythm analysis
  recordEvent(ip, fingerprint);
  
  // Check threat level (0.0 = safe, 1.0 = definite threat)
  const threatScore = predictThreat(ip, fingerprint);
  
  if (threatScore > 0.8) {
    res.status(403).json({ error: 'Access Denied - Suspicious Activity Detected' });
    return;
  }
  
  next();
});

// 3. Input validation middleware
app.post('/api/login', (req, res) => {
  const { username, password } = req.body;
  
  // Detect SQL injection, XSS, command injection, etc.
  if (checkMaliciousInput(req.ip, username) || 
      checkMaliciousInput(req.ip, password)) {
    res.status(400).json({ error: 'Malicious input detected' });
    return;
  }
  
  // Safe to process...
});

app.listen(3000);

Fastify Integration

const fastify = require('fastify')();
const { initFirewall, recordEvent, predictThreat, analyzeBehavior } = require('native-shield-guard');

initFirewall();

fastify.addHook('preHandler', async (request, reply) => {
  const ip = request.ip;
  const path = request.url;
  const fingerprint = request.headers['user-agent'];
  
  recordEvent(ip, fingerprint);
  
  // Multi-factor analysis: rhythm + behavior + trust score
  const allowed = analyzeBehavior(ip, path, fingerprint);
  if (!allowed) {
    reply.code(403).send({ error: 'Blocked' });
  }
});

fastify.listen({ port: 3000 });

⚙️ Configuration

Create firewall-config.json in your project root with complete example:

{
  "urls_enabled": ["/api/*", "/health"],
  "allowed_ips": ["*"],
  "security_enabled": true,
  "max_violations": 5,
  "honeypots": ["/admin", "/.git", "/config.php", "/wp-admin"],
  "max_score": 100.0,
  "logging_enabled": true,
  "log_file": "firewall.log",
  
  "structural_similarity_threshold": 0.95,
  "rhythm_cv_threshold": 0.12,
  "ema_alpha": 0.3,
  "honeypot_penalty_score": 50.0,
  "honeypot_penalty_trust": 60.0,
  "fuzzy_detect_score_penalty": 25.0,
  "fuzzy_detect_trust_penalty": 20.0,
  "malicious_pattern_score": 15.0,
  "malicious_pattern_trust": 10.0,
  "high_freq_threshold": 100,
  "botnet_cluster_size": 5,
  "min_trust_score_for_block": 20.0,
  "ban_duration_secs": 3600,
  "malicious_ban_duration_secs": 600,
  "suspicious_fp_score": 20.0,
  "suspicious_fp_trust": 15.0
}

Configuration Options

All these options are loaded at runtime. Change them and call reloadConfig() without recompiling.

Basics: | Option | Type | Default | Description | |--------|------|---------|-------------| | urls_enabled | string[] | — | Protected routes (supports wildcards: /api/*) | | allowed_ips | string[] | ["*"] | Allowed IPs (IP or CIDR: 192.168.0.*) | | security_enabled | boolean | true | Enable/disable threat detection | | max_violations | number | 5 | Auto-ban after N violations | | honeypots | string[] | [] | Fake paths to catch scanners | | logging_enabled | boolean | true | Write events to disk (1GB auto-rotation) | | log_file | string | firewall.log | Log file name (in .log/ directory) |

Detection Tuning (Runtime Configurable): | Option | Type | Default | Description | |--------|------|---------|-------------| | structural_similarity_threshold | f64 | 0.90 | Threshold for polymorphic attack detection (0.0-1.0) | | rhythm_cv_threshold | f64 | 0.12 | Coefficient of Variation for botnet detection (lower = stricter) | | ema_alpha | f64 | 0.3 | EMA weight for rhythmic analysis (0.1-0.5) | | honeypot_penalty_score | f32 | 50.0 | Reputation penalty for honeypot access | | honeypot_penalty_trust | f32 | 60.0 | Trust penalty for honeypot access | | fuzzy_detect_score_penalty | f32 | 25.0 | Penalty for structural similarity detected | | fuzzy_detect_trust_penalty | f32 | 20.0 | Trust penalty for similarity | | malicious_pattern_score | f32 | 15.0 | Penalty for malicious pattern detected | | malicious_pattern_trust | f32 | 10.0 | Trust penalty for malicious pattern | | high_freq_threshold | u32 | 100 | Requests to mark as high frequency | | botnet_cluster_size | u32 | 5 | IPs needed to detect botnet cluster | | min_trust_score_for_block | f32 | 20.0 | Minimum trust score before blocking | | ban_duration_secs | u64 | 3600 | Ban duration for suspicious behavior (seconds) | | malicious_ban_duration_secs | u64 | 600 | Ban duration for detected attacks (seconds) | | suspicious_fp_score | f32 | 20.0 | Penalty for suspicious fingerprint | | suspicious_fp_trust | f32 | 15.0 | Trust penalty for suspicious fingerprint |

🧠 How It Works: The Science Behind Detection

Method 1: Rhythmic Analysis (Botnet Detection)

Bots attack with mechanical precision; humans attack randomly.

Human traffic pattern:     Bot traffic pattern:
┌─────┐                    ┌─┐
│     │     ┌────┐         │ │ │ │ │
│     │     │    │──┐      │ │ │ │ │  (perfect timing = CV < 0.12)
└─────┴─────┴────┴──┘      └─┴─┴─┴─┘
 High variance (CV > 0.12)   Low variance = BLOCKED

• Tracks last 15 request intervals per IP
• Uses Exponential Moving Average (EMA) to calculate variance
• Coefficient of Variation (CV) = σ/μ
• If CV drops below 0.12 → Botnet detected ✅

Method 2: Structural Fingerprinting (Polymorphic Attacks)

Attackers change values but keep structure (e.g., different usernames, same injection pattern).

Attack 1: {"user": "admin", "cmd": "DROP TABLE"}  ─┐
Attack 2: {"user": "test",  "cmd": "DELETE FROM"}  ├─→ Same DNA
Attack 3: {"user": "root",  "cmd": "TRUNCATE"}   ─┘

Canonical form: {cmd:S, user:S}  (SHA256 hash)

• Converts JSON to canonical skeleton (ignoring values)
• Groups similar attacks by hash
• Persists patterns to oxide.brain for learning

Method 3: Pattern Matching (7 Attack Categories)

Advanced regex detection for:

| Category | Coverage | |----------|----------| | SQL Injection | UNION SELECT, DROP TABLE, SLEEP(), stored procs, etc. | | XSS | <script>, event handlers, eval(), etc. | | Path Traversal | ../, ..\, Windows reserved names | | Command Injection | Shell commands: ls, cat, pipes, backticks | | XXE | <!DOCTYPE>, <!ENTITY>, protocol handlers | | SSRF | Localhost variants, internal IPs (10.0, 172.16, 192.168, ::1) | | Log Injection | CRLF/LF escape sequences |

Method 4: Count-Min Sketch (O(1) Frequency Tracking)

Memory-efficient request frequency counting:

CMS Table: 4 rows × 2000 columns = ~32KB total
Perfect for tracking millions of IPs without memory explosion

Why not a JavaScript Map?

• Map: 1M IPs × 100 bytes = 100MB+ RAM
• CMS: 4 × 2000 × 4 bytes = 32KB RAM
• 3,000x more efficient!

📊 Complete API Reference

Core Functions

initFirewall(): boolean

Initializes the engine and loads previous state from firewall-state.json.

const success = initFirewall();
if (success) console.log('Firewall ready');

recordEvent(ip: string, fingerprint: string): void

Records a request for threat analysis (call on every request).

recordEvent('203.0.113.42', 'Mozilla/5.0...');

predictThreat(ip: string, fingerprint: string): number

Returns threat score (0.0 = safe, 1.0 = definite threat).

Score Breakdown:

• +0.4 if frequency > 100 requests
• +0.2 if frequency > 50 requests
• +0.5 if known attack signature
• +0.8 if botnet rhythm detected (CV < 0.12)
• max = 1.0 (normalized)

const score = predictThreat('203.0.113.42', fingerprint);
if (score > 0.8) {
  // Definite threat
  app.locals.blocked.push('203.0.113.42');
}

checkMaliciousInput(ip: string, input: string): boolean

Returns true if input contains attack patterns.

if (checkMaliciousInput(ip, req.body.username)) {
  res.status(400).json({ error: 'Invalid input' });
}

analyzeBehavior(ip: string, path: string, fingerprint: string): boolean

Multi-factor analysis: checks ban status, honeypots, fingerprint reputation.

Returns true = allowed, false = blocked.

const allowed = analyzeBehavior(ip, '/api/users', ua);
if (!allowed) {
  res.status(403).send('Access denied');
}

getStructuralSignature(body: string): string

Returns hex-encoded SHA-256 hash of JSON structure.

const sig = getStructuralSignature('{"user":"admin","pass":"x"}');
// → "a1b2c3d4e5f6..."

State Management

saveState(): boolean

Persists IP reputation and ban list to firewall-state.json.

// Call before shutdown
process.on('SIGTERM', () => {
  saveState();
  process.exit(0);
});

loadState(): boolean

Restores previous state (called by initFirewall()).

saveIntelligence(): void

Saves learned threat patterns to oxide.brain.

// Call periodically (hourly)
setInterval(() => {
  saveIntelligence();
}, 3600000);

loadIntelligence(): void

Restores threat intelligence from oxide.brain.

Admin/Monitoring

getSecurityStatus(): object

Returns real-time statistics.

const stats = getSecurityStatus();
// {
//   active_bans: 5,
//   tracked_ips: 1203,
//   reputation_records: 8450
// }

logMessage(ip: string, message: string): void

Custom logging for integration with external systems.

logMessage('203.0.113.42', 'Attempted account takeover - 10 failed logins');

reloadConfig(): boolean

Hot-reload configuration without restart.

// After updating firewall-config.json
reloadConfig();

🚨 Production Deployment

1. Performance Tuning (No Recompilation)

Modify values in firewall-config.json and reload without stopping the server:

// In your app
app.post('/admin/reload-config', (req, res) => {
  const success = lib.reloadConfig();
  res.json({ success, message: 'Config reloaded' });
});

Tuning examples:

// ← More permissive (reduce false positives in login)
{
  "structural_similarity_threshold": 0.98,
  "fuzzy_detect_score_penalty": 5.0
}

// ← More strict (increase detection on critical APIs)
{
  "rhythm_cv_threshold": 0.08,
  "malicious_ban_duration_secs": 1800
}

2. Reload Configuration at Runtime

Call reloadConfig() after changing firewall-config.json:

const lib = require('native-shield-guard');
const fs = require('fs');

// Watch for config changes
fs.watch('firewall-config.json', () => {
  console.log('Config changed, reloading...');
  lib.reloadConfig();
});

3. Monitoring Dashboard

// Expose stats every 30 seconds
app.get('/health/security', (req, res) => {
  const stats = getSecurityStatus();
  res.json({
    timestamp: new Date(),
    ...stats,
    memory: process.memoryUsage()
  });
});

4. Log Rotation & Retention

Logs auto-rotate at 1GB. Archive with:

# Daily backup
0 2 * * * tar -czf archive-$(date +%Y%m%d).tar.gz .log/*.log

4. Threat Intelligence Export

// Hourly export for SIEM integration
setInterval(async () => {
  const stats = getSecurityStatus();
  await fetch('https://siem.example.com/api/events', {
    method: 'POST',
    body: JSON.stringify(stats)
  });
}, 3600000);

📈 Benchmarks

Tested on a 4-core Intel i7, scanning JSON payloads:

Threat Detection Speed:
├─ Pattern matching:     0.08ms per request
├─ Rhythm analysis:      0.12ms per request
├─ Structural hash:      0.03ms per request
└─ Total overhead:       < 0.3ms (99%ile)

Memory Footprint:
├─ CMS Sketch:            32 KB  (millions of IPs)
├─ Reputation map:        ~10 MB (10K tracked IPs)
├─ Rhythm tracker:        ~5 MB  (10K tracked IPs)
└─ Total:                 ~16 MB (baseline)

Scalability:
├─ Tracks:               1M+ unique IPs
├─ Handles:              10K+ req/sec per core
├─ No GC pauses:         Rust memory management
└─ p99 latency:          < 1ms (sub-millisecond)

🔒 Security Checklist

• ✅ Input validation (7 attack categories)
• ✅ Rate limiting (per-IP frequency tracking)
• ✅ DDoS detection (botnet rhythm analysis)
• ✅ Honeypot trapping (scanner detection)
• ✅ Zero-day pattern matching (polymorphic attacks)
• ✅ IP reputation system (trust scoring)
• ✅ Automatic ban enforcement (configurable thresholds)
• ✅ Persistent learning (oxide.brain)
• ✅ Audit logging (1GB rotating logs)
• ✅ Healthcare-ready (HIPAA-compatible logging)

📝 Examples

See examples/ directory for:

• bot-login-attack.js - Simulate botnet attack
• brute-force-accounts.js - Test brute-force detection
• fuzzy-attack.js - Polymorphic payload variants
• honeypot-test.js - Scanner detection
• normal-traffic-simulator.js - Baseline behavior
• predictive-test.js - Threat scoring examples

Run any example:

node examples/bot-login-attack.js

📚 Documentation

• IMPROVEMENTS.md - v2.0 changes & tunable constants
• Spanish: README_ES.md
• Portuguese: README_PT.md

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md

⚖️ License

MIT License © 2026 - Villalba Ricardo Daniel

Built with ❤️ for high-security healthcare applications