Praetorian CLI 🏛️

Guardian of Configurations – Universal Validation Framework for DevSecOps

⚠️ NOTICE: This is an ALPHA release. While thoroughly tested with 1225+ tests and 38.32% mutation score, it's still under active development. Use in production with caution.

🚀 LATEST: v0.0.4-alpha with Pipeline Mode support for CI/CD integration!

  ____                 _             _                ____ _     ___ 
 |  _ \ _ __ __ _  ___| |_ ___  _ __(_) __ _ _ __    / ___| |   |_ _|
 | |_) | '__/ _` |/ _ \ __/ _ \| '__| |/ _` | '_ \  | |   | |    | | 
 |  __/| | | (_| |  __/ || (_) | |  | | (_| | | | | | |___| |___ | | 
 |_|   |_|  \__,_|\___|\__\___/|_|  |_|\__,_|_| |_|  \____|_____|___|
                                                                     
🛡️  Guardian of Configurations & Security

🎉 ALPHA-4 RELEASE HIGHLIGHTS

🚀 Praetorian CLI v0.0.4-alpha - PIPELINE MODE RELEASE!

✅ NEW FEATURES & IMPROVEMENTS:

• 🏗️ Clean Architecture - Complete codebase reorganization with SOLID principles
• 🧪 Robust Testing - 557 tests passing with comprehensive coverage (100% success rate)
• 🧬 Mutation Testing - 22.40% mutation score with improved test quality
• 📦 Optimized Dependencies - 36 unnecessary packages removed (66% reduction)
• 🔧 Enhanced Build System - Improved TypeScript compilation and error handling
• 📚 Professional Documentation - Complete English documentation with working examples
• 🎯 Perfect Example - Ready-to-use example that demonstrates best practices
• 🛡️ Plugin System - Functional plugin architecture for extensibility
• ⚡ Performance Improvements - Faster validation and better error handling
• 🧹 Automatic Cleanup - Smart temporary file management
• 🔍 Advanced Validation - Improved key comparison and structure validation
• 🎨 Declarative Programming - Functional patterns with 100% mutation score
• 🔧 Multi-Format Support - 9 file formats supported with clean adapters
• 🔒 Schema Validation - NEW! JSON Schema validation with type checking and pattern matching
• 🎯 Pattern Matching - NEW! Advanced pattern validation (email, URL, UUID, regex)
• 🛡️ Security Rules - NEW! Secret detection, vulnerability scanning, and compliance checking
• 🔐 Secret Detection - NEW! Detect exposed API keys, passwords, and sensitive data
• 🔍 Vulnerability Scanning - NEW! Scan for weak encryption, SQL injection, XSS vulnerabilities
• 📋 Compliance Checking - NEW! PCI-DSS, GDPR, HIPAA, SOX, ISO 27001 compliance validation
• 🚀 Pipeline Mode - NEW! CI/CD friendly output with --pipeline flag for automated workflows
• 📊 Dual Output Modes - User-friendly detailed output + concise pipeline output
• 🔧 DevSecOps Integration - Ready for Jenkins, GitHub Actions, Dockerfile, and Makefile integration
• 🔧 Permission Validation - NEW! File permission validation for security-sensitive files

✅ CORE FEATURES (All Working):

• CLI with professional banner - Beautiful ASCII art with security colors
• Key comparison - Compare keys across multiple configuration files (JSON/YAML/ENV/TOML/INI/XML/Properties/HCL/PLIST)
• Multi-folder support - Works with files in different directories
• C# compatibility - Supports appsettings.json and other .NET configurations
• Configuration file - praetorian.yaml for defining files to compare
• Exit codes - Proper exit codes for CI/CD integration
• Missing file detection - Automatically create empty structure files for missing configurations
• Required keys validation - Ensure mandatory configuration keys are present
• Environment mapping - Support for environment-specific configuration files

🚧 COMING IN FUTURE RELEASES:

• JSON/HTML reports for CI/CD
• Improved mutation score (50%+ target)
• Custom rule plugins & audit engine
• Secret management integrations (AWS/Azure/GCP)
• Performance optimizations (parallel processing)

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

✅ Feature Checklist (At a Glance)

Available

• Multi-format adapters: JSON, YAML, .env, TOML, INI, XML, Properties, HCL, PLIST
• Key comparison and required keys validation
• Environment mapping and auto-create for missing files
• Declarative Rule System: core/local/custom ruleSets, overrides, and customRules
• DevSecOps template (praetorian init --devsecops) with environment-specific sources
• Security features: secret detection, vulnerability scanning, compliance checks
• Permission validation for security-sensitive files
• Functional validation engine (pure functions, guard clauses)
• Plugin system (loader, manager, health checks)
• CLI commands: init, validate
• 557 tests across 34 suites; mutation testing configured (22.40%)

Planned

• JSON/HTML reports for CI/CD
• Improved mutation score (50%+ target)
• Custom rule plugins & audit engine
• Secret management integrations (AWS/Azure/GCP)
• Performance optimizations (parallel processing)

🚀 Description

Concept Overview

• Schema Validation: Validates objects against a JSON-like schema (types, required fields, ranges, nested structures). Designed for fast, pure-functional checks with clear error codes.
• Pattern Matching: Validates strings using known formats (email, URL, UUID, semver) and custom regex patterns; supports warnings or errors via rule severity.
• Security Rules: Detects secrets, weak constructs and compliance issues via rule sets; configurable by environment with guard-clause based evaluators.
• Permission Validation: Checks file permissions by file type and provides recommended secure modes (e.g., .env → 600, config.* → 644).
• Rule Loader & Dictionary: Loads rules from core/local/remote sources, deduplicates by unique ID, supports overrides and user-defined custom rules.
• DevSecOps Rule Connector: Declarative source selection per environment; merges, overrides and disables rules deterministically; CI/CD friendly.

Praetorian CLI is a multi-environment configuration validation tool designed for DevSecOps teams. It ensures that your configuration files remain consistent across environments, enables declarative rule sets, and integrates seamlessly with CI/CD pipelines.

Perfect for:

• 🏗️ Microservices architectures with multiple config files
• 🔄 Multi-environment deployments (dev, staging, prod)
• 🛡️ Security compliance and configuration drift detection
• 🚀 CI/CD pipelines requiring config validation
• 📝 Development workflow - Auto-create missing configuration structures

✨ Features

• 🛡️ Multi-file, multi-environment validation (dev, staging, prod)
• 🔍 Detects missing keys or inconsistent values across files
• 📁 Multi-folder support - Compare files in different directories
• 🔧 Framework agnostic - Works with any tech stack
• 📝 Simple setup with praetorian.yaml
• 📦 CI/CD friendly with proper exit codes
• 🔑 Supports ignored keys and required keys validation
• 🆕 Auto-create missing files - Generate empty structure files for missing configurations
• 🌍 Environment mapping - Validate specific environments or all environments

🔧 Compatible With

• Configuration Formats: JSON, YAML, .env, TOML, INI, XML files
• Frameworks: Node.js, .NET (appsettings.json), Python, Java, Go, Rust
• Environments: Development, Staging, Production, Testing
• Architectures: Monoliths, Microservices, Serverless
• Platforms: Docker, Kubernetes, Cloud (AWS, Azure, GCP)

📁 Supported File Formats

Praetorian supports multiple configuration file formats through its modular adapter system:

✅ Recent Fixes

PLIST File Adapter - Bug Fixed! 🎉

Issue: Complex nested structures with arrays containing objects were not fully supported.

Status: ✅ FIXED - The PlistFileAdapterV2 now correctly handles complex array structures.

What was fixed:

• ✅ Simple arrays work correctly: <array><string>item1</string><string>item2</string></array>
• ✅ Nested dictionaries work correctly: <dict><key>nested</key><dict>...</dict></dict>
• ✅ Arrays with objects now work perfectly: <array><dict>...</dict><dict>...</dict></array>

Example of now-working structure:

<dict>
    <key>configs</key>
    <array>
        <dict>
            <key>debug</key>
            <true/>
            <key>env</key>
            <string>dev</string>
        </dict>
        <dict>
            <key>debug</key>
            <false/>
            <key>env</key>
            <string>prod</string>
        </dict>
    </array>
</dict>

Result: { configs: [{ debug: true, env: 'dev' }, { debug: false, env: 'prod' }] } ✅

Technical Details: The fix involved properly handling the currentKey storage in the PlistStateManager when processing arrays, ensuring that arrays are correctly associated with their parent dictionary keys.

🚀 Quick Start

# config.yaml
database:
  host: localhost
  port: 5432

DevSecOps Quick Start (NEW)

# Generate DevSecOps template
praetorian init --devsecops --config praetorian.yaml

# Validate by environment
praetorian validate --env dev --config praetorian.yaml
praetorian validate --env prod --config praetorian.yaml

// config.json
{
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

# config.toml
[database]
host = "localhost"
port = 5432

# config.ini
[database]
host=localhost
port=5432

<!-- config.xml -->
<config>
  <database>
    <host>localhost</host>
    <port>5432</port>
  </database>
</config>

📦 Installation

npm install -g @syntropysoft/praetorian

Prerequisites:

• Node.js 18+ (recommended: use NVM)
• npm or yarn

⚙️ Basic Configuration

Create a praetorian.yaml file:

files:
  - config-dev.yaml
  - config-prod.yaml
  - config-staging.yaml

ignore_keys:
  - debug
  - temp

required_keys:
  - database.host
  - database.port
  - api.version
  - api.port

environments:
  dev: config-dev.yaml
  prod: config-prod.yaml
  staging: config-staging.yaml

🛠️ Usage

Available Commands

# Validate configuration files for key consistency
praetorian validate [FILES] [OPTIONS]

# Initialize a new configuration file
praetorian init [OPTIONS]

# Generate DevSecOps configuration template
praetorian init --devsecops [--config devsecops.yaml]

Basic Validation

Validate that all configuration files have matching keys:

praetorian validate

Output example:

📊 Validation Results:
✅ All configuration files are consistent!
📈 Summary:
  • Files compared: 3
  • Total keys: 15
  • Duration: 2ms

In case of differences:

❌ Key inconsistencies found:
  • Key 'database.url' is missing in config-staging.yaml
  • Key 'api.timeout' is missing in config-dev.yaml

Environment-Specific Validation

Validate a specific environment:

praetorian validate --env dev

Validate all environments:

praetorian validate --all

Missing File Detection

When files are missing, Praetorian automatically creates empty structure files:

⚠️  Missing files detected: config-staging.yaml
💡 Creating empty structure files...
✅ Created 1 empty structure file(s)

The created file will have the structure based on required_keys:

# config-staging.yaml (auto-created)
database:
  host: null
  port: null
api:
  version: null
  port: null

Rule System (NEW)

Praetorian uses a declarative, unified, and extensible rule system.

Concepts:

• ruleSets: list of rule sources to load (core/local/remote)
• overrideRules: override properties by id (e.g., severity)
• customRules: additional user-defined rules

Minimal praetorian.yaml example:

ruleSets:
  - "@praetorian/core/all"
  - "./rules/structure.yaml"
  - "./rules/security.yaml"

overrideRules:
  - id: "version-format"
    severity: "warning"

customRules:
  - id: "team-tag-required"
    name: "Team Tag Required"
    description: "Every config must include team tag"
    type: "structure"
    severity: "error"
    enabled: true
    category: "governance"
    requiredProperties: ["metadata.team"]

📋 Examples

🎯 Quick Examples

Example 1: Basic Configuration Files

# config-dev.yaml
app:
  name: my-app
  debug: true
  port: 3000

database:
  host: localhost
  port: 5432

# config-prod.yaml
app:
  name: my-app
  port: 80

database:
  host: prod-db.example.com
  port: 5432
  url: postgresql://user:pass@prod-db.example.com:5432/db

Example 2: C# appsettings.json

// apps/web/appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=WebApp;"
  },
  "AppSettings": {
    "ApiKey": "web-api-key-12345",
    "BaseUrl": "https://web.example.com"
  }
}

Example 3: Multi-folder Structure

# praetorian.yaml
files:
  - configs/frontend/app.config.json
  - configs/backend/app.config.json
  - apps/web/appsettings.json
  - apps/api/appsettings.json

ignore_keys:
  - debug
  - Logging
  - AllowedHosts

required_keys:
  - database.host
  - api.port
  - logging.level

Example 4: Environment Mapping

# environments.yaml
dev: config-dev.yaml
staging: config-staging.yaml
production: config-prod.yaml

# Validate specific environment
praetorian validate --environments environments.yaml --env dev

# Validate all environments
praetorian validate --environments environments.yaml --all

📚 Complete Examples

Check out our examples directory for comprehensive examples:

• Perfect Example - NEW! Complete working example with consistent structure
• Missing Files Demo - NEW! Automatic file creation demonstration
• YAML Examples - Basic YAML configuration validation
• JSON Examples - JSON configuration files
• ENV Examples - Environment file validation
• .NET Examples - C# appsettings.json and multi-folder validation

Each example includes:

🔒 NEW: Advanced Security Features

🛡️ Secret Detection

Detect exposed sensitive data in configuration files:

# Run validation (secrets detection is enabled via ruleSets)
praetorian validate --config praetorian.yaml

Supported Secret Types:

• API Keys: sk-, pk_, ak_, api_key
• JWT Tokens: eyJ...
• Passwords: password: "mypassword123"
• Database URLs: mysql://user:pass@host/db

🔍 Vulnerability Scanning

Scan for security vulnerabilities:

# Run validation (vulnerability checks are enabled via ruleSets)
praetorian validate --config praetorian.yaml

Detected Vulnerabilities:

• Weak Encryption: MD5, SHA1, DES, RC4
• Insecure Protocols: HTTP, FTP, Telnet
• Weak Credentials: Default passwords, short passwords
• SQL Injection: String interpolation in queries
• XSS: innerHTML with interpolation

📋 Compliance Checking

Verify compliance with security standards:

# Run validation (compliance checks are enabled via ruleSets)
praetorian validate --config praetorian.yaml

Supported Standards:

• PCI DSS: Credit card data encryption
• GDPR: Personal data protection
• HIPAA: Health information access control
• SOX: Financial data controls
• ISO 27001: Information security management

🔧 Permission Validation

Validate file permissions for security:

# Run validation (permission checks are enabled via ruleSets)
praetorian validate --config praetorian.yaml

Permission Rules:

• Environment Files: .env → 600 permissions
• Config Files: config.* → 644 permissions
• Secret Files: *secret* → 600 permissions
• Key Files: *.key → 600 permissions

🧪 Testing & Quality

Comprehensive Test Suite

• ✅ 557 tests passing across 34 test suites (100% success rate)
• ✅ Unit tests for all core functionality
• ✅ Integration tests for end-to-end validation
• ✅ Mutation testing configured with Stryker (22.40% mutation score)
• ✅ Coverage reporting for quality assurance
• ✅ Schema validation tests for new JSON Schema functionality
• ✅ Pattern matching tests for regex and format validation
• ✅ Security validation tests for secret detection and vulnerability scanning
• ✅ Permission validation tests for file security and access control

Test Coverage Highlights

• 100% coverage on core validation logic
• 100% coverage on plugin management
• 100% coverage on environment management
• 97% coverage on utility functions
• 86% coverage on validation rules
• 100% mutation score on declarative programming patterns

Mutation Testing Improvements

• FormatValidator: 72.00% mutation score (improved from 61.14%)
• PermissionValidator: 39.16% mutation score (improved from 0%)
• SchemaValidator: 25.74% mutation score (improved from 23.53%)
• SecretDetector: 22.66% mutation score (improved from 12.32%)
• Overall Project: 22.40% mutation score (improved from 20.96%)

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run mutation tests
npm run test:mutation

# Run integration tests only
npm run test:integration

# Run mutation tests
npm run test:mutation

Quality Metrics

• Clean Architecture - SOLID principles applied
• Functional Programming - Pure functions and immutability
• Type Safety - Full TypeScript coverage
• Error Handling - Comprehensive error management
• Performance - Optimized for speed and efficiency
• Sample configuration files
• praetorian.yaml setup
• Expected validation results
• Common use cases

🧩 CI/CD Integration

GitHub Actions Example

- name: Validate Configurations
  run: |
    npm install -g @syntropysoft/praetorian
    praetorian validate --config praetorian.yaml

GitLab CI Example

validate_configs:
  stage: test
  script:
    - npm install -g @syntropysoft/praetorian
    - praetorian validate

🧬 Testing & Quality Improvements v0.0.4-alpha

Enhanced Test Coverage

• +315 new tests added (from 242 to 557 total tests)
• +7 new test suites → 34 suites en total
• Permission validation tests - File permission security validation
• Enhanced schema validation tests - Complex nested object and array validation
• Improved pattern matching tests - Advanced regex and format validation
• Extended security tests - Secret detection and vulnerability scanning

Mutation Testing Enhancements

• 22.40% overall mutation score
• FormatValidator: 72.00% mutation score (+10.86% improvement)
• PermissionValidator: 39.16% mutation score (new coverage from 0%)
• SchemaValidator: 25.74% mutation score (+2.21% improvement)
• SecretDetector: 22.66% mutation score (+10.34% improvement)

Test Organization

• Hierarchical test structure - Tests organized by architectural layers
• Domain tests - Core business logic validation
• Application tests - Service and orchestrator validation
• Infrastructure tests - Adapter and plugin validation
• Integration tests - End-to-end workflow validation

🗺️ Roadmap

• Schema validation - Type checking and pattern matching ✅ COMPLETED v0.0.4-alpha
• Security rules - Detect sensitive data exposure ✅ COMPLETED v0.0.4-alpha
• Pattern matching - Advanced regex and format validation ✅ COMPLETED v0.0.4-alpha
• Enhanced testing - Comprehensive test coverage and mutation testing ✅ COMPLETED v0.0.4-alpha
• Pipeline Mode - CI/CD friendly output with --pipeline flag ✅ COMPLETED v0.0.4-alpha
• JSON/HTML reports - Detailed validation reports
• Improved mutation score - Target 50%+ mutation score for production readiness
• Custom rule plugins - Extensible validation system
• Secret management integration - AWS Secrets Manager, Azure Key Vault
• Performance optimization - Parallel processing for large configs

🏢 About SyntropySoft

Praetorian CLI is proudly developed by SyntropySoft - Your trusted partner in DevSecOps solutions.

Our Products

• 🔍 SyntropyLog - Advanced logging and monitoring platform
• 🎨 SyntropyFront - Modern frontend development framework
• 🛡️ Praetorian CLI - Configuration validation framework (you are here)

Connect With Us

• 🌐 Website
• 📧 Contact
• 💼 LinkedIn

📜 License

Apache 2.0 © SyntropySoft

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

🤝 Contributing

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

Star us on GitHub ⭐ - It helps a lot!