@bernierllc/validators-security

Composite domain validator for comprehensive security validation combining secret detection, header policies, cryptographic parameters, form transport security, and signature validation.

Installation

npm install @bernierllc/validators-security

Overview

The security validator orchestrates multiple primitive validators to provide comprehensive security validation for applications. It combines:

• Secret Pattern Detection - Scans code for hardcoded API keys, passwords, tokens, and private keys
• HTTP Header Security Policies - Validates security headers (CSP, CORS, HSTS, etc.)
• Form Transport Security - Ensures forms use HTTPS and secure cookie settings
• Signature Replay Attack Detection - Validates request signatures and timestamps
• Cryptographic Parameter Validation - Checks algorithm strength, key sizes, and iteration counts

Usage

Basic Usage

import { validateSecurity } from '@bernierllc/validators-security';
import { createSharedUtils } from '@bernierllc/validators-utils';

const utils = createSharedUtils();

const content = {
  code: 'const apiKey = "sk_test_12345678901234567890";',
  headers: {
    'Content-Security-Policy': "default-src 'self'",
    'X-Frame-Options': 'DENY',
  },
};

const result = await validateSecurity(content, {}, utils);

if (result.problems.length === 0) {
  console.log('Security validation passed!');
} else {
  console.log('Security issues found:', result.problems);
}

Validate Multiple Security Aspects

const content = {
  code: sourceCode,
  headers: responseHeaders,
  form: htmlFormContent,
  request: {
    body: requestBody,
    signature: requestSignature,
    timestamp: Date.now(),
  },
  crypto: {
    algorithm: 'AES-256-GCM',
    keySize: 256,
    iterations: 100000,
  },
};

const result = await validateSecurity(content, {}, utils);

Custom Validator Configuration

import { createSecurityValidator } from '@bernierllc/validators-security';

const validator = createSecurityValidator({
  validateSecrets: true,
  validateHeaders: true,
  validateFormTransport: false, // Skip form validation
  validateSignatures: true,
  validateCryptoParameters: true,
  severity: 'error',
});

const result = await validator.validate(content, utils);
console.log('Security validation:', result);

Configure Primitive Validators

const result = await validateSecurity(
  content,
  {
    validateSecrets: true,
    secretsOptions: {
      minEntropyScore: 5.0,
      checkApiKeys: true,
      checkPasswords: true,
      excludePatterns: [/test_key_\w+/],
    },
    validateHeaders: true,
    headersOptions: {
      requireCSP: true,
      requireHSTS: true,
    },
    validateCryptoParameters: true,
    cryptoOptions: {
      minKeySize: 2048,
      allowedAlgorithms: ['AES-256-GCM', 'RSA-2048'],
    },
  },
  utils
);

API Reference

validateSecurity(content, options, utils)

Main validation function that orchestrates all security validators.

Parameters:

• content: SecurityContent - Content to validate
  • code?: string - Source code to scan for secrets
  • headers?: Record<string, string> - HTTP headers to validate
  • form?: string - HTML form content to check
  • request?: { body: string; signature: string; timestamp?: number } - Request data for signature validation
  • crypto?: { algorithm?: string; keySize?: number; iterations?: number; saltLength?: number } - Cryptographic parameters
• options: SecurityValidationOptions - Validation options
  • validateSecrets?: boolean - Enable secret detection (default: true)
  • secretsOptions?: Partial<SecretPatternOptions> - Secret validator options
  • validateHeaders?: boolean - Enable header validation (default: true)
  • headersOptions?: Partial<HeaderPolicyOptions> - Header validator options
  • validateFormTransport?: boolean - Enable form security (default: true)
  • formTransportOptions?: Partial<FormTransportOptions> - Form validator options
  • validateSignatures?: boolean - Enable signature validation (default: true)
  • signaturesOptions?: Partial<SignatureReplayOptions> - Signature validator options
  • validateCryptoParameters?: boolean - Enable crypto validation (default: true)
  • cryptoOptions?: Partial<CryptoParametersOptions> - Crypto validator options
  • severity?: 'error' | 'warn' | 'info' - Problem severity (default: 'warn')
• utils: SharedUtils - Shared utility functions

Returns: Promise<ValidationResult>

• problems: Problem[] - Array of validation issues
• stats - Validation statistics
  • targets: number - Number of targets validated
  • durationMs: number - Validation duration in milliseconds
  • rulesApplied: string[] - List of rules that were applied

createSecurityValidator(options)

Creates a configured security validator instance.

Parameters:

• options: SecurityValidationOptions - Configuration options

Returns: Validator object with:

• validate(content, utils): Promise<ValidationResult> - Validation function
• getMeta() - Get validator metadata
  • name: string - Validator package name
  • version: string - Package version
  • description: string - Validator description
  • domain: 'security' - Validation domain
  • enabledRules: string[] - List of enabled validation rules

Composed Primitive Validators

This domain validator composes the following primitive validators:

• @bernierllc/validators-secret-patterns - Detects hardcoded secrets
• @bernierllc/validators-header-policy - Validates HTTP security headers
• @bernierllc/validators-form-transport - Validates form security
• @bernierllc/validators-signature-replay - Detects replay attacks
• @bernierllc/validators-crypto-parameters - Validates cryptographic parameters

Examples

CI/CD Security Scanning

import { validateSecurity } from '@bernierllc/validators-security';
import { createSharedUtils } from '@bernierllc/validators-utils';
import * as fs from 'fs';

const utils = createSharedUtils();

// Scan source code for secrets
const sourceCode = fs.readFileSync('./src/config.ts', 'utf-8');

const result = await validateSecurity(
  { code: sourceCode },
  {
    validateSecrets: true,
    severity: 'error',
  },
  utils
);

if (result.problems.length > 0) {
  console.error('Security issues found:');
  result.problems.forEach(problem => {
    console.error(`- ${problem.message} (${problem.ruleId})`);
  });
  process.exit(1);
}

API Response Header Validation

const responseHeaders = {
  'Content-Security-Policy': response.headers['content-security-policy'],
  'X-Frame-Options': response.headers['x-frame-options'],
  'Strict-Transport-Security': response.headers['strict-transport-security'],
};

const result = await validateSecurity(
  { headers: responseHeaders },
  {
    validateHeaders: true,
    headersOptions: {
      requireCSP: true,
      requireHSTS: true,
    },
  },
  utils
);

if (result.problems.length > 0) {
  console.warn('Security header issues:', result.problems);
}

Webhook Signature Validation

const request = {
  body: JSON.stringify(webhookPayload),
  signature: req.headers['x-webhook-signature'],
  timestamp: parseInt(req.headers['x-webhook-timestamp']),
};

const result = await validateSecurity(
  { request },
  {
    validateSignatures: true,
    signaturesOptions: {
      maxTimestampAge: 300, // 5 minutes
      algorithm: 'sha256',
    },
  },
  utils
);

if (result.problems.length > 0) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Cryptographic Configuration Audit

const cryptoConfig = {
  algorithm: config.encryption.algorithm,
  keySize: config.encryption.keySize,
  iterations: config.hashing.iterations,
};

const result = await validateSecurity(
  { crypto: cryptoConfig },
  {
    validateCryptoParameters: true,
    cryptoOptions: {
      minKeySize: 2048,
      minIterations: 10000,
      allowedAlgorithms: ['AES-256-GCM', 'RSA-2048', 'SHA-256'],
    },
  },
  utils
);

if (result.problems.some(p => p.severity === 'error')) {
  console.error('Cryptographic configuration is not secure');
}

Integration

Integration Status

• Logger Integration: not-applicable - Domain validator with no logging requirements. This is a pure validation function that composes primitive validators and has no need for @bernierllc/logger integration.
• Docs-Suite: ready - Full TypeDoc documentation available
• NeverHub Integration: not-applicable - Pure validation function with no service dependencies. This validator has no need for @bernierllc/neverhub-adapter as it performs synchronous validation with no external service communication.

Used By

• Web application security audits
• CI/CD security scanning pipelines
• API security validation
• Configuration security reviews

License

Copyright (c) 2025 Bernier LLC. All rights reserved.