@syntropysoft/praetorian

v0.0.4-alpha

Published

2 months ago

Praetorian CLI – A universal multi-environment configuration validator for DevSecOps teams. Validate, compare, and secure YAML/ENV files with ease.

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

[x] Multi-format adapters: JSON, YAML, .env, TOML, INI, XML, Properties, HCL, PLIST
[x] Key comparison and required keys validation
[x] Environment mapping and auto-create for missing files
[x] Declarative Rule System: core/local/custom ruleSets, overrides, and customRules
[x] DevSecOps template (praetorian init --devsecops) with environment-specific sources
[x] Security features: secret detection, vulnerability scanning, compliance checks
[x] Permission validation for security-sensitive files
[x] Functional validation engine (pure functions, guard clauses)
[x] Plugin system (loader, manager, health checks)
[x] CLI commands: init, validate
[x] 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:

| Format | Extensions | Status | Notes | |--------|------------|--------|-------| | JSON | .json | ✅ Full Support | Native support with nested object validation | | YAML | .yaml, .yml | ✅ Full Support | Supports anchors, aliases, and complex structures | | Environment | .env, env.* | ✅ Full Support | Key-value pairs with type inference | | TOML | .toml | ✅ Full Support | Table-based configuration format | | INI | .ini, .cfg, .conf | ✅ Full Support | Section-based configuration | | XML | .xml | ✅ Full Support | Nested element validation | | Properties | .properties | ✅ Full Support | Java-style properties with multiple separators | | HCL | .hcl, .tf, .tfvars | ✅ Full Support | HashiCorp Configuration Language | | PLIST | .plist | ✅ Full Support | Apple Property List format |

✅ 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:[email protected]: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

[x] Schema validation - Type checking and pattern matching ✅ COMPLETED v0.0.4-alpha
[x] Security rules - Detect sensitive data exposure ✅ COMPLETED v0.0.4-alpha
[x] Pattern matching - Advanced regex and format validation ✅ COMPLETED v0.0.4-alpha
[x] Enhanced testing - Comprehensive test coverage and mutation testing ✅ COMPLETED v0.0.4-alpha
[x] 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

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!