SDK Documentatie

Runtime beveiliging voor JavaScript en TypeScript applicaties. Detecteer en blokkeer aanvallen voordat ze je applicatie bereiken.

7 threat detectors

XSS, SQLi, CSRF en meer

Sub-milliseconde

Geen merkbare latency

Auto-updating

Dagelijkse signature updates

Packages

De ShadowGuard SDK bestaat uit twee packages: een framework-agnostische core en een Next.js adapter.

@shadowguard/core

Framework-agnostische security engine met threat detectie, scoring en telemetry. Geen Node.js- of framework-specifieke imports.

TypeScriptESM + CJS0 dependencies

@shadowguard/nextjs

Next.js middleware adapter. Integreert de security engine in je middleware.ts met automatische route-filtering en configuratie.

Next.js 14+MiddlewareEdge Runtime

Installatie

npm

npm install @shadowguard/core @shadowguard/nextjs

pnpm

pnpm add @shadowguard/core @shadowguard/nextjs

yarn

yarn add @shadowguard/core @shadowguard/nextjs

Quick Start

In 3 stappen runtime beveiliging toevoegen aan je Next.js applicatie.

1Environment variable instellen

Voeg je ShadowGuard API key toe aan je .env.local bestand.

.env.local

SHADOWGUARD_API_KEY=sg_jouw_api_key
SHADOWGUARD_SITE_ID=jouw-site-uuid

2Next.js config aanpassen

Voeg de ShadowGuard plugin toe aan je Next.js configuratie voor build-time validatie.

next.config.tsTypeScript

const nextConfig = {
  // je bestaande Next.js config
}

export default nextConfig

3Middleware instellen

Maak of pas je middleware.ts aan om de ShadowGuard security middleware te gebruiken.

middleware.tsTypeScript

import { withShadowGuard } from '@shadowguard/nextjs'

export default withShadowGuard({
  edition: 'pro', // 'lite' | 'pro' | 'elite' | 'internal'
  apiKey: process.env.SHADOWGUARD_API_KEY!,
  siteId: process.env.SHADOWGUARD_SITE_ID!,
  sensitivity: 'balanced',
  telemetry: {
    enabled: true,
    batchInterval: 60000,
    endpoint: process.env.SHADOWGUARD_ENDPOINT || 'https://shadowguard.nl',
  },
  cloudIntelligence: {
    enabled: true,
  },
  excludedRoutes: [
    '/api/webhooks/*',  // Webhook routes uitsluiten
    '/favicon.ico',
  ],
})

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

Klaar! Je Next.js applicatie is nu beschermd met real-time threat detectie. Geblokkeerde aanvallen verschijnen automatisch in je ShadowGuard dashboard.

Configuratie

Alle beschikbare configuratie-opties voor de SDK.

Optie	Type	Default	Beschrijving
`apiKey`	string	-	Je ShadowGuard API key (verplicht)
`siteId`	string	-	UUID van je site (verplicht)
`sensitivity`	'strict' \| 'balanced' \| 'permissive'	'balanced'	Detectie gevoeligheid
`exclude`	string[]	[]	URL patronen om uit te sluiten (support * wildcards)
`telemetry`	boolean	true	Telemetry naar ShadowGuard versturen
`autoUpdate`	boolean	true	Automatische signature updates (elke 24 uur)
`blockAction`	'block' \| 'log'	'block'	Actie bij detectie: blokkeren of alleen loggen
`customBlockPage`	string	-	Custom URL voor block page redirect

Gevoeligheidsniveaus

De sensitivity instelling bepaalt de drempelwaarde voor het blokkeren van verzoeken.

strict

Drempel: 0.70+

Blokkeert agressief. Geschikt voor high-security omgevingen. Meer false positives mogelijk.

balanced

Drempel: 0.85+

Aanbevolen instelling. Goede balans tussen beveiliging en false positives.

permissive

Drempel: 0.95+

Alleen zeer zekere bedreigingen worden geblokkeerd. Minimale false positives.

Threat Detectors

De SDK bevat 7 ingebouwde threat detectors met 44+ baseline signatures.

XSS Detection

10 signatures

Cross-Site Scripting patronen in URL, headers en body

SQL Injection

10 signatures

SQL injection via parameters, union-based, blind SQLi

CSRF Detection

3 signatures

Cross-Site Request Forgery via origin/referer validatie

Path Traversal

6 signatures

Directory traversal en file inclusion pogingen

Command Injection

8 signatures

OS command injection via shell metacharacters

Header Injection

4 signatures

HTTP header injection en response splitting

Bot Detection

3 signatures

Geautomatiseerde bot en scraper detectie via isbot

Core API

De @shadowguard/core package biedt directe toegang tot de security engine.

SecurityEngineTypeScript

import { SecurityEngine, type SecurityConfig } from '@shadowguard/core'

const engine = new SecurityEngine({
  sensitivity: 'balanced',
  signatures: [], // Gebruik baseline of custom signatures
})

// Analyseer een verzoek
const result = engine.analyze({
  url: '/api/users?id=1 OR 1=1',
  method: 'GET',
  headers: { 'user-agent': 'Mozilla/5.0...' },
  body: null,
})

if (result.blocked) {
  console.log('Geblokkeerd:', result.threats)
  // [{ type: 'sql_injection', confidence: 0.95, rule: 'sql-03' }]
}

console.log('Score:', result.score) // 0.0 - 1.0

TelemetryCollectorTypeScript

import { TelemetryCollector } from '@shadowguard/core'

const telemetry = new TelemetryCollector({
  apiKey: 'sg_...',
  siteId: 'site-uuid',
  batchInterval: 60000, // 60s batch interval
  maxEvents: 1000,      // Circular buffer grootte
})

// Kritieke events worden direct verstuurd
telemetry.track({
  type: 'block',
  threat: 'sql_injection',
  url: '/api/users',
  confidence: 0.95,
})

// Aggregate stats worden elke 60s gebatcht
telemetry.trackAggregate({
  requests: 1500,
  blocked: 3,
  period: '60s',
})

Signature UpdatesTypeScript

import { SignatureUpdater } from '@shadowguard/core'

const updater = new SignatureUpdater({
  apiKey: 'sg_...',
  updateInterval: 86400000, // 24 uur
  timeout: 10000,            // 10s timeout
  onUpdate: (signatures) => {
    console.log(`${signatures.length} signatures geladen`)
    engine.updateSignatures(signatures)
  },
})

// Start automatische updates
updater.start()

// Of handmatig updaten
const signatures = await updater.fetchLatest()

Next.js Integratie

Geavanceerde patronen voor Next.js integratie.

Gecombineerde middleware

Combineer ShadowGuard met je bestaande middleware (bijv. NextAuth).

middleware.tsTypeScript

import { withShadowGuard } from '@shadowguard/nextjs'
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

const securityMiddleware = withShadowGuard({
  apiKey: process.env.SHADOWGUARD_API_KEY!,
  siteId: process.env.SHADOWGUARD_SITE_ID!,
  sensitivity: 'balanced',
  telemetry: {
    enabled: true,
    endpoint: process.env.SHADOWGUARD_ENDPOINT || 'https://shadowguard.nl',
  },
  cloudIntelligence: {
    enabled: true,
  },
})

export async function middleware(request: NextRequest) {
  // 1. ShadowGuard security check eerst
  const securityResponse = await securityMiddleware(request)

  // Als geblokkeerd, return meteen
  if (securityResponse.status === 403) {
    return securityResponse
  }

  // 2. Je eigen middleware logica
  const response = NextResponse.next()

  // Voorbeeld: custom headers toevoegen
  response.headers.set('X-Custom-Header', 'waarde')

  return response
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

Route-specifieke configuratie

Stel verschillende gevoeligheidsniveaus in per route.

middleware.tsTypeScript

import { withShadowGuard } from '@shadowguard/nextjs'

// Strikte beveiliging voor API routes
const apiSecurity = withShadowGuard({
  apiKey: process.env.SHADOWGUARD_API_KEY!,
  siteId: process.env.SHADOWGUARD_SITE_ID!,
  sensitivity: 'strict',
  telemetry: {
    enabled: true,
    endpoint: process.env.SHADOWGUARD_ENDPOINT || 'https://shadowguard.nl',
  },
  cloudIntelligence: {
    enabled: true,
  },
})

// Mildere beveiliging voor publieke pagina's
const pageSecurity = withShadowGuard({
  apiKey: process.env.SHADOWGUARD_API_KEY!,
  siteId: process.env.SHADOWGUARD_SITE_ID!,
  sensitivity: 'permissive',
  telemetry: {
    enabled: true,
    endpoint: process.env.SHADOWGUARD_ENDPOINT || 'https://shadowguard.nl',
  },
  cloudIntelligence: {
    enabled: true,
  },
})

export async function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/api/')) {
    return apiSecurity(request)
  }
  return pageSecurity(request)
}

Log-only modus

Begin met monitoring zonder blokkeren om false positives te identificeren.

middleware.tsTypeScript

import { withShadowGuard } from '@shadowguard/nextjs'

const securityMiddleware = withShadowGuard({
  mode: 'monitor',
  apiKey: process.env.SHADOWGUARD_API_KEY!,
  siteId: process.env.SHADOWGUARD_SITE_ID!,
  sensitivity: 'balanced',
  telemetry: {
    enabled: true,
    endpoint: process.env.SHADOWGUARD_ENDPOINT || 'https://shadowguard.nl',
  },
  cloudIntelligence: {
    enabled: true,
  },
})

// Alle bedreigingen worden gelogd naar je ShadowGuard dashboard
// zonder bezoekers te blokkeren. Perfect voor de eerste week.

Foutafhandeling

De SDK is ontworpen met een fail-open principe: fouten blokkeren nooit legitimate traffic.

API key ongeldig of verlopenSDK laat verkeer door, logt waarschuwing

Telemetry backend onbereikbaarCircuit breaker opent na 5 fouten, events in buffer tot reconnectie

Signature update misluktGebruikt baseline signatures, probeert opnieuw bij volgende interval

Onverwachte parsing foutRequest wordt doorgelaten, fout wordt gelogd

Memory buffer vol (1000 events)Oudste events worden FIFO verwijderd

Hulp bij implementatie? GuardFoundry is uw development partnerMeer info

Volgende stap

Gebruik de CLI voor scans en monitoring vanuit je terminal.

CLI Guide