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!


---

``text
____ _ _ ____ _ ___
| _ \ _ __ __ _ ___| |_ ___ _ __(_) __ _ _ __ / ___| | |_ _|
| |_) | '__/ _ |/ _ \ __/ _ \| '__| |/ _ | '_ \ | | | | | |
| __/| | | (_| | __/ || (_) | | | | (_| | | | | | |___| |___ | |
|_| |_| \__,_|\___|\__\___/|_| |_|\__,_|_| |_| \____|_____|___|

🛡️ 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)

$3


- [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%)

$3

- [ ] 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

$3

- 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

$3

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: item1item2
- ✅ Nested dictionaries work correctly: nested...
- ✅ Arrays with objects now work perfectly: ......

Example of now-working structure:
`xml

configs


debug

env
dev


debug

env
prod



`

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

`yaml


config.yaml


database:
host: localhost
port: 5432
`

$3

`bash


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
`

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

`toml


config.toml


[database]
host = "localhost"
port = 5432
`

`ini


config.ini


[database]
host=localhost
port=5432
`

`xml



localhost
5432


`

---

📦 Installation

`bash
npm install -g @syntropysoft/praetorian
`

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

---

⚙️ Basic Configuration

Create a praetorian.yaml file:

`yaml
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

$3

`bash


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]

`

$3

Validate that all configuration files have matching keys:

`bash
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
`

$3

Validate a specific environment:

`bash
praetorian validate --env dev
`

Validate all environments:

`bash
praetorian validate --all
`

$3

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:

`yaml


config-staging.yaml (auto-created)


database:
host: null
port: null
api:
version: null
port: null
`

$3

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:

`yaml
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

$3

#### Example 1: Basic Configuration Files

`yaml


config-dev.yaml

app:
name: my-app
debug: true
port: 3000

database:
host: localhost
port: 5432
`

`yaml


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

`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

`yaml


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

`yaml


environments.yaml


dev: config-dev.yaml
staging: config-staging.yaml
production: config-prod.yaml
`

`bash


Validate specific environment

praetorian validate --environments environments.yaml --env dev

Validate all environments

praetorian validate --environments environments.yaml --all
`

$3

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

$3

Detect exposed sensitive data in configuration files:

`bash


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

$3

Scan for security vulnerabilities:

`bash


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

$3

Verify compliance with security standards:

`bash


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

$3

Validate file permissions for security:

`bash


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

$3

- ✅ 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

$3

- 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

$3

- 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%)

$3

`bash

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
`

$3

- 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

$3

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

$3

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

---

🧬 Testing & Quality Improvements v0.0.4-alpha

$3

- +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

$3

- 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)

$3

- 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.

$3

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

$3

- 🌐 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!