JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 90
  • Score
    100M100P100Q54556F
  • License MIT

Guardian of configurations and security - Universal validation framework for DevSecOps

Package Exports

  • @syntropysoft/praetorian
  • @syntropysoft/praetorian/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@syntropysoft/praetorian) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Praetorian Logo

SyntropySoft Praetorian ๐Ÿ›ก๏ธ

Guardian of configurations and security - Universal validation framework for DevSecOps

โš ๏ธ ALPHA VERSION WARNING

๐Ÿšจ This is an ALPHA version (0.0.1-alpha.1) - Use at your own risk!

  • Not production ready - This version is for testing and feedback only
  • API may change - Breaking changes are expected in future releases
  • Limited features - Core functionality is implemented but may have bugs
  • Testing phase - Please report issues and provide feedback

For production use, wait for stable releases (1.0.0+)

License: MIT Node.js TypeScript

๐ŸŽฏ Philosophy

Praetorian embodies the spirit of the elite Roman guard - protecting, validating, and ensuring the integrity of your configuration files. Built with complete transparency and exceptional developer experience, Praetorian is designed to be:

  • ๐Ÿ” Configuration Validator - Validate YAML, JSON, and ENV files with custom rules
  • ๐Ÿ”Œ Rule-Based System - Create and share validation rules for your infrastructure
  • โšก Developer-First - Simple APIs for configuration validation
  • ๐Ÿ›ก๏ธ Security-Focused - Built for DevSecOps and compliance teams

๐Ÿš€ Quick Start

Installation

npm install @syntropysoft/praetorian

Basic Usage

import { Validator } from '@syntropysoft/praetorian';

// Create a validator with custom rules
const validator = new Validator({
  plugins: ['security', 'compliance'],
  rules: {
    'no-secrets': true,
    'required-fields': true,
    'format-validation': true
  }
});

// Validate a YAML configuration file
const result = await validator.validate({
  config: { /* your config object */ },
  context: {
    config: { /* config object */ },
    environment: 'production',
    project: 'my-app',
    timestamp: new Date(),
    metadata: {}
  }
});

console.log(result.success ? 'โœ… Configuration Valid' : 'โŒ Configuration Invalid');

CLI Usage

# Validate a configuration file
praetorian validate config.yaml

# Validate with specific rules
praetorian validate config.yaml --rules security,compliance

# Run a comprehensive audit
praetorian audit --security --compliance

# Check specific configuration aspects
praetorian check --env --yaml --json

๐Ÿ—๏ธ Configuration Validation Framework

Supported File Types

  • YAML - Configuration files, Kubernetes manifests, Docker Compose
  • JSON - Package.json, configuration objects, API specs
  • ENV - Environment variables, .env files
  • Custom - Extensible for any configuration format

Core Components

  • Validator - Main validation engine for configuration files
  • AuditEngine - Comprehensive configuration auditing
  • PluginManager - Rule-based plugin system
  • BasePlugin - Foundation for custom validation rules

๐Ÿ”Œ Rule-Based Validation System

Built-in Rules

// Security Rules
const securityRules = {
  'no-secrets-in-code': {
    description: 'Detect hardcoded secrets in configuration',
    severity: 'error',
    validate: (config) => {
      // Check for API keys, passwords, tokens
    }
  },
  'required-security-headers': {
    description: 'Ensure security headers are configured',
    severity: 'warning',
    validate: (config) => {
      // Validate security headers
    }
  }
};

// Compliance Rules
const complianceRules = {
  'required-fields': {
    description: 'Ensure all required fields are present',
    severity: 'error',
    validate: (config) => {
      // Check required fields
    }
  },
  'format-validation': {
    description: 'Validate configuration format',
    severity: 'warning',
    validate: (config) => {
      // Validate format
    }
  }
};

Custom Rules

import { BasePlugin } from '@syntropysoft/praetorian';

class CustomValidationPlugin extends BasePlugin {
  protected initializeRules() {
    this.addRule({
      id: 'custom-yaml-structure',
      name: 'Custom YAML Structure Validation',
      description: 'Validate specific YAML structure for your project',
      category: 'custom',
      severity: 'error',
      enabled: true
    });
  }

  protected async executeRule(rule, config, context) {
    // Your custom validation logic here
    if (rule.id === 'custom-yaml-structure') {
      // Validate your specific YAML structure
      return this.validateYamlStructure(config);
    }
  }

  private validateYamlStructure(config) {
    // Custom validation logic
    const errors = [];
    
    // Example: Check if required sections exist
    if (!config.database) {
      errors.push({
        code: 'MISSING_DATABASE_SECTION',
        message: 'Database configuration section is required',
        severity: 'error'
      });
    }

    return {
      success: errors.length === 0,
      errors,
      warnings: []
    };
  }
}

๐Ÿ“‹ Configuration Examples

YAML Configuration Validation

# config.yaml
database:
  host: localhost
  port: 5432
  name: myapp
  credentials:
    username: admin
    password: ${DB_PASSWORD}  # โœ… Good: Using environment variable

security:
  cors:
    origin: ["https://myapp.com"]
    credentials: true
  headers:
    x-frame-options: DENY
    x-content-type-options: nosniff

logging:
  level: info
  format: json
  output: stdout

Validation Rules for YAML

const yamlRules = {
  'database-credentials': {
    description: 'Database credentials must use environment variables',
    validate: (config) => {
      const errors = [];
      if (config.database?.credentials?.password && 
          !config.database.credentials.password.startsWith('${')) {
        errors.push({
          code: 'HARDCODED_PASSWORD',
          message: 'Database password should use environment variable',
          path: 'database.credentials.password'
        });
      }
      return { success: errors.length === 0, errors };
    }
  },
  'security-headers': {
    description: 'Required security headers must be present',
    validate: (config) => {
      const requiredHeaders = ['x-frame-options', 'x-content-type-options'];
      const errors = [];
      
      requiredHeaders.forEach(header => {
        if (!config.security?.headers?.[header]) {
          errors.push({
            code: 'MISSING_SECURITY_HEADER',
            message: `Missing required security header: ${header}`,
            path: `security.headers.${header}`
          });
        }
      });
      
      return { success: errors.length === 0, errors };
    }
  }
};

ENV File Validation

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/db
API_KEY=${API_KEY_SECRET}
NODE_ENV=production
PORT=3000

JSON Configuration Validation

{
  "app": {
    "name": "my-application",
    "version": "1.0.0",
    "environment": "production"
  },
  "database": {
    "url": "${DATABASE_URL}",
    "pool": {
      "min": 2,
      "max": 10
    }
  },
  "security": {
    "jwt": {
      "secret": "${JWT_SECRET}",
      "expiresIn": "24h"
    }
  }
}

๐ŸŽฏ Integration Examples

CI/CD Pipeline Integration

# .github/workflows/validate-config.yml
name: Validate Configuration
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Praetorian
        run: npm install @syntropysoft/praetorian
      
      - name: Validate Configuration
        run: |
          praetorian validate config.yaml --rules security,compliance
          praetorian validate .env --rules env-validation
          praetorian validate package.json --rules json-structure

Local Development

# Pre-commit validation
praetorian validate config.yaml --strict

# Development environment check
praetorian check --env dev --yaml config-dev.yaml

# Production readiness audit
praetorian audit --security --compliance --performance

๐Ÿ”ง Configuration

Praetorian Configuration File

# praetorian.yaml
plugins:
  - name: security
    enabled: true
    config:
      max-severity: error
  - name: compliance
    enabled: true
    config:
      standards: [SOC2, ISO27001]

rules:
  no-secrets-in-code: true
  required-fields: true
  format-validation: true
  custom-yaml-structure: true

validation:
  strict: false
  fail-fast: false
  output-format: pretty

๐Ÿงช Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Run in development mode
npm run dev

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/syntropysoft/praetorian.git
cd praetorian
npm install
npm run dev

๐Ÿ“„ License

MIT License - see LICENSE for details.

๐Ÿ›๏ธ Part of the SyntropySoft Ecosystem


Praetorian - Protecting your configurations with the vigilance of the elite guard. ๐Ÿ›ก๏ธ