@guardcore

Framework-agnostic security middleware engine for Node.js and edge runtimes.

TypeScript port of guard-core — the engine that powers the Guard security ecosystem. All shared security logic lives here. Framework-specific adapters wire it into Express, Fastify, NestJS, and Hono.

Ecosystem

@guardcore/core                    <- Engine: all security logic
├── @guardcore/express             <- Express middleware adapter
├── @guardcore/fastify             <- Fastify plugin adapter
├── @guardcore/nestjs              <- NestJS middleware + module
└── @guardcore/hono                <- Hono middleware (edge-safe)

Features

• IP Control — Whitelisting, blacklisting, CIDR ranges, auto-ban on suspicious activity
• Rate Limiting — Global, per-endpoint, per-route, geo-based limits with Redis sliding window
• Penetration Detection — 75 regex patterns + semantic analysis for XSS, SQLi, command injection, path traversal
• Security Headers — 10 default headers (HSTS, CSP, CORP, COEP, COOP, etc.)
• Behavioral Analysis — Usage monitoring, return pattern tracking, ban/throttle/alert actions
• Cloud Provider Blocking — AWS, GCP, Azure IP range detection
• Country Filtering — GeoIP-based blocking/whitelisting via MaxMind
• HTTPS Enforcement — Automatic HTTP to HTTPS redirect with trusted proxy support
• Decorator System — 20 decorator methods for per-route security configuration
• Redis Integration — Distributed rate limiting, shared IP bans, cloud IP caching
• Edge Runtime Support — Uint8Array protocols, re2-wasm regex, no Node-only dependencies in core

Quick Start

Express

npm install @guardcore/core @guardcore/express

import express from 'express';
import { createSecurityMiddleware } from '@guardcore/express';

const app = express();

app.use(createSecurityMiddleware({
  config: {
    enableRateLimiting: true,
    rateLimit: 100,
    rateLimitWindow: 60,
    blockedUserAgents: ['badbot', 'scrapy'],
    enablePenetrationDetection: true,
  },
}));

app.listen(3000);

Fastify

npm install @guardcore/core @guardcore/fastify

import Fastify from 'fastify';
import { guardPlugin } from '@guardcore/fastify';

const app = Fastify();

app.register(guardPlugin, {
  config: {
    enableRateLimiting: true,
    rateLimit: 100,
    rateLimitWindow: 60,
  },
});

app.listen({ port: 3000 });

NestJS

npm install @guardcore/core @guardcore/nestjs

import { Module } from '@nestjs/common';
import { GuardModule } from '@guardcore/nestjs';

@Module({
  imports: [
    GuardModule.forRoot({
      config: {
        enableRateLimiting: true,
        rateLimit: 100,
      },
    }),
  ],
})
export class AppModule {}

Hono (Edge)

npm install @guardcore/core @guardcore/hono

import { Hono } from 'hono';
import { createGuardMiddleware } from '@guardcore/hono';

const app = new Hono();

app.use('*', createGuardMiddleware({
  config: {
    enableRateLimiting: true,
    rateLimit: 100,
  },
}));

export default app;

SecurityConfig

The central configuration object controls all security behavior:

import { SecurityConfigSchema } from '@guardcore/core';

const config = SecurityConfigSchema.parse({
  blacklist: ['192.168.100.0/24'],
  trustedProxies: ['172.16.0.0/12', '10.0.0.0/8'],
  blockCloudProviders: ['AWS', 'GCP', 'Azure'],
  blockedUserAgents: ['badbot', 'scrapy'],
  enableRateLimiting: true,
  rateLimit: 30,
  rateLimitWindow: 60,
  enableIpBanning: true,
  autoBanThreshold: 5,
  autoBanDuration: 300,
  enablePenetrationDetection: true,
  enforceHttps: true,
  enableRedis: true,
  redisUrl: 'redis://localhost:6379',
  logFormat: 'json',
  securityHeaders: {
    enabled: true,
    hsts: { maxAge: 31536000, includeSubdomains: true, preload: true },
    csp: { 'default-src': ["'self'"], 'script-src': ["'self'"] },
  },
});

SecurityDecorator

Per-route security configuration via decorators:

import { SecurityDecorator, SecurityConfigSchema } from '@guardcore/core';

const guard = new SecurityDecorator(SecurityConfigSchema.parse({}));

function myHandler() { /* ... */ }

guard.requireIp(['10.0.0.0/8'])(myHandler);
guard.rateLimit(100, 3600)(myHandler);
guard.requireAuth('bearer')(myHandler);
guard.blockCountries(['CN', 'RU'])(myHandler);
guard.usageMonitor(5, 3600, 'ban')(myHandler);

Python Parity

This is a faithful TypeScript port of guard-core. The Python codebase is the source of truth for features, architecture, and behavior. All 75 detection patterns, 44 SecurityConfig fields, 6 protocols, 17 security checks, and 9 handlers are ported 1:1.

The Python Guard ecosystem:

• guard-core — Engine (Python)
• fastapi-guard — FastAPI adapter
• flaskapi-guard — Flask adapter
• djapi-guard — Django adapter

Development

pnpm install
pnpm build
pnpm test
pnpm lint

Or use Make:

make install
make build
make test
make lint

See CONTRIBUTING.md for development guidelines.

Security

See SECURITY.md for vulnerability reporting and security best practices.

License

MIT