{ "report_info": { "version": "9.0.1", "generated_at": "2026-04-02T13:42:28Z", "target_directory": "/home/kodachi/k900/dashboard/hooks", "total_binaries": 25 }, "binaries": [ { "name": "deps-checker", "path": "/home/kodachi/k900/dashboard/hooks/deps-checker", "timestamp": "2026-04-02T13:42:13Z", "file_info": { "size": 2478880, "sha256": "7c0117ea2d008914c786e0c4928bfe231774482109dee395f49396a55f16a42f" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "Dependency checker for Kodachi OS Rust binaries - Validates system dependencies and generates installation scripts", "features": [ "Multi-profile dependency checking (minimal/full)", "Automatic missing package installation", "Installation script generation for multiple shells", "Software Bill of Materials (SBOM) generation", "External dependency database support", "Comprehensive JSON output for automation", "Strict mode for CI/CD pipelines", "Dry-run mode for safe previewing" ], "license": "Proprietary", "name": "deps-checker", "securityFeatures": { "authentication": "Secure package repository authentication", "encryption": "TLS for all package downloads", "inputValidation": "All user inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for package operations" }, "systemRequirements": { "dependencies": [ "apt-get", "dpkg", "curl" ], "os": "Linux (Debian-based, Kodachi OS)", "privileges": "root/sudo required for package installation" }, "version": "9.0.1", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:13.612405809Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T13:42:13.676151051Z", "gitCommit": "unknown", "name": "deps-checker", "rustVersion": "rustc 1.94.1 (e408947bf 2026-03-25)", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:13.676152356Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Dependency Checking", "commands": [ { "description": "Check dependencies for a specific binary", "examples": [ "deps-checker check dns-switch", "deps-checker check dns-switch --profile minimal", "deps-checker check dns-switch --json", "deps-checker check dns-switch --profile full --json" ], "name": "check", "options": [ { "default": "full", "description": "Dependency profile to use (default: full)", "flag": "-p, --profile ", "required": false }, { "description": "Path to external dependency database", "flag": "--db ", "required": false } ], "requires_sudo": false, "usage": "deps-checker check [OPTIONS] " }, { "description": "Check dependencies for all known binaries", "examples": [ "deps-checker check-all", "deps-checker check-all --profile full", "deps-checker check-all --json", "deps-checker check-all --strict --json" ], "name": "check-all", "options": [ { "default": "full", "description": "Dependency profile to use (default: full)", "flag": "-p, --profile ", "required": false }, { "description": "Treat warnings as errors", "flag": "--strict", "required": false } ], "requires_sudo": false, "usage": "deps-checker check-all [OPTIONS]" }, { "description": "Install missing packages for specified binary or all", "examples": [ "deps-checker install-missing dns-leak", "deps-checker install-missing all", "deps-checker install-missing all --json" ], "name": "install-missing", "options": [ { "default": "full", "description": "Dependency profile to use (default: full)", "flag": "-p, --profile ", "required": false }, { "description": "Preview without executing", "flag": "--dry-run", "required": false } ], "requires_sudo": true, "usage": "deps-checker install-missing [OPTIONS] " }, { "description": "List all known binaries", "examples": [ "deps-checker list-binaries", "deps-checker list-binaries --json" ], "name": "list-binaries", "options": [], "requires_sudo": false, "usage": "deps-checker list-binaries [OPTIONS]" }, { "description": "List available profiles for a binary", "examples": [ "deps-checker list-profiles health-control", "deps-checker list-profiles health-control --json" ], "name": "list-profiles", "options": [], "requires_sudo": false, "usage": "deps-checker list-profiles [OPTIONS] " } ] }, { "category": "Script Generation", "commands": [ { "description": "Generate installation script from JSON input", "examples": [ "deps-checker check-all --json | deps-checker generate-script", "deps-checker check-all --json | deps-checker generate-script --shell zsh", "deps-checker check-all --json | deps-checker generate-script --execute" ], "name": "generate-script", "options": [ { "default": "bash", "description": "Shell syntax for scripts (default: bash)", "flag": "--shell ", "required": false }, { "description": "Execute the generated script", "flag": "--execute", "required": false }, { "description": "Preview without executing", "flag": "--dry-run", "required": false } ], "requires_sudo": true, "usage": "deps-checker generate-script [OPTIONS]" } ] } ], "description": "Dependency checker for Kodachi OS Rust binaries", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "~/.config/deps-checker/config.json", "description": "Path to configuration file", "name": "DEPS_CHECKER_CONFIG", "values": "/path/to/config.json" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " }, { "description": "Dependency profile to use (minimal/full)", "flag": "-p, --profile " }, { "description": "Shell syntax for scripts (bash/zsh/fish)", "flag": "--shell " }, { "description": "Write output to file instead of stdout", "flag": "-o, --output " }, { "description": "Path to external dependency database", "flag": "--db " }, { "description": "Treat warnings as errors (exit code 1)", "flag": "--strict" }, { "description": "Don't execute network operations", "flag": "--dry-run" }, { "description": "Execute generated installation script", "flag": "--execute" }, { "description": "Generate Software Bill of Materials in CycloneDX JSON", "flag": "--sbom" } ], "name": "deps-checker", "usage": "deps-checker [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:13.739162671Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Common dependency checking operations", "examples": [ { "command": "deps-checker check dns-switch", "description": "Check single binary - shows profile, status, dependencies and conflicts", "expectedOutput": "Dependency status report for dns-switch", "notes": "Shows all required packages and their status" }, { "command": "deps-checker check dns-switch --json", "description": "JSON output for scripting", "expectedOutput": "JSON formatted dependency report", "notes": "Includes exit codes and machine-readable format" }, { "command": "deps-checker check-all", "description": "Overview of all dependencies", "expectedOutput": "Summary of all binaries and their dependency status", "notes": "Shows counts and overall system status" }, { "command": "deps-checker check-all --json -o deps-check-report.json", "description": "Save full dependency check report to file", "expectedOutput": "JSON dependency report saved to file", "notes": "Useful for automated processing and CI/CD" }, { "command": "sudo deps-checker install-missing dns-leak", "description": "Install for specific binary", "expectedOutput": "Package installation status", "notes": "Only installs packages needed by dns-leak" }, { "command": "sudo deps-checker install-missing all", "description": "Install all missing packages", "expectedOutput": "Mass installation status", "notes": "Installs all missing dependencies system-wide" }, { "command": "deps-checker list-binaries", "description": "Show all supported binaries", "expectedOutput": "List of all supported Rust binaries", "notes": "Shows which binaries can be checked" }, { "command": "deps-checker list-profiles health-control", "description": "Show available profiles (minimal/full)", "expectedOutput": "Available dependency profiles", "notes": "Different dependency sets for different use cases" } ], "id": "1_basic_commands", "title": "Basic Commands" }, { "description": "Different dependency sets for specific use cases", "examples": [ { "command": "deps-checker check health-control -p minimal", "description": "Minimal profile - core dependencies only", "expectedOutput": "Essential packages for basic functionality", "notes": "Smallest footprint, core features only" }, { "command": "deps-checker check health-control -p full", "description": "Full profile - includes audio, security tools, etc", "expectedOutput": "Complete package list including optional features", "notes": "Maximum functionality, larger footprint" }, { "command": "deps-checker check-all -p full", "description": "Apply full profile to all binaries", "expectedOutput": "Full dependency check for all binaries", "notes": "Comprehensive system-wide analysis" } ], "id": "2_profile_usage", "title": "Profile Usage" }, { "description": "Generate automated installation scripts", "examples": [ { "command": "deps-checker check-all --json | deps-checker generate-script", "description": "Generate install script from check results", "expectedOutput": "Shell script to install missing packages", "notes": "Creates executable script based on current system state" }, { "command": "deps-checker check-all --json | deps-checker generate-script --shell zsh", "description": "Generate for zsh shell", "expectedOutput": "Zsh-compatible installation script", "notes": "Optimized for zsh shell environment" }, { "command": "deps-checker check-all --json | deps-checker generate-script --dry-run", "description": "Preview script without executing", "expectedOutput": "Script preview without installation", "notes": "Useful for reviewing changes before applying" }, { "command": "deps-checker check-all --json | sudo deps-checker generate-script --execute", "description": "Generate and execute installation", "expectedOutput": "Script generated and executed immediately", "notes": "One-step solution for installing all dependencies" } ], "id": "3_installation_scripts", "title": "Installation Script Generation" }, { "description": "Advanced configuration and output control", "examples": [ { "command": "deps-checker check-all --strict", "description": "Exit code 1 if warnings exist", "expectedOutput": "Strict validation with non-zero exit on warnings", "notes": "Useful for CI/CD pipelines requiring zero warnings" }, { "command": "deps-checker check-all --db ./custom-deps-db", "description": "Use custom TOML definitions", "expectedOutput": "Dependency check using custom database", "notes": "Allows custom dependency definitions" }, { "command": "deps-checker check dns-switch -o dns-switch-deps-report.json --json", "description": "Save single binary dependency check to file", "expectedOutput": "JSON report saved to dns-switch-deps-report.json", "notes": "Targeted dependency report for specific binary" }, { "command": "deps-checker check-all -o deps-check-full-report.json --json", "description": "Save comprehensive dependency report to file", "expectedOutput": "Comprehensive JSON dependency report saved to file", "notes": "Complete system dependency analysis" } ], "id": "4_advanced_options", "title": "Advanced Options" }, { "description": "Basic information and help commands", "examples": [ { "command": "deps-checker --version", "description": "Show version", "expectedOutput": "Version information" }, { "command": "deps-checker --info", "description": "Show program details", "expectedOutput": "Detailed program information", "notes": "Includes author, features, and system requirements" }, { "command": "deps-checker --help", "description": "Show help", "expectedOutput": "Command usage help" }, { "command": "deps-checker --examples", "description": "Show this examples page", "expectedOutput": "Usage examples" } ], "id": "5_quick_info", "title": "Quick Information" }, { "description": "Typical usage patterns and workflows", "examples": [ { "command": "deps-checker check-all", "description": "See what's missing", "expectedOutput": "Overview of missing dependencies", "notes": "First step in dependency management workflow" }, { "command": "sudo deps-checker install-missing all", "description": "Install everything missing", "expectedOutput": "Installation of all missing packages", "notes": "Follow-up command after checking dependencies" }, { "command": "deps-checker check-all -o deps-check-report.json --json", "description": "Generate dependency check report", "expectedOutput": "JSON dependency report saved for review", "notes": "Part of review-before-install workflow" }, { "command": "cat deps-check-report.json | jq '.summary'", "description": "Review dependency report summary", "expectedOutput": "Summary of dependency status", "notes": "Use jq to parse JSON report" }, { "command": "deps-checker check-all --strict || exit 1", "description": "Fail build on warnings", "expectedOutput": "Exit code 1 if any warnings exist", "notes": "CI/CD integration pattern" }, { "command": "deps-checker check-all --json | jq -e '.summary.with_missing == 0'", "description": "Check if all satisfied", "expectedOutput": "Boolean result of dependency satisfaction", "notes": "Automated validation for CI/CD" }, { "command": "deps-checker check-all --json | jq '.summary.exit_code'", "description": "Get exit code for automation", "expectedOutput": "Numeric exit code", "notes": "For automated decision making" }, { "command": "deps-checker check-all --sbom", "description": "Generate CycloneDX SBOM for software inventory", "expectedOutput": "Software Bill of Materials in CycloneDX format", "notes": "For security scanning and compliance" }, { "command": "deps-checker check-all --sbom -o deps-check-sbom.json", "description": "Save SBOM to file for compliance tracking", "expectedOutput": "SBOM saved to file", "notes": "Persistent SBOM for audit trails" } ], "id": "6_common_workflows", "title": "Common Workflows" } ], "description": "Usage examples for deps-checker", "name": "deps-checker", "quickReference": [ "deps-checker --help", "deps-checker --version", "deps-checker --info --json", "deps-checker --examples --json", "deps-checker check-all", "sudo deps-checker install-missing all" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:13.866853669Z", "version": "9.0.1", "warnings": [] } }, { "name": "workflow-manager", "path": "/home/kodachi/k900/dashboard/hooks/workflow-manager", "timestamp": "2026-04-02T13:42:14Z", "file_info": { "size": 3597064, "sha256": "42e962e4cc050aace3cf1c91ab754511a69723692850988c259c5a8b9ea3925d" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "Workflow manager for batch command execution with conditional logic", "features": [ "Template-based workflow management", "Conditional command execution", "Batch processing with retry logic", "State tracking and logging", "Concurrent execution support", "Pause steps with user confirmation", "Pattern matching and regex conditions", "JSON path subset support (dot fields + array indexes)", "Prerequisites validation before execution", "System state checking and probes", "Reusable probe functions for conditions" ], "license": "Proprietary", "name": "workflow-manager", "securityFeatures": { "authentication": "Secure authentication with certificate pinning", "encryption": "TLS 1.3 for all network communications", "inputValidation": "All inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for network operations" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.0.1", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.136185818Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T13:42:14.202022112Z", "gitCommit": "unknown", "name": "workflow-manager", "rustVersion": "1.82.0", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.202863766Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Commands", "commands": [ { "description": "Create a new workflow template", "name": "create", "options": [], "requires_sudo": false, "usage": "workflow-manager create [OPTIONS]" }, { "description": "Add a step to a workflow template", "name": "add", "options": [], "requires_sudo": false, "usage": "workflow-manager add [OPTIONS]" }, { "description": "Add a pause step to a workflow template", "name": "pause", "options": [], "requires_sudo": false, "usage": "workflow-manager pause [OPTIONS]" }, { "description": "Add an include step to a workflow template (includes another profile)", "name": "include", "options": [], "requires_sudo": false, "usage": "workflow-manager include [OPTIONS]" }, { "description": "List all workflow templates", "name": "list", "options": [], "requires_sudo": false, "usage": "workflow-manager list [OPTIONS]" }, { "description": "Show details of a workflow template", "name": "show", "options": [], "requires_sudo": false, "usage": "workflow-manager show [OPTIONS]" }, { "description": "Run a workflow template", "name": "run", "options": [], "requires_sudo": false, "usage": "workflow-manager run [OPTIONS]" }, { "description": "Update a step in a workflow template", "name": "update", "options": [], "requires_sudo": false, "usage": "workflow-manager update [OPTIONS]" }, { "description": "Delete a step from a workflow template", "name": "delete-step", "options": [], "requires_sudo": false, "usage": "workflow-manager delete-step [OPTIONS]" }, { "description": "Delete an entire workflow template", "name": "delete", "options": [], "requires_sudo": false, "usage": "workflow-manager delete [OPTIONS]" }, { "description": "Query system state", "name": "state", "options": [], "requires_sudo": false, "usage": "workflow-manager state [OPTIONS]" }, { "description": "Validate workflow prerequisites", "name": "prereq", "options": [], "requires_sudo": false, "usage": "workflow-manager prereq [OPTIONS]" } ] } ], "description": "Workflow manager for batch command execution with conditional logic", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " } ], "name": "workflow-manager", "usage": "workflow-manager [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.268799829Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Create, list, view, and delete workflow templates", "examples": [ { "command": "workflow-manager create my-workflow", "description": "Creates a new empty workflow template named 'my-workflow'", "expectedOutput": "Template 'my-workflow' created successfully" }, { "command": "workflow-manager create backup-workflow --description 'Daily backup routine'", "description": "Creates a workflow with a descriptive label", "expectedOutput": "Template 'backup-workflow' created successfully" }, { "command": "workflow-manager list", "description": "Shows all available workflow templates", "expectedOutput": "Workflow Templates (2 total)" }, { "command": "workflow-manager show my-workflow", "description": "Displays the full structure of a workflow template", "expectedOutput": "Workflow Template: my-workflow" }, { "command": "workflow-manager delete my-workflow", "description": "Permanently removes a workflow template", "expectedOutput": "Template 'my-workflow' deleted successfully" } ], "id": "template-management", "title": "Template Management" }, { "description": "Add steps to workflows. Use comma-separated commands for multiple steps in one call, or add individually.", "examples": [ { "command": "workflow-manager add my-workflow 'echo Hello World'", "description": "Adds a single command as step 1", "expectedOutput": "Step 1 added to template 'my-workflow'", "notes": "Single command creates one step" }, { "command": "workflow-manager add w1 \"sudo ip-fetch\",\"sudo online-auth check-login\",\"ip addr show\"", "description": "Add multiple steps in one command using comma separation", "expectedOutput": "3 steps added to template 'w1'", "notes": "Comma-separated commands create multiple steps automatically" }, { "command": "workflow-manager add diagnostics \"./health-control net-check\",\"./tor-switch status\",\"./dns-leak test\"", "description": "Create a diagnostic workflow with 3 steps at once", "expectedOutput": "3 steps added to template 'diagnostics'", "notes": "All steps share the same timeout and condition settings" }, { "command": "workflow-manager add my-workflow 'tar czf backup.tar.gz /data' --timeout 600", "description": "Adds a command with a 10-minute timeout", "expectedOutput": "Step added with 600 second timeout" }, { "command": "workflow-manager add my-workflow 'cleanup.sh' --condition if_success", "description": "Runs only if the previous command succeeded", "expectedOutput": "Step added with conditional execution" }, { "command": "workflow-manager add my-workflow 'notify-admin.sh' --if-contains 'ERROR'", "description": "Runs only if previous output contains 'ERROR'", "expectedOutput": "Step added with pattern matching condition" } ], "id": "adding-commands", "title": "Adding Commands to Workflows" }, { "description": "Run workflows and control execution behavior", "examples": [ { "command": "sudo workflow-manager run my-workflow", "description": "Executes all commands in the workflow sequentially", "expectedOutput": "✅ Workflow completed: Success", "notes": "Conditions are evaluated before each step" }, { "command": "sudo workflow-manager run my-workflow --dry-run", "description": "Shows what would be executed without running commands", "expectedOutput": "Dry run: 5 steps would be executed", "notes": "Use for testing workflows before execution" } ], "id": "workflow-execution", "title": "Workflow Execution" }, { "description": "Update, delete, and inspect individual workflow steps", "examples": [ { "command": "workflow-manager show my-workflow", "description": "View all steps with their IDs and details", "expectedOutput": "Step 1: echo Hello\nStep 2: ./backup.sh\nStep 3: ./cleanup.sh", "notes": "Use this to identify step IDs before updating or deleting" }, { "command": "workflow-manager delete-step my-workflow 2", "description": "Remove step #2 from the workflow", "expectedOutput": "Step 2 deleted from 'my-workflow'", "notes": "Step IDs are renumbered after deletion" }, { "command": "workflow-manager update my-workflow 1 'echo Updated Command' --timeout 300", "description": "Change step #1 command and timeout", "expectedOutput": "Step 1 updated successfully", "notes": "All step properties can be updated" } ], "id": "step-management", "title": "Managing Individual Steps" }, { "description": "Build complete workflows quickly by chaining multiple 'add' commands with &&", "examples": [ { "command": "workflow-manager create tor-recovery && workflow-manager add tor-recovery './routing-switch recover internet' --timeout 60 && workflow-manager add tor-recovery './health-control net-check' -c if_success && workflow-manager add tor-recovery './tor-switch start' -c if_success --timeout 120", "description": "Create workflow and add 3 steps in one command chain", "expectedOutput": "Template created, 3 steps added successfully", "notes": "Use && to chain commands efficiently" }, { "command": "workflow-manager add diagnostics './health-control net-check' --timeout 30 && workflow-manager add diagnostics './tor-switch status' -c if_success && workflow-manager add diagnostics './dns-leak test' -c if_success && workflow-manager add diagnostics './integrity-check verify' -c if_success", "description": "Add 4 diagnostic steps with conditional execution", "expectedOutput": "4 steps added to diagnostics workflow" }, { "command": "workflow-manager add backup 'tar czf backup.tar.gz /data' && workflow-manager pause backup --message 'Check backup size' -c if_success && workflow-manager add backup 'rsync backup.tar.gz remote:/backups' -c if_success && workflow-manager add backup 'rm backup.tar.gz' -c if_success", "description": "Build complete backup workflow with pause and cleanup", "expectedOutput": "Backup workflow with 4 steps created", "notes": "Mix commands and pauses for interactive workflows" } ], "id": "batch-building", "title": "Efficient Batch Building" }, { "description": "All available condition types with practical examples", "examples": [ { "command": "workflow-manager add my-workflow './check-status.sh' -c always", "description": "Always execute (default behavior, runs regardless)", "expectedOutput": "Step added with 'always' condition" }, { "command": "workflow-manager add my-workflow './deploy.sh' -c if_success", "description": "Execute only if previous step succeeded (exit code 0)", "expectedOutput": "Step added with if_success condition", "notes": "Most common condition for sequential workflows" }, { "command": "workflow-manager add my-workflow './rollback.sh' -c if_fail", "description": "Execute only if previous step failed (exit code ≠ 0)", "expectedOutput": "Step added with if_fail condition", "notes": "Useful for error recovery and rollback scenarios" }, { "command": "workflow-manager add my-workflow './alert-success.sh' --if-contains \"success\"", "description": "Execute if previous output contains pattern \"success\"", "expectedOutput": "Step added with pattern matching condition", "notes": "Case-sensitive - matches JSON like \\\"status\\\":\\\"success\\\"" }, { "command": "workflow-manager add my-workflow './continue.sh' --if-not-contains \"errors\"", "description": "Execute if previous output does NOT contain \"errors\"", "expectedOutput": "Step added with negative pattern condition", "notes": "Case-sensitive - checks for absence of \\\"errors\\\" in JSON output" }, { "command": "workflow-manager add my-workflow './handle-done.sh' --if-equals \"ready\"", "description": "Execute if previous output exactly equals \"ready\"", "expectedOutput": "Step added with exact match condition", "notes": "Exact match (case-sensitive) - output is trimmed before comparison" }, { "command": "workflow-manager add my-workflow './process-result.sh' --if-regex '^status: (ok|success)$'", "description": "Execute if previous output matches regex pattern", "expectedOutput": "Step added with regex condition", "notes": "Supports full regex syntax for complex matching" }, { "command": "workflow-manager add my-workflow './skip-if-hardened.sh' --if-not-regex 'HARDENED.*HARDENED.*HARDENED.*HARDENED'", "description": "Execute if output does NOT match regex (counting: skip if 4+ HARDENED found)", "expectedOutput": "Step added with if_not_regex condition", "notes": "Inverse regex match - useful for counting occurrences. Pattern matches 4+ 'HARDENED' words." }, { "command": "workflow-manager add my-workflow './alert-few-services.sh' --if-not-regex '(service.*active.*){5,}'", "description": "Execute if fewer than 5 services are active (counting with regex quantifiers)", "expectedOutput": "Step added with if_not_regex condition", "notes": "Uses regex quantifiers {5,} to count occurrences. Step runs if pattern does NOT match (< 5 services)." }, { "command": "workflow-manager add my-workflow './handle-connected.sh' --if-json-path '$.status=\"connected\"'", "description": "Execute if JSON field $.status equals 'connected'", "expectedOutput": "Step added with JSON path condition", "notes": "Previous output must be valid JSON" }, { "command": "workflow-manager add my-workflow './finland-detected.sh' --if-json-path '$.data.records[0].country_name=\"Finland\"'", "description": "Execute if JSON array element matches value", "expectedOutput": "Step added with JSON path array condition", "notes": "Supports array indexing [0], [1], etc. for nested JSON arrays" }, { "command": "workflow-manager add my-workflow './proxy-active.sh' --if-json-path '$.data.records[0].connection_status.connection_type=\"Proxy\"'", "description": "Execute if nested JSON path with array matches", "expectedOutput": "Step added with complex nested JSON path condition", "notes": "Can navigate through objects and arrays: $.path.to.array[index].field" }, { "command": "workflow-manager add my-workflow './ip-online.sh' --if-json-path '$.ip_connectivity=true'", "description": "Execute if JSON boolean field is true", "expectedOutput": "Step added with JSON boolean condition", "notes": "Supports true/false without quotes" }, { "command": "workflow-manager add my-workflow './status-check.sh' --if-json-path '$.status_code=2'", "description": "Execute if JSON number field matches", "expectedOutput": "Step added with JSON number condition", "notes": "Numbers don't need quotes: =2 not =\"2\"" } ], "id": "conditional-logic", "title": "Conditional Logic" }, { "description": "Pause steps and advanced workflow management", "examples": [ { "command": "workflow-manager pause my-workflow --message 'Review results before continuing'", "description": "Adds an interactive pause point in the workflow", "expectedOutput": "Pause step added to workflow", "notes": "User must press Enter to continue workflow execution" }, { "command": "workflow-manager pause backup --message 'Verify backup integrity' -c if_success", "description": "Conditional pause only if previous step succeeded", "expectedOutput": "Conditional pause step added", "notes": "Combine pauses with conditions for smart workflows" } ], "id": "advanced-features", "title": "Advanced Features" }, { "description": "Practical workflows using actual Kodachi commands", "examples": [ { "command": "workflow-manager create ip-verify && workflow-manager add ip-verify 'sudo ip-fetch --json' --timeout 60 && workflow-manager add ip-verify 'echo Finland detected' --if-json-path '$.data.records[0].country_name=\"Finland\"' && workflow-manager run ip-verify", "description": "Check IP geolocation and verify country", "expectedOutput": "Finland detected", "notes": "Uses JSON path with array indexing to check nested geolocation data" }, { "command": "workflow-manager create auth-check && workflow-manager add auth-check 'sudo online-auth check-login --json' --timeout 30 && workflow-manager add auth-check 'echo Session valid' --if-contains 'valid' && workflow-manager run auth-check", "description": "Verify authentication and session status", "expectedOutput": "Session valid", "notes": "Pattern matching on authentication response to confirm valid login" }, { "command": "workflow-manager create health-audit && workflow-manager add health-audit 'sudo health-control net-check --json' --timeout 60 && workflow-manager add health-audit 'echo Network online' --if-json-path '$.ip_connectivity=true' && workflow-manager add health-audit 'sudo routing-switch status --json' -c if_success --timeout 30 && workflow-manager run health-audit", "description": "Complete system health and network connectivity check", "expectedOutput": "Network online", "notes": "Combines network check with JSON boolean evaluation and cascading conditions" }, { "command": "workflow-manager create tor-verify && workflow-manager add tor-verify 'sudo tor-switch get-tor-status --json' --timeout 30 && workflow-manager add tor-verify 'echo Tor responding' --if-json-path '$.data.is_responding=true' && workflow-manager run tor-verify", "description": "Verify Tor service health and responsiveness", "expectedOutput": "Tor responding", "notes": "Checks Tor daemon status using JSON path boolean evaluation" } ], "id": "kodachi-workflows", "title": "Real-World Kodachi Workflows" }, { "description": "Define system state requirements that must be met before workflow execution", "examples": [ { "command": "# Example profile with prerequisites (edit JSON manually):\n{\n \"prerequisites\": {\n \"required\": [\n {\"check\": \"state.online\", \"expect\": true, \"error\": \"Internet connection required\"},\n {\"check\": \"state.torrify\", \"expect\": false, \"error\": \"System must not be torrified\"},\n {\"check\": \"state.tor_running\", \"expect\": true, \"error\": \"Tor must be running\"}\n ],\n \"on_failure\": \"abort\"\n }\n}", "description": "Prerequisites block in profile JSON - validates state before execution", "expectedOutput": "✅ Prerequisites validated or ❌ Prerequisites not met - aborting", "notes": "If prerequisites is null or not present, no prerequisite checks are performed" }, { "command": "workflow-manager prereq check initial_terminal_setup_wireguard_torrify", "description": "Validate prerequisites without running the workflow", "expectedOutput": "✅ All prerequisites met or ❌ Prerequisite failures listed", "notes": "Use this to test prerequisites before execution" } ], "id": "prerequisites", "title": "Prerequisites" }, { "description": "Query current system state for debugging and validation", "examples": [ { "command": "workflow-manager state", "description": "Show all system states as JSON", "expectedOutput": "{\"online\": true, \"torrify\": false, \"dnscrypt\": true, \"routing_mode\": \"wireguard\", \"tor_running\": true}" }, { "command": "workflow-manager state online", "description": "Check specific state (online connectivity)", "expectedOutput": "{\"state\": \"online\", \"value\": true}", "notes": "20 states available: online, routing_mode, vpn_connected, dnscrypt, ipv6_disabled, dns_kodachi_managed, firewall_active, kill_switch_armed, network_hardened, disk_encrypted, security_score, torrify, tor_running, tor_dns_active, tor_verified, mac_spoofing, bluetooth_enabled, wifi_enabled, authenticated, tor_instances_count" } ], "id": "state-checking", "title": "System State Checking" }, { "description": "Define reusable probe functions in profiles for complex conditions", "examples": [ { "command": "# Example profile with probes (edit JSON manually):\n{\n \"probes\": {\n \"harden_count\": {\n \"probe_type\": \"count\",\n \"expression\": \"count('harden', previous_output)\",\n \"description\": \"Count 'harden' occurrences\"\n },\n \"is_hardened\": {\n \"probe_type\": \"expression\",\n \"expression\": \"probe('harden_count') >= 4\"\n }\n },\n \"steps\": [\n {\n \"id\": 2,\n \"cmd\": \"echo 'Already hardened, skipping'\",\n \"condition\": {\n \"type\": \"if_probe\",\n \"probe\": \"is_hardened\",\n \"expect\": true\n }\n }\n ]\n}", "description": "Define probes at profile level and use in step conditions", "expectedOutput": "Step executes based on probe evaluation", "notes": "Probe types: builtin, expression, count" } ], "id": "probe-functions", "title": "Probe Functions" }, { "description": "Complete reference for workflow-level configuration options and their interactions", "examples": [ { "command": "# Global Settings in profile JSON:\n{\n \"global_settings\": {\n \"kill_policy\": \"stop\",\n \"continue_policy\": true,\n \"max_log_size\": 10485760,\n \"default_timeout\": 300,\n \"working_dir\": \".\"\n }\n}", "description": "All available global settings with default values", "expectedOutput": "kill_policy: \"stop\" (how to handle step failures)\ncontinue_policy: true (whether to continue after failures)\nmax_log_size: 10485760 bytes (max log file size)\ndefault_timeout: 300 seconds (default step timeout)\nworking_dir: \".\" (base directory for commands)", "notes": "Global settings apply to entire workflow unless overridden at step level" }, { "command": "workflow-manager show policy-demo --json", "description": "kill_policy determines workflow behavior when steps fail", "expectedOutput": "Profile JSON showing global_settings.kill_policy and continue_policy values", "notes": "kill_policy options: stop (default/safest), continue (best-effort), skip_remaining (skip rest without fail). continue_policy=true overrides kill_policy and always continues." }, { "command": "# Interaction between kill_policy and continue_policy:\nIf continue_policy = true:\n → Always continue (kill_policy ignored)\nIf continue_policy = false:\n → Check kill_policy:\n - \"stop\" → stop workflow\n - \"continue\" → continue workflow\n - \"skip_remaining\" → skip remaining steps", "description": "Priority logic: continue_policy overrides kill_policy", "expectedOutput": "continue_policy acts as master override switch\nkill_policy provides granular control when continue_policy=false", "notes": "For security-critical workflows: kill_policy='stop', continue_policy=false. For recovery workflows: kill_policy='continue', continue_policy=true" }, { "command": "# Timeout and working directory:\n{\n \"global_settings\": {\n \"default_timeout\": 180,\n \"working_dir\": \".\"\n },\n \"steps\": [\n {\n \"cmd\": \"./health-control net-check\",\n \"timeout\": 60\n }\n ]\n}", "description": "default_timeout applies to all steps, working_dir sets base path for relative commands", "expectedOutput": "Steps without explicit timeout use default_timeout (180s)\nCommands execute from working_dir path\nStep-level timeout (60s) overrides default", "notes": "max_log_size prevents runaway log growth. Logs are truncated when limit reached. Default 10MB is suitable for most workflows" } ], "id": "global-settings-reference", "title": "Global Settings Reference" }, { "description": "Complete guide to workflow prerequisites - requirements that must be met before workflow runs", "examples": [ { "command": "# Prerequisites in profile JSON:\n{\n \"prerequisites\": {\n \"authenticated\": true,\n \"online\": true,\n \"torrify\": false,\n \"on_failure\": \"abort\"\n }\n}", "description": "Prerequisites define conditions that must be true before workflow executes", "expectedOutput": "authenticated: User must be logged in with valid session\nonline: Internet connectivity required\ntorrify: Tor routing must be active (true) or inactive (false)\non_failure: Action when prerequisites not met", "notes": "Prerequisites are checked BEFORE any steps execute. All must pass (AND logic)" }, { "command": "workflow-manager show prereq-demo --json", "description": "on_failure controls behavior when prerequisites fail", "expectedOutput": "Profile JSON showing prerequisites.on_failure policy", "notes": "on_failure options: abort (default/safest), skip (optional workflows), warn (informational checks). Use abort for auth/security-critical flows." }, { "command": "# Common prerequisite patterns:\n# Security-critical workflow:\n\"prerequisites\": {\n \"authenticated\": true,\n \"on_failure\": \"abort\"\n}\n\n# Tor setup workflow:\n\"prerequisites\": {\n \"online\": true,\n \"torrify\": false,\n \"on_failure\": \"abort\"\n}\n\n# Recovery workflow (run anytime):\n\"prerequisites\": {} # Empty - no requirements", "description": "Real-world prerequisite patterns for different workflow types", "expectedOutput": "Security workflows: Require authentication\nSetup workflows: Require specific system state\nRecovery workflows: No prerequisites (always available)", "notes": "Combine prerequisites with AND logic - all must pass. For OR logic, create separate workflows" }, { "command": "# How prerequisites are checked:\nauthenticated: Check ~/.kodachi/auth/session file exists and valid\nonline: Ping check or DNS resolution test\ntorrify: Check routing-switch status for active Tor routing", "description": "Backend implementation of prerequisite checks", "expectedOutput": "Each prerequisite type has specific system check\nFailed checks trigger on_failure behavior\nPrerequisite status shown in workflow output", "notes": "Use 'workflow-manager prereq check ' to test prerequisites without running workflow" } ], "id": "prerequisites-explained", "title": "Prerequisites Explained" }, { "description": "Comprehensive reference for all condition types and evaluation logic", "examples": [ { "command": "# All supported condition types:\n1. \"always\" - Always execute (unconditional)\n2. \"never\" - Never execute (placeholder/disabled)\n3. \"if_success\" - Execute if previous step succeeded (exit code 0)\n4. \"if_fail\" - Execute if previous step failed (exit code != 0)\n5. \"if_pattern\" - Execute if previous output matches pattern (glob)\n6. \"if_not_pattern\" - Execute if previous output does NOT match pattern\n7. \"if_json_path\" - Execute if JSON path query (dot fields + [index]) returns true\n8. \"if_expression\" - Execute if complex boolean expression evaluates true\n9. \"if_probe\" - Execute based on probe function result", "description": "Complete list of condition types with brief descriptions", "expectedOutput": "Each condition type evaluates differently\nConditions determine whether step executes or skips\nMultiple steps can have same condition type", "notes": "Conditions are evaluated sequentially - each step checks its condition before executing" }, { "command": "# Pattern matching (if_pattern, if_not_pattern):\n{\n \"condition\": {\n \"type\": \"if_pattern\",\n \"pattern\": \"*SUCCESS*\"\n }\n}\n\nPattern syntax (glob-style):\n- \"*\" matches any characters (wildcard)\n- \"?\" matches single character\n- \"[abc]\" matches any char in brackets\n- \"[!abc]\" matches any char NOT in brackets\n- \"**\" recursive directory match\n\nCase-sensitive by default!", "description": "Pattern matching uses glob syntax for flexible text matching", "expectedOutput": "Patterns match against previous step's output\nWildcards allow partial matching\nCase matters: 'SUCCESS' != 'success'", "notes": "Use if_not_pattern for exclusion logic (e.g., skip if output contains ERROR)" }, { "command": "# JSON path evaluation (if_json_path):\n{\n \"condition\": {\n \"type\": \"if_json_path\",\n \"path\": \"$.status.connected\",\n \"expect\": true\n }\n}\n\nJSON path syntax:\n- \"$\" root object\n- \".field\" object field access\n- \"[index]\" array index access\n\nUnsupported in this matcher:\n- \"..\" recursive descent\n- \"*\" wildcard (all elements)", "description": "if_json_path evaluates JSON output from previous command", "expectedOutput": "Extracts value at path and compares to 'expect'\nUseful for structured command output (health-control, tor-switch)\nPath evaluation uses a strict JSONPath subset (dot fields + array indexes)", "notes": "Example: health-control --json returns JSON, use if_json_path to check specific fields like $.security.score" }, { "command": "workflow-manager add my-workflow './health-control security-status --json' --if-expression \"probe('hardened_count') >= 4\"", "description": "if_expression allows complex boolean logic combining multiple checks", "expectedOutput": "Step added with if_expression condition for runtime evaluation", "notes": "Supported operators: comparison (== != < > <= >=), logical (&& || !), functions (contains(), count(), probe()), and variables (previous_output, step_id, workflow_status)." }, { "command": "# Probe-based conditions (if_probe):\n{\n \"probes\": {\n \"is_connected\": {\n \"probe_type\": \"builtin\",\n \"check\": \"network_status\"\n }\n },\n \"steps\": [\n {\n \"condition\": {\n \"type\": \"if_probe\",\n \"probe\": \"is_connected\",\n \"expect\": true\n }\n }\n ]\n}", "description": "if_probe evaluates reusable probe functions defined in profile", "expectedOutput": "Define probe once, use in multiple steps\nProbe types: builtin (system checks), expression (custom logic), count (occurrence counting)\nCleaner than repeating same condition", "notes": "See Category 11 'Probe Functions' for detailed probe documentation" } ], "id": "condition-types-deep-dive", "title": "Condition Types Deep Dive" }, { "description": "Complete reference for all step-level configuration options", "examples": [ { "command": "# Complete step structure:\n{\n \"id\": 1,\n \"type\": \"command\",\n \"cmd\": \"sudo health-control net-check\",\n \"description\": \"Check network connectivity\",\n \"condition\": {\n \"type\": \"always\"\n },\n \"timeout\": 60,\n \"confirm\": false,\n \"nice_level\": 0\n}", "description": "All available step configuration fields with example values", "expectedOutput": "id: Unique step number (required, integer)\ntype: Step type (required: 'command', 'pause', 'include')\ncmd: Command to execute (required for command type)\ndescription: Human-readable label (required)\ncondition: Execution condition (required object)\ntimeout: Max execution seconds (optional, uses default_timeout if omitted)\nconfirm: Require user confirmation (optional, default false)\nnice_level: Process priority -20 to 19 (optional, default 0)", "notes": "Required fields: id, type, cmd (if command type), description, condition. All others optional with sensible defaults" }, { "command": "# Step types explained:\n1. \"command\" - Execute shell command\n Requires: cmd field\n Example: \"cmd\": \"sudo tor-switch status\"\n\n2. \"pause\" - Wait for user input or delay\n Requires: message field (shown to user)\n Example: \"message\": \"Press Enter to continue...\"\n\n3. \"include\" - Include another workflow profile\n Requires: profile field\n Example: \"profile\": \"base-recovery-sequence\"", "description": "Three step types with different requirements and behaviors", "expectedOutput": "command: Most common type for executing system operations\npause: Interactive workflows requiring user decisions\ninclude: Compose complex workflows from smaller reusable pieces", "notes": "Include type allows workflow composition - build libraries of reusable profiles and chain them together" }, { "command": "# Timeout behavior:\n{\n \"global_settings\": {\n \"default_timeout\": 300\n },\n \"steps\": [\n {\n \"cmd\": \"quick-command\",\n \"timeout\": 10\n },\n {\n \"cmd\": \"slow-command\"\n # Uses default_timeout (300s)\n }\n ]\n}", "description": "Step-level timeout overrides global default_timeout", "expectedOutput": "Omit timeout to use default (300s from global_settings)\nSpecify timeout for time-sensitive commands\nTimeout prevents hanging on stuck commands", "notes": "Set timeout=0 for no limit (use carefully). Commands killed with SIGTERM after timeout, then SIGKILL if unresponsive" }, { "command": "# Confirm and nice_level:\n{\n \"cmd\": \"sudo health-control panic hard\",\n \"confirm\": true,\n \"nice_level\": -10\n}\n\nconfirm: true prompts user before executing\nnice_level: -20 (highest priority) to 19 (lowest priority)\n - Negative values require root (higher CPU priority)\n - Positive values lower priority (background tasks)\n - 0 is default (normal priority)", "description": "confirm adds safety for destructive operations, nice_level controls CPU priority", "expectedOutput": "Use confirm=true for dangerous commands (panic, wipe, reset)\nUse negative nice_level for critical real-time operations\nUse positive nice_level for background tasks", "notes": "Example: Recovery workflows use nice_level=-5 for priority, diagnostic scripts use nice_level=10 for background execution" } ], "id": "step-configuration-reference", "title": "Step Configuration Reference" } ], "description": "Usage examples for workflow-manager", "name": "workflow-manager", "quickReference": [ "sudo workflow-manager --help", "sudo workflow-manager --version", "sudo workflow-manager --info --json", "sudo workflow-manager --examples --json" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.398520394Z", "version": "9.0.1", "warnings": [] } }, { "name": "health-control", "path": "/home/kodachi/k900/dashboard/hooks/health-control", "timestamp": "2026-04-02T13:42:14Z", "file_info": { "size": 14475264, "sha256": "a77ed72f4159ef2c7410299b45ba705bc6a2614219e1976fd35cda32c2767648" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Kodachi", "description": "Health control system for Kodachi that includes network connectivity checks and system health monitoring", "features": [ "Network connectivity monitoring", "Internet traffic control", "Security hardening", "System integrity checking", "Offline system management" ], "license": "Proprietary", "name": "health-control", "securityFeatures": { "authentication": "Secure authentication with certificate pinning", "encryption": "TLS 1.3 for all network communications", "inputValidation": "All inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for network operations" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.0.1", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 13, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.711219013Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T13:42:14.772805838Z", "gitCommit": "unknown", "name": "health-control", "rustVersion": "1.82.0", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 14, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.788681805Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Data Destruction", "commands": [ { "description": "Securely wipe a file with multiple passes", "examples": [ "sudo health-control wipe-file --file /path/to/file.txt", "sudo health-control wipe-file --file /path/to/file.txt --passes 7 --json" ], "name": "wipe-file", "options": [], "requires_sudo": true, "usage": "health-control wipe-file [OPTIONS]" }, { "description": "Securely wipe an entire directory and its contents", "examples": [ "sudo health-control wipe-directory --path /tmp/sensitive_dir", "sudo health-control wipe-directory --path /path/to/directory --passes 7 --json" ], "name": "wipe-directory", "options": [], "requires_sudo": true, "usage": "health-control wipe-directory [OPTIONS]" }, { "description": "Securely wipe a common user directory (downloads, desktop, documents)", "examples": [ "sudo health-control wipe-user-dir --target downloads", "sudo health-control wipe-user-dir --target desktop", "sudo health-control wipe-user-dir --target documents --json" ], "name": "wipe-user-dir", "options": [], "requires_sudo": true, "usage": "health-control wipe-user-dir [OPTIONS]" }, { "description": "Securely wipe system logs (journal, syslog, auth.log, kern.log), user history (bash, zsh, python), and application cache logs", "examples": [ "sudo health-control wipe-logs # Wipe all logs (system + user)", "sudo health-control wipe-logs --type system # Wipe only system logs (/var/log/*, journal)", "sudo health-control wipe-logs --type user # Wipe only user logs (history, cache)", "sudo health-control wipe-logs --type all --json # Show detailed JSON output" ], "name": "wipe-logs", "options": [], "requires_sudo": true, "usage": "health-control wipe-logs [OPTIONS]" }, { "description": "Batch wipe multiple files", "examples": [ "sudo # Multiple file paths as arguments:", "sudo health-control wipe-batch file1.png file2.png --passes 7", "sudo health-control wipe-batch /tmp/sensitive.doc /home/user/data.txt", "sudo ", "sudo # Alternative comma-separated format:", "sudo health-control wipe-batch --paths \"file1.png,file2.png\" --passes 7", "sudo health-control wipe-batch --paths \"/tmp/file1,/tmp/file2\" --json", "sudo ", "sudo ⚠ Security Note: Using actual paths may expose system directory structure" ], "name": "wipe-batch", "options": [], "requires_sudo": true, "usage": "health-control wipe-batch [OPTIONS]" }, { "description": "Wipe browser data and history", "examples": [ "sudo health-control wipe-browser-data # Wipe all browsers", "sudo health-control wipe-browser-data --browser firefox # Firefox only", "sudo health-control wipe-browser-data --browser brave # Brave only", "sudo health-control wipe-browser-data --browser tor # Tor Browser only", "sudo health-control wipe-browser-data --browser all --json" ], "name": "wipe-browser-data", "options": [], "requires_sudo": true, "usage": "health-control wipe-browser-data [OPTIONS]" }, { "description": "Securely wipe free space on a mounted filesystem (use mount points like '/', '/home' or device paths)", "examples": [ "sudo health-control wipe-free-space --device /", "sudo health-control wipe-free-space --device /home", "sudo health-control wipe-free-space --device /dev/sda1 --json", "sudo health-control wipe-free-space --device /tmp" ], "name": "wipe-free-space", "options": [], "requires_sudo": true, "usage": "health-control wipe-free-space [OPTIONS]" }, { "description": "Wipe files matching pattern (use --pattern flag or positional argument)", "examples": [ "sudo health-control wipe-pattern --pattern '*.tmp'", "sudo health-control wipe-pattern '*.tmp'", "sudo health-control wipe-pattern --pattern '*.log' --directory /var/log", "sudo health-control wipe-pattern '*.log' --directory /var/log", "sudo health-control wipe-pattern --pattern 'backup*' --json", "sudo health-control wipe-pattern 'backup*' --json", "sudo health-control wipe-pattern --pattern '*.cache' --directory ~/.cache", "sudo health-control wipe-pattern '*.cache' --directory ~/.cache" ], "name": "wipe-pattern", "options": [], "requires_sudo": true, "usage": "health-control wipe-pattern [OPTIONS]" }, { "description": "Schedule automatic data wiping", "examples": [ "sudo health-control wipe-schedule temp --frequency daily", "sudo health-control wipe-schedule logs --frequency weekly", "sudo health-control wipe-schedule browser --json" ], "name": "wipe-schedule", "options": [], "requires_sudo": true, "usage": "health-control wipe-schedule [OPTIONS]" }, { "description": "Verify that a file was wiped properly", "examples": [ "sudo health-control wipe-verify --path /tmp/sensitive.txt", "sudo health-control wipe-verify --path /home/user/data.bin --json" ], "name": "wipe-verify", "options": [], "requires_sudo": true, "usage": "health-control wipe-verify [OPTIONS]" } ] }, { "category": "Display & Power", "commands": [ { "description": "Start Conky widget", "examples": [ "health-control conky-enable", "health-control conky-enable --json" ], "name": "conky-enable", "options": [], "requires_sudo": false, "usage": "health-control conky-enable [OPTIONS]" }, { "description": "Stop Conky widget", "examples": [ "health-control conky-disable", "health-control conky-disable --json" ], "name": "conky-disable", "options": [], "requires_sudo": false, "usage": "health-control conky-disable [OPTIONS]" }, { "description": "Check Conky running/installed/boot state", "examples": [ "health-control conky-status", "health-control conky-status --json" ], "name": "conky-status", "options": [], "requires_sudo": false, "usage": "health-control conky-status [OPTIONS]" }, { "description": "Enable Conky on boot (autostart/systemd)", "examples": [ "health-control conky-boot-enable", "health-control conky-boot-enable --json" ], "name": "conky-boot-enable", "options": [], "requires_sudo": false, "usage": "health-control conky-boot-enable [OPTIONS]" }, { "description": "Disable Conky on boot", "examples": [ "health-control conky-boot-disable", "health-control conky-boot-disable --json" ], "name": "conky-boot-disable", "options": [], "requires_sudo": false, "usage": "health-control conky-boot-disable [OPTIONS]" }, { "description": "Disable XFCE screensaver", "examples": [ "health-control screensaver-disable", "health-control screensaver-disable --json" ], "name": "screensaver-disable", "options": [], "requires_sudo": false, "usage": "health-control screensaver-disable [OPTIONS]" }, { "description": "Enable XFCE screensaver", "examples": [ "health-control screensaver-enable", "health-control screensaver-enable --json" ], "name": "screensaver-enable", "options": [], "requires_sudo": false, "usage": "health-control screensaver-enable [OPTIONS]" }, { "description": "Check screensaver status", "examples": [ "health-control screensaver-status", "health-control screensaver-status --json" ], "name": "screensaver-status", "options": [], "requires_sudo": false, "usage": "health-control screensaver-status [OPTIONS]" }, { "description": "Disable display power management", "examples": [ "health-control dpms-disable", "health-control dpms-disable --json" ], "name": "dpms-disable", "options": [], "requires_sudo": false, "usage": "health-control dpms-disable [OPTIONS]" }, { "description": "Enable display power management", "examples": [ "health-control dpms-enable", "health-control dpms-enable --json" ], "name": "dpms-enable", "options": [], "requires_sudo": false, "usage": "health-control dpms-enable [OPTIONS]" }, { "description": "Check DPMS and timeout settings", "examples": [ "health-control dpms-status", "health-control dpms-status --json" ], "name": "dpms-status", "options": [], "requires_sudo": false, "usage": "health-control dpms-status [OPTIONS]" }, { "description": "Lock the screen", "examples": [ "health-control lock-screen", "health-control lock-screen --json" ], "name": "lock-screen", "options": [], "requires_sudo": false, "usage": "health-control lock-screen [OPTIONS]" }, { "description": "End XFCE session", "examples": [ "health-control session-logout", "health-control session-logout --json" ], "name": "session-logout", "options": [], "requires_sudo": false, "usage": "health-control session-logout [OPTIONS]" }, { "description": "Suspend to RAM", "examples": [ "health-control suspend", "health-control suspend --json" ], "name": "suspend", "options": [], "requires_sudo": false, "usage": "health-control suspend [OPTIONS]" }, { "description": "Mask sensitive info in Conky panels", "examples": [ "health-control conky-mask-enable", "health-control conky-mask-enable --json" ], "name": "conky-mask-enable", "options": [], "requires_sudo": false, "usage": "health-control conky-mask-enable [OPTIONS]" }, { "description": "Unmask Conky panels", "examples": [ "health-control conky-mask-disable", "health-control conky-mask-disable --json" ], "name": "conky-mask-disable", "options": [], "requires_sudo": false, "usage": "health-control conky-mask-disable [OPTIONS]" }, { "description": "Check if Conky privacy masking is active", "examples": [ "health-control conky-mask-status", "health-control conky-mask-status --json" ], "name": "conky-mask-status", "options": [], "requires_sudo": false, "usage": "health-control conky-mask-status [OPTIONS]" } ] }, { "category": "Emergency Operations", "commands": [ { "description": "Arm the emergency kill switch - sets system to high-alert state for manual activation. NOTE: This prepares the system for rapid response but does NOT actively monitor for threats. It's a preparedness state that allows quick manual activation via kill-switch-activate command.", "examples": [ "sudo health-control kill-switch-arm", "sudo health-control kill-switch-arm --json" ], "name": "kill-switch-arm", "options": [], "requires_sudo": true, "usage": "health-control kill-switch-arm [OPTIONS]" }, { "description": "Disarm the emergency kill switch", "examples": [ "sudo health-control kill-switch-disarm", "sudo health-control kill-switch-disarm --json" ], "name": "kill-switch-disarm", "options": [], "requires_sudo": true, "usage": "health-control kill-switch-disarm [OPTIONS]" }, { "description": "Check if kill switch monitoring is armed/disarmed. Shows armed time, trigger count, and monitoring state. Does NOT activate anything - just displays current status.", "examples": [ "health-control kill-switch-status", "health-control kill-switch-status --json" ], "name": "kill-switch-status", "options": [], "requires_sudo": false, "usage": "health-control kill-switch-status [OPTIONS]" }, { "description": "IMMEDIATELY activate emergency procedures. Unlike 'arm' which monitors, this executes panic mode NOW. Choose level: soft (network+lock), medium (default: +kill processes), hard (+RAM wipe+shutdown)", "examples": [ "sudo health-control kill-switch-activate", "sudo health-control kill-switch-activate --level hard --force", "sudo health-control kill-switch-activate --level soft --json" ], "name": "kill-switch-activate", "options": [], "requires_sudo": true, "usage": "health-control kill-switch-activate [OPTIONS]" }, { "description": "IMMEDIATE soft panic mode. Actions: Kill all network connections, clear clipboard, lock screen. NO CONFIRMATION. Reversible by restarting network. Use for quick privacy protection.", "examples": [ "sudo health-control panic-soft", "sudo health-control panic-soft --json", "sudo health-control panic-soft --dry-run" ], "name": "panic-soft", "options": [], "requires_sudo": true, "usage": "health-control panic-soft [OPTIONS]" }, { "description": "IMMEDIATE hard panic mode with CONFIRMATION. CRITICAL: Kill network, clear clipboard, terminate ALL processes, clear memory, unmount devices, wipe RAM, IMMEDIATE SHUTDOWN. IRREVERSIBLE - system will shutdown!", "examples": [ "sudo health-control panic-hard", "sudo health-control panic-hard --json", "sudo health-control panic-hard --dry-run" ], "name": "panic-hard", "options": [], "requires_sudo": true, "usage": "health-control panic-hard [OPTIONS]" }, { "description": "IMMEDIATE medium panic mode with CONFIRMATION. Actions: Kill network, clear clipboard, terminate non-essential processes, clear memory, unmount devices, lock screen. Requires manual system restart to fully restore.", "examples": [ "sudo health-control panic-medium", "sudo health-control panic-medium --json", "sudo health-control panic-medium --dry-run" ], "name": "panic-medium", "options": [], "requires_sudo": true, "usage": "health-control panic-medium [OPTIONS]" }, { "description": "Configure automated emergency response profile that defines system actions during panic mode activation", "examples": [ "sudo # Configure light security response (recommended for public wifi):", "sudo health-control panic-profile --profile stealth", "sudo ", "sudo # Configure maximum security lockdown (for high-risk situations):", "sudo health-control panic-profile --profile paranoid", "sudo ", "sudo # Configure recovery mode (to restore system to safe state):", "sudo health-control panic-profile --profile recovery", "sudo ", "sudo # Get JSON output with profile configuration details:", "sudo health-control panic-profile --profile paranoid --json" ], "name": "panic-profile", "options": [], "requires_sudo": true, "usage": "health-control panic-profile [OPTIONS]" }, { "description": "Activate panic recovery mode", "examples": [ "sudo health-control panic-recover", "sudo health-control panic-recover --json" ], "name": "panic-recover", "options": [], "requires_sudo": true, "usage": "health-control panic-recover [OPTIONS]" }, { "description": "Create system recovery checkpoint", "examples": [ "sudo health-control create-recovery-point", "sudo health-control create-recovery-point --name pre-update", "sudo health-control create-recovery-point --json" ], "name": "create-recovery-point", "options": [], "requires_sudo": true, "usage": "health-control create-recovery-point [OPTIONS]" }, { "description": "Execute emergency data destruction sequence (DANGEROUS - use --dry-run for testing)", "examples": [ "health-control nuke-execute --dry-run", "health-control nuke-execute --method fast --dry-run", "health-control nuke-execute --method paranoid --dry-run --json" ], "name": "nuke-execute", "options": [ { "default": "secure", "description": "Wipe method: fast, secure (default), paranoid", "flag": "--method, -m ", "required": false }, { "description": "Test mode - shows actions without executing", "flag": "--dry-run", "required": false }, { "description": "Skip confirmation prompt (DANGEROUS)", "flag": "--force, -f", "required": false } ], "requires_sudo": false, "usage": "health-control nuke-execute [--method fast|secure|paranoid] [--dry-run] [--force]" }, { "description": "Get current nuke mode execution progress", "examples": [ "health-control nuke-progress", "health-control nuke-progress --json" ], "name": "nuke-progress", "options": [], "requires_sudo": false, "usage": "health-control nuke-progress" }, { "description": "Detect storage type (SSD/HDD/NVMe) for a device", "examples": [ "health-control nuke-storage-detect --device /dev/sda", "health-control nuke-storage-detect -d /dev/nvme0n1 --json" ], "name": "nuke-storage-detect", "options": [ { "description": "Device path to check", "flag": "--device, -d ", "required": true } ], "requires_sudo": false, "usage": "health-control nuke-storage-detect --device /dev/sda" } ] }, { "category": "Emergency Shortcuts", "commands": [ { "description": "Execute an emergency plan (dashboard, luks, both). Requires local session token from kodachi-session-helper daemon. Use --dry-run for testing.", "examples": [ "sudo health-control emergency-trigger --plan dashboard --dry-run", "sudo health-control emergency-trigger --plan luks --device /dev/sda2 --dry-run", "sudo health-control emergency-trigger --plan both --device /dev/sda2 --dry-run --json" ], "name": "emergency-trigger", "options": [ { "description": "Emergency plan: dashboard, luks, both", "flag": "--plan ", "required": true }, { "description": "LUKS device path (required for luks/both plans)", "flag": "--device ", "required": false }, { "description": "Log planned actions without executing", "flag": "--dry-run", "required": false }, { "description": "Suppress stdout output", "flag": "--silent", "required": false }, { "description": "Skip readiness checks", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "health-control emergency-trigger --plan [--device ] [--silent] [--force] [--dry-run]" }, { "description": "Start a delayed countdown that triggers an emergency plan when the timer expires. Persists state for crash recovery. Requires local session token.", "examples": [ "sudo health-control emergency-lockdown --delay 300 --dry-run", "sudo health-control emergency-lockdown --delay 60 --plan luks --device /dev/sda2", "sudo health-control emergency-lockdown --delay 120 --plan both --device /dev/sda2 --json" ], "name": "emergency-lockdown", "options": [ { "description": "Countdown delay in seconds", "flag": "--delay ", "required": true }, { "default": "dashboard", "description": "Emergency plan: dashboard (default), luks, both", "flag": "--plan ", "required": false }, { "description": "LUKS device path (required for luks/both plans)", "flag": "--device ", "required": false }, { "description": "Log planned actions without starting timer", "flag": "--dry-run", "required": false } ], "requires_sudo": true, "usage": "health-control emergency-lockdown --delay [--plan ] [--device ] [--dry-run]" }, { "description": "Show current emergency lockdown state: active/inactive, remaining seconds, plan. No authentication required (read-only).", "examples": [ "health-control emergency-lockdown-status", "health-control emergency-lockdown-status --json" ], "name": "emergency-lockdown-status", "options": [], "requires_sudo": false, "usage": "health-control emergency-lockdown-status [--json]" }, { "description": "Cancel an active emergency lockdown countdown. Requires local session token.", "examples": [ "sudo health-control emergency-lockdown-cancel", "sudo health-control emergency-lockdown-cancel --json" ], "name": "emergency-lockdown-cancel", "options": [], "requires_sudo": true, "usage": "health-control emergency-lockdown-cancel" } ] }, { "category": "Hardware Security", "commands": [ { "description": "Verify hardware random number generator status", "examples": [ "sudo health-control hardware-rng-verify", "sudo health-control hardware-rng-verify --json" ], "name": "hardware-rng-verify", "options": [], "requires_sudo": true, "usage": "health-control hardware-rng-verify [OPTIONS]" }, { "description": "Check system entropy pool status and quality", "examples": [ "sudo health-control entropy-status", "sudo health-control entropy-status --json" ], "name": "entropy-status", "options": [], "requires_sudo": true, "usage": "health-control entropy-status [OPTIONS]" }, { "description": "Enable cold boot defense mechanisms", "examples": [ "sudo health-control coldboot-defense-enable", "sudo health-control coldboot-defense-enable --json" ], "name": "coldboot-defense-enable", "options": [], "requires_sudo": true, "usage": "health-control coldboot-defense-enable [OPTIONS]" }, { "description": "Disable cold boot defense mechanisms", "examples": [ "sudo health-control coldboot-defense-disable", "sudo health-control coldboot-defense-disable --json", "sudo health-control coldboot-defense-disable --json-human" ], "name": "coldboot-defense-disable", "options": [], "requires_sudo": true, "usage": "health-control coldboot-defense-disable [OPTIONS]" }, { "description": "Check cold boot defense mechanisms status", "examples": [ "sudo health-control coldboot-defense-status", "sudo health-control coldboot-defense-status --json" ], "name": "coldboot-defense-status", "options": [], "requires_sudo": true, "usage": "health-control coldboot-defense-status [OPTIONS]" }, { "description": "Check boot chain integrity and security status", "examples": [ "sudo health-control boot-integrity-check", "sudo health-control boot-integrity-check --json" ], "name": "boot-integrity-check", "options": [], "requires_sudo": true, "usage": "health-control boot-integrity-check [OPTIONS]" } ] }, { "category": "Hostname Management", "commands": [ { "description": "Set the default hostname", "examples": [ "sudo health-control set-default-hostname", "sudo health-control set-default-hostname --json" ], "name": "set-default-hostname", "options": [], "requires_sudo": true, "usage": "health-control set-default-hostname [OPTIONS]" }, { "description": "Set a random hostname", "examples": [ "sudo health-control set-random-hostname", "sudo health-control set-random-hostname --json" ], "name": "set-random-hostname", "options": [], "requires_sudo": true, "usage": "health-control set-random-hostname [OPTIONS]" }, { "description": "Set a custom hostname", "examples": [ "sudo health-control set-custom-hostname --name MyHost", "sudo health-control set-custom-hostname --name secure-host --json" ], "name": "set-custom-hostname", "options": [], "requires_sudo": true, "usage": "health-control set-custom-hostname [OPTIONS]" } ] }, { "category": "Internet Traffic Control", "commands": [ { "description": "Block all internet traffic", "examples": [ "sudo health-control block-internet", "sudo health-control block-internet --method firewall", "sudo health-control block-internet --method ufw", "sudo health-control block-internet --method iptables", "sudo health-control block-internet --method nftables", "sudo health-control block-internet --method interfaces", "sudo health-control block-internet --method all", "sudo health-control block-internet --allow-local", "sudo health-control block-internet --method iptables --allow-local", "sudo health-control block-internet --method all --allow-local", "sudo health-control block-internet --json" ], "name": "block-internet", "options": [], "requires_sudo": true, "usage": "health-control block-internet [OPTIONS]" }, { "description": "Unblock internet traffic", "examples": [ "sudo health-control unblock-internet", "sudo health-control unblock-internet --method firewall", "sudo health-control unblock-internet --method ufw", "sudo health-control unblock-internet --method iptables", "sudo health-control unblock-internet --method nftables", "sudo health-control unblock-internet --method interfaces", "sudo health-control unblock-internet --method all", "sudo health-control unblock-internet --json" ], "name": "unblock-internet", "options": [], "requires_sudo": true, "usage": "health-control unblock-internet [OPTIONS]" }, { "description": "Check internet blocking status", "examples": [ "sudo health-control internet-status", "sudo health-control internet-status --silent", "sudo health-control internet-status --skipnotification", "sudo health-control internet-status --skip-notification", "sudo health-control internet-status --skipnotifcation", "sudo health-control internet-status --json" ], "name": "internet-status", "options": [], "requires_sudo": true, "usage": "health-control internet-status [OPTIONS]" }, { "description": "Recover internet connectivity", "examples": [ "sudo health-control recover-internet", "sudo health-control recover-internet --check-dns", "sudo health-control recover-internet --force", "sudo health-control recover-internet --check-dns --force", "sudo health-control recover-internet --silent", "sudo health-control recover-internet --skipnotification", "sudo health-control recover-internet --skip-notification", "sudo health-control recover-internet --skipnotifcation", "sudo health-control recover-internet --json" ], "name": "recover-internet", "options": [], "requires_sudo": true, "usage": "health-control recover-internet [OPTIONS]" }, { "description": "Fast internet recovery - bounce interface, restart NetworkManager, renew DHCP", "examples": [ "sudo health-control fast-recover-internet", "sudo health-control fast-recover-internet --force", "sudo health-control fast-recover-internet --force --silent", "sudo health-control fast-recover-internet --silent", "sudo health-control fast-recover-internet --skipnotification", "sudo health-control fast-recover-internet --skip-notification", "sudo health-control fast-recover-internet --skipnotifcation", "sudo health-control fast-recover-internet --json" ], "name": "fast-recover-internet", "options": [], "requires_sudo": true, "usage": "health-control fast-recover-internet [OPTIONS]" }, { "description": "Emergency network kill switch", "examples": [ "sudo health-control kill-network", "sudo health-control kill-network --json" ], "name": "kill-network", "options": [], "requires_sudo": true, "usage": "health-control kill-network [OPTIONS]" }, { "description": "Kill specific network interface", "examples": [ "sudo health-control kill-network-interface --interface wlan0", "sudo health-control kill-network-interface --interface eth0 --json" ], "name": "kill-network-interface", "options": [], "requires_sudo": true, "usage": "health-control kill-network-interface [OPTIONS]" }, { "description": "Kill specific process by name or PID", "examples": [ "sudo health-control kill-process --process firefox", "sudo health-control kill-process --process 1234 --json" ], "name": "kill-process", "options": [], "requires_sudo": true, "usage": "health-control kill-process [OPTIONS]" }, { "description": "Enable a watch-guard to monitor system changes and block internet on triggers", "examples": [ "sudo health-control enable --type watch-guard --watch ip --method nftables", "sudo health-control enable --type watch-guard --watch timezone --method iptables", "sudo health-control enable --type watch-guard --watch timezone --method iptables --daemon", "sudo health-control enable --type watch-guard --watch interfaces --method firewall", "sudo health-control enable --type watch-guard --watch process --target tor --method all", "sudo health-control enable --type watch-guard --watch process --target firefox --method auto", "sudo health-control enable --type watch-guard --watch mac --method nftables --interval 5", "sudo health-control enable --type watch-guard --watch hostname --method iptables", "sudo health-control enable --type watch-guard --watch vpn --method nftables --interval 3", "sudo health-control enable --type watch-guard --watch dns --method firewall", "sudo health-control enable --type watch-guard --watch mac --method nftables --actions log_event,randomize_hostname", "sudo health-control enable --type watch-guard --watch vpn --method nftables --actions log_event,show_alert,block_network" ], "name": "enable", "options": [ { "description": "Type of watch-guard to enable", "flag": "--type", "required": true }, { "description": "What to watch for changes (ip, timezone, interfaces, process)", "flag": "--watch", "required": true }, { "description": "Process name to watch (required for process watch)", "flag": "--target", "required": false }, { "description": "Blocking method to use when triggered", "flag": "--method", "required": true }, { "description": "Run monitoring as a persistent daemon process", "flag": "--daemon", "required": false }, { "default": "varies by watch type", "description": "Custom check interval in seconds (1-300)", "flag": "--interval", "required": false }, { "default": "log_event,show_alert,play_sound,block_network", "description": "Comma-separated actions to execute when triggered", "flag": "--actions", "required": false } ], "requires_sudo": true, "usage": "health-control enable --type watch-guard --watch --method " }, { "description": "Disable an active watch-guard and optionally unblock internet", "examples": [ "sudo health-control disable --type watch-guard ip", "sudo health-control disable --type watch-guard timezone", "sudo health-control disable --type watch-guard interfaces", "sudo health-control disable --type watch-guard tor", "sudo health-control disable --type watch-guard all", "sudo health-control disable --type watch-guard all --no-unblock" ], "name": "disable", "options": [ { "description": "Type of command to disable", "flag": "--type", "required": true }, { "description": "Do not unblock internet after disabling watch-guard", "flag": "--no-unblock", "required": false } ], "requires_sudo": true, "usage": "health-control disable --type watch-guard " }, { "description": "Show status of active watch-guards", "examples": [ "sudo health-control watch-guard status", "sudo health-control watch-guard status --json" ], "name": "watch-guard", "options": [], "requires_sudo": true, "usage": "health-control watch-guard status" }, { "description": "Run watch-guard monitoring as a persistent daemon process", "examples": [ "sudo health-control daemon --config-id timezone_iptables" ], "name": "daemon", "options": [ { "description": "Configuration ID to monitor", "flag": "--config-id", "required": true } ], "requires_sudo": true, "usage": "health-control daemon --config-id " } ] }, { "category": "MAC Address Management", "commands": [ { "description": "Change all MAC addresses", "examples": [ "sudo health-control mac-change-all", "sudo health-control mac-change-all --json" ], "name": "mac-change-all", "options": [], "requires_sudo": true, "usage": "health-control mac-change-all [OPTIONS]" }, { "description": "Force change all MAC addresses (disable interfaces first)", "examples": [ "sudo health-control mac-force-change", "sudo health-control mac-force-change --json" ], "name": "mac-force-change", "options": [], "requires_sudo": true, "usage": "health-control mac-force-change [OPTIONS]" }, { "description": "Change specific interface MAC address", "examples": [ "sudo health-control mac-change-specific --interface eth0", "sudo health-control mac-change-specific --interface wlan0 --json" ], "name": "mac-change-specific", "options": [], "requires_sudo": true, "usage": "health-control mac-change-specific [OPTIONS]" }, { "description": "Show available network interfaces", "examples": [ "sudo health-control mac-show-interfaces", "sudo health-control mac-show-interfaces --json" ], "name": "mac-show-interfaces", "options": [], "requires_sudo": true, "usage": "health-control mac-show-interfaces [OPTIONS]" }, { "description": "Show current MAC addresses", "examples": [ "sudo health-control mac-show-macs", "sudo health-control mac-show-macs --json" ], "name": "mac-show-macs", "options": [], "requires_sudo": true, "usage": "health-control mac-show-macs [OPTIONS]" }, { "description": "Reset all MAC addresses to default", "examples": [ "sudo health-control mac-reset-all", "sudo health-control mac-reset-all --json" ], "name": "mac-reset-all", "options": [], "requires_sudo": true, "usage": "health-control mac-reset-all [OPTIONS]" }, { "description": "Show active network interface", "examples": [ "sudo health-control mac-active-interface", "sudo health-control mac-active-interface --json" ], "name": "mac-active-interface", "options": [], "requires_sudo": true, "usage": "health-control mac-active-interface [OPTIONS]" } ] }, { "category": "Memory Management", "commands": [ { "description": "Clean memory caches and buffers", "examples": [ "sudo health-control memory-clean", "sudo health-control memory-clean --json" ], "name": "memory-clean", "options": [], "requires_sudo": true, "usage": "health-control memory-clean [OPTIONS]" }, { "description": "Force clean memory by killing top process", "examples": [ "sudo health-control memory-force-clean", "sudo health-control memory-force-clean --json" ], "name": "memory-force-clean", "options": [], "requires_sudo": true, "usage": "health-control memory-force-clean [OPTIONS]" }, { "description": "Secure RAM wipe (sdmem)", "examples": [ "sudo health-control memory-wipe", "sudo health-control memory-wipe --json" ], "name": "memory-wipe", "options": [], "requires_sudo": true, "usage": "health-control memory-wipe [OPTIONS]" }, { "description": "Wipe memory of specific process", "examples": [ "sudo health-control memory-wipe-process --value firefox", "sudo health-control memory-wipe-process --value 1234 --json" ], "name": "memory-wipe-process", "options": [], "requires_sudo": true, "usage": "health-control memory-wipe-process [OPTIONS]" }, { "description": "Manage process memory limits", "examples": [ "sudo health-control memory-limits", "sudo health-control memory-limits --value firefox --limit 1024", "sudo health-control memory-limits --value chrome --limit 2048", "sudo health-control memory-limits --value brave --limit 1536", "sudo health-control memory-limits --json" ], "name": "memory-limits", "options": [], "requires_sudo": true, "usage": "health-control memory-limits [OPTIONS]" }, { "description": "Display memory statistics and history", "examples": [ "sudo health-control memory-stats", "sudo health-control memory-stats --history --json" ], "name": "memory-stats", "options": [], "requires_sudo": true, "usage": "health-control memory-stats [OPTIONS]" }, { "description": "Configure swap settings", "examples": [ "sudo health-control swap-configure --swappiness 10 --cache-pressure 50", "sudo health-control swap-configure --swappiness 0 --json" ], "name": "swap-configure", "options": [], "requires_sudo": true, "usage": "health-control swap-configure [OPTIONS]" }, { "description": "Disable swap memory", "examples": [ "sudo health-control disable-swap", "sudo health-control disable-swap --json" ], "name": "disable-swap", "options": [], "requires_sudo": true, "usage": "health-control disable-swap [OPTIONS]" }, { "description": "Enable swap memory", "examples": [ "sudo health-control enable-swap", "sudo health-control enable-swap --size 2048", "sudo health-control enable-swap --size 4096", "sudo health-control enable-swap --json" ], "name": "enable-swap", "options": [], "requires_sudo": true, "usage": "health-control enable-swap [OPTIONS]" } ] }, { "category": "Network Connectivity", "commands": [ { "description": "Check network connectivity (IP and DNS only)", "examples": [ "sudo health-control net-check", "sudo health-control net-check --json", "sudo health-control net-check --timeout 15", "sudo health-control net-check --http --json", "sudo health-control net-check --ip-only", "sudo health-control net-check --domain-only", "sudo health-control net-check --domain-only --dns-server 127.0.0.1:5353" ], "name": "net-check", "options": [ { "default": "10", "description": "Timeout in seconds for each connectivity check", "flag": "--timeout ", "required": false }, { "description": "Include HTTP connectivity check", "flag": "--http", "required": false }, { "description": "Check IP connectivity only, skip DNS checks", "flag": "--ip-only", "required": false }, { "description": "Check domain connectivity only, skip IP ping", "flag": "--domain-only", "required": false }, { "description": "Custom DNS server address (e.g., 127.0.0.1:5353 for Tor DNS)", "flag": "--dns-server ", "required": false } ], "requires_sudo": true, "usage": "health-control net-check [--timeout ] [--http] [--ip-only] [--domain-only] [--dns-server ]" }, { "description": "Check network connectivity including HTTP", "examples": [ "sudo health-control net-check-http", "sudo health-control net-check-http --timeout 15", "sudo health-control net-check-http --json" ], "name": "net-check-http", "options": [], "requires_sudo": true, "usage": "health-control net-check-http [OPTIONS]" }, { "description": "List IPs used for connectivity testing", "examples": [ "sudo health-control list-ips", "sudo health-control list-ips --json" ], "name": "list-ips", "options": [], "requires_sudo": true, "usage": "health-control list-ips [OPTIONS]" }, { "description": "List domains used for connectivity testing", "examples": [ "sudo health-control list-domains", "sudo health-control list-domains --json" ], "name": "list-domains", "options": [], "requires_sudo": true, "usage": "health-control list-domains [OPTIONS]" } ] }, { "category": "Offline Actions", "commands": [ { "description": "Manage PostgreSQL database service", "examples": [ "sudo health-control offline-postgresql --action disable", "sudo health-control offline-postgresql --action enable", "sudo health-control offline-postgresql --action check --json" ], "name": "offline-postgresql", "options": [], "requires_sudo": true, "usage": "health-control offline-postgresql [OPTIONS]" } ] }, { "category": "Password Generation", "commands": [ { "description": "Generate secure passwords using multiple methods (pass, pwgen, xkcdpass)", "examples": [ "sudo health-control genpass", "sudo health-control genpass --method pwgen", "sudo health-control genpass --count 10", "sudo health-control genpass --method pwgen --count 50", "sudo health-control genpass --method xkcdpass --count 20 --json", "sudo health-control genpass --length 32 --symbols \"@-_!#$\"" ], "name": "genpass", "options": [], "requires_sudo": true, "usage": "health-control genpass [OPTIONS]" } ] }, { "category": "Security", "commands": [ { "description": "Show comprehensive security status", "examples": [ "sudo health-control security-status", "sudo health-control security-status --category network", "sudo health-control security-status --category all --json", "sudo health-control security-status all", "sudo health-control security-status network --json" ], "name": "security-status", "options": [], "requires_sudo": true, "usage": "health-control security-status [OPTIONS]" } ] }, { "category": "Security Assessment", "commands": [ { "description": "Calculate security score and get recommendations", "examples": [ "health-control security-score", "health-control security-score --json" ], "name": "security-score", "options": [], "requires_sudo": false, "usage": "health-control security-score [OPTIONS]" }, { "description": "Generate comprehensive security report", "examples": [ "sudo health-control security-report", "sudo health-control security-report --format detailed", "sudo health-control security-report --format compliance --json" ], "name": "security-report", "options": [], "requires_sudo": true, "usage": "health-control security-report [OPTIONS]" }, { "description": "Set security profile and thresholds", "examples": [ "sudo health-control security-profile --value minimal", "sudo health-control security-profile --value balanced", "sudo health-control security-profile --value paranoid", "sudo health-control security-profile --value balanced --json" ], "name": "security-profile", "options": [], "requires_sudo": true, "usage": "health-control security-profile [OPTIONS]" }, { "description": "View security configuration history", "examples": [ "sudo health-control security-history", "sudo health-control security-history --days 30", "sudo health-control security-history --json" ], "name": "security-history", "options": [], "requires_sudo": true, "usage": "health-control security-history [OPTIONS]" }, { "description": "Auto-remediate security issues", "examples": [ "sudo health-control security-remediate", "sudo health-control security-remediate --bool true", "sudo health-control security-remediate --bool false --json" ], "name": "security-remediate", "options": [], "requires_sudo": true, "usage": "health-control security-remediate [OPTIONS]" }, { "description": "Schedule security scans (hourly, daily, weekly, monthly, disable)", "examples": [ "sudo health-control security-schedule --value daily", "sudo health-control security-schedule --value weekly", "sudo health-control security-schedule --value disable --json" ], "name": "security-schedule", "options": [], "requires_sudo": true, "usage": "health-control security-schedule [OPTIONS]" }, { "description": "Enhanced rootkit scanning with multiple tools", "examples": [ "sudo health-control rootkit-scan-enhanced", "sudo health-control rootkit-scan-enhanced --deep", "sudo health-control rootkit-scan-enhanced --json" ], "name": "rootkit-scan-enhanced", "options": [], "requires_sudo": true, "usage": "health-control rootkit-scan-enhanced [OPTIONS]" }, { "description": "Run Lynis security audit", "examples": [ "sudo health-control lynis-audit", "sudo health-control lynis-audit --value quick", "sudo health-control lynis-audit --value pentest --json" ], "name": "lynis-audit", "options": [], "requires_sudo": true, "usage": "health-control lynis-audit [OPTIONS]" }, { "description": "Check Lynis installation status", "examples": [ "health-control lynis-status", "health-control lynis-status --json" ], "name": "lynis-status", "options": [], "requires_sudo": false, "usage": "health-control lynis-status [OPTIONS]" }, { "description": "Scan system with ClamAV antivirus", "examples": [ "sudo health-control clamav-scan", "sudo health-control clamav-scan --path /home --recursive", "sudo health-control clamav-scan --quarantine --json" ], "name": "clamav-scan", "options": [], "requires_sudo": true, "usage": "health-control clamav-scan [OPTIONS]" }, { "description": "Perform comprehensive system security audit", "examples": [ "sudo health-control system-audit", "sudo health-control system-audit --level comprehensive", "sudo health-control system-audit --modules network,filesystem --json" ], "name": "system-audit", "options": [], "requires_sudo": true, "usage": "health-control system-audit [OPTIONS]" } ] }, { "category": "Security Hardening", "commands": [ { "description": "Apply comprehensive security hardening", "examples": [ "sudo health-control security-harden", "sudo health-control security-harden --profile standard", "sudo # STANDARD PROFILE (soft) — Nothing breaks, score 5/7", "sudo # Applies: Safe kernel sysctls, secure filesystem mounts,", "sudo # ASLR=2, symlink/hardlink protection, SYN flood protection,", "sudo # auditd monitoring, AppArmor/Firejail detection", "sudo # Also normalizes: Reverts any stricter settings left from medium/paranoid", "sudo # Safe for: All systems, all browsers, VPN/Tor routing", "sudo ", "sudo health-control security-harden --profile medium", "sudo # MEDIUM PROFILE (moderate) — Browsers+internet still work, score 6/7", "sudo # Includes Standard, PLUS: hidepid=2 on /proc, hardened_malloc,", "sudo # vm.dirty_ratio tuning, file integrity monitoring", "sudo # Also normalizes: Reverts paranoid-only settings (namespaces, IP forwarding)", "sudo # May affect: LUKS systems (higher memory from hardened_malloc)", "sudo ", "sudo health-control security-harden --profile paranoid", "sudo # PARANOID PROFILE (maximum) — Full lockdown, score 7/7", "sudo # Includes Medium, PLUS: disable user namespaces, disable IP forwarding,", "sudo # MAC spoofing, DNS firewall, LKRG, Tirdad, SMT off, RAM wipe", "sudo # WILL BREAK: Browsers, Internet, VPN/Tor routing", "sudo # Recover: health-control security-recover", "sudo ", "sudo health-control security-harden --break-monitoring", "sudo # Alias for --profile paranoid + makes /sys/class/net root-only", "sudo ", "sudo health-control security-harden --modules kernel,network --json", "sudo # Apply only specific modules with JSON output", "sudo ", "sudo # LUKS encryption notice:", "sudo # On LUKS systems, medium/paranoid profiles increase memory usage.", "sudo # If OOM or browser crashes occur: health-control security-recover" ], "name": "security-harden", "options": [], "requires_sudo": true, "usage": "health-control security-harden [OPTIONS]" }, { "description": "Verify if security hardening is properly applied (checks all 7 modules and reports their status)", "examples": [ "sudo health-control security-verify", "sudo # Check status of all 7 security modules against current profile", "sudo # Also checks for forbidden leftover settings from higher profiles", "sudo # Standard expects: 5/7 modules, no medium/paranoid leftovers", "sudo # Medium expects: 6/7 modules, no paranoid leftovers", "sudo # Paranoid expects: 7/7 modules configured", "sudo ", "sudo health-control security-verify --profile medium", "sudo # Verify against medium profile expectations", "sudo ", "sudo health-control security-verify --profile paranoid", "sudo # Verify against paranoid profile expectations", "sudo ", "sudo health-control security-verify --json", "sudo # Get detailed JSON output with all verification data + leftover warnings" ], "name": "security-verify", "options": [], "requires_sudo": true, "usage": "health-control security-verify [OPTIONS]" }, { "description": "Temporarily revert security hardening (keeps framework enabled for quick re-hardening)", "examples": [ "sudo # Temporarily revert security hardening (keeps framework ready for re-hardening)", "sudo health-control security-recover", "sudo ", "sudo # After recovery, modules show 'ENABLED (needs configuration)'", "sudo # This means: Framework is ready but no restrictions are enforced", "sudo # Use this when: Troubleshooting issues, planning to re-harden later", "sudo ", "sudo # Recover only specific modules", "sudo health-control security-recover --modules network,kernel", "sudo ", "sudo # LUKS systems: If hardening caused OOM kills or browser crashes,", "sudo # recovery restores vm.dirty_ratio=20 (default) and re-enables", "sudo # user namespaces for browser sandbox compatibility.", "sudo ", "sudo # To re-apply hardening after recovery:", "sudo health-control security-harden" ], "name": "security-recover", "options": [], "requires_sudo": true, "usage": "health-control security-recover [OPTIONS]" }, { "description": "Completely disable all security modules and framework (permanent removal)", "examples": [ "sudo # Completely disable all security modules and framework", "sudo health-control security-reset", "sudo ", "sudo # After reset, security-verify shows modules as NOT HARDENED", "sudo # This means: All applied security hardening has been reverted", "sudo # Use this when: You want to permanently remove security hardening", "sudo ", "sudo # Skip confirmation prompt", "sudo health-control security-reset --force", "sudo ", "sudo # Warning: After reset, security-harden will need to rebuild framework" ], "name": "security-reset", "options": [], "requires_sudo": true, "usage": "health-control security-reset [OPTIONS]" }, { "description": "Enable system monitoring features", "examples": [ "sudo health-control monitoring-enable", "sudo health-control monitoring-enable --modules auditd,lkrg,file-integrity", "sudo health-control monitoring-enable --json" ], "name": "monitoring-enable", "options": [], "requires_sudo": true, "usage": "health-control monitoring-enable [OPTIONS]" }, { "description": "Disable system monitoring features", "examples": [ "sudo health-control monitoring-disable", "sudo health-control monitoring-disable --modules auditd,lkrg", "sudo health-control monitoring-disable --json" ], "name": "monitoring-disable", "options": [], "requires_sudo": true, "usage": "health-control monitoring-disable [OPTIONS]" }, { "description": "Check system security monitoring status", "examples": [ "sudo health-control monitoring-status", "sudo health-control monitoring-status --json" ], "name": "monitoring-status", "options": [], "requires_sudo": true, "usage": "health-control monitoring-status [OPTIONS]" }, { "description": "Disable IPv6 system-wide", "examples": [ "sudo health-control ipv6-disable", "sudo health-control ipv6-disable --json" ], "name": "ipv6-disable", "options": [], "requires_sudo": true, "usage": "health-control ipv6-disable [OPTIONS]" }, { "description": "Enable IPv6 system-wide", "examples": [ "sudo health-control ipv6-enable", "sudo health-control ipv6-enable --json" ], "name": "ipv6-enable", "options": [], "requires_sudo": true, "usage": "health-control ipv6-enable [OPTIONS]" }, { "description": "Enable Tirdad TCP ISN randomization", "examples": [ "sudo health-control tirdad-enable", "sudo health-control tirdad-enable --json" ], "name": "tirdad-enable", "options": [], "requires_sudo": true, "usage": "health-control tirdad-enable [OPTIONS]" }, { "description": "Disable Tirdad TCP ISN randomization", "examples": [ "sudo health-control tirdad-disable", "sudo health-control tirdad-disable --json" ], "name": "tirdad-disable", "options": [], "requires_sudo": true, "usage": "health-control tirdad-disable [OPTIONS]" }, { "description": "Check Tirdad TCP ISN randomization status", "examples": [ "health-control tirdad-status", "health-control tirdad-status --json" ], "name": "tirdad-status", "options": [], "requires_sudo": false, "usage": "health-control tirdad-status [OPTIONS]" }, { "description": "Check IPv6 status", "examples": [ "health-control ipv6-status", "health-control ipv6-status --json" ], "name": "ipv6-status", "options": [], "requires_sudo": false, "usage": "health-control ipv6-status [OPTIONS]" }, { "description": "Enable secure RAM wiping on shutdown", "examples": [ "sudo health-control ram-wipe", "sudo health-control ram-wipe --json" ], "name": "ram-wipe", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe [OPTIONS]" }, { "description": "Install RAM wipe system (hooks + configuration) - Run this first if not already installed", "examples": [ "sudo health-control wipe-ram-install", "sudo health-control wipe-ram-install --policy kodachi-wiper", "sudo health-control wipe-ram-install --policy sdmem --passes 3", "sudo health-control wipe-ram-install --time 120", "sudo health-control wipe-ram-install --policy sdmem --passes 5", "sudo health-control wipe-ram-install --policy both --time 120 --passes 3", "sudo health-control wipe-ram-install --force", "sudo health-control wipe-ram-install --json" ], "name": "wipe-ram-install", "options": [ { "default": "false", "description": "Force installation even if Kicksecure/Whonix RAM wipe detected. WARNING: May conflict with existing systems", "flag": "--force" }, { "default": "kodachi-wiper", "description": "Initial wipe policy: kodachi-wiper (fast, recommended)|sdmem (secure DoD-standard)|both (hybrid)|auto (intelligent auto-selection)", "flag": "--policy " }, { "default": "60", "description": "Time budget for shutdown RAM wiping (default: 60s). Recommended: 60-90s desktops, 120-300s servers", "flag": "--time " }, { "default": "3", "description": "Number of sdmem overwrite passes 1-9 (default: 3). More passes = more secure but slower. Recommended: 3 balanced, 7+ high-security", "flag": "--passes " } ], "requires_sudo": true, "usage": "health-control wipe-ram-install [OPTIONS]" }, { "description": "Show RAM wipe system status - Check this first before installing or configuring", "examples": [ "sudo health-control ram-wipe-status", "sudo health-control ram-wipe-status --json" ], "name": "ram-wipe-status", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe-status [OPTIONS]" }, { "description": "Update RAM wipe configuration - Use this to modify settings after installation", "examples": [ "sudo health-control wipe-ram-config --policy auto", "sudo health-control wipe-ram-config --policy kodachi-wiper", "sudo health-control wipe-ram-config --time 120", "sudo health-control wipe-ram-config --passes 5", "sudo health-control wipe-ram-config --split 70", "sudo health-control wipe-ram-config --policy both --time 120", "sudo health-control wipe-ram-config --policy both --time 90 --passes 3 --split 60", "sudo health-control wipe-ram-config --json" ], "name": "wipe-ram-config", "options": [ { "description": "Set policy: kodachi-wiper (fast native wiper)|sdmem (secure multi-pass)|both (balanced hybrid)|auto (intelligent auto-detection: prefers kodachi-wiper, falls back to sdmem if unavailable)", "flag": "--policy " }, { "description": "Set time budget for shutdown RAM wiping. Recommended: 60-90s desktops, 120-300s servers", "flag": "--time " }, { "description": "Set number of sdmem passes (1-9). More = secure but slower. Recommended: 3 balanced, 7+ high-security", "flag": "--passes " }, { "description": "Set time split for 'both' mode (10-90). Example: 70 = 70% kodachi-wiper, 30% sdmem. Higher = faster but less secure", "flag": "--split " } ], "requires_sudo": true, "usage": "health-control wipe-ram-config [OPTIONS]" }, { "description": "Enable automatic RAM wiping on shutdown", "examples": [ "sudo health-control ram-wipe-enable", "sudo health-control ram-wipe-enable --schedule immediate", "sudo health-control ram-wipe-enable --schedule delay", "sudo health-control ram-wipe-enable --passes 5", "sudo health-control ram-wipe-enable --schedule shutdown --passes 3", "sudo health-control ram-wipe-enable --json" ], "name": "ram-wipe-enable", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe-enable [OPTIONS]" }, { "description": "Disable automatic RAM wiping", "examples": [ "sudo health-control ram-wipe-disable", "sudo health-control ram-wipe-disable --preserve-config", "sudo health-control ram-wipe-disable --json" ], "name": "ram-wipe-disable", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe-disable [OPTIONS]" }, { "description": "Test RAM wipe operation (dry-run with short time budget) - Run this to verify installation before relying on automatic wipes", "examples": [ "sudo health-control wipe-ram-test", "sudo health-control wipe-ram-test --policy kodachi-wiper", "sudo health-control wipe-ram-test --policy sdmem", "sudo health-control wipe-ram-test --policy both --time 60", "sudo health-control wipe-ram-test --time 30", "sudo health-control wipe-ram-test --policy kodachi-wiper --time 20", "sudo health-control wipe-ram-test --json" ], "name": "wipe-ram-test", "options": [ { "description": "Test specific wipe policy: kodachi-wiper (fast)|sdmem (secure DoD-standard)|both (hybrid)|auto (intelligent auto-selection)", "flag": "--policy " }, { "default": "10", "description": "Test time budget in seconds (default: 10). Quick test only - actual shutdown wipe uses configured time budget from wipe-ram-config", "flag": "--time " } ], "requires_sudo": true, "usage": "health-control wipe-ram-test [OPTIONS]" }, { "description": "Execute RAM wipe operation (primarily used by systemd/init shutdown hooks, but can be run manually for testing)", "examples": [ "sudo health-control wipe-ram", "sudo health-control wipe-ram --policy kodachi-wiper", "sudo health-control wipe-ram --policy sdmem", "sudo health-control wipe-ram --policy both --time 120", "sudo health-control wipe-ram --time 120", "sudo health-control wipe-ram --no-console", "sudo health-control wipe-ram --json", "sudo health-control wipe-ram --shutdown-mode" ], "name": "wipe-ram", "options": [ { "default": "false", "description": "INTERNAL USE - Shutdown-optimized mode for systemd/init hooks. Users should use 'wipe-ram' without this flag", "flag": "--shutdown-mode" }, { "default": "false", "description": "Disable console output for silent operation (useful in scripts and background tasks)", "flag": "--no-console" }, { "description": "Override wipe policy: kodachi-wiper (fast native wiper for quick shutdowns)|sdmem (secure DoD-standard multi-pass for maximum security)|both (hybrid approach: fast+secure)|auto (intelligent auto-selection based on system capabilities)", "flag": "--policy " }, { "description": "Override time budget in seconds (how long to spend wiping RAM). Higher values = more memory wiped but longer shutdown time", "flag": "--time " } ], "requires_sudo": true, "usage": "health-control wipe-ram [OPTIONS]" }, { "description": "Detect Kicksecure/Whonix RAM wipe installation", "examples": [ "sudo health-control ram-wipe-detect-kicksecure", "sudo health-control ram-wipe-detect-kicksecure --json", "sudo health-control ram-wipe-detect-kicksecure --json-human" ], "name": "ram-wipe-detect-kicksecure", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe-detect-kicksecure" }, { "description": "Update RAM wipe configuration (alias for wipe-ram-config)", "examples": [ "sudo health-control ram-wipe-update --policy auto", "sudo health-control ram-wipe-update --policy both --time 150", "sudo health-control ram-wipe-update --policy kodachi-wiper", "sudo health-control ram-wipe-update --time 120", "sudo health-control ram-wipe-update --passes 5", "sudo health-control ram-wipe-update --json" ], "name": "ram-wipe-update", "options": [ { "description": "Set policy: kodachi-wiper (fast native wiper)|sdmem (secure multi-pass)|both (balanced hybrid)|auto (intelligent auto-detection: prefers kodachi-wiper, falls back to sdmem if unavailable)", "flag": "--policy " }, { "description": "Set time budget in seconds", "flag": "--time " }, { "description": "Set sdmem passes (1-9)", "flag": "--passes " }, { "description": "Set custom/sdmem split for 'both' mode (10-90)", "flag": "--split " } ], "requires_sudo": true, "usage": "health-control ram-wipe-update [OPTIONS]" }, { "description": "Check disk encryption status and security", "examples": [ "sudo health-control disk-encryption-status", "sudo health-control disk-encryption-status --json" ], "name": "disk-encryption-status", "options": [], "requires_sudo": true, "usage": "health-control disk-encryption-status [OPTIONS]" }, { "description": "Enable swap partition/file", "examples": [ "sudo health-control swap-enable", "sudo health-control swap-enable --json" ], "name": "swap-enable", "options": [], "requires_sudo": true, "usage": "health-control swap-enable [OPTIONS]" }, { "description": "Disable swap partition/file", "examples": [ "sudo health-control swap-disable", "sudo health-control swap-disable --json" ], "name": "swap-disable", "options": [], "requires_sudo": true, "usage": "health-control swap-disable [OPTIONS]" }, { "description": "Encrypt swap partition/file", "examples": [ "sudo health-control swap-encrypt", "sudo health-control swap-encrypt --json" ], "name": "swap-encrypt", "options": [], "requires_sudo": true, "usage": "health-control swap-encrypt [OPTIONS]" }, { "description": "Check swap status and configuration", "examples": [ "sudo health-control swap-status", "sudo health-control swap-status --json" ], "name": "swap-status", "options": [], "requires_sudo": true, "usage": "health-control swap-status [OPTIONS]" }, { "description": "Decrypt encrypted swap partition/file", "examples": [ "sudo health-control swap-decrypt", "sudo health-control swap-decrypt --device /dev/sda3", "sudo health-control swap-decrypt --json" ], "name": "swap-decrypt", "options": [], "requires_sudo": true, "usage": "health-control swap-decrypt [OPTIONS]" }, { "description": "Check swap encryption status", "examples": [ "sudo health-control swap-encrypt-status", "sudo health-control swap-encrypt-status --json" ], "name": "swap-encrypt-status", "options": [], "requires_sudo": true, "usage": "health-control swap-encrypt-status [OPTIONS]" }, { "description": "List all USB devices", "examples": [ "sudo health-control usb-list", "sudo health-control usb-list --json" ], "name": "usb-list", "options": [], "requires_sudo": true, "usage": "health-control usb-list [OPTIONS]" }, { "description": "Manage LUKS nuke passwords", "examples": [ "sudo # AUTOMATED HEADER BACKUP + Nuke Configuration", "sudo ", "sudo # Check nuke password status", "sudo health-control luks-nuke --action status", "sudo → Shows all LUKS devices and nuke password status", "sudo ", "sudo # Check specific device", "sudo health-control luks-nuke --action status --device /dev/sda5", "sudo → Shows nuke password status for /dev/sda5 only", "sudo ", "sudo # Configure nuke password (FULLY AUTOMATED)", "sudo health-control luks-nuke --action configure --device /dev/sda5", "sudo → Backs up LUKS header AUTOMATICALLY to /backups/", "sudo → Encrypts backup with GPG automatically", "sudo → Configures nuke password via cryptsetup-nuke-password", "sudo → Verifies everything works", "sudo → NO manual cryptsetup commands needed!", "sudo ", "sudo # Configure with CLI password (INSECURE - visible in history)", "sudo health-control luks-nuke --action configure --device /dev/sda5 --password nuke123", "sudo ⚠️ WARNING: Password visible in shell history!", "sudo → Still backs up header automatically", "sudo ", "sudo # Header backup location", "sudo # Saved to: /backups/header-{device-name}-{timestamp}.img.gpg", "sudo # Keep this file SAFE - it's your ONLY recovery option!", "sudo ", "sudo # Remove nuke password", "sudo health-control luks-nuke --action remove --device /dev/sda5", "sudo → Removes nuke password via cryptsetup-nuke-password", "sudo ", "sudo # MANUAL EMERGENCY EXECUTE (IRREVERSIBLE)", "sudo health-control luks-nuke --action execute --device /dev/sda5 --force-execute", "sudo → Immediately destroys LUKS key material on selected device.", "sudo → Data becomes permanently unrecoverable.", "sudo ", "sudo # ℹ️ FILE-BASED LUKS CONTAINERS SUPPORTED", "sudo # Works with both block devices (/dev/*) AND file-based containers", "sudo ", "sudo # Configure nuke for live-boot persistence image (AUTOMATED)", "sudo health-control luks-nuke --action configure --device /tmp/persistence", "sudo → Backs up header automatically", "sudo → Supports file-based LUKS containers created by create-persistence", "sudo ", "sudo # Check nuke status on encrypted persistence file", "sudo health-control luks-nuke --action status --device /media/kodachi/persistence", "sudo → File must exist and be a valid LUKS container", "sudo ", "sudo # Remove nuke from file-based container", "sudo health-control luks-nuke --action remove --device /tmp/encrypted-container.img", "sudo → Works identically with files and block devices", "sudo ", "sudo # COMPLETE AUTOMATED WORKFLOW", "sudo # Create encrypted persistence with nuke password - ZERO manual steps", "sudo ", "sudo # Step 1: List devices to find USB", "sudo health-control list-storage-devices", "sudo ", "sudo # Step 2: Check device safety", "sudo health-control usb-safety-check --device /dev/sdc2", "sudo ", "sudo # Step 3: Create encrypted persistence (AUTOMATED)", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type kali --encrypted", "sudo → Confirms device selection", "sudo → Formats automatically", "sudo → Creates persistence.conf automatically", "sudo → Done!", "sudo ", "sudo # Step 4: Configure nuke password (AUTOMATED)", "sudo health-control luks-nuke --action configure --device /dev/sdc2", "sudo → Backs up header automatically to /backups/", "sudo → Configures nuke password automatically", "sudo → Verifies everything works", "sudo → Done!", "sudo ", "sudo # ✅ ZERO MANUAL COMMANDS!", "sudo # ✅ NO manual mounting/unmounting!", "sudo # ✅ NO manual backup commands!", "sudo # ✅ Everything automated with safety confirmations!", "sudo ", "sudo # EMERGENCY: Restore header if nuke password used accidentally", "sudo gpg -d /backups/header-sdc2-*.img.gpg | sudo cryptsetup luksHeaderRestore /dev/sdc2", "sudo ", "sudo # List available encrypted header backups", "sudo health-control luks-nuke --action list-backups --device /dev/sda1", "sudo ", "sudo # Restore from encrypted backup", "sudo health-control luks-nuke --action restore-backup --device /dev/sda1 --backup-file header-sda1-20260304-014630.img.gpg", "sudo ", "sudo # Delete old backup", "sudo health-control luks-nuke --action delete-backup --backup-file header-sda1-20260304-014630.img.gpg", "sudo ⚠️ USE ONLY IF nuke password was accidentally entered!", "sudo ", "sudo # JSON output for monitoring", "sudo health-control luks-nuke --action status --json" ], "name": "luks-nuke", "options": [], "requires_sudo": true, "usage": "health-control luks-nuke [OPTIONS]" }, { "description": "Detect valid LUKS devices on the system", "examples": [ "sudo health-control luks-detect", "sudo health-control luks-detect --all-devices", "sudo health-control luks-detect --json" ], "name": "luks-detect", "options": [], "requires_sudo": true, "usage": "health-control luks-detect [OPTIONS]" }, { "description": "Manage LUKS encrypted devices", "examples": [ "sudo health-control luks-manage --action list", "sudo health-control luks-manage --action unlock --device /dev/sdb1", "sudo health-control luks-manage --action lock --device /dev/sdb1" ], "name": "luks-manage", "options": [], "requires_sudo": true, "usage": "health-control luks-manage [OPTIONS]" }, { "description": "Advanced LUKS nuke configuration (emergency wipe)", "examples": [ "sudo health-control luks-nuke-advanced --device /dev/sdb1 --password EMERGENCY", "sudo health-control luks-nuke-advanced --device /dev/sda2 --json" ], "name": "luks-nuke-advanced", "options": [], "requires_sudo": true, "usage": "health-control luks-nuke-advanced [OPTIONS]" }, { "description": "Remove LUKS encryption from device", "examples": [ "sudo health-control luks-remove /dev/sdb1", "sudo health-control luks-remove /dev/sdb1 --force" ], "name": "luks-remove", "options": [], "requires_sudo": true, "usage": "health-control luks-remove [OPTIONS]" }, { "description": "Advanced LUKS device management", "examples": [ "sudo health-control luks-manage-advanced --action backup-header --device /dev/sdb1 --backup-file /tmp/header.backup", "sudo health-control luks-manage-advanced --action restore-header --device /dev/sdb1 --backup-file /tmp/header.backup", "sudo health-control luks-manage-advanced --action add-key --device /dev/sdb1 --key-file /tmp/newkey" ], "name": "luks-manage-advanced", "options": [], "requires_sudo": true, "usage": "health-control luks-manage-advanced [OPTIONS]" }, { "description": "Create Debian live-boot persistence media", "examples": [ "sudo health-control create-persistence", "sudo health-control create-persistence --size 8", "sudo health-control create-persistence --encrypted", "sudo health-control create-persistence --encrypted --size 8", "sudo health-control create-persistence --encrypted --password 'MySecurePass123'", "sudo health-control create-persistence --size 4 --output /tmp/persistence --json" ], "name": "create-persistence", "options": [], "requires_sudo": true, "usage": "health-control create-persistence [OPTIONS]" }, { "description": "Create persistence for other Linux distributions (Kali, Parrot, Tails)", "examples": [ "sudo # FULLY AUTOMATED - No manual mounting needed!", "sudo ", "sudo # RECOMMENDED: List devices first to see what's safe", "sudo health-control list-storage-devices", "sudo → Shows which devices are SAFE vs DANGEROUS", "sudo ", "sudo # Check if your device is safe", "sudo health-control usb-safety-check --device /dev/sdc2", "sudo → Verifies device before formatting", "sudo ", "sudo # Unencrypted persistence for Kali Linux (AUTOMATED)", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type kali", "sudo → Confirms device selection", "sudo → Formats partition automatically", "sudo → Creates persistence.conf automatically", "sudo → Ready to use - NO manual mounting!", "sudo ", "sudo # Encrypted persistence for Parrot OS (FULLY AUTOMATED)", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type parrot --encrypted", "sudo → Password prompted securely (not visible in history)", "sudo → Confirms device selection", "sudo → Encrypts partition automatically", "sudo → Mounts, configures, unmounts automatically", "sudo → Everything automated with safety confirmations!", "sudo ", "sudo # Encrypted persistence for Tails with CLI password (INSECURE)", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type tails --encrypted --password 'MyPass123'", "sudo ⚠️ WARNING: Password visible in shell history!", "sudo ", "sudo # Complete safe workflow (AUTOMATED)", "sudo health-control list-storage-devices && \\", "sudo health-control usb-safety-check --device /dev/sdc2 && \\", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type kali --encrypted", "sudo → Entire workflow automated - just type YES when prompted!", "sudo ", "sudo # With JSON output", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type kali --encrypted --json" ], "name": "create-persistence-other-os", "options": [], "requires_sudo": true, "usage": "health-control create-persistence-other-os [OPTIONS]" }, { "description": "Check storage encryption status", "examples": [ "sudo # Check overall system encryption status", "sudo health-control encryption-status", "sudo → Shows: LUKS devices, encrypted filesystems, swap encryption", "sudo → Shows: Home directory encryption, full disk encryption status", "sudo → Reports: Encryption count summary (X/Y devices encrypted)", "sudo → Lists: Active encrypted containers and their mount points", "sudo ", "sudo # Typical output includes:", "sudo # - LUKS devices: /dev/sda5 (/, 120 GB), /dev/sdb1 (backup, 500 GB)", "sudo # - Encrypted swap: Yes (dm-crypt)", "sudo # - Home encryption: Yes (LUKS)", "sudo # - Full disk encryption: Yes (all partitions encrypted)", "sudo # - Encryption strength: AES-256-XTS", "sudo ", "sudo # JSON output for monitoring/scripting", "sudo health-control encryption-status --json", "sudo → Structured data: luks_devices[], encrypted_filesystems[]", "sudo → Boolean flags: home_encryption, swap_encrypted, full_disk_encryption", "sudo → Device details: cipher, key_size, device_path, mount_point, size", "sudo → Use in monitoring scripts for encryption compliance" ], "name": "encryption-status", "options": [], "requires_sudo": true, "usage": "health-control encryption-status [OPTIONS]" }, { "description": "Create encrypted container", "examples": [ "sudo # Create encrypted container (default: ext4, 1GB)", "sudo health-control container-create --path /tmp/secure.img", "sudo → Size: 1024 MB (default)", "sudo → Filesystem: ext4 (default)", "sudo → Creates sparse file (doesn't use full size immediately)", "sudo → Ready to mount and use", "sudo ", "sudo # Create large LUKS encrypted container", "sudo health-control container-create --path /secure/data.img --size 5000 --fs-type luks", "sudo → Size: 5000 MB (5 GB)", "sudo → Prompts for strong password (8+ chars recommended)", "sudo → Uses cryptsetup for LUKS2 format", "sudo → Hardware crypto acceleration if available", "sudo ", "sudo # Create VeraCrypt compatible container", "sudo health-control container-create --path /backup/portable.img --size 2048 --fs-type veracrypt", "sudo → Cross-platform compatibility (Windows, Mac, Linux)", "sudo → Can be opened with VeraCrypt GUI", "sudo → Good for external backup drives", "sudo ", "sudo # Filesystem types explained:", "sudo # --fs-type ext4:", "sudo # - Standard Linux filesystem (fastest)", "sudo # - No encryption by default", "sudo # - Best for temporary/non-sensitive data", "sudo ", "sudo # --fs-type luks:", "sudo # - LUKS2 encrypted container (RECOMMENDED for sensitive data)", "sudo # - AES-256-XTS encryption", "sudo # - Linux native, best performance", "sudo # - Requires password to mount", "sudo ", "sudo # --fs-type veracrypt:", "sudo # - VeraCrypt compatible (cross-platform)", "sudo # - Works on Windows, Mac, Linux", "sudo # - Slightly slower than LUKS", "sudo # - Good for portability", "sudo ", "sudo # Size guidelines:", "sudo # Small (100-500 MB): Documents, passwords, keys", "sudo # Medium (500-2000 MB): Photos, code projects", "sudo # Large (2000-10000 MB): Videos, backups, archives", "sudo # Very Large (10000+ MB): Full system backups" ], "name": "container-create", "options": [], "requires_sudo": true, "usage": "health-control container-create [OPTIONS]" }, { "description": "Mount encrypted container", "examples": [ "sudo # Mount encrypted container (password prompted securely)", "sudo health-control container-mount --container /path/to/secure.img --mount-point /mnt/secure", "sudo → Prompts for LUKS password (not visible, not logged)", "sudo → Creates /mnt/secure automatically if it doesn't exist", "sudo → Opens LUKS device with cryptsetup", "sudo → Mounts to /mnt/secure/ - ready to use", "sudo ", "sudo # Complete workflow: create → mount → use → unmount", "sudo ", "sudo # Step 1: Create encrypted container", "sudo health-control container-create --path /tmp/data.img --size 500 --fs-type luks", "sudo ", "sudo # Step 2: Mount container", "sudo health-control container-mount --container /tmp/data.img --mount-point /mnt/data", "sudo # Enter password when prompted", "sudo ", "sudo # Step 3: Use the container (copy files, edit, etc.)", "sudo cp -r /sensitive/documents /mnt/data/", "sudo echo 'secret data' > /mnt/data/confidential.txt", "sudo ", "sudo # Step 4: Unmount when done", "sudo health-control container-unmount --mount-point /mnt/data", "sudo ", "sudo # ✅ Complete encrypted container lifecycle!", "sudo # ✅ Data encrypted at rest, decrypted only when mounted", "sudo # ✅ Mount point automatically created and cleaned up" ], "name": "container-mount", "options": [], "requires_sudo": true, "usage": "health-control container-mount [OPTIONS]" }, { "description": "Unmount encrypted container", "examples": [ "sudo # Safely unmount encrypted container", "sudo health-control container-unmount --mount-point /mnt/secure", "sudo → Unmounts filesystem from /mnt/secure", "sudo → Closes LUKS mapper device automatically", "sudo → Cleans up mount point (removes directory)", "sudo → ⚠️ Close all files in /mnt/secure BEFORE unmounting!", "sudo ", "sudo # Check if anything is using the mount before unmounting", "sudo lsof +D /mnt/secure # List open files in mount point", "sudo # If files are open, close them first, then:", "sudo health-control container-unmount --mount-point /mnt/secure", "sudo ", "sudo # Error handling: If unmount fails due to busy device", "sudo # 1. Check for open files:", "sudo lsof +D /mnt/secure", "sudo # 2. Kill processes using the mount:", "sudo fuser -km /mnt/secure # Kill processes (use with caution!)", "sudo # 3. Try unmounting again:", "sudo health-control container-unmount --mount-point /mnt/secure", "sudo ", "sudo # Safe workflow: Always unmount before system shutdown", "sudo # 1. Copy files out of container", "sudo # 2. Close all applications accessing the mount", "sudo # 3. Unmount container", "sudo # 4. Container is now encrypted and safe to store/transport" ], "name": "container-unmount", "options": [], "requires_sudo": true, "usage": "health-control container-unmount [OPTIONS]" } ] }, { "category": "Security Tools", "commands": [ { "description": "Quick rootkit scan (fast, essential checks)", "examples": [ "sudo health-control rootkit-scan", "sudo health-control rootkit-scan --json" ], "name": "rootkit-scan", "options": [], "requires_sudo": true, "usage": "health-control rootkit-scan [OPTIONS]" }, { "description": "Check Kloak keyboard anonymization status", "examples": [ "health-control kloak-status", "health-control kloak-status --json" ], "name": "kloak-status", "options": [], "requires_sudo": false, "usage": "health-control kloak-status [OPTIONS]" }, { "description": "Enable Kloak keyboard anonymization", "examples": [ "sudo health-control kloak-enable", "sudo health-control kloak-enable --json" ], "name": "kloak-enable", "options": [], "requires_sudo": true, "usage": "health-control kloak-enable [OPTIONS]" }, { "description": "Disable Kloak keyboard anonymization", "examples": [ "sudo health-control kloak-disable", "sudo health-control kloak-disable --json" ], "name": "kloak-disable", "options": [], "requires_sudo": true, "usage": "health-control kloak-disable [OPTIONS]" }, { "description": "Configure Kloak keystroke anonymization settings", "examples": [ "sudo health-control kloak-configure --delay 100", "sudo health-control kloak-configure --mode aggressive --jitter 50", "sudo health-control kloak-configure --json" ], "name": "kloak-configure", "options": [], "requires_sudo": true, "usage": "health-control kloak-configure [OPTIONS]" }, { "description": "Set Kloak event processing mode", "examples": [ "sudo health-control kloak-event-mode --mode raw", "sudo health-control kloak-event-mode --mode filtered", "sudo health-control kloak-event-mode --mode adaptive --json" ], "name": "kloak-event-mode", "options": [], "requires_sudo": true, "usage": "health-control kloak-event-mode [OPTIONS]" }, { "description": "Show Kloak keystroke anonymization statistics", "examples": [ "health-control kloak-stats", "health-control kloak-stats --reset", "health-control kloak-stats --json" ], "name": "kloak-stats", "options": [], "requires_sudo": false, "usage": "health-control kloak-stats [OPTIONS]" }, { "description": "Update AIDE database after legitimate changes", "examples": [ "sudo health-control aide-update", "sudo health-control aide-update --accept-changes", "sudo health-control aide-update --json" ], "name": "aide-update", "options": [], "requires_sudo": true, "usage": "health-control aide-update [OPTIONS]" }, { "description": "Check file integrity with AIDE", "examples": [ "sudo health-control aide-check", "sudo health-control aide-check --json" ], "name": "aide-check", "options": [], "requires_sudo": true, "usage": "health-control aide-check [OPTIONS]" }, { "description": "Initialize AIDE database for file integrity monitoring", "examples": [ "sudo health-control aide-init", "sudo health-control aide-init --config ./aide.conf", "sudo health-control aide-init --timeout 7200", "sudo health-control aide-init --background", "sudo health-control aide-init --json" ], "name": "aide-init", "options": [], "requires_sudo": true, "usage": "health-control aide-init [OPTIONS]" }, { "description": "Reinitialize AIDE database (reset baseline)", "examples": [ "sudo health-control aide-reinit", "sudo health-control aide-reinit --force", "sudo health-control aide-reinit --json" ], "name": "aide-reinit", "options": [], "requires_sudo": true, "usage": "health-control aide-reinit [OPTIONS]" }, { "description": "Scan specific directory with AIDE", "examples": [ "sudo health-control aide-scan-dir ./config", "sudo health-control aide-scan-dir /usr/bin --recursive", "sudo health-control aide-scan-dir /home --json" ], "name": "aide-scan-dir", "options": [], "requires_sudo": true, "usage": "health-control aide-scan-dir [OPTIONS]" } ] }, { "category": "Storage & USB Security", "commands": [ { "description": "List all storage devices with safety information for persistence operations", "examples": [ "sudo # List all storage devices with safety indicators", "sudo health-control list-storage-devices", "sudo → Shows which devices are safe (USB) vs dangerous (system)", "sudo ", "sudo # Include all devices (loop, ram, etc)", "sudo health-control list-storage-devices --all", "sudo ", "sudo # JSON output for scripting", "sudo health-control list-storage-devices --json", "sudo ", "sudo # Before creating persistence (recommended workflow)", "sudo health-control list-storage-devices && \\", "sudo health-control create-persistence-other-os --device /dev/sdc2 --os-type kali" ], "name": "list-storage-devices", "options": [], "requires_sudo": true, "usage": "health-control list-storage-devices [OPTIONS]" }, { "description": "Check if a device is safe for persistence/formatting operations", "examples": [ "sudo # Check if device is safe for persistence", "sudo health-control usb-safety-check --device /dev/sdc2", "sudo → Returns: SAFE, CAUTION, or DANGER with details", "sudo ", "sudo # Check system drive (will warn)", "sudo health-control usb-safety-check --device /dev/sda1", "sudo → Shows why device is dangerous (system drive)", "sudo ", "sudo # JSON output for scripting", "sudo health-control usb-safety-check --device /dev/sdc2 --json" ], "name": "usb-safety-check", "options": [], "requires_sudo": true, "usage": "health-control usb-safety-check [OPTIONS]" } ] }, { "category": "Storage Security", "commands": [ { "description": "Securely wipe storage devices and free space", "examples": [ "sudo health-control storage-wipe --free-space", "sudo health-control storage-wipe --device /dev/sdb --json" ], "name": "storage-wipe", "options": [], "requires_sudo": true, "usage": "health-control storage-wipe [OPTIONS]" }, { "description": "Encrypt a storage device", "examples": [ "sudo health-control storage-encrypt --device /dev/sdb1", "sudo health-control storage-encrypt --device /dev/sdc --json" ], "name": "storage-encrypt", "options": [], "requires_sudo": true, "usage": "health-control storage-encrypt [OPTIONS]" }, { "description": "Optimize encryption performance and security settings", "examples": [ "sudo # Understanding encryption performance profiles", "sudo ", "sudo # Benchmark all ciphers and show recommendations (dry-run, no changes)", "sudo health-control encryption-tune --profile performance --benchmark", "sudo → Benchmarks all available ciphers", "sudo → Recommends fastest cipher for your hardware", "sudo → Shows throughput in MB/s", "sudo → No changes applied (dry-run mode)", "sudo ", "sudo # Apply performance optimizations", "sudo health-control encryption-tune --profile performance --apply", "sudo → Sets: aes-xts-plain64 cipher, 256-bit key", "sudo → Optimizes: I/O scheduler (deadline), queue depth (256)", "sudo → Enables hardware crypto acceleration", "sudo → May require reboot for full effect", "sudo ", "sudo # Security-focused tuning (paranoid mode)", "sudo health-control encryption-tune --profile security --iter-time 5000 --apply", "sudo → Maximizes key derivation time (slower unlock, more secure)", "sudo → Uses strongest available cipher", "sudo → 5000ms iteration time (vs 2000ms default)", "sudo → Recommended for high-security environments", "sudo ", "sudo # Balanced profile (default)", "sudo health-control encryption-tune --profile balanced", "sudo → Good balance between performance and security", "sudo → aes-xts-plain64 with 256-bit key", "sudo → Standard iteration time (2000ms)", "sudo → Shows recommendations without applying (add --apply to implement)", "sudo ", "sudo # Device-specific tuning for external drive", "sudo health-control encryption-tune --device /dev/sdb1 --cipher aes-xts-plain64 --key-size 512", "sudo → Applies settings to specific device only", "sudo → 512-bit key for maximum security", "sudo → Requires unlocking and reformatting (data loss!)", "sudo ", "sudo # Check current tuning status", "sudo health-control encryption-tune", "sudo → Shows current encryption settings", "sudo → Shows cipher, key size, iteration time", "sudo → No changes made (default dry-run)", "sudo ", "sudo # JSON output for scripting", "sudo health-control encryption-tune --json", "sudo → Structured output with recommendations", "sudo → Cipher benchmarks and current settings" ], "name": "encryption-tune", "options": [], "requires_sudo": true, "usage": "health-control encryption-tune [OPTIONS]" } ] }, { "category": "System Control", "commands": [ { "description": "Get the current hostname", "examples": [ "health-control get-hostname", "health-control get-hostname --json" ], "name": "get-hostname", "options": [], "requires_sudo": false, "usage": "health-control get-hostname" }, { "description": "Change hostname (prompts for new hostname)", "examples": [ "sudo health-control change-hostname", "sudo health-control change-hostname new-hostname", "sudo health-control change-hostname --json" ], "name": "change-hostname", "options": [], "requires_sudo": true, "usage": "health-control change-hostname [OPTIONS]" }, { "description": "List available hostnames by category", "examples": [ "health-control list-hostnames", "health-control list-hostnames --category all", "health-control list-hostnames --category windows", "health-control list-hostnames --category linux", "health-control list-hostnames --category apple", "health-control list-hostnames --category network", "health-control list-hostnames --category mobile", "health-control list-hostnames --category iot", "health-control list-hostnames --category gaming", "health-control list-hostnames --category fiction", "health-control list-hostnames --json" ], "name": "list-hostnames", "options": [], "requires_sudo": false, "usage": "health-control list-hostnames [OPTIONS]" }, { "description": "Set a random hostname from a specific category", "examples": [ "sudo health-control set-random-hostname-category", "sudo health-control set-random-hostname-category --category windows", "sudo health-control set-random-hostname-category --category linux", "sudo health-control set-random-hostname-category --category apple", "sudo health-control set-random-hostname-category --category network", "sudo health-control set-random-hostname-category --category fiction --json" ], "name": "set-random-hostname-category", "options": [], "requires_sudo": true, "usage": "health-control set-random-hostname-category [OPTIONS]" }, { "description": "Get the actual logged-in user (handles sudo correctly)", "examples": [ "health-control get-logged-user", "health-control get-logged-user --json", "sudo health-control get-logged-user", "sudo health-control get-logged-user --json-pretty" ], "name": "get-logged-user", "options": [], "requires_sudo": false, "usage": "health-control get-logged-user [OPTIONS]" }, { "description": "Show current system timezone", "examples": [ "health-control show-timezone", "health-control show-timezone --json" ], "name": "show-timezone", "options": [], "requires_sudo": false, "usage": "health-control show-timezone [OPTIONS]" }, { "description": "Sync timezone based on IP geolocation", "examples": [ "sudo health-control sync-timezone", "sudo health-control sync-timezone --json" ], "name": "sync-timezone", "options": [], "requires_sudo": true, "usage": "health-control sync-timezone [OPTIONS]" }, { "description": "Show timezone based on current IP location", "examples": [ "health-control show-remote-timezone", "health-control show-remote-timezone --json" ], "name": "show-remote-timezone", "options": [], "requires_sudo": false, "usage": "health-control show-remote-timezone [OPTIONS]" }, { "description": "Set system timezone", "examples": [ "sudo health-control set-timezone --timezone America/New_York", "sudo health-control set-timezone --timezone Europe/London", "sudo health-control set-timezone --timezone Asia/Tokyo --json", "sudo health-control set-timezone --value America/Chicago" ], "name": "set-timezone", "options": [], "requires_sudo": true, "usage": "health-control set-timezone [OPTIONS]" }, { "description": "List available timezones by category", "examples": [ "health-control list-timezones", "health-control list-timezones --category all", "health-control list-timezones --category africa", "health-control list-timezones --category americas", "health-control list-timezones --category asia", "health-control list-timezones --category europe", "health-control list-timezones --category australia", "health-control list-timezones --category pacific", "health-control list-timezones --category utc", "health-control list-timezones --json" ], "name": "list-timezones", "options": [], "requires_sudo": false, "usage": "health-control list-timezones [OPTIONS]" }, { "description": "Set a random timezone from a specific category", "examples": [ "sudo health-control set-random-timezone", "sudo health-control set-random-timezone --category americas", "sudo health-control set-random-timezone --category europe", "sudo health-control set-random-timezone --category asia", "sudo health-control set-random-timezone --category africa", "sudo health-control set-random-timezone --category pacific --json" ], "name": "set-random-timezone", "options": [], "requires_sudo": true, "usage": "health-control set-random-timezone [OPTIONS]" }, { "description": "Play notification sound", "examples": [ "sudo health-control play-sound", "sudo health-control play-sound --sound alert", "sudo health-control play-sound success", "sudo health-control play-sound warning -m mp3", "sudo health-control play-sound alert --debug" ], "name": "play-sound", "options": [], "requires_sudo": true, "usage": "health-control play-sound [OPTIONS]" }, { "description": "Send desktop notification", "examples": [ "health-control notify --message \"Security check complete\"", "health-control notify --message \"Hello from Kodachi\"", "health-control notify --message \"Alert\" --body \"VPN connected\"", "health-control notify --message \"Warning\" --urgency critical --duration 30", "health-control notify --message \"Update\" --notify-icon \"/path/to/icon.png\"" ], "name": "notify", "options": [], "requires_sudo": false, "usage": "health-control notify [OPTIONS]" } ] }, { "category": "System Information", "commands": [ { "description": "Display comprehensive system information", "examples": [ "sudo health-control offline-info-system", "sudo health-control offline-info-system --json" ], "name": "offline-info-system", "options": [], "requires_sudo": true, "usage": "health-control offline-info-system [OPTIONS]" }, { "description": "Display hardware information", "examples": [ "sudo health-control offline-info-hardware", "sudo health-control offline-info-hardware --json" ], "name": "offline-info-hardware", "options": [], "requires_sudo": true, "usage": "health-control offline-info-hardware [OPTIONS]" }, { "description": "Display process information", "examples": [ "sudo health-control offline-info-process", "sudo health-control offline-info-process --json" ], "name": "offline-info-process", "options": [], "requires_sudo": true, "usage": "health-control offline-info-process [OPTIONS]" }, { "description": "Display security and encryption status", "examples": [ "sudo health-control offline-info-security", "sudo health-control offline-info-security --json" ], "name": "offline-info-security", "options": [], "requires_sudo": true, "usage": "health-control offline-info-security [OPTIONS]" }, { "description": "Display network information", "examples": [ "sudo health-control offline-info-network", "sudo health-control offline-info-network --json" ], "name": "offline-info-network", "options": [], "requires_sudo": true, "usage": "health-control offline-info-network [OPTIONS]" }, { "description": "Display user information", "examples": [ "sudo health-control offline-info-user", "sudo health-control offline-info-user --json" ], "name": "offline-info-user", "options": [], "requires_sudo": true, "usage": "health-control offline-info-user [OPTIONS]" }, { "description": "Display storage information", "examples": [ "sudo health-control offline-info-storage", "sudo health-control offline-info-storage --json" ], "name": "offline-info-storage", "options": [], "requires_sudo": true, "usage": "health-control offline-info-storage [OPTIONS]" }, { "description": "Display system services information", "examples": [ "sudo health-control offline-info-services", "sudo health-control offline-info-services --json" ], "name": "offline-info-services", "options": [], "requires_sudo": true, "usage": "health-control offline-info-services [OPTIONS]" }, { "description": "Display all system information", "examples": [ "sudo health-control offline-info-all", "sudo health-control offline-info-all --json" ], "name": "offline-info-all", "options": [], "requires_sudo": true, "usage": "health-control offline-info-all [OPTIONS]" }, { "description": "Ping a random privacy-respecting target and return latency", "examples": [ "health-control ping", "health-control ping --json" ], "name": "ping", "options": [], "requires_sudo": false, "usage": "health-control ping [OPTIONS]" }, { "description": "Get process uptime for VPN or Tor", "examples": [ "health-control process-age --process vpn", "health-control process-age --process tor", "health-control process-age --process vpn --json", "health-control process-age --process tor --json" ], "name": "process-age", "options": [], "requires_sudo": false, "usage": "health-control process-age [OPTIONS]" } ] }, { "category": "System Information & Offline Actions", "commands": [ { "description": "Enable/disable/check Bluetooth service", "examples": [ "sudo health-control offline-bluetooth --action disable", "sudo health-control offline-bluetooth --action enable", "sudo health-control offline-bluetooth --action check --json" ], "name": "offline-bluetooth", "options": [], "requires_sudo": true, "usage": "health-control offline-bluetooth [OPTIONS]" }, { "description": "Manage WiFi connectivity", "examples": [ "sudo health-control offline-wifi --action disable", "sudo health-control offline-wifi --action enable", "sudo health-control offline-wifi --action check --json" ], "name": "offline-wifi", "options": [], "requires_sudo": true, "usage": "health-control offline-wifi [OPTIONS]" }, { "description": "Manage USB storage devices", "examples": [ "sudo health-control offline-usb-storage --action disable", "sudo health-control offline-usb-storage --action enable", "sudo health-control offline-usb-storage --action check --json" ], "name": "offline-usb-storage", "options": [], "requires_sudo": true, "usage": "health-control offline-usb-storage [OPTIONS]" }, { "description": "Manage webcam device", "examples": [ "sudo health-control offline-webcam --action disable", "sudo health-control offline-webcam --action enable", "sudo health-control offline-webcam --action check --json" ], "name": "offline-webcam", "options": [], "requires_sudo": true, "usage": "health-control offline-webcam [OPTIONS]" }, { "description": "Manage microphone device", "examples": [ "sudo health-control offline-microphone --action disable", "sudo health-control offline-microphone --action enable", "sudo health-control offline-microphone --action check --json" ], "name": "offline-microphone", "options": [], "requires_sudo": true, "usage": "health-control offline-microphone [OPTIONS]" }, { "description": "Manage system logging", "examples": [ "sudo health-control offline-systemlogs --action disable", "sudo health-control offline-systemlogs --action enable", "sudo health-control offline-systemlogs --action check --json" ], "name": "offline-systemlogs", "options": [], "requires_sudo": true, "usage": "health-control offline-systemlogs [OPTIONS]" }, { "description": "Manage CUPS printing service", "examples": [ "sudo health-control offline-cups --action disable # Disable printer service (CUPS)", "sudo health-control offline-cups --action enable # Enable printer service (CUPS)", "sudo health-control offline-cups --action check --json" ], "name": "offline-cups", "options": [], "requires_sudo": true, "usage": "health-control offline-cups [OPTIONS]" }, { "description": "Manage NetworkManager service", "examples": [ "sudo health-control offline-networkmanager --action disable", "sudo health-control offline-networkmanager --action enable", "sudo health-control offline-networkmanager --action check --json" ], "name": "offline-networkmanager", "options": [], "requires_sudo": true, "usage": "health-control offline-networkmanager [OPTIONS]" }, { "description": "Manage NumLock configuration", "examples": [ "sudo health-control offline-numlock --action enable", "sudo health-control offline-numlock --action disable", "sudo health-control offline-numlock --action check --json" ], "name": "offline-numlock", "options": [], "requires_sudo": true, "usage": "health-control offline-numlock [OPTIONS]" }, { "description": "Manage command history", "examples": [ "sudo health-control offline-cmdhistory --action disable", "sudo health-control offline-cmdhistory --action enable", "sudo health-control offline-cmdhistory --action check --json" ], "name": "offline-cmdhistory", "options": [], "requires_sudo": true, "usage": "health-control offline-cmdhistory [OPTIONS]" }, { "description": "Enable/disable/check auto-login functionality", "examples": [ "sudo health-control offline-autologin --action disable", "sudo health-control offline-autologin --action enable", "sudo health-control offline-autologin --action check --json" ], "name": "offline-autologin", "options": [], "requires_sudo": true, "usage": "health-control offline-autologin [OPTIONS]" }, { "description": "Manage screen locking", "examples": [ "sudo health-control offline-screen-lock --action enable", "sudo health-control offline-screen-lock --action disable", "sudo health-control offline-screen-lock --action check --json" ], "name": "offline-screen-lock", "options": [], "requires_sudo": true, "usage": "health-control offline-screen-lock [OPTIONS]" }, { "description": "Enable/disable/check file descriptor limits", "examples": [ "sudo health-control offline-fdlimit --action enable --soft-limit 1024 --hard-limit 4096", "sudo health-control offline-fdlimit --action disable", "sudo health-control offline-fdlimit --action check --json" ], "name": "offline-fdlimit", "options": [], "requires_sudo": true, "usage": "health-control offline-fdlimit [OPTIONS]" }, { "description": "Enable/disable/check network optimization", "examples": [ "sudo health-control offline-netoptimize --action enable", "sudo health-control offline-netoptimize --action disable", "sudo health-control offline-netoptimize --action check --json" ], "name": "offline-netoptimize", "options": [], "requires_sudo": true, "usage": "health-control offline-netoptimize [OPTIONS]" }, { "description": "Enable/disable/check BBR congestion control", "examples": [ "sudo health-control offline-bbr --action enable", "sudo health-control offline-bbr --action disable", "sudo health-control offline-bbr --action check --json" ], "name": "offline-bbr", "options": [], "requires_sudo": true, "usage": "health-control offline-bbr [OPTIONS]" }, { "description": "Enable/disable/check interface speed optimization", "examples": [ "sudo health-control offline-ifspeed --action enable --interface eth0 --speed 1000", "sudo health-control offline-ifspeed --action disable", "sudo health-control offline-ifspeed --action check --json", "sudo health-control offline-ifspeed --action enable --interface wlan0" ], "name": "offline-ifspeed", "options": [], "requires_sudo": true, "usage": "health-control offline-ifspeed [OPTIONS]" }, { "description": "Manage Avahi daemon service", "examples": [ "sudo health-control offline-avahi --action disable", "sudo health-control offline-avahi --action enable", "sudo health-control offline-avahi --action check --json" ], "name": "offline-avahi", "options": [], "requires_sudo": true, "usage": "health-control offline-avahi [OPTIONS]" }, { "description": "Manage ModemManager service", "examples": [ "sudo health-control offline-modem-manager --action disable", "sudo health-control offline-modem-manager --action enable", "sudo health-control offline-modem-manager --action check --json" ], "name": "offline-modem-manager", "options": [], "requires_sudo": true, "usage": "health-control offline-modem-manager [OPTIONS]" }, { "description": "Manage SSH daemon service", "examples": [ "sudo health-control offline-ssh --action disable", "sudo health-control offline-ssh --action enable", "sudo health-control offline-ssh --action check --json" ], "name": "offline-ssh", "options": [], "requires_sudo": true, "usage": "health-control offline-ssh [OPTIONS]" }, { "description": "Manage Apache web server service", "examples": [ "sudo health-control offline-apache --action disable", "sudo health-control offline-apache --action enable", "sudo health-control offline-apache --action check --json" ], "name": "offline-apache", "options": [], "requires_sudo": true, "usage": "health-control offline-apache [OPTIONS]" }, { "description": "Manage Nginx web server service", "examples": [ "sudo health-control offline-nginx --action disable", "sudo health-control offline-nginx --action enable", "sudo health-control offline-nginx --action check --json" ], "name": "offline-nginx", "options": [], "requires_sudo": true, "usage": "health-control offline-nginx [OPTIONS]" }, { "description": "Manage Docker container service", "examples": [ "sudo health-control offline-docker --action disable", "sudo health-control offline-docker --action enable", "sudo health-control offline-docker --action check --json" ], "name": "offline-docker", "options": [], "requires_sudo": true, "usage": "health-control offline-docker [OPTIONS]" }, { "description": "Manage MySQL database service", "examples": [ "sudo health-control offline-mysql --action disable", "sudo health-control offline-mysql --action enable", "sudo health-control offline-mysql --action check --json" ], "name": "offline-mysql", "options": [], "requires_sudo": true, "usage": "health-control offline-mysql [OPTIONS]" } ] }, { "category": "System Maintenance", "commands": [ { "description": "Enable automatic security updates", "examples": [ "sudo health-control auto-updates-enable", "sudo health-control auto-updates-enable --json" ], "name": "auto-updates-enable", "options": [], "requires_sudo": true, "usage": "health-control auto-updates-enable [OPTIONS]" }, { "description": "Disable automatic security updates", "examples": [ "sudo health-control auto-updates-disable", "sudo health-control auto-updates-disable --json" ], "name": "auto-updates-disable", "options": [], "requires_sudo": true, "usage": "health-control auto-updates-disable [OPTIONS]" }, { "description": "Check automatic updates status", "examples": [ "sudo health-control auto-updates-status", "sudo health-control auto-updates-status --json" ], "name": "auto-updates-status", "options": [], "requires_sudo": true, "usage": "health-control auto-updates-status [OPTIONS]" }, { "description": "Enable system maintenance settings", "examples": [ "health-control system-maintenance-enable", "health-control system-maintenance-enable --json" ], "name": "system-maintenance-enable", "options": [], "requires_sudo": false, "usage": "health-control system-maintenance-enable [OPTIONS]" }, { "description": "Disable system maintenance settings", "examples": [ "health-control system-maintenance-disable", "health-control system-maintenance-disable --json" ], "name": "system-maintenance-disable", "options": [], "requires_sudo": false, "usage": "health-control system-maintenance-disable [OPTIONS]" }, { "description": "Check system maintenance status", "examples": [ "health-control system-maintenance-status", "health-control system-maintenance-status --json" ], "name": "system-maintenance-status", "options": [], "requires_sudo": false, "usage": "health-control system-maintenance-status [OPTIONS]" }, { "description": "Enable password policy enforcement", "examples": [ "sudo health-control password-policy-enable", "sudo health-control password-policy-enable --json" ], "name": "password-policy-enable", "options": [], "requires_sudo": true, "usage": "health-control password-policy-enable [OPTIONS]" }, { "description": "Disable password policy enforcement", "examples": [ "sudo health-control password-policy-disable", "sudo health-control password-policy-disable --json" ], "name": "password-policy-disable", "options": [], "requires_sudo": true, "usage": "health-control password-policy-disable [OPTIONS]" }, { "description": "Check password policy status", "examples": [ "sudo health-control password-policy-status", "sudo health-control password-policy-status --json" ], "name": "password-policy-status", "options": [], "requires_sudo": true, "usage": "health-control password-policy-status [OPTIONS]" }, { "description": "Enable user security hardening", "examples": [ "sudo health-control user-security-enable", "sudo health-control user-security-enable --json" ], "name": "user-security-enable", "options": [], "requires_sudo": true, "usage": "health-control user-security-enable [OPTIONS]" }, { "description": "Disable user security hardening", "examples": [ "sudo health-control user-security-disable", "sudo health-control user-security-disable --json" ], "name": "user-security-disable", "options": [], "requires_sudo": true, "usage": "health-control user-security-disable [OPTIONS]" }, { "description": "Check user security status", "examples": [ "sudo health-control user-security-status", "sudo health-control user-security-status --json" ], "name": "user-security-status", "options": [], "requires_sudo": true, "usage": "health-control user-security-status [OPTIONS]" }, { "description": "Enable two-factor authentication", "examples": [ "# ⚠️ WARNING: 2FA has known bugs with XFCE/LightDM login!", "# Works reliably for: SSH, sudo | Unreliable for: XFCE login, lock screen", "health-control 2fa-enable", "health-control 2fa-enable --value $(whoami) --json", " ⚠ Security Note: Using $(whoami) exposes current username in command history" ], "name": "2fa-enable", "options": [], "requires_sudo": false, "usage": "health-control 2fa-enable [OPTIONS]" }, { "description": "Disable two-factor authentication", "examples": [ "# ⚠️ WARNING: 2FA has known bugs with XFCE/LightDM login!", "health-control 2fa-disable", "health-control 2fa-disable --json" ], "name": "2fa-disable", "options": [], "requires_sudo": false, "usage": "health-control 2fa-disable [OPTIONS]" }, { "description": "Check two-factor authentication status", "examples": [ "# ⚠️ WARNING: 2FA has known bugs with XFCE/LightDM login!", "# Works reliably for: SSH, sudo | Unreliable for: XFCE login, lock screen", "health-control 2fa-status", "health-control 2fa-status --json" ], "name": "2fa-status", "options": [], "requires_sudo": false, "usage": "health-control 2fa-status [OPTIONS]" }, { "description": "Check and install required packages", "examples": [ "sudo health-control check-and-install tor openvpn", "sudo health-control check-and-install rkhunter chkrootkit --json" ], "name": "check-and-install", "options": [], "requires_sudo": true, "usage": "health-control check-and-install [OPTIONS]" }, { "description": "Execute installation after checking dependencies", "examples": [ "sudo health-control check-and-install-do", "sudo health-control check-and-install-do --json" ], "name": "check-and-install-do", "options": [], "requires_sudo": true, "usage": "health-control check-and-install-do [OPTIONS]" }, { "description": "Clean up unnecessary packages", "examples": [ "health-control package-cleanup", "health-control package-cleanup --json" ], "name": "package-cleanup", "options": [], "requires_sudo": false, "usage": "health-control package-cleanup [OPTIONS]" }, { "description": "Clear system memory caches", "examples": [ "sudo health-control clear-cache", "sudo health-control clear-cache --level 1", "sudo health-control clear-cache --level 2", "sudo health-control clear-cache --level 3", "sudo health-control clear-cache --json" ], "name": "clear-cache", "options": [], "requires_sudo": true, "usage": "health-control clear-cache [OPTIONS]" } ] }, { "category": "System Recovery", "commands": [ { "description": "Fix broken sudo permissions (uses pkexec/su, no sudo required)", "examples": [ "sudo health-control fix-sudo", "sudo health-control fix-sudo --json", "sudo # This command tries pkexec first, then su -c, to fix sudo without sudo" ], "name": "fix-sudo", "options": [], "requires_sudo": true, "usage": "health-control fix-sudo [OPTIONS]" }, { "description": "Check sudo installation status and permissions", "examples": [ "sudo health-control check-sudo", "sudo health-control check-sudo --json" ], "name": "check-sudo", "options": [], "requires_sudo": true, "usage": "health-control check-sudo [OPTIONS]" } ] }, { "category": "USB Security", "commands": [ { "description": "Check USB Guard protection status", "examples": [ "sudo health-control usb-status", "sudo health-control usb-status --json" ], "name": "usb-status", "options": [], "requires_sudo": true, "usage": "health-control usb-status [OPTIONS]" }, { "description": "Enable USB Guard protection", "examples": [ "sudo health-control usb-guard-enable", "sudo health-control usb-guard-enable --json" ], "name": "usb-guard-enable", "options": [], "requires_sudo": true, "usage": "health-control usb-guard-enable [OPTIONS]" }, { "description": "Disable USB Guard protection", "examples": [ "sudo health-control usb-guard-disable", "sudo health-control usb-guard-disable --json" ], "name": "usb-guard-disable", "options": [], "requires_sudo": true, "usage": "health-control usb-guard-disable [OPTIONS]" }, { "description": "Manage USB device policies", "examples": [ "sudo health-control usb-policy --action list", "sudo health-control usb-policy --action add --device-id 1234:5678 --allow", "sudo health-control usb-policy --action remove --device-id 1234:5678" ], "name": "usb-policy", "options": [], "requires_sudo": true, "usage": "health-control usb-policy [OPTIONS]" }, { "description": "Monitor USB device connections in real-time", "examples": [ "sudo health-control usb-monitor", "sudo health-control usb-monitor --duration 300", "sudo health-control usb-monitor --alert", "sudo health-control usb-monitor --block-unauthorized --log-only", "sudo health-control usb-monitor --json" ], "name": "usb-monitor", "options": [], "requires_sudo": true, "usage": "health-control usb-monitor [OPTIONS]" }, { "description": "View USB device connection history", "examples": [ "sudo health-control usb-history", "sudo health-control usb-history --days 30", "sudo health-control usb-history --device-id 1234:5678", "sudo health-control usb-history --clear --days 90", "sudo health-control usb-history --json" ], "name": "usb-history", "options": [], "requires_sudo": true, "usage": "health-control usb-history [OPTIONS]" }, { "description": "Manage USB device whitelist", "examples": [ "sudo # Find device IDs first (use lsusb)", "sudo lsusb # Shows vendor:product IDs (e.g., 1234:5678)", "sudo → Bus 003 Device 002: ID 1234:5678 Vendor Name Product Name", "sudo ", "sudo # List current whitelist", "sudo health-control usb-whitelist --action list", "sudo → Shows all whitelisted device IDs", "sudo ", "sudo # Add device to whitelist", "sudo health-control usb-whitelist --action add --device-id 1234:5678", "sudo → Device allowed to connect automatically", "sudo ", "sudo # Remove device from whitelist", "sudo health-control usb-whitelist --action remove --device-id 1234:5678", "sudo → Device will be blocked on next connection", "sudo ", "sudo # Export whitelist (backup configuration)", "sudo health-control usb-whitelist --action export --file ~/usb-whitelist-backup.json", "sudo → Saves whitelist to JSON file for backup/transfer", "sudo ", "sudo # Import whitelist (restore configuration)", "sudo health-control usb-whitelist --action import --file ~/usb-whitelist-backup.json", "sudo → Restores whitelist from JSON backup file", "sudo ", "sudo # Clear all whitelisted devices", "sudo health-control usb-whitelist --action clear", "sudo ⚠️ WARNING: Removes ALL whitelisted devices - use with caution!", "sudo ", "sudo # JSON output for scripting", "sudo health-control usb-whitelist --action list --json" ], "name": "usb-whitelist", "options": [], "requires_sudo": true, "usage": "health-control usb-whitelist [OPTIONS]" } ] } ], "description": "Health control system for Kodachi that includes network connectivity checks and system health monitoring", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " } ], "name": "health-control", "usage": "health-control [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 17, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:14.870266307Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Test network connectivity and configuration", "examples": [ { "command": "sudo health-control net-check", "description": "Test both IP and domain connectivity (DNS only)", "expectedOutput": "Network connectivity status" }, { "command": "sudo health-control net-check --http", "description": "Test IP and domain connectivity including HTTP", "expectedOutput": "HTTP connectivity test results" }, { "command": "sudo health-control net-check --json", "description": "Network check with JSON output for automation", "expectedOutput": "JSON formatted network status" }, { "command": "sudo health-control net-check --http --json", "description": "HTTP network check with JSON output", "expectedOutput": "JSON formatted HTTP connectivity results" }, { "command": "sudo health-control net-check --ip-only", "description": "Check IP connectivity only, skip DNS checks", "expectedOutput": "IP connectivity test results" }, { "command": "sudo health-control net-check --domain-only", "description": "Check domain connectivity only, skip IP ping", "expectedOutput": "Domain connectivity test results" }, { "command": "sudo health-control net-check --timeout 15", "description": "Use custom timeout for network checks", "expectedOutput": "Network check with 15 second timeout" }, { "command": "sudo health-control net-check --ip-only --json", "description": "IP-only connectivity check with JSON output", "expectedOutput": "JSON formatted IP connectivity results" }, { "command": "sudo health-control net-check --domain-only --timeout 20", "description": "Domain-only connectivity check with custom timeout", "expectedOutput": "Domain connectivity test with 20 second timeout" }, { "command": "sudo health-control list-ips", "description": "Show IPs used for connectivity testing", "expectedOutput": "List of test IP addresses" }, { "command": "sudo health-control list-domains", "description": "Show domains used for connectivity testing", "expectedOutput": "List of test domain names" } ], "id": "1_network_connectivity", "title": "Network Connectivity" }, { "description": "Block and unblock internet traffic", "examples": [ { "command": "sudo health-control block-internet", "description": "Block internet using auto-detected method (tries nftables, then iptables, then UFW, then interfaces)", "expectedOutput": "Internet blocked successfully", "notes": "Without --method specified, health-control automatically selects the best available method" }, { "command": "sudo health-control block-internet --method iptables", "description": "Block using iptables firewall rules", "expectedOutput": "Iptables rules applied successfully" }, { "command": "sudo health-control block-internet --method nftables", "description": "Block using nftables firewall rules (preferred modern firewall)", "expectedOutput": "Nftables rules applied successfully" }, { "command": "sudo health-control block-internet --method firewall", "description": "Block using UFW (Uncomplicated Firewall)", "expectedOutput": "UFW rules applied successfully" }, { "command": "sudo health-control block-internet --method interfaces", "description": "Block by disabling network interfaces", "expectedOutput": "Network interfaces disabled successfully" }, { "command": "sudo health-control block-internet --method all", "description": "Block using ALL methods (UFW, nftables, iptables, and interfaces)", "expectedOutput": "All blocking methods applied successfully", "notes": "Applies all available blocking methods for maximum security" }, { "command": "sudo health-control block-internet --allow-local", "description": "Block internet but allow local network traffic", "expectedOutput": "Internet blocked, local traffic allowed" }, { "command": "sudo health-control block-internet --json", "description": "Block internet with JSON output", "expectedOutput": "JSON formatted blocking status" }, { "command": "sudo health-control block-internet --method iptables --allow-local --json", "description": "Block internet with iptables, allow local, JSON output", "expectedOutput": "JSON formatted blocking status with details" }, { "command": "sudo health-control block-internet --method all --allow-local", "description": "Block using ALL methods but allow local network traffic", "expectedOutput": "All blocking methods applied, local traffic allowed" }, { "command": "sudo health-control unblock-internet", "description": "Unblock internet traffic", "expectedOutput": "Internet unblocked successfully" }, { "command": "sudo health-control unblock-internet --method nftables", "description": "Unblock using nftables specifically", "expectedOutput": "Internet unblocked using nftables" }, { "command": "sudo health-control unblock-internet --method iptables", "description": "Unblock using iptables specifically", "expectedOutput": "Internet unblocked using iptables" }, { "command": "sudo health-control unblock-internet --method firewall", "description": "Unblock using UFW specifically", "expectedOutput": "Internet unblocked using UFW" }, { "command": "sudo health-control unblock-internet --method all", "description": "Unblock ALL methods (clears UFW, nftables, iptables, and re-enables interfaces)", "expectedOutput": "All blocking methods cleared successfully", "notes": "Ensures complete restoration by clearing all possible blocks" }, { "command": "sudo health-control unblock-internet --json", "description": "Unblock internet with JSON output", "expectedOutput": "JSON formatted unblocking status" }, { "command": "sudo health-control internet-status", "description": "Check current internet blocking status", "expectedOutput": "Internet traffic status" }, { "command": "sudo health-control internet-status --json", "description": "Check if internet traffic is blocked with JSON output", "expectedOutput": "JSON formatted block status" }, { "command": "sudo health-control kill-switch-arm", "description": "ARM the emergency kill switch - sets system to high-alert monitoring mode", "expectedOutput": "Kill switch ARMED - Monitoring mode active", "notes": "MONITORING MODE: Sets up automated threat detection using multiple monitoring methods:\n• NETWORK MONITORING: Uses netstat, ss, and iptables logs to detect unauthorized connections\n• FILE SYSTEM WATCHING: Monitors critical system files via inotify for unauthorized modifications\n• PROCESS MONITORING: Tracks running processes using ps/proc for suspicious behavior patterns\n• AUTH MONITORING: Watches /var/log/auth.log for failed login attempts (threshold: 5 failures)\n• SYSTEM INTEGRITY: Checks system file hashes and permissions for tampering\nDoes NOT take action until triggered - only prepares for rapid response. Auto-activates MEDIUM panic level when threats detected." }, { "command": "sudo health-control kill-switch-disarm", "description": "DISARM kill switch monitoring", "expectedOutput": "Kill switch DISARMED", "notes": "Stops monitoring mode. Use after threat has passed or false alarm." }, { "command": "sudo health-control kill-switch-status", "description": "Check if monitoring is armed/disarmed", "expectedOutput": "Shows armed status, trigger count, armed time", "notes": "READ-ONLY: Just displays current state, takes no action" }, { "command": "sudo health-control kill-switch-activate", "description": "IMMEDIATELY activate kill switch (default: medium panic)", "expectedOutput": "KILL SWITCH ACTIVATED - emergency procedures executed", "notes": "IMMEDIATE ACTION: Unlike 'arm', this executes panic NOW. Prompts for confirmation. Use --level soft/medium/hard" }, { "command": "sudo health-control panic-soft", "description": "IMMEDIATE soft panic (NO confirmation)", "expectedOutput": "Soft panic activated", "notes": "Actions: Kill network, clear clipboard (adaptive: wl-copy/xclip/xsel for Wayland/X11), lock screen. Reversible." }, { "command": "sudo health-control panic-medium", "description": "IMMEDIATE medium panic (WITH confirmation)", "expectedOutput": "Medium panic activated", "notes": "Actions: Kill network, terminate processes, clear memory, unmount devices. Requires manual restart." }, { "command": "sudo health-control panic-hard", "description": "IMMEDIATE hard panic with SHUTDOWN (WITH confirmation)", "expectedOutput": "Hard panic activated - system will shutdown", "notes": "CRITICAL: Wipes RAM, unmounts all, IMMEDIATE SHUTDOWN. IRREVERSIBLE!" }, { "command": "sudo health-control panic-recover", "description": "Recover from panic mode", "expectedOutput": "System recovered from panic mode", "notes": "Re-enables network, remounts volumes, restores services" } ], "id": "2_internet_traffic_control", "title": "Internet Traffic Control" }, { "description": "Monitor system changes and block internet on triggers", "examples": [ { "command": "sudo health-control enable --type watch-guard --watch ip --method nftables", "description": "Enable watch-guard to block internet if IP changes (VPN protection)", "expectedOutput": "Watch-guard enabled message with initial IP", "notes": "Blocks internet using nftables if external IP changes" }, { "command": "sudo health-control enable --type watch-guard --watch timezone --method iptables", "description": "Enable watch-guard for timezone changes", "expectedOutput": "Watch-guard enabled with current timezone", "notes": "Detects system time manipulation attempts" }, { "command": "sudo health-control enable --type watch-guard --watch interfaces --method firewall", "description": "Monitor network interfaces for changes", "expectedOutput": "Watch-guard monitoring interface list", "notes": "Blocks if new interfaces appear or existing ones change" }, { "command": "sudo health-control enable --type watch-guard --watch process --target tor --method interfaces", "description": "Monitor Tor process and block if it dies", "expectedOutput": "Watch-guard watching Tor process count", "notes": "Ensures no clearnet traffic if Tor crashes" }, { "command": "sudo health-control enable --type watch-guard --watch process --target firefox --method all", "description": "Monitor Firefox and use all block methods if it stops", "expectedOutput": "Watch-guard active for Firefox process", "notes": "Maximum blocking using all available methods" }, { "command": "sudo health-control watch-guard status", "description": "Show all active watch-guards and their trigger counts", "expectedOutput": "List of active watch-guards with details" }, { "command": "sudo health-control disable --type watch-guard ip", "description": "Disable IP watch-guard and unblock internet", "expectedOutput": "Watch-guard disabled confirmation", "notes": "Automatically unblocks internet unless --no-unblock used" }, { "command": "sudo health-control disable --type watch-guard all --no-unblock", "description": "Disable all watch-guards but keep internet blocked", "expectedOutput": "All watch-guards disabled message", "notes": "Use when you want manual control over unblocking" } ], "id": "3_watchguard", "title": "Watch-Guard Management" }, { "description": "Diagnose and fix connectivity issues", "examples": [ { "command": "sudo health-control recover-internet", "description": "Automatically diagnose and fix connectivity issues", "expectedOutput": "Recovery steps performed and status" }, { "command": "sudo health-control recover-internet --check-dns", "description": "Include DNS resolution testing and fixes", "expectedOutput": "Recovery with DNS diagnostics" }, { "command": "sudo health-control recover-internet --force", "description": "Force recovery even if connectivity appears working", "expectedOutput": "Forced recovery completion status" }, { "command": "sudo health-control recover-internet --silent", "description": "Run full internet recovery without desktop/terminal notifications", "expectedOutput": "Recovery runs silently (no notifications)", "notes": "Also supports --skipnotification, --skip-notification, and typo-compatible --skipnotifcation" }, { "command": "sudo health-control fast-recover-internet", "description": "Fast recovery: bounce interface + restart NetworkManager + DHCP renew", "expectedOutput": "FAST_RECOVER: SUCCESS", "notes": "Lightweight alternative to recover-internet — tries quick fix before full 9-method recovery" }, { "command": "sudo health-control fast-recover-internet --silent", "description": "Run fast recovery without desktop/terminal notifications", "expectedOutput": "FAST_RECOVER runs silently (no notifications)", "notes": "Also supports --skipnotification, --skip-notification, and typo-compatible --skipnotifcation" }, { "command": "sudo health-control fast-recover-internet --json", "description": "Fast recovery with JSON output", "expectedOutput": "JSON envelope with success status and method details" } ], "id": "4_network_recovery", "title": "Network Recovery" }, { "description": "Manage system timezone settings", "examples": [ { "command": "sudo health-control sync-timezone", "description": "Sync timezone based on IP geolocation", "expectedOutput": "Timezone synchronized to detected location" }, { "command": "sudo health-control show-timezone", "description": "Show current system timezone", "expectedOutput": "Current timezone information" }, { "command": "sudo health-control set-timezone --timezone \"America/New_York\"", "description": "Set specific timezone", "expectedOutput": "Timezone set to America/New_York" }, { "command": "sudo health-control show-remote-timezone", "description": "Show timezone based on current IP location", "expectedOutput": "Remote location timezone information" }, { "command": "health-control list-timezones", "description": "List all timezone categories", "expectedOutput": "List of timezone categories with counts" }, { "command": "health-control list-timezones --category all", "description": "List all available timezones", "expectedOutput": "Complete list of timezones" }, { "command": "health-control list-timezones --category africa", "description": "List African timezones", "expectedOutput": "List of African timezones" }, { "command": "health-control list-timezones --category americas", "description": "List American timezones", "expectedOutput": "List of North and South American timezones" }, { "command": "health-control list-timezones --category asia", "description": "List Asian timezones", "expectedOutput": "List of Asian timezones" }, { "command": "health-control list-timezones --category europe", "description": "List European timezones", "expectedOutput": "List of European timezones" }, { "command": "health-control list-timezones --category australia", "description": "List Australian timezones", "expectedOutput": "List of Australian timezones" }, { "command": "health-control list-timezones --category pacific", "description": "List Pacific timezones", "expectedOutput": "List of Pacific timezones" }, { "command": "health-control list-timezones --category utc", "description": "List UTC timezones", "expectedOutput": "List of UTC timezones" }, { "command": "health-control list-timezones --json", "description": "List timezone categories in JSON format", "expectedOutput": "JSON output of timezone categories" }, { "command": "sudo health-control set-random-timezone", "description": "Set a random timezone from all available", "expectedOutput": "Timezone set to random value", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category americas", "description": "Set random American timezone", "expectedOutput": "Timezone set to random American timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category europe", "description": "Set random European timezone", "expectedOutput": "Timezone set to random European timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category asia", "description": "Set random Asian timezone", "expectedOutput": "Timezone set to random Asian timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category africa", "description": "Set random African timezone", "expectedOutput": "Timezone set to random African timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category pacific --json", "description": "Set random Pacific timezone with JSON output", "expectedOutput": "JSON output of timezone change", "notes": "Requires sudo privileges" } ], "id": "5_timezone_management", "title": "Timezone Management" }, { "description": "Change and manage MAC addresses", "examples": [ { "command": "sudo health-control mac-change-all", "description": "Change MAC addresses for all interfaces", "expectedOutput": "All MAC addresses changed" }, { "command": "sudo health-control mac-force-change", "description": "Force change MAC addresses", "expectedOutput": "MAC addresses force-changed", "notes": "Use when regular change fails" }, { "command": "sudo health-control mac-change-specific --interface eth0", "description": "Change MAC for specific interface", "expectedOutput": "MAC address changed for eth0" }, { "command": "sudo health-control mac-show-interfaces", "description": "Show all network interfaces", "expectedOutput": "List of network interfaces" }, { "command": "sudo health-control mac-show-macs", "description": "Show current MAC addresses", "expectedOutput": "List of interfaces and MAC addresses" }, { "command": "sudo health-control mac-reset-all", "description": "Reset all MACs to original values", "expectedOutput": "MAC addresses reset to original" }, { "command": "sudo health-control mac-active-interface", "description": "Show active network interface", "expectedOutput": "Currently active network interface" } ], "id": "6_mac_address_management", "title": "MAC Address Management" }, { "description": "Get and set system hostname", "examples": [ { "command": "sudo health-control get-hostname", "description": "Get current system hostname", "expectedOutput": "Current hostname" }, { "command": "sudo health-control get-hostname --json", "description": "Get hostname in JSON format", "expectedOutput": "JSON formatted hostname" }, { "command": "health-control get-logged-user", "description": "Get the actual logged-in user (handles sudo correctly)", "expectedOutput": "Username of logged-in user", "notes": "Returns actual user even when run with sudo" }, { "command": "sudo health-control get-logged-user --json", "description": "Get logged user with additional info in JSON format", "expectedOutput": "JSON with username, home directory, and detection method" }, { "command": "sudo health-control set-default-hostname", "description": "Set default system hostname", "expectedOutput": "Default hostname set" }, { "command": "sudo health-control set-random-hostname", "description": "Set random hostname for privacy", "expectedOutput": "Random hostname set" }, { "command": "sudo health-control set-random-hostname --json", "description": "Set random hostname with JSON output", "expectedOutput": "JSON formatted hostname change result" }, { "command": "sudo health-control set-custom-hostname --name MyHost", "description": "Set custom hostname", "expectedOutput": "Hostname set to MyHost" }, { "command": "sudo health-control set-custom-hostname --name privacy-machine", "description": "Set descriptive custom hostname", "expectedOutput": "Hostname set to privacy-machine" }, { "command": "sudo health-control set-custom-hostname --name secure-workstation --json", "description": "Set custom hostname with JSON output", "expectedOutput": "JSON formatted hostname change result" }, { "command": "health-control list-hostnames", "description": "List all hostname categories", "expectedOutput": "List of available hostname categories with counts" }, { "command": "health-control list-hostnames --category all", "description": "List all available hostnames", "expectedOutput": "Complete list of all predefined hostnames" }, { "command": "health-control list-hostnames --category windows", "description": "List Windows hostnames", "expectedOutput": "List of Windows-style hostnames" }, { "command": "health-control list-hostnames --category linux", "description": "List Linux hostnames", "expectedOutput": "List of Linux distribution hostnames" }, { "command": "health-control list-hostnames --category apple", "description": "List Apple/Mac hostnames", "expectedOutput": "List of macOS and Apple device hostnames" }, { "command": "health-control list-hostnames --json", "description": "List hostname categories in JSON format", "expectedOutput": "JSON formatted category list with counts" }, { "command": "sudo health-control set-random-hostname-category", "description": "Set random hostname from all categories", "expectedOutput": "Random hostname selected and set" }, { "command": "sudo health-control set-random-hostname-category --category windows", "description": "Set random Windows hostname", "expectedOutput": "Random Windows-style hostname set" }, { "command": "sudo health-control set-random-hostname-category --category linux", "description": "Set random Linux hostname", "expectedOutput": "Random Linux distribution hostname set" }, { "command": "sudo health-control set-random-hostname-category --category fiction --json", "description": "Set random fictional hostname with JSON output", "expectedOutput": "Random fictional hostname set with JSON result" } ], "id": "7_hostname_management", "title": "Hostname Management" }, { "description": "Control and monitor IPv6 protocol settings", "examples": [ { "command": "sudo health-control ipv6-status", "description": "Check current IPv6 configuration status", "expectedOutput": "IPv6 Status: ENABLED/DISABLED with interface details", "notes": "Shows runtime status, boot config, and active interfaces" }, { "command": "sudo health-control ipv6-disable", "description": "Disable IPv6 system-wide (sysctl and GRUB)", "expectedOutput": "IPv6 disabled with details of changes applied", "notes": "Reboot recommended for full effect" }, { "command": "sudo health-control ipv6-enable", "description": "Enable IPv6 system-wide", "expectedOutput": "IPv6 enabled with details of changes applied", "notes": "Reboot recommended for full effect" }, { "command": "sudo health-control ipv6-status --json", "description": "Get detailed IPv6 status in JSON format", "expectedOutput": "Complete IPv6 configuration including runtime, boot config, and interfaces" } ], "id": "8_ipv6_management", "title": "IPv6 Management" }, { "description": "Apply and verify comprehensive security settings (7 modules: kernel, process, filesystem, network, memory, monitoring, sandboxing)", "examples": [ { "command": "sudo health-control security-harden", "description": "Apply standard security hardening (network-safe): kernel hardening, process isolation, filesystem security, memory protection, monitoring, sandboxing - PRESERVES internet connectivity", "expectedOutput": "Security hardening completed (network connectivity preserved)", "notes": "Standard profile maintains system usability and network connectivity" }, { "command": "sudo health-control security-harden --profile medium", "description": "Apply MEDIUM profile - Enhanced security with hidepid, hardened_malloc, file integrity monitoring. Browsers and internet still work", "expectedOutput": "Medium security hardening applied (browsers and internet preserved)", "notes": "Medium profile adds hidepid=2, hardened_malloc, dirty_ratio tuning, file integrity. May increase memory on LUKS systems" }, { "command": "sudo health-control security-harden --profile paranoid", "description": "Apply PARANOID profile - WARNING: WILL BREAK browsers and internet: disables user namespaces, IP forwarding, DNS firewall, MAC spoofing", "expectedOutput": "Paranoid security applied (network isolated)", "notes": "⚠️ BROWSERS AND INTERNET DISABLED - To recover: sudo health-control security-recover" }, { "command": "sudo health-control security-harden --break-monitoring", "description": "Apply paranoid profile plus break-monitoring mode: forces /sys/class/net to root-only and breaks non-root monitoring tools (btop/conky/dashboard)", "expectedOutput": "Paranoid hardening applied with monitoring intentionally restricted", "notes": "⚠️ ALSO BREAKS NON-ROOT MONITORING - Use only when this behavior is explicitly required" }, { "command": "sudo health-control security-verify", "description": "Check if all 7 security modules are enabled and properly configured", "expectedOutput": "Shows each module: ENABLED/DISABLED and configuration status", "notes": "Use after security-harden to verify settings are applied" }, { "command": "sudo health-control security-harden --modules kernel,network", "description": "Apply only specific modules (kernel sysctl and network firewall)", "expectedOutput": "Applied 2 modules: kernel and network hardening", "notes": "Modules: kernel, process, filesystem, network, memory, monitoring, sandboxing" }, { "command": "sudo health-control security-recover", "description": "Temporarily revert security hardening (keeps framework ready for quick re-hardening)", "expectedOutput": "Security recovery completed - modules show 'ENABLED (needs configuration)'", "notes": "Use for troubleshooting. Framework remains enabled for easy re-hardening with security-harden." }, { "command": "sudo health-control security-recover --modules network,kernel", "description": "Recover only specific security modules", "expectedOutput": "Selected modules recovered", "notes": "Available modules: kernel, filesystem, network, memory, monitoring, smt" }, { "command": "sudo health-control security-reset", "description": "Completely disable all security modules and framework (permanent removal)", "expectedOutput": "All modules show 'DISABLED' - framework completely removed", "notes": "WARNING: Unlike security-recover, this permanently disables the framework. Requires rebuilding to re-enable." }, { "command": "sudo health-control security-reset --force", "description": "Reset security framework without confirmation prompt", "expectedOutput": "Security framework completely disabled", "notes": "Use --force to skip the confirmation prompt in automation scripts" }, { "command": "sudo health-control monitoring-enable", "description": "Enable system security monitoring (auditd, LKRG, file integrity, auth events)", "expectedOutput": "Security monitoring enabled", "notes": "Enables auditd for system call auditing, LKRG for kernel integrity, file integrity monitoring (AIDE/Tripwire), and auth event logging" }, { "command": "sudo health-control monitoring-disable", "description": "Disable system security monitoring services", "expectedOutput": "Security monitoring disabled", "notes": "Stops all security monitoring services - reduces system overhead but decreases security visibility" }, { "command": "sudo health-control monitoring-status", "description": "Check current system security monitoring status", "expectedOutput": "Security monitoring status details", "notes": "Shows status of auditd, LKRG, AIDE, and auth logging - helps verify which monitoring services are active" }, { "command": "sudo health-control tirdad-enable", "description": "Enable Tirdad kernel module for TCP ISN randomization (prevents OS fingerprinting)", "expectedOutput": "Tirdad enabled successfully", "notes": "Randomizes TCP Initial Sequence Numbers to prevent remote OS fingerprinting attacks and TCP sequence prediction" }, { "command": "sudo health-control tirdad-disable", "description": "Disable Tirdad TCP ISN randomization module", "expectedOutput": "Tirdad disabled successfully", "notes": "Restores default TCP ISN generation - may make system identifiable via network fingerprinting" }, { "command": "sudo health-control tirdad-status", "description": "Check Tirdad TCP ISN randomization module status", "expectedOutput": "Tirdad status: ENABLED/DISABLED", "notes": "Shows if kernel module is loaded and TCP ISN randomization is active" }, { "command": "sudo health-control disk-encryption-status", "description": "Check disk encryption status", "expectedOutput": "Disk encryption configuration", "notes": "Displays LUKS encryption status for all disks, cipher algorithms, and key slot usage" }, { "command": "sudo health-control usb-list", "description": "List all USB devices", "expectedOutput": "Connected USB devices", "notes": "Shows all connected USB devices with vendor/product IDs for security auditing" }, { "command": "sudo health-control create-persistence", "description": "Create unencrypted live-boot persistence media", "expectedOutput": "Debian live-boot persistence media created successfully", "notes": "Creates a 4GB unencrypted ext4 persistence image named 'persistence' with a root persistence.conf of '/ union' so /opt, /etc, and other system paths survive reboots on Kodachi live USBs. Use --encrypted for LUKS encryption or --size to change size." }, { "command": "sudo health-control create-persistence --encrypted", "description": "Create encrypted persistence (interactive)", "expectedOutput": "Encrypted persistence media created", "notes": "Creates LUKS2-encrypted Debian live-boot persistence media named 'persistence' and writes '/ union' to persistence.conf. Secure method - password not visible in history." }, { "command": "sudo health-control create-persistence --encrypted --password 'pass123'", "description": "Create encrypted persistence (CLI password)", "expectedOutput": "Encrypted persistence media created", "notes": "⚠️ INSECURE: Password visible in shell history! Shows security warnings. Use interactive mode instead." }, { "command": "sudo health-control encryption-status", "description": "Show overall encryption status", "expectedOutput": "System encryption status report", "notes": "Comprehensive report of all encryption: disks, swap, home directories, and key management" } ], "id": "9_security_hardening", "title": "Security Hardening" }, { "description": "Monitor system health and run security audits", "examples": [ { "command": "sudo health-control system-audit", "description": "Perform comprehensive system security audit", "expectedOutput": "System audit status report" }, { "command": "sudo health-control rootkit-scan", "description": "Scan system for rootkits", "expectedOutput": "Rootkit scan results" }, { "command": "sudo health-control security-status --json", "description": "Check system security status", "expectedOutput": "JSON formatted security status info" }, { "command": "sudo health-control lynis-audit", "description": "Run comprehensive Lynis security audit", "expectedOutput": "Complete Lynis audit report", "notes": "Comprehensive security assessment" }, { "command": "sudo health-control lynis-status", "description": "Check Lynis installation and status", "expectedOutput": "Lynis service status" }, { "command": "sudo health-control aide-init", "description": "Initialize AIDE database", "expectedOutput": "AIDE database created successfully", "notes": "First time setup required" }, { "command": "sudo health-control aide-check", "description": "Check file integrity with AIDE", "expectedOutput": "File integrity check results" }, { "command": "sudo health-control kloak-status", "description": "Check kloak keystroke anonymization status", "expectedOutput": "Kloak service status and configuration" }, { "command": "sudo health-control kloak-enable", "description": "Enable kloak keystroke anonymization", "expectedOutput": "Kloak enabled successfully" }, { "command": "sudo health-control kloak-disable", "description": "Disable kloak keystroke anonymization", "expectedOutput": "Kloak disabled successfully" } ], "id": "10_system_health_security", "title": "System Health & Security Tools" }, { "description": "LUKS nuke passwords for emergency data destruction", "examples": [ { "command": "sudo health-control luks-nuke --action status", "description": "List all LUKS devices and nuke password status", "expectedOutput": "LUKS device status and configuration", "notes": "Shows which devices have nuke passwords configured" }, { "command": "sudo health-control luks-nuke --action status --device /dev/sda5", "description": "⚠️ STEP 1: Check current nuke status for target device", "expectedOutput": "Current LUKS nuke configuration status for /dev/sda5", "notes": "⚠️ ALWAYS backup header BEFORE configuring nuke password. This status check helps confirm current device state before changes." }, { "command": "sudo health-control luks-nuke --action configure --device /dev/sda5 --password 'StrongNukePassword123!'", "description": "⚠️ STEP 2: Configure nuke password (DATA DESTRUCTION FEATURE)", "expectedOutput": "Nuke password configured in keyslot 7", "notes": "⚠️ CRITICAL WARNING: This creates a password that will PERMANENTLY DESTROY all data on /dev/sda5 when entered! Use only if you understand the consequences. Requires header backup from STEP 1. Password must be strong (12+ chars, mixed case, numbers, symbols). Avoid obvious words like 'nuke', 'destroy', 'emergency'." }, { "command": "sudo health-control luks-nuke --action remove --device /dev/sda5", "description": "Remove nuke password from device", "expectedOutput": "Nuke password removed from keyslot 7", "notes": "Removes the data destruction feature from the device. You will be prompted to confirm which keyslot to remove (usually keyslot 7). Requires current LUKS password." }, { "command": "gpg -d ~/Desktop/header-backup-*.img.gpg | sudo cryptsetup luksHeaderRestore /dev/sda5", "description": "⚠️ EMERGENCY: Restore LUKS header after nuke password was used", "expectedOutput": "LUKS header restored from backup", "notes": "⚠️ USE ONLY IF nuke password was accidentally used! This restores the LUKS header from your encrypted backup. You MUST have created a header backup BEFORE the nuke password was triggered. After restoration, you can unlock the device with your original LUKS password. Without a backup, data is PERMANENTLY LOST." } ], "id": "11_luks_nuke_operations", "title": "LUKS Nuke & Data Destruction" }, { "description": "Full system data destruction for emergency situations. IRREVERSIBLE - use with extreme caution.", "examples": [ { "command": "health-control nuke-execute --dry-run", "description": "⚠️ TEST MODE: Preview what would be destroyed without actually wiping", "expectedOutput": "[DRY_RUN] messages showing all files/directories that would be wiped", "notes": "ALWAYS test with --dry-run first! Shows exactly what will be destroyed including: SSH keys, GPG keys, crypto wallets, browser data, messaging apps, email, documents, and system logs." }, { "command": "health-control nuke-execute --method fast --dry-run", "description": "Fast wipe mode (1-pass) - quickest destruction (~27 seconds)", "expectedOutput": "Fast wipe simulation with single-pass overwrite", "notes": "Best for SSDs where multi-pass is ineffective. Uses blkdiscard for SSDs, single shred pass for HDDs." }, { "command": "health-control nuke-execute --method secure --dry-run", "description": "Secure wipe mode (3-pass DoD) - balanced security (~45 seconds)", "expectedOutput": "Secure wipe simulation with 3-pass DoD standard", "notes": "DEFAULT mode. 3-pass overwrite following DoD 5220.22-M standard. Good balance of speed and security for HDDs." }, { "command": "health-control nuke-execute --method paranoid --dry-run", "description": "Paranoid wipe mode (7-pass) - maximum security (~60 seconds)", "expectedOutput": "Paranoid wipe simulation with 7-pass Gutmann-style", "notes": "Maximum security. 7-pass overwrite. Also wipes boot sector, GRUB, kernel, initrd, and MBR. System will be unbootable." }, { "command": "health-control nuke-execute --method fast --force", "description": "⚠️ DANGER: Execute REAL fast wipe - DESTROYS ALL DATA", "expectedOutput": "Data destruction in progress... System will reboot when complete.", "notes": "⚠️ IRREVERSIBLE! This PERMANENTLY DESTROYS: ~/.ssh, ~/.gnupg, crypto wallets (Bitcoin/Monero/Electrum), all browsers, Signal/Telegram/Discord, Thunderbird, Documents/Downloads/Desktop, AWS/Docker/Kube credentials, bash history, system logs. System forces reboot after completion." }, { "command": "health-control nuke-progress", "description": "Check current nuke operation progress", "expectedOutput": "Phase: 5 - browser_data, Complete: false, Active: true", "notes": "Monitor ongoing destruction progress. Shows current phase, completion status, and any errors." }, { "command": "health-control nuke-storage-detect --device /dev/sda", "description": "Detect storage type for optimal wipe method", "expectedOutput": "Device: /dev/sda, Storage Type: SSD", "notes": "Detects if device is SSD, HDD, or NVMe. SSDs use blkdiscard (instant secure erase), HDDs use shred (multi-pass overwrite), NVMe uses nvme format command." } ], "id": "11b_emergency_nuke_operations", "title": "Emergency Nuke Operations" }, { "description": "Complete USB security management - device listing, USBGuard policies, storage control, and monitoring", "examples": [ { "command": "", "description": "UNDERSTANDING USB SECURITY LAYERS", "expectedOutput": "", "notes": "USB security has TWO independent control systems:\n\n1. USBGuard (usb-guard-* commands):\n- Controls WHICH devices are allowed/blocked\n- Device authorization policy management\n- Works at the USBGuard daemon level\n\n2. USB Storage Modules (offline-usb-storage):\n- Controls IF USB storage drivers are loaded at all\n- Manages kernel modules (usb_storage, uas)\n- Manages device authorization at kernel level\n- Integrates with USBGuard automatically\n\n⚠️ CRITICAL: For USB drives to work, you need:\n- USB storage modules enabled (offline-usb-storage --action enable)\n- USBGuard allowing the device (or disabled)\n- Device authorized at kernel level (handled by offline-usb-storage)\n\n💡 TIP: Use 'offline-usb-storage --action enable' for complete USB storage access.\nIt handles all 4 layers automatically!" }, { "command": "sudo health-control usb-list", "description": "List all connected USB devices", "expectedOutput": "USB device list with security status" }, { "command": "sudo health-control offline-usb-storage --action check", "description": "Check USB storage module status (all 4 layers)", "expectedOutput": "Modules loaded: yes/no, Blacklist exists: yes/no, USBGuard active: yes/no, Authorized devices: N", "notes": "Shows complete status of all USB storage control layers" }, { "command": "sudo health-control offline-usb-storage --action enable", "description": "Enable USB storage completely (recommended)", "expectedOutput": "USB storage enabled successfully - All layers configured", "notes": "Handles ALL 4 layers: Removes blacklist, loads modules, authorizes devices, integrates with USBGuard.\nYour USB drives should appear immediately in 'lsblk' after this command." }, { "command": "sudo health-control offline-usb-storage --action enable --verbose", "description": "Enable USB storage with detailed layer-by-layer output", "expectedOutput": "Shows: modules loaded → devices authorized → USBGuard integration → udev triggered", "notes": "Use verbose mode to see exactly what happens at each layer" }, { "command": "sudo health-control offline-usb-storage --action disable", "description": "Disable USB storage completely (security lockdown)", "expectedOutput": "USB storage disabled successfully - All layers configured", "notes": "Blocks USB storage at all 4 layers: deauthorizes devices, blocks in USBGuard, unloads modules, creates blacklist" }, { "command": "sudo health-control usb-guard-enable", "description": "Enable USB Guard protection service", "expectedOutput": "USB Guard enabled successfully", "notes": "⚠️ This only enables USBGuard service - does NOT enable USB storage modules!\nIf USB storage modules are blocked, your drives won't appear even with USBGuard enabled.\nUse 'offline-usb-storage --action enable' for complete access." }, { "command": "sudo health-control usb-guard-disable", "description": "Disable USB Guard protection service", "expectedOutput": "USB Guard disabled successfully", "notes": "Disables USBGuard service but does NOT affect USB storage modules.\nStorage modules may still be blocked separately." }, { "command": "sudo health-control usb-policy --action add --device-id 1234:5678 --allow", "description": "Add USB device to USBGuard allow policy", "expectedOutput": "USB device policy added", "notes": "Use lsusb to find device IDs. This manages USBGuard policy only.\nDevice must also be authorized at kernel level (handled by offline-usb-storage)." }, { "command": "sudo health-control usb-policy --action list", "description": "List all USB policies in USBGuard", "expectedOutput": "Current USB device policies" }, { "command": "sudo health-control usb-policy --action status", "description": "Check USB security policies", "expectedOutput": "USB security policy assessment" }, { "command": "sudo health-control usb-monitor", "description": "Start USB device monitoring", "expectedOutput": "USB monitoring started" }, { "command": "sudo health-control usb-history --days 7", "description": "View USB device history for last 7 days", "expectedOutput": "USB device connection history" } ], "id": "12_usb_device_security", "title": "USB & Device Security" }, { "description": "Secure data wiping procedures", "examples": [ { "command": "sudo health-control wipe-file --file /path/to/file --passes 7", "description": "Securely wipe file with 7 passes", "expectedOutput": "File securely wiped and unrecoverable", "notes": "Multiple passes increase security" }, { "command": "sudo health-control wipe-directory --path /path/to/directory --passes 3", "description": "Securely wipe entire directory", "expectedOutput": "Directory and contents wiped securely", "notes": "All files in directory will be destroyed" }, { "command": "sudo health-control wipe-free-space --device /dev/sda1", "description": "Wipe free space on device", "expectedOutput": "Free space wiped securely", "notes": "Prevents recovery of deleted files" }, { "command": "sudo health-control wipe-logs", "description": "Wipe system and application logs", "expectedOutput": "Logs wiped successfully", "notes": "Removes log file traces" }, { "command": "sudo health-control wipe-browser-data", "description": "Wipe browser history and data", "expectedOutput": "Browser data wiped", "notes": "Removes browsing history and cache" }, { "command": "sudo health-control wipe-schedule temp --frequency daily", "description": "Schedule automatic temporary file wiping daily", "expectedOutput": "File wipe scheduled successfully", "notes": "Automatically wipes temp files based on frequency" }, { "command": "sudo health-control wipe-pattern \"*.tmp\"", "description": "Wipe all temporary files matching pattern", "expectedOutput": "Files matching pattern wiped", "notes": "Uses glob patterns to match files for wiping" }, { "command": "sudo health-control wipe-verify /path/to/file", "description": "Verify file has been securely wiped", "expectedOutput": "File wipe verification results" }, { "command": "sudo health-control wipe-batch /path1 /path2 /path3 --passes 7", "description": "Batch wipe multiple files with 7 passes", "expectedOutput": "Batch file wiping completed", "notes": "Space-separated file paths" } ], "id": "13_data_destruction", "title": "Data Destruction & Secure Wiping" }, { "description": "Automated updates, password policies, and system maintenance", "examples": [ { "command": "sudo health-control auto-updates-enable", "description": "Enable automatic security updates", "expectedOutput": "Automatic security updates enabled" }, { "command": "sudo health-control auto-updates-disable", "description": "Disable automatic updates", "expectedOutput": "Automatic updates disabled" }, { "command": "sudo health-control auto-updates-status", "description": "Check automatic updates status", "expectedOutput": "Auto-updates configuration status" }, { "command": "sudo health-control password-policy-enable", "description": "Enable strong password policy", "expectedOutput": "Strong password policy enforced" }, { "command": "sudo health-control password-policy-disable", "description": "Disable strong password policy", "expectedOutput": "Password policy disabled" }, { "command": "sudo health-control user-security-enable", "description": "Enable user security checks", "expectedOutput": "User security policies enabled" }, { "command": "sudo health-control 2fa-enable --value username", "description": "Enable 2FA for specific user", "expectedOutput": "Two-factor authentication enabled" }, { "command": "sudo health-control 2fa-disable --user username", "description": "Disable 2FA for user", "expectedOutput": "Two-factor authentication disabled" }, { "command": "sudo health-control system-maintenance-enable", "description": "Enable automatic system maintenance", "expectedOutput": "System maintenance automation enabled" }, { "command": "sudo health-control package-cleanup", "description": "Clean up unnecessary packages", "expectedOutput": "System packages cleaned and optimized" }, { "command": "sudo health-control password-policy-status", "description": "Check password policy status", "expectedOutput": "Current password policy configuration" }, { "command": "sudo health-control user-security-disable", "description": "Disable user security checks", "expectedOutput": "User security policies disabled" }, { "command": "sudo health-control user-security-status", "description": "Check user security status", "expectedOutput": "User security configuration status" }, { "command": "sudo health-control 2fa-status", "description": "Check 2FA status for users", "expectedOutput": "Two-factor authentication status" }, { "command": "sudo health-control system-maintenance-disable", "description": "Disable automatic system maintenance", "expectedOutput": "System maintenance automation disabled" }, { "command": "sudo health-control system-maintenance-status", "description": "Check system maintenance status", "expectedOutput": "System maintenance configuration status" } ], "id": "14_system_maintenance", "title": "System Maintenance & Updates" }, { "description": "System configuration and control operations", "examples": [ { "command": "sudo health-control play-sound --sound alert", "description": "Play system alert sound", "expectedOutput": "Sound played successfully" }, { "command": "sudo health-control play-sound success", "description": "Play success notification sound", "expectedOutput": "Success sound played" }, { "command": "sudo health-control play-sound warning -m mp3", "description": "Play warning sound in MP3 format", "expectedOutput": "Warning sound played in MP3" }, { "command": "sudo health-control play-sound alert --debug", "description": "Play alert sound with debug output", "expectedOutput": "Alert sound played with debug info" }, { "command": "health-control notify --message \"Security check complete\"", "description": "Send system notification", "expectedOutput": "Notification sent successfully" }, { "command": "health-control notify --message \"Hello from Kodachi\"", "description": "Send basic notification message", "expectedOutput": "Notification sent successfully" }, { "command": "health-control notify --message \"Alert\" --body \"VPN connected\"", "description": "Send notification with message body", "expectedOutput": "Detailed notification sent" }, { "command": "health-control notify --message \"Warning\" --urgency critical --duration 30", "description": "Send critical notification with 30 second duration", "expectedOutput": "Critical notification sent" }, { "command": "health-control notify --message \"Update\" --notify-icon \"/path/to/icon.png\"", "description": "Send notification with custom icon", "expectedOutput": "Notification with icon sent" } ], "id": "15_system_control", "title": "System Control & Notifications" }, { "description": "Emergency security measures with two modes: MONITORING (arm/disarm) prepares for threats, IMMEDIATE (panic/activate) executes emergency procedures", "examples": [ { "command": "sudo health-control kill-switch-arm", "description": "ARM kill switch monitoring (preparation mode)", "expectedOutput": "Kill switch ARMED - Monitoring mode active", "notes": "MONITORING MODE: Sets up automated threat detection using multiple monitoring methods:\n• NETWORK MONITORING: Uses netstat, ss, and iptables logs to detect unauthorized connections\n• FILE SYSTEM WATCHING: Monitors critical system files via inotify for unauthorized modifications\n• PROCESS MONITORING: Tracks running processes using ps/proc for suspicious behavior patterns\n• AUTH MONITORING: Watches /var/log/auth.log for failed login attempts (threshold: 5 failures)\n• SYSTEM INTEGRITY: Checks system file hashes and permissions for tampering\nDoes NOT take action until triggered - only prepares for rapid response. Auto-activates MEDIUM panic level when threats detected." }, { "command": "sudo health-control kill-switch-disarm", "description": "DISARM kill switch monitoring", "expectedOutput": "Kill switch DISARMED", "notes": "Stops monitoring mode. Use after threat has passed or false alarm." }, { "command": "sudo health-control kill-switch-status", "description": "Check if monitoring is armed/disarmed", "expectedOutput": "Shows armed status, trigger count, armed time", "notes": "READ-ONLY: Just displays current state, takes no action" }, { "command": "sudo health-control kill-switch-activate", "description": "IMMEDIATELY activate kill switch (default: medium panic)", "expectedOutput": "KILL SWITCH ACTIVATED - emergency procedures executed", "notes": "IMMEDIATE ACTION: Unlike 'arm', this executes panic NOW. Prompts for confirmation. Use --level soft/medium/hard" }, { "command": "sudo health-control panic-soft", "description": "IMMEDIATE soft panic (NO confirmation)", "expectedOutput": "Network killed, clipboard cleared (adaptive: Wayland/X11), screen locked", "notes": "INSTANT: Kill network + clear clipboard (wl-copy/xclip/xsel) + lock screen. Reversible. Good for quick privacy." }, { "command": "sudo health-control panic-medium", "description": "IMMEDIATE medium panic (requires confirmation)", "expectedOutput": "Panic mode activated after confirmation", "notes": "WITH CONFIRMATION: Kill network + clear clipboard (adaptive: wl-copy/xclip/xsel) + terminate processes + clear memory + unmount devices + lock screen (6 actions). Requires manual restart to restore." }, { "command": "sudo health-control panic-hard", "description": "IMMEDIATE hard panic (double confirmation)", "expectedOutput": "System shutdown initiated", "notes": "CRITICAL - DOUBLE CONFIRM: All medium actions + RAM wipe + IMMEDIATE shutdown (7 actions total). IRREVERSIBLE! System shuts down NOW!" }, { "command": "sudo health-control create-recovery-point", "description": "Create recovery checkpoint BEFORE panic", "expectedOutput": "Recovery point created", "notes": "Create BEFORE activating panic modes. Allows restoration of configs after emergency." }, { "command": "sudo health-control panic-recover", "description": "Restore system after panic activation", "expectedOutput": "System recovered from panic mode", "notes": "Use AFTER panic to restore normal operation. Restarts services, fixes permissions." }, { "command": "sudo health-control panic-profile --profile paranoid", "description": "Configure panic response to paranoid security level", "expectedOutput": "Panic profile set: paranoid\nActions configured: 12", "notes": "PROFILE MODES:\n• STEALTH: Light response (network blocking only, preserve user data)\n• PARANOID: Maximum security (network kill, data wipe, process termination, interface shutdown)\n• RECOVERY: System restoration (restart services, fix permissions, restore connectivity)\n\nProfile determines automatic actions when panic mode triggers. Use 'kill-switch-activate' to manually trigger the configured profile." }, { "command": "sudo health-control kill-network-interface --interface eth0", "description": "Kill specific network interface", "expectedOutput": "Network interface eth0 terminated", "notes": "Selective network isolation" }, { "command": "sudo health-control kill-process --process firefox", "description": "Terminate specific process immediately", "expectedOutput": "Process firefox terminated", "notes": "Emergency process termination" } ], "id": "16_emergency_operations", "title": "Emergency Operations - Kill Switch & Panic Modes" }, { "description": "Storage device encryption, secure wiping, LUKS encrypted containers, and volume management", "examples": [ { "command": "sudo health-control list-storage-devices", "description": "List all storage devices with safety indicators (SAFE/CAUTION/DANGER)", "expectedOutput": "Shows devices categorized by safety level for persistence operations", "notes": "Use BEFORE creating persistence to identify safe devices. Protects against accidental system drive formatting." }, { "command": "sudo health-control list-storage-devices --all", "description": "List all storage devices including loop and ram devices", "expectedOutput": "Complete device inventory with safety categorization including virtual devices" }, { "command": "sudo health-control usb-safety-check --device /dev/sdc2", "description": "Check if specific device is safe for persistence operations", "expectedOutput": "Returns safety level: SAFE, CAUTION, or DANGER with detailed warnings", "notes": "Validates device before destructive operations. Prevents accidental system drive formatting." }, { "command": "sudo health-control storage-encrypt --device /dev/sdb1", "description": "Encrypt storage device", "expectedOutput": "Storage device encrypted successfully", "notes": "Backup data before encryption" }, { "command": "sudo health-control storage-wipe --device /dev/sdb1 --passes 3", "description": "Securely wipe storage device", "expectedOutput": "Storage device wiped securely", "notes": "Data will be permanently destroyed" }, { "command": "sudo health-control container-create /secure/data.img --size 500", "description": "Create encrypted container (500MB)", "expectedOutput": "Encrypted container created successfully", "notes": "Creates LUKS2-encrypted container file. You'll be prompted for password interactively.\nContainer file path is positional argument (not --output)." }, { "command": "sudo health-control container-create /tmp/secure.img --size 100", "description": "Create small encrypted container (100MB)", "expectedOutput": "Container created: /tmp/secure.img, Size: 100 MB", "notes": "Smaller size for testing. Password will be prompted." }, { "command": "sudo health-control container-mount /secure/data.img --mount-point /mnt/secure", "description": "Mount encrypted container", "expectedOutput": "Container mounted successfully", "notes": "You'll be prompted for the container password.\nMount point will be created automatically if it doesn't exist." }, { "command": "sudo health-control container-unmount /mnt/secure", "description": "Unmount encrypted container", "expectedOutput": "Container unmounted: /mnt/secure", "notes": "Automatically closes the LUKS mapper device." } ], "id": "17_storage_encryption", "title": "Storage Encryption & Secure Containers" }, { "description": "Security scoring and reporting", "examples": [ { "command": "sudo health-control security-score", "description": "Calculate overall security score", "expectedOutput": "Shows score (0-100), security level (Critical/Poor/Fair/Good/Excellent), and actionable fixes" }, { "command": "sudo health-control security-score --json", "description": "Get security score in JSON format", "expectedOutput": "Full JSON with category breakdowns (Core/Network/Hardening/Device/Advanced), individual check scores, and specific remediation commands" }, { "command": "sudo health-control security-report", "description": "Generate comprehensive security report", "expectedOutput": "Detailed security assessment report" }, { "command": "sudo health-control security-report --json", "description": "Generate security report in JSON format", "expectedOutput": "JSON formatted security report" }, { "command": "sudo health-control security-history --days 30", "description": "View security score history for last 30 days", "expectedOutput": "Security score trends and historical data", "notes": "Shows security improvements over time" }, { "command": "sudo health-control security-history --days 7 --json", "description": "View last 7 days security history in JSON", "expectedOutput": "JSON formatted security history" }, { "command": "sudo health-control security-remediate", "description": "Review security fixes before applying", "expectedOutput": "Security fix recommendations displayed", "notes": "Manual review mode for security fixes" } ], "id": "18_security_assessment", "title": "Security Assessment & Scoring" }, { "description": "Hardware-level security features", "examples": [ { "command": "sudo health-control hardware-rng-verify", "description": "Verify hardware random number generator", "expectedOutput": "Hardware RNG status and quality", "notes": "Checks if hardware RNG is available and functioning properly for cryptographic operations" }, { "command": "sudo health-control entropy-status", "description": "Check system entropy status", "expectedOutput": "Entropy pool status and quality", "notes": "Monitors available entropy for secure random number generation, critical for encryption" }, { "command": "sudo health-control boot-integrity-check", "description": "Check boot integrity", "expectedOutput": "Boot integrity verification results", "notes": "Verifies boot process integrity to detect tampering or unauthorized modifications to bootloader/kernel" } ], "id": "19_hardware_security", "title": "Hardware Security" }, { "description": "System information, diagnostics, and hardware/service management", "examples": [ { "command": "sudo health-control offline-info-system", "description": "Display comprehensive system information", "expectedOutput": "Complete system details and configuration" }, { "command": "sudo health-control offline-info-hardware", "description": "Display hardware information", "expectedOutput": "Hardware components and specifications" }, { "command": "sudo health-control offline-info-hardware --json", "description": "Display hardware information in JSON", "expectedOutput": "JSON formatted hardware details" }, { "command": "sudo health-control offline-info-process", "description": "Display process information", "expectedOutput": "Running processes and resource usage" }, { "command": "sudo health-control offline-info-security", "description": "Display security configuration", "expectedOutput": "Security settings and status" }, { "command": "sudo health-control offline-info-network", "description": "Display network configuration", "expectedOutput": "Network interfaces and settings" }, { "command": "sudo health-control offline-info-user", "description": "Display user information", "expectedOutput": "User accounts and permissions" }, { "command": "sudo health-control offline-info-storage", "description": "Display storage information", "expectedOutput": "Disk usage and filesystem details" }, { "command": "sudo health-control offline-info-services", "description": "Display services information", "expectedOutput": "System services status" }, { "command": "sudo health-control offline-info-all", "description": "Display all system information", "expectedOutput": "Complete system information report" }, { "command": "sudo health-control offline-bluetooth --action check", "description": "Check Bluetooth status", "expectedOutput": "Bluetooth status: enabled/disabled" }, { "command": "sudo health-control offline-bluetooth --action enable", "description": "Enable Bluetooth service", "expectedOutput": "Bluetooth enabled successfully" }, { "command": "sudo health-control offline-bluetooth --action disable", "description": "Disable Bluetooth service", "expectedOutput": "Bluetooth disabled successfully" }, { "command": "sudo health-control offline-wifi --action check", "description": "Check WiFi status", "expectedOutput": "WiFi status: enabled/disabled" }, { "command": "sudo health-control offline-wifi --action enable", "description": "Enable WiFi service", "expectedOutput": "WiFi enabled successfully" }, { "command": "sudo health-control offline-wifi --action disable", "description": "Disable WiFi with persistent blacklisting", "expectedOutput": "WiFi disabled and blacklisted" }, { "command": "sudo health-control offline-webcam --action check", "description": "Check webcam status", "expectedOutput": "Webcam status: enabled/disabled" }, { "command": "sudo health-control offline-webcam --action enable", "description": "Enable webcam devices", "expectedOutput": "Webcam access enabled" }, { "command": "sudo health-control offline-webcam --action disable", "description": "Disable webcam devices", "expectedOutput": "Webcam access disabled" }, { "command": "sudo health-control offline-microphone --action check", "description": "Check microphone status", "expectedOutput": "Microphone status: enabled/disabled" }, { "command": "sudo health-control offline-microphone --action enable", "description": "Enable microphone devices", "expectedOutput": "Microphone access enabled" }, { "command": "sudo health-control offline-microphone --action disable", "description": "Disable microphone devices", "expectedOutput": "Microphone access disabled" }, { "command": "sudo health-control offline-screen-lock --action enable", "description": "Enable automatic screen lock", "expectedOutput": "Screen lock enabled" }, { "command": "sudo health-control offline-systemlogs --action disable", "description": "Disable system logging", "expectedOutput": "System logging disabled" }, { "command": "sudo health-control offline-cups --action disable", "description": "Disable CUPS printing service", "expectedOutput": "CUPS printing disabled" }, { "command": "sudo health-control offline-networkmanager --action disable", "description": "Disable NetworkManager", "expectedOutput": "NetworkManager disabled" }, { "command": "sudo health-control offline-numlock --action enable", "description": "Enable NumLock on boot", "expectedOutput": "NumLock enabled on boot" }, { "command": "sudo health-control offline-cmdhistory --action disable", "description": "Disable command history logging", "expectedOutput": "Command history disabled" }, { "command": "sudo health-control offline-autologin --action disable", "description": "Disable automatic login", "expectedOutput": "Automatic login disabled" }, { "command": "sudo health-control offline-fdlimit --action enable --soft-limit 1024 --hard-limit 4096", "description": "Set file descriptor limits", "expectedOutput": "File descriptor limit set" }, { "command": "sudo health-control offline-netoptimize --action enable", "description": "Enable network optimizations", "expectedOutput": "Network optimizations enabled" }, { "command": "sudo health-control offline-bbr --action enable", "description": "Enable BBR congestion control", "expectedOutput": "BBR congestion control enabled" }, { "command": "sudo health-control offline-ifspeed --action enable --interface eth0 --speed 1000", "description": "Configure interface speed", "expectedOutput": "Interface speed configured" }, { "command": "sudo health-control offline-avahi --action disable", "description": "Disable Avahi service discovery", "expectedOutput": "Avahi service disabled", "notes": "Supported services: avahi, modem-manager, ssh, apache, nginx, docker, mysql, postgresql" }, { "command": "sudo health-control offline-modem-manager --action disable", "description": "Disable ModemManager service", "expectedOutput": "ModemManager disabled" }, { "command": "sudo health-control offline-ssh --action enable", "description": "Enable SSH service", "expectedOutput": "SSH service enabled" }, { "command": "sudo health-control offline-apache --action disable", "description": "Disable Apache web server", "expectedOutput": "Apache web server disabled" }, { "command": "sudo health-control offline-nginx --action disable", "description": "Disable Nginx web server", "expectedOutput": "Nginx web server disabled" }, { "command": "sudo health-control offline-docker --action disable", "description": "Disable Docker service", "expectedOutput": "Docker service disabled" }, { "command": "sudo health-control offline-mysql --action disable", "description": "Disable MySQL database service", "expectedOutput": "MySQL service disabled" }, { "command": "sudo health-control offline-postgresql --action disable", "description": "Disable PostgreSQL database service", "expectedOutput": "PostgreSQL service disabled" }, { "command": "sudo health-control offline-usb-storage --action enable", "description": "Enable USB storage devices", "expectedOutput": "USB storage access enabled" }, { "command": "sudo health-control offline-usb-storage --action disable", "description": "Disable USB storage devices", "expectedOutput": "USB storage access blocked" } ], "id": "20_system_info_offline", "title": "System Information & Offline Actions" }, { "description": "Generate secure passwords using multiple methods with batch support (auto-detects installed packages)", "examples": [ { "command": "sudo health-control genpass", "description": "Generate one password using all three methods", "expectedOutput": "Three passwords (pass, pwgen, xkcdpass)", "notes": "Automatically uses system packages if available, falls back to native implementations" }, { "command": "sudo health-control genpass --method pwgen --count 10", "description": "Generate 10 random passwords using pwgen method", "expectedOutput": "10 random passwords", "notes": "Use --count for batch generation; max 1000 per method" }, { "command": "sudo health-control genpass --method xkcdpass --count 50", "description": "Generate 50 memorable XKCD-style passphrases", "expectedOutput": "50 word-based passphrases", "notes": "XKCD method creates memorable multi-word passwords" }, { "command": "sudo health-control genpass --count 90", "description": "Generate 90 passwords from each method (270 total)", "expectedOutput": "270 passwords (90 from each of the 3 methods)", "notes": "When using --count without --method, generates specified count from ALL methods" }, { "command": "sudo health-control genpass --method pwgen --count 20 --length 32 --symbols \"@-_!#$\"", "description": "Generate 20 custom passwords with specific length and symbols", "expectedOutput": "20 passwords with 32 characters including specified symbols", "notes": "Customize password generation with --length and --symbols options" }, { "command": "sudo health-control genpass --uppercase --digits --count 15", "description": "Generate 15 passwords with only uppercase letters and digits", "expectedOutput": "15 alphanumeric passwords (uppercase + digits only)" }, { "command": "sudo health-control genpass --count 100 --json", "description": "Generate 100 passwords from each method in JSON format", "expectedOutput": "JSON array with 300 passwords", "notes": "JSON output ideal for scripting and automation" }, { "command": "sudo health-control genpass --force-native --count 25", "description": "Force use of native Rust implementations (skip package detection)", "expectedOutput": "25 passwords from each method using native fallbacks", "notes": "Useful for testing or when system packages are unreliable" } ], "id": "21_password_generation", "title": "Password Generation" }, { "description": "Automatic RAM wiping on shutdown with multiple policies (custom, sdmem, both, auto), installation, configuration, testing, and cold boot attack defenses", "examples": [ { "command": "# WORKFLOW: Setting up RAM wipe on shutdown", "description": "Complete workflow for first-time RAM wipe setup", "expectedOutput": "Step-by-step guide", "notes": "STEP 1: Install hooks (REQUIRED FIRST): sudo health-control wipe-ram-install\nSTEP 2: Configure policy (OPTIONAL): sudo health-control wipe-ram-config --policy sdmem\nSTEP 3: Enable if disabled: sudo health-control ram-wipe-enable\nSTEP 4: Verify status: sudo health-control ram-wipe-status\n\nKEY DIFFERENCES:\n• wipe-ram-install = FIRST-TIME SETUP (installs systemd shutdown hooks)\n• ram-wipe-enable = ENABLE/DISABLE (turns functionality on/off, hooks must exist)\n• wipe-ram-config = UPDATE SETTINGS (change policy, passes, time budget)\n• wipe-ram = MANUAL EXECUTION (test or emergency wipe NOW, not on shutdown)" }, { "command": "sudo health-control wipe-ram-install", "description": "Install RAM wipe system with default settings (kodachi-wiper policy, 60s timeout)", "expectedOutput": "RAM wipe system installed successfully", "notes": "FIRST-TIME SETUP - Installs systemd hooks, configures policies, detects Kicksecure compatibility. Creates /etc/kodachi-ram-wipe.conf with defaults" }, { "command": "sudo health-control wipe-ram-install --policy kodachi-wiper --time 60", "description": "Install RAM wipe with kodachi-wiper policy and 60 second time budget", "expectedOutput": "Installed with kodachi-wiper policy", "notes": "Fastest installation - Single-pass wipe, suitable for systems with <8GB RAM or frequent reboots" }, { "command": "sudo health-control wipe-ram-install --policy sdmem --passes 3", "description": "Install RAM wipe with sdmem policy using 3 overwrite passes", "expectedOutput": "Installed with sdmem 3-pass policy", "notes": "SECURE INSTALLATION - 3 passes (random, zeros, random). Good balance of security and speed. Recommended for 8-16GB RAM systems" }, { "command": "sudo health-control wipe-ram-install --policy both --split 60", "description": "Install with both policies: 60% time for kodachi-wiper, 40% for sdmem", "expectedOutput": "Installed with dual-policy split", "notes": "HYBRID APPROACH - Time-split between kodachi-wiper (fast) and sdmem (thorough). Example: 120s budget = 72s kodachi-wiper + 48s sdmem. Maximum security coverage" }, { "command": "sudo health-control wipe-ram-install --force", "description": "Force installation even if Kicksecure/Whonix RAM wipe detected", "expectedOutput": "Force installed, Kicksecure overridden", "notes": "OVERRIDE MODE - Bypasses Kicksecure detection. Use when you want Kodachi's RAM wipe instead of Kicksecure's built-in wipe. May cause conflicts" }, { "command": "sudo health-control ram-wipe-status", "description": "Check RAM wipe configuration and current status", "expectedOutput": "RAM wipe status with memory info and auto-wipe settings", "notes": "Shows: enabled/disabled state, current policy (kodachi-wiper/sdmem/both/auto), time budget, sdmem passes, total RAM size, Kicksecure detection" }, { "command": "sudo health-control ram-wipe-status --json", "description": "RAM wipe status in JSON format for automation", "expectedOutput": "JSON formatted status with all configuration details", "notes": "JSON OUTPUT DEMO - Shows all config fields in machine-readable format for scripts and monitoring systems" }, { "command": "sudo health-control wipe-ram-config --policy auto", "description": "Update existing RAM wipe policy to auto-detection", "expectedOutput": "Policy updated to auto" }, { "command": "sudo health-control wipe-ram-config --passes 5 --split 70", "description": "Update sdmem passes to 5 and time split to 70/30", "expectedOutput": "Multiple parameters updated", "notes": "PASS COUNT - More passes = more thorough but slower. 1-3=fast, 4-6=balanced, 7-9=maximum. SPLIT - Higher kodachi-wiper%=speed, higher sdmem%=security" }, { "command": "sudo health-control ram-wipe-enable", "description": "Enable RAM wipe configuration (hooks must be installed first)", "expectedOutput": "RAM wipe configuration enabled + WARNING if hooks not installed", "notes": "IMPORTANT: This only enables the CONFIG. You must run 'wipe-ram-install' FIRST to install systemd hooks. Will show clear warning if hooks are missing." }, { "command": "sudo health-control ram-wipe-disable", "description": "Disable automatic RAM wiping", "expectedOutput": "RAM wipe disabled successfully", "notes": "WARNING - Disabling RAM wipe leaves sensitive data in RAM accessible to physical attacks" }, { "command": "sudo health-control wipe-ram-test", "description": "Test RAM wipe system with dry-run (no actual wiping)", "expectedOutput": "RAM wipe test completed successfully", "notes": "SAFE TESTING - Simulates wipe operation without actually overwriting memory. Tests configuration, timing, and policy execution. Use before first real wipe" }, { "command": "sudo health-control wipe-ram-test --policy kodachi-wiper --time 10", "description": "Test kodachi-wiper policy with 10 second time budget", "expectedOutput": "Kodachi-wiper policy test completed in 10s", "notes": "Quick test - Validates kodachi-wiper policy works correctly. 10s budget ensures fast test completion" }, { "command": "sudo health-control wipe-ram-test --json", "description": "Test RAM wipe with detailed JSON diagnostic metrics", "expectedOutput": "JSON test results with performance data", "notes": "DIAGNOSTIC OUTPUT - Returns timing, memory stats, policy execution details, and potential issues. Essential for troubleshooting" }, { "command": "sudo health-control wipe-ram", "description": "Execute RAM wipe operation manually with configured policy", "expectedOutput": "RAM wiped successfully", "notes": "ADVANCED - Manually trigger RAM wipe using system configuration. Automatically called by shutdown hooks. Use for testing or emergency wipe" }, { "command": "sudo health-control wipe-ram --shutdown-mode", "description": "Execute RAM wipe optimized for shutdown context", "expectedOutput": "RAM wiped in shutdown mode", "notes": "INTERNAL USE - Shutdown-optimized mode disables unnecessary checks and output. Used by systemd shutdown hooks" }, { "command": "sudo health-control wipe-ram --policy kodachi-wiper", "description": "Execute RAM wipe using kodachi-wiper overwrite policy", "expectedOutput": "RAM wiped with kodachi-wiper policy", "notes": "POLICY: Kodachi-wiper fast overwrite algorithm - Single pass with random data. Fastest but least thorough (60-120 seconds for 8GB)" }, { "command": "sudo health-control wipe-ram --policy sdmem", "description": "Execute RAM wipe using sdmem utility (multiple passes)", "expectedOutput": "RAM wiped with sdmem", "notes": "POLICY: sdmem (secure-delete memory) - Multiple passes with patterns. Slower but more thorough (3-7 passes configurable). Government-grade erasure" }, { "command": "sudo health-control wipe-ram --policy both", "description": "Execute RAM wipe using both kodachi-wiper AND sdmem sequentially", "expectedOutput": "RAM wiped with combined policy", "notes": "POLICY: Maximum security - Kodachi-wiper FIRST (fast pass), then sdmem (thorough passes). Best security but longest time. Recommended for high-security environments" }, { "command": "sudo health-control wipe-ram --policy auto", "description": "Execute RAM wipe with automatic policy selection based on available RAM", "expectedOutput": "RAM wiped with auto-detected policy", "notes": "POLICY: Auto-detection - Chooses policy based on RAM size and available time: <4GB=kodachi-wiper, 4-16GB=both, >16GB=sdmem. Balances speed and security" }, { "command": "sudo health-control wipe-ram --time 120", "description": "Execute RAM wipe with 120 second time budget", "expectedOutput": "RAM wiped within time limit", "notes": "TIME BUDGET - Maximum seconds allowed for wipe operation. System will shutdown/reboot when time expires even if wipe incomplete. Critical for automated shutdowns" }, { "command": "sudo health-control ram-wipe-detect-kicksecure", "description": "Detect if Kicksecure/Whonix RAM wipe is installed", "expectedOutput": "Kicksecure detection results", "notes": "COMPATIBILITY CHECK - Detects Kicksecure's ram-wipe-on-boot package. Prevents conflicts between Kodachi and Kicksecure RAM wipe systems" }, { "command": "sudo health-control ram-wipe-update --policy auto --time 150", "description": "Update RAM wipe policy to auto with 150 second time budget", "expectedOutput": "Policy and time budget updated", "notes": "SMART MODE - System automatically selects best policy based on: RAM size, shutdown urgency, battery status (laptops). Recommended for most users" }, { "command": "sudo health-control coldboot-defense-enable", "description": "Enable cold boot attack defense mechanisms", "expectedOutput": "Cold boot defense enabled", "notes": "PHYSICAL SECURITY - Protects against cold boot attacks that recover encryption keys from RAM after power loss. Enables: RAM overwriting on shutdown, memory scrambling, DMA protection" }, { "command": "sudo health-control coldboot-defense-disable", "description": "Disable cold boot attack defense", "expectedOutput": "Cold boot defense disabled", "notes": "WARNING - Disabling leaves encryption keys vulnerable to physical RAM extraction attacks. Only disable if you have alternative physical security" } ], "id": "22_ram_wipe_cold_boot", "title": "RAM Wipe & Cold Boot Protection" }, { "description": "Swap space enable/disable, configuration, encryption with dm-crypt, and performance tuning with swappiness and cache pressure settings", "examples": [ { "command": "sudo health-control swap-enable", "description": "Enable and activate swap space for memory overflow", "expectedOutput": "Swap enabled successfully", "notes": "STABILITY FEATURE - Activates swap partitions/files for memory overflow. Improves system stability under memory pressure but may leak sensitive data to disk" }, { "command": "sudo health-control swap-disable", "description": "Disable and deactivate all swap space", "expectedOutput": "Swap disabled successfully", "notes": "SECURITY FEATURE - Deactivates all swap to prevent disk leakage of sensitive data. May cause out-of-memory errors if RAM insufficient" }, { "command": "sudo health-control swap-status", "description": "Check swap status, devices, size, and usage", "expectedOutput": "Swap devices list with usage statistics", "notes": "Shows: active swap devices, total/used/available size, swap usage percentage, encryption status, swappiness value" }, { "command": "sudo health-control swap-configure --swappiness 10 --cache-pressure 100", "description": "Configure swap parameters for optimal performance", "expectedOutput": "Swap parameters configured", "notes": "PERFORMANCE TUNING - Swappiness (0-100): 0=never swap, 10=minimal, 60=default, 100=aggressive. Cache pressure controls VFS cache retention (default 100)" }, { "command": "sudo health-control swap-encrypt", "description": "Encrypt swap with random key generated on each boot", "expectedOutput": "Swap space encrypted", "notes": "ENCRYPTION SECURITY - Uses dm-crypt with random key per boot. Protects swapped memory from offline disk forensics. Slight performance impact (~5-10%)" }, { "command": "sudo health-control swap-decrypt", "description": "Remove swap encryption and revert to plain swap", "expectedOutput": "Swap decrypted", "notes": "WARNING - Removes encryption protection. Swapped data will be readable from disk in clear text. Only use if encryption causes performance issues" }, { "command": "sudo health-control swap-encrypt-status", "description": "Check swap encryption status and configuration", "expectedOutput": "Encryption status with cipher details", "notes": "Shows: encryption enabled/disabled, cipher type (aes-xts-plain64), key size, whether using random keys, encrypted device mapper name" }, { "command": "sudo health-control enable-swap", "description": "Enable swap (alternative command alias)", "expectedOutput": "Swap enabled" }, { "command": "sudo health-control disable-swap", "description": "Disable swap (alternative command alias)", "expectedOutput": "Swap disabled" } ], "id": "23_swap_management", "title": "Swap Management & Encryption" }, { "description": "Memory usage statistics, cache cleaning, and memory optimization without data loss", "examples": [ { "command": "sudo health-control memory-stats", "description": "Show current memory usage statistics (total, available, used, cached)", "expectedOutput": "Memory usage breakdown with utilization percentages" }, { "command": "sudo health-control memory-stats --json-human", "description": "Memory statistics in human-readable JSON format", "expectedOutput": "Pretty-printed JSON with human-readable sizes (MB/GB)", "notes": "JSON OUTPUT DEMO - Use --json for compact machine-readable format, --json-human for readable format with color and formatting" }, { "command": "sudo health-control memory-clean", "description": "Clean memory caches and buffers (pagecache, dentries, inodes)", "expectedOutput": "Memory cleaned successfully", "notes": "Safe operation - drops caches but does NOT kill processes. Improves available memory without data loss" }, { "command": "sudo health-control memory-force-clean", "description": "Force aggressive memory cleanup (sync + drop_caches=3)", "expectedOutput": "Memory force cleaned", "notes": "ADVANCED - Kills top memory-consuming process + aggressive cache drop. Use with caution in production" } ], "id": "24_memory_stats_cleanup", "title": "Memory Statistics & Cleanup" }, { "description": "Secure process memory wiping before termination and per-process memory limits using cgroups for browsers and applications", "examples": [ { "command": "sudo health-control memory-wipe", "description": "Securely wipe memory contents (anti-forensics)", "expectedOutput": "Memory wiped securely", "notes": "SECURITY FEATURE - Overwrites memory with random data to prevent forensic recovery. Used for sensitive operations" }, { "command": "sudo health-control memory-wipe-process --value firefox", "description": "Securely wipe Firefox process memory before termination", "expectedOutput": "Firefox process memory wiped successfully", "notes": "PRIVACY PROTECTION - Clears sensitive data (passwords, session keys, browsing history) from process memory before kill" }, { "command": "sudo health-control memory-wipe-process --value chrome", "description": "Securely wipe Chrome browser memory", "expectedOutput": "Chrome process memory wiped successfully", "notes": "Clears authentication tokens, cached passwords, and browsing data from Chrome's memory space" }, { "command": "sudo health-control memory-wipe-process --value thunderbird", "description": "Securely wipe Thunderbird email client memory", "expectedOutput": "Thunderbird process memory wiped successfully", "notes": "Erases email content, credentials, and encryption keys from email client memory" }, { "command": "sudo health-control memory-wipe-process --value tor-browser", "description": "Securely wipe Tor Browser memory", "expectedOutput": "Tor Browser process memory wiped successfully", "notes": "Clears Tor circuit keys, browsing session data, and cached .onion addresses from memory" }, { "command": "sudo health-control memory-limits --value firefox --limit 2048", "description": "Set Firefox memory limit to 2048 MB using cgroups", "expectedOutput": "Firefox memory limit set to 2048 MB", "notes": "RESOURCE CONTROL - Uses Linux cgroups to enforce hard memory limits per process. Prevents single process from consuming excessive memory. Process killed if limit exceeded" }, { "command": "sudo health-control memory-limits --value chrome --limit 1024", "description": "Set Chrome memory limit to 1024 MB", "expectedOutput": "Chrome memory limit set to 1024 MB", "notes": "Chrome often consumes excessive memory. Limiting prevents system slowdown. Note: Limit applies to total browser memory across all processes" }, { "command": "sudo health-control memory-limits --value tor-browser --limit 1536", "description": "Set Tor Browser memory limit to 1536 MB", "expectedOutput": "Tor Browser memory limit set to 1536 MB", "notes": "Tor Browser requires more memory than standard browsers due to Tor circuit management and enhanced security features. 1536MB recommended minimum" }, { "command": "sudo health-control memory-limits --list", "description": "List all configured memory limits and their current usage", "expectedOutput": "Table of processes with memory limits and usage", "notes": "Shows: process name, configured limit, current memory usage, limit utilization percentage, cgroup path, status (active/inactive)" } ], "id": "25_process_memory_security", "title": "Process Memory Security" }, { "description": "Hardware keyboard shortcuts for emergency operations via kodachi-session-helper daemon. All commands use LOCAL session tokens (no online auth required). Works fully offline. Session token is read automatically from $XDG_RUNTIME_DIR/kodachi-session-helper/session.token", "examples": [ { "command": "sudo health-control emergency-trigger --plan dashboard --dry-run", "description": "Dry-run dashboard nuke to test without executing destructive actions", "expectedOutput": "DRY RUN: Would execute plan 'dashboard' - no changes made", "notes": "SAFE TESTING - Validates session token and plan without executing. Use for testing shortcut configuration and daemon integration. Session token read from $XDG_RUNTIME_DIR/kodachi-session-helper/session.token" }, { "command": "sudo health-control emergency-trigger --plan dashboard", "description": "Trigger dashboard nuke via emergency shortcut (wipe dashboard data, logs, configs)", "expectedOutput": "Emergency plan 'dashboard' executed successfully", "notes": "KEYBOARD: The session helper uses the shortcut currently configured in the dashboard. Hold the approved combo for roughly 2-3 seconds. The global trigger is silent and does not reopen the dashboard UI." }, { "command": "sudo health-control emergency-trigger --plan luks --device /dev/sda2", "description": "Trigger LUKS nuke via emergency shortcut (destroy encrypted partition headers)", "expectedOutput": "Emergency plan 'luks' executed successfully", "notes": "KEYBOARD: Uses the dashboard-configured approved combo. Hold it for roughly 2-3 seconds. IRREVERSIBLE - destroys LUKS headers making encrypted data unrecoverable. --device is required for luks and both plans." }, { "command": "sudo health-control emergency-trigger --plan both --device /dev/sda2", "description": "Trigger full nuke (dashboard + LUKS combined) via emergency shortcut", "expectedOutput": "Emergency plan 'both' executed successfully", "notes": "KEYBOARD: Uses the dashboard-configured approved combo and should be held for roughly 2-3 seconds. Combines dashboard-nuke and luks-nuke for maximum data destruction. IRREVERSIBLE." }, { "command": "sudo health-control emergency-trigger --plan dashboard --json", "description": "Trigger emergency action with JSON output for automation", "expectedOutput": "JSON result with plan, success status, execution time, and details", "notes": "JSON output includes: plan name, success status, execution duration, affected components. Useful for logging and monitoring." }, { "command": "sudo health-control emergency-trigger --plan luks --device /dev/sda2 --dry-run --json", "description": "Dry-run LUKS nuke with JSON output for pre-flight validation", "expectedOutput": "JSON dry-run result showing planned actions without executing", "notes": "Combines --dry-run and --json for safe testing with machine-readable output. Ideal for dashboard integration testing." }, { "command": "sudo health-control emergency-trigger --plan both --device /dev/sda2 --force --silent", "description": "Force-trigger full nuke silently (skip readiness checks, suppress output)", "expectedOutput": "(no stdout output - silent mode)", "notes": "DAEMON MODE - Used by kodachi-session-helper daemon. --force skips readiness checks, --silent suppresses stdout. For automated invocation only." }, { "command": "sudo health-control emergency-lockdown --delay 300 --plan dashboard --dry-run", "description": "Dry-run a 5-minute delayed lockdown for dashboard nuke", "expectedOutput": "DRY RUN: Would start 300s countdown for plan 'dashboard'", "notes": "SAFE TESTING - Preview lockdown without starting timer. Validates parameters and session token." }, { "command": "sudo health-control emergency-lockdown --delay 300 --plan dashboard", "description": "Start a 5-minute delayed lockdown that triggers dashboard nuke", "expectedOutput": "Lockdown started: plan 'dashboard' in 300 seconds", "notes": "DELAYED LOCKDOWN - Schedules emergency action after countdown. User can cancel before timer expires with emergency-lockdown-cancel. Useful for dead-man-switch scenarios." }, { "command": "sudo health-control emergency-lockdown --delay 60 --plan luks --device /dev/sda2", "description": "Start a 1-minute delayed lockdown for LUKS nuke", "expectedOutput": "Lockdown started: plan 'luks' (device: /dev/sda2) in 60 seconds", "notes": "SHORT TIMER - 60 second countdown before LUKS header destruction. Cancel with emergency-lockdown-cancel if needed." }, { "command": "sudo health-control emergency-lockdown-status", "description": "Check if a delayed lockdown is currently active and its remaining time", "expectedOutput": "Lockdown active: plan 'dashboard', 247 seconds remaining", "notes": "READ-ONLY - No session token required. Shows: active status, scheduled plan, remaining seconds, start time. Returns 'No active lockdown' if none pending." }, { "command": "sudo health-control emergency-lockdown-status --json", "description": "Check lockdown status in JSON format for dashboard integration", "expectedOutput": "JSON with active, plan, device, delay_seconds, remaining_seconds, started_at, expires_at", "notes": "JSON output for dashboard polling and monitoring systems. No authentication required for status checks." }, { "command": "sudo health-control emergency-lockdown-cancel", "description": "Cancel an active delayed lockdown before it triggers", "expectedOutput": "Lockdown cancelled successfully", "notes": "Cancels pending lockdown and kills the timer process. Requires valid session token. Returns error if no lockdown is active." }, { "command": "sudo health-control emergency-lockdown-cancel --json", "description": "Cancel lockdown with JSON confirmation output", "expectedOutput": "JSON confirmation with cancelled plan details and timestamp", "notes": "Machine-readable cancellation confirmation for dashboard integration." } ], "id": "26_emergency_shortcuts", "title": "Emergency Shortcuts - Keyboard-Triggered Actions" }, { "description": "Conky, screensaver, DPMS, and session power controls", "examples": [ { "command": "health-control conky-enable", "description": "Start Conky widget", "expectedOutput": "Conky enabled. Running: yes" }, { "command": "health-control conky-disable", "description": "Stop Conky widget", "expectedOutput": "Conky disabled. Running: no" }, { "command": "health-control conky-status --json", "description": "Conky status as JSON", "expectedOutput": "JSON with installed, running, start_on_boot, service_available, autostart_enabled fields" }, { "command": "health-control conky-boot-enable", "description": "Enable Conky autostart on boot", "expectedOutput": "Conky boot enabled. Start on boot: true" }, { "command": "health-control conky-boot-disable", "description": "Disable Conky autostart", "expectedOutput": "Conky boot disabled. Start on boot: false" }, { "command": "health-control screensaver-disable", "description": "Disable XFCE screensaver", "expectedOutput": "Screensaver disabled. Running: no" }, { "command": "health-control screensaver-enable", "description": "Re-enable screensaver", "expectedOutput": "Screensaver enabled. Running: yes" }, { "command": "health-control screensaver-status --json", "description": "Check screensaver state", "expectedOutput": "JSON with screensaver_running, screensaver_autostart_enabled, screensaver_binary_available" }, { "command": "health-control dpms-disable", "description": "Keep display always on", "expectedOutput": "DPMS disabled. Display will stay on." }, { "command": "health-control dpms-enable", "description": "Restore display power saving", "expectedOutput": "DPMS enabled. Display power management active." }, { "command": "health-control dpms-status --json", "description": "Check DPMS timeouts", "expectedOutput": "JSON with dpms_enabled, standby_seconds, suspend_seconds, off_seconds, blanking fields" }, { "command": "health-control lock-screen", "description": "Lock screen immediately", "expectedOutput": "Screen locked via loginctl", "notes": "Multi-fallback: loginctl > xdg-screensaver > xflock4" }, { "command": "health-control session-logout", "description": "End XFCE session", "expectedOutput": "Session logout initiated via xfce4-session-logout", "notes": "Fallback: loginctl terminate-user" }, { "command": "health-control suspend", "description": "Suspend to RAM", "expectedOutput": "Suspend initiated via xfce4-session-logout", "notes": "Fallback: systemctl suspend" }, { "command": "health-control conky-mask-enable", "description": "Mask sensitive info in Conky panels for safe screenshots", "expectedOutput": "Privacy masking enabled. Conky panels will show masked data." }, { "command": "health-control conky-mask-disable", "description": "Unmask Conky panels to show real data", "expectedOutput": "Privacy masking disabled. Conky panels will show real data." }, { "command": "health-control conky-mask-status", "description": "Check if Conky privacy masking is active", "expectedOutput": "Privacy masking: disabled" } ], "id": "30_display_power", "title": "Display & Power" } ], "description": "Usage examples for health-control", "name": "health-control", "quickReference": [ "sudo health-control --help", "sudo health-control --version", "sudo health-control --info --json", "sudo health-control --examples --json" ] }, "errors": [], "metadata": { "executionTime": 13, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:15.054635968Z", "version": "9.0.1", "warnings": [] } }, { "name": "ai-admin", "path": "/home/kodachi/k900/dashboard/hooks/ai-admin", "timestamp": "2026-04-02T13:42:15Z", "file_info": { "size": 2704048, "sha256": "6dd597cf8176d2a2904cd0d018522dcede7796d0b4b59dac029366c0a5b630ea" }, "flag_n": { "status": "success", "timestamp": "2026-04-02T13:42:15.433614980Z", "command": "info", "version": "9.0.1", "data": { "name": "ai-admin", "version": "9.0.1", "author": "Warith Al Maawali ", "description": "AI system administration and maintenance", "copyright": "© 2026 Linux Kodachi", "website": "https://www.digi77.com", "license": "Proprietary", "features": [], "securityFeatures": { "inputValidation": "All inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for network operations", "authentication": "Secure authentication with certificate pinning", "encryption": "TLS 1.3 for all network communications" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_v": { "status": "success", "timestamp": "2026-04-02T13:42:15.505808975Z", "command": "version", "version": "9.0.1", "data": { "name": "ai-admin", "version": "9.0.1", "buildDate": "2026-04-02T13:42:15.505551217Z", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_h": { "status": "success", "timestamp": "2026-04-02T13:42:15.574517184Z", "command": "help", "version": "9.0.1", "data": { "name": "ai-admin", "description": "AI system administration and maintenance", "usage": "ai-admin [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Commands", "commands": [ { "name": "db", "description": "Database management operations", "usage": "ai-admin db [OPTIONS]", "options": [], "requires_sudo": false }, { "name": "diagnostics", "description": "Run system diagnostics", "usage": "ai-admin diagnostics [OPTIONS]", "options": [], "requires_sudo": false }, { "name": "tune", "description": "Performance tuning and optimization", "usage": "ai-admin tune [OPTIONS]", "options": [], "requires_sudo": false } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" }, { "flag": "--timeout ", "description": "Set timeout (default: 30)" }, { "flag": "--retry ", "description": "Retry attempts (default: 3)" } ], "environmentVariables": [ { "name": "RUST_LOG", "description": "Set logging level", "default": "info", "values": "error|warn|info|debug|trace" }, { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "3": "Permission denied", "2": "Invalid arguments", "4": "Network error", "5": "File not found" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_e": { "status": "success", "timestamp": "2026-04-02T13:42:15.707364286Z", "command": "examples", "version": "9.0.1", "data": { "name": "ai-admin", "description": "Usage examples for ai-admin", "categories": [ { "id": "1_database", "title": "Database Operations", "description": "Database backup, restore, and management", "examples": [ { "command": "ai-admin db backup --output ./backup.db", "description": "Create database backup", "expectedOutput": "Backup created successfully", "notes": "Backup file will be created in execution folder" }, { "command": "ai-admin db restore --backup ./backup.db", "description": "Restore database from backup", "expectedOutput": "Database restored successfully", "notes": "Current database will be backed up before restore" }, { "command": "ai-admin db integrity-check", "description": "Check database integrity", "expectedOutput": "Database integrity check results" }, { "command": "ai-admin db migrate", "description": "Run database migrations", "expectedOutput": "Migrations applied successfully" }, { "command": "ai-admin db info", "description": "Show database information and statistics", "expectedOutput": "Database size, table counts, and statistics", "notes": "Useful for monitoring database growth" }, { "command": "ai-admin db info --json", "description": "Show database info as JSON", "expectedOutput": "Database information in JSON format", "notes": "Useful for automated monitoring" } ] }, { "id": "2_diagnostics", "title": "System Diagnostics", "description": "System health checks and diagnostics", "examples": [ { "command": "ai-admin diagnostics", "description": "Run basic diagnostics", "expectedOutput": "System diagnostics report" }, { "command": "ai-admin diagnostics --full", "description": "Run full diagnostics including integrity checks", "expectedOutput": "Comprehensive diagnostics report", "notes": "Includes database integrity and model validation" }, { "command": "ai-admin diagnostics --full --json", "description": "Full diagnostics with JSON output", "expectedOutput": "Comprehensive diagnostics in JSON format", "notes": "Full diagnostics include integrity checks" }, { "command": "ai-admin diagnostics --json", "description": "Run diagnostics with JSON output", "expectedOutput": "Basic diagnostics in JSON format", "notes": "Useful for automated health monitoring" } ] }, { "id": "2b_tier_config", "title": "AI Tier Configuration", "description": "Administration of the 6-tier AI engine system", "examples": [ { "command": "ai-admin diagnostics --full --json", "description": "Full diagnostics including all AI tier health", "expectedOutput": "JSON with tier availability, model paths, and health status", "notes": "Covers TF-IDF, ONNX, Mistral.rs, GenAI/Ollama, Legacy LLM, Claude" }, { "command": "ai-admin diagnostics --json", "description": "Quick diagnostics with AI tier status summary", "expectedOutput": "JSON with basic tier configuration info", "notes": "Faster than --full, covers essential tier checks" } ] }, { "id": "3_performance", "title": "Performance Tuning", "description": "Database optimization and performance tuning", "examples": [ { "command": "ai-admin tune optimize", "description": "Optimize database performance", "expectedOutput": "Database optimized successfully", "notes": "Runs VACUUM and ANALYZE operations" }, { "command": "ai-admin tune rebuild-index", "description": "Rebuild database indexes", "expectedOutput": "Indexes rebuilt successfully" }, { "command": "ai-admin tune cleanup --days 30", "description": "Clean up old data (older than 30 days)", "expectedOutput": "Cleanup completed, X records removed" }, { "command": "ai-admin tune cleanup --days 7", "description": "Clean up data older than 7 days", "expectedOutput": "Cleanup completed, X records removed", "notes": "More aggressive cleanup for recent data" }, { "command": "ai-admin tune optimize --json", "description": "Optimize database with JSON output", "expectedOutput": "Optimization results in JSON format", "notes": "Shows detailed optimization statistics" }, { "command": "ai-admin tune rebuild-index --json", "description": "Rebuild indexes with JSON output", "expectedOutput": "Index rebuild results in JSON format", "notes": "Structured output for automation pipelines" }, { "command": "ai-admin tune cleanup --days 7 --json", "description": "Aggressive cleanup with JSON output", "expectedOutput": "JSON with cleanup statistics and records removed", "notes": "Combines short retention with structured output" } ] } ], "quickReference": [ "sudo ai-admin --help", "sudo ai-admin --version", "sudo ai-admin --info --json", "sudo ai-admin --examples --json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } } }, { "name": "global-launcher", "path": "/home/kodachi/k900/dashboard/hooks/global-launcher", "timestamp": "2026-04-02T13:42:15Z", "file_info": { "size": 1762048, "sha256": "7a9e1f22084490d74e497f99e17ab1f9f80e6c00053aa989bd8f0f60b36c3893" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "Global launcher for Kodachi dashboard binaries with execution folder containment", "features": [ "Dynamic binary discovery and deployment", "Execution folder containment for security", "Symlink-based global access", "Comprehensive error handling and logging", "Support for both Rust and Gambas binaries", "Deployment verification and rollback", "JSON and text output formats", "Zero hardcoded paths - fully dynamic" ], "license": "Proprietary", "name": "global-launcher", "securityFeatures": { "authentication": "Integrates with system permissions and user context", "encryption": "Secure configuration embedded in binary", "inputValidation": "All binary names and paths are validated against security rules", "rateLimiting": "Configurable timeouts prevent resource exhaustion" }, "systemRequirements": { "dependencies": [ "cli-core library", "logs-hook service", "symlink support in filesystem" ], "os": "Linux (Debian-based, specifically Kodachi OS)", "privileges": "root/sudo for global deployment" }, "version": "9.0.1", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:15.959379997Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T11:06:49.159846048Z", "gitCommit": "facf0db", "name": "global-launcher", "rustVersion": "rustc 1.94.1 (e408947bf 2026-03-25)", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.021966612Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Management Commands", "commands": [ { "description": "Deploy global symlinks for all dashboard binaries", "examples": [ "sudo ./global-launcher deploy", "sudo ./global-launcher deploy --json", "sudo ./global-launcher deploy --force" ], "name": "deploy", "options": [ { "default": "false", "description": "Force deployment even if binaries exist", "flag": "--force" }, { "default": "false", "description": "Skip verification after deployment", "flag": "--no-verify" }, { "default": "false", "description": "Save SHA256 hash report to results directory", "flag": "--save-hashes" } ], "requires_sudo": false, "usage": "global-launcher deploy [OPTIONS]" }, { "description": "Verify deployed symlinks are working", "examples": [ "./global-launcher verify", "./global-launcher verify --json", "./global-launcher verify --detailed" ], "name": "verify", "options": [ { "default": "false", "description": "Show detailed verification info", "flag": "--detailed" }, { "default": "false", "description": "Save SHA256 hash report to results directory", "flag": "--save-hashes" } ], "requires_sudo": false, "usage": "global-launcher verify [OPTIONS]" }, { "description": "Remove all deployed symlinks", "examples": [ "sudo ./global-launcher cleanup", "sudo ./global-launcher cleanup --yes", "sudo ./global-launcher cleanup --json" ], "name": "cleanup", "options": [ { "default": "false", "description": "Confirm cleanup without prompting", "flag": "--yes" } ], "requires_sudo": false, "usage": "global-launcher cleanup [OPTIONS]" } ] } ], "description": "Global launcher for Kodachi dashboard binaries", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "auto-detected", "description": "Override hooks directory location", "name": "KODACHI_BASE_DIR", "values": "/path/to/hooks" } ], "exitCodes": { "0": "Success", "1": "General error", "10": "Security violation", "2": "Invalid arguments", "3": "Permission denied", "4": "Binary not found", "5": "Directory not found", "6": "Timeout", "7": "Deployment error", "8": "Execution error", "9": "Validation error" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (default: 900)", "flag": "--timeout " }, { "description": "Override target user for deployment", "flag": "--user-override " } ], "name": "global-launcher", "usage": "global-launcher [OPTIONS] [COMMAND]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.083705638Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Deploying and managing global binary access", "examples": [ { "command": "sudo ./global-launcher deploy", "description": "Deploy global access for all dashboard binaries", "expectedOutput": "Creates symlinks in /usr/local/bin for all discovered binaries", "notes": "Requires sudo for writing to /usr/local/bin" }, { "command": "sudo ./global-launcher deploy --json", "description": "Deploy with JSON terminal output", "expectedOutput": "JSON response with deployment results and statistics on terminal" }, { "command": "sudo ./global-launcher deploy --save-hashes", "description": "Deploy and save SHA256 hash report to results directory", "expectedOutput": "Creates deployment-hashes.json with SHA256 hashes in hooks/results/", "notes": "Includes source binary and launcher hashes for integrity verification" }, { "command": "sudo ./global-launcher deploy --force", "description": "Force deployment, replacing existing symlinks", "expectedOutput": "Overwrites existing symlinks and creates backups" } ], "id": "1_deployment", "title": "Deployment Operations" }, { "description": "Verifying deployed symlinks work correctly", "examples": [ { "command": "./global-launcher verify", "description": "Verify all deployed symlinks", "expectedOutput": "Reports on symlink status and any issues found" }, { "command": "./global-launcher verify --save-hashes", "description": "Verify and save hash report to results directory", "expectedOutput": "Creates verification-hashes.json with SHA256 hashes in hooks/results/", "notes": "Includes source binary hashes and launcher hash for integrity checks" }, { "command": "./global-launcher verify --detailed --json", "description": "Detailed verification with JSON terminal output", "expectedOutput": "Comprehensive JSON with symlink status and SHA256 hashes", "notes": "Each binary includes source_binary_hash and launcher_hash fields" } ], "id": "2_verification", "title": "Verification Operations" }, { "description": "SHA256 hash verification for binary integrity and update detection", "examples": [ { "command": "./global-launcher verify --save-hashes", "description": "Save SHA256 hash report for all deployed binaries", "expectedOutput": "Creates verification-hashes.json in hooks/results/", "notes": "Includes source binary hashes and launcher hash for integrity verification" }, { "command": "sudo ./global-launcher deploy --save-hashes", "description": "Deploy binaries and save hash report", "expectedOutput": "Creates deployment-hashes.json in hooks/results/", "notes": "Hash report useful for tracking binary versions and detecting tampering" }, { "command": "cat hooks/results/verification-hashes.json", "description": "View saved hash report", "expectedOutput": "JSON report with SHA256 hashes for all binaries", "notes": "Compare hashes between deployments to detect binary changes" }, { "command": "./global-launcher verify --save-hashes --json | jq '.data.verified_symlinks[0] | {name, source_binary_hash, launcher_hash}'", "description": "Save hash report and extract specific hashes from JSON output", "expectedOutput": "Both creates hash file and displays hashes on terminal", "notes": "Combine --save-hashes with --json for both file storage and terminal output" } ], "id": "3_hash_integrity", "title": "Hash Integrity Verification" }, { "description": "Once deployed, binaries work from anywhere", "examples": [ { "command": "health-control status", "description": "Run health-control from any directory", "expectedOutput": "Executes health-control in hooks directory context", "notes": "Works from any location after deployment" }, { "command": "ip-fetch --json", "description": "Run ip-fetch with JSON output globally", "expectedOutput": "IP information in JSON format" }, { "command": "dns-switch list", "description": "List DNS servers from anywhere", "expectedOutput": "DNS server list with current configuration" } ], "id": "4_usage", "title": "Using Global Binaries" }, { "description": "Removing global binary access", "examples": [ { "command": "sudo ./global-launcher cleanup", "description": "Remove all deployed symlinks", "expectedOutput": "Removes all symlinks and reports count", "notes": "Requires sudo for removing from /usr/local/bin" }, { "command": "sudo ./global-launcher cleanup --yes --json", "description": "Auto-confirm cleanup with JSON terminal output", "expectedOutput": "JSON response with cleanup results on terminal" } ], "id": "5_cleanup", "title": "Cleanup Operations" } ], "description": "Usage examples for global-launcher", "name": "global-launcher", "quickReference": [ "sudo ./global-launcher deploy", "./global-launcher verify", "health-control status", "ip-fetch --json", "sudo ./global-launcher cleanup" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.210117251Z", "version": "9.0.1", "warnings": [] } }, { "name": "conky-status", "path": "/home/kodachi/k900/dashboard/hooks/conky-status", "timestamp": "2026-04-02T13:42:16Z", "file_info": { "size": 1962848, "sha256": "3223c73976eaa35d64f252edcd990cb0fb4ef373c230bdf9df9c81abb2781502" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "Unified Rust gateway for Kodachi Conky data", "features": [ "Bounded parallel adapter collection", "Unified snapshot cache with lock + atomic writes", "Privacy-first redaction for sensitive identifiers", "Compatibility aliases for legacy Conky scripts", "User-defined Conky command registry via JSON config", "Kodachi-standard CLI flags via cli-core" ], "license": "Proprietary", "name": "conky-status", "securityFeatures": { "authentication": "Secure authentication with certificate pinning", "encryption": "TLS 1.3 for all network communications", "inputValidation": "All inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for network operations" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.0.1", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.472936887Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T13:42:16.533405925Z", "gitCommit": "unknown", "name": "conky-status", "rustVersion": "1.82.0", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.538573296Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Data", "commands": [ { "description": "Collect and output unified conky-status snapshot", "examples": [ "./conky-status snapshot --json", "./conky-status snapshot --json-pretty", "./conky-status snapshot --json-human", "./conky-status snapshot --cached --ttl 30", "./conky-status snapshot --refresh --max-parallel 2 --timeout-ms 1500" ], "name": "snapshot", "options": [ { "default": "true unless --cached is set", "description": "Force refresh now", "flag": "--refresh", "required": false }, { "default": "false", "description": "Prefer cache if fresh", "flag": "--cached", "required": false }, { "default": "20", "description": "Cache freshness threshold", "flag": "--ttl ", "required": false } ], "requires_sudo": false, "usage": "conky-status snapshot [--refresh] [--cached] [--ttl ] [--max-parallel ] [--timeout-ms ]" }, { "description": "Get a single key value (snapshot key or user. registry command)", "examples": [ "./conky-status get data.auth.group", "./conky-status get ip-cache.ip", "./conky-status get auth-detail.sessionid", "./conky-status get data.health.score_display --default 0", "./conky-status get security-status.vpn --json", "./conky-status get data.system.network.interface --refresh", "./conky-status get dns-cache.mode --default Unknown", "./conky-status get user.hostname_short", "./conky-status get user.uptime_pretty --default N/A" ], "name": "get", "options": [ { "description": "Fallback value when key is missing", "flag": "--default ", "required": false }, { "default": "false", "description": "Force refresh before lookup", "flag": "--refresh", "required": false } ], "requires_sudo": false, "usage": "conky-status get [--default ] [--refresh] [--ttl ] # key supports user." }, { "description": "Get a batched subset for a panel", "examples": [ "./conky-status panel security", "./conky-status panel system --json-pretty", "./conky-status panel network --refresh", "./conky-status panel resources", "./conky-status panel gauges --json", "./conky-status panel all --json-human" ], "name": "panel", "options": [], "requires_sudo": false, "usage": "conky-status panel [--refresh]" }, { "description": "Manage and execute user-defined Conky commands from JSON registry", "examples": [ "./conky-status user path", "./conky-status user init", "./conky-status user list", "./conky-status user run hostname_short", "./conky-status user run uptime_pretty --json-pretty" ], "name": "user", "options": [], "requires_sudo": false, "usage": "conky-status user [args]" } ] } ], "description": "Unified Rust gateway for Kodachi Conky data", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " } ], "name": "conky-status", "usage": "conky-status [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.614925855Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Kodachi-standard global flags and output modes", "examples": [ { "command": "./conky-status -h", "description": "Show full CLI help", "expectedOutput": "Command/option reference" }, { "command": "./conky-status -v", "description": "Show binary version", "expectedOutput": "conky-status version 9.0.1" }, { "command": "./conky-status -n --json-pretty", "description": "Show program metadata using JSON pretty mode", "expectedOutput": "Envelope with info payload" }, { "command": "./conky-status -e", "description": "Show comprehensive usage examples", "expectedOutput": "Category-based examples list" }, { "command": "./conky-status snapshot --json-human", "description": "Use human-readable JSON rendering (jq-like)", "expectedOutput": "Enhanced JSON envelope", "notes": "Falls back to pretty JSON if jq is unavailable" } ], "id": "1_core_flags", "title": "Core Flags" }, { "description": "Refresh, cache, concurrency, and timeout controls", "examples": [ { "command": "./conky-status snapshot --json", "description": "Collect snapshot using default refresh behavior", "expectedOutput": "Envelope with meta/adapters/data" }, { "command": "./conky-status snapshot --cached --ttl 30", "description": "Prefer cached snapshot if age <= 30 seconds", "expectedOutput": "Fast cached response when fresh" }, { "command": "./conky-status snapshot --refresh --timeout-ms 1200", "description": "Force new collection with tighter adapter timeout", "expectedOutput": "Fresh snapshot with possible degraded adapters" }, { "command": "./conky-status snapshot --refresh --max-parallel 6 --json-pretty", "description": "Override adapter concurrency budget", "expectedOutput": "Pretty JSON snapshot", "notes": "Use moderate values to avoid subprocess storms" } ], "id": "2_snapshot_modes", "title": "Snapshot Modes" }, { "description": "Read direct snapshot key paths", "examples": [ { "command": "./conky-status get data.auth.group", "description": "Read authenticated user group", "expectedOutput": "Group value or '?'" }, { "command": "./conky-status get data.health.score_display --default 0", "description": "Read health score with default fallback", "expectedOutput": "Numeric score string" }, { "command": "./conky-status get data.system.network.interface --refresh", "description": "Force refresh before interface lookup", "expectedOutput": "Interface name like ens33/wlan0" }, { "command": "./conky-status get data.tor.torrified_onoff --json", "description": "Structured JSON response for a single key", "expectedOutput": "Envelope with key, resolved_key, value, stale" } ], "id": "3_get_native_keys", "title": "Get Native Keys" }, { "description": "Legacy script-compatible key aliases for Conky migration", "examples": [ { "command": "./conky-status get ip-cache.ip --default Offline", "description": "Effective external IP (Tor exit when torrified, direct IP otherwise)", "expectedOutput": "Effective IP or Offline" }, { "command": "./conky-status get ip-public.ip --default Offline", "description": "Direct/public WAN IP regardless of Tor exit routing", "expectedOutput": "Public IP or Offline" }, { "command": "./conky-status get auth-detail.sessionid", "description": "Equivalent of auth-detail.sh sessionid", "expectedOutput": "Masked session token or N/A" }, { "command": "./conky-status get dns-cache.mode --default Unknown", "description": "Equivalent of dns-cache.sh mode", "expectedOutput": "DNS mode string" }, { "command": "./conky-status get system-status.swapperc --default 0", "description": "Gauge-ready swap usage percent from gateway", "expectedOutput": "Integer 0-100" }, { "command": "./conky-status get net-traffic.totalpercent --default 0", "description": "Gauge-ready total bandwidth percent (0-100)", "expectedOutput": "Integer 0-100", "notes": "Computed from total uploaded+downloaded bytes against 10 GiB scale" }, { "command": "./conky-status get security-status.vpn --json-pretty", "description": "Equivalent of security-status.sh vpn", "expectedOutput": "JSON envelope with boolean value" }, { "command": "./conky-status get cloud-status.cards", "description": "Equivalent of cloud-status.sh cards", "expectedOutput": "Cloud cards count or '?'" } ], "id": "4_get_compat_keys", "title": "Get Compatibility Keys" }, { "description": "Batched panel subsets for exec/execpi integration", "examples": [ { "command": "./conky-status panel security", "description": "Key=value output for security panel", "expectedOutput": "Multiple lines: internet/login/group/..." }, { "command": "./conky-status panel system --json-pretty", "description": "System panel subset in JSON", "expectedOutput": "Envelope with panel data map" }, { "command": "./conky-status panel network --refresh", "description": "Refresh before network panel render", "expectedOutput": "Updated panel key=value lines" }, { "command": "./conky-status panel resources", "description": "Resource panel subset (traffic + booleans)", "expectedOutput": "Panel key=value lines" }, { "command": "./conky-status panel all --json-human", "description": "Dump full data section in human JSON mode", "expectedOutput": "Large JSON envelope" } ], "id": "5_panel_modes", "title": "Panel Modes" }, { "description": "Drop-in commands for wrapper scripts and panel configs", "examples": [ { "command": "${exec ~/.config/kodachi/conky/scripts/ip-cache.sh ip} -> ${exec ./conky-status get ip-cache.ip --default Offline}", "description": "Replace legacy IP script call", "expectedOutput": "Same scalar value in Conky text field" }, { "command": "${exec ~/.config/kodachi/conky/scripts/auth-detail.sh group} -> ${exec ./conky-status get auth-detail.group --default '?'}", "description": "Replace auth detail script call", "expectedOutput": "Same group text output" }, { "command": "${exec ~/.config/kodachi/conky/scripts/dns-cache.sh ns1} -> ${exec ./conky-status get dns-cache.ns1 --default N/A}", "description": "Replace DNS cache script call", "expectedOutput": "Primary nameserver text" }, { "command": "${execpi 20 ./conky-status panel security}", "description": "Use panel mode for grouped values", "expectedOutput": "key=value lines for panel rendering", "notes": "No Conky restart required to validate command output" } ], "id": "6_conky_integration", "title": "Conky Integration" }, { "description": "Configure custom commands in JSON so Conky can call unsupported fields through the gateway", "examples": [ { "command": "./conky-status user path", "description": "Show registry file path", "expectedOutput": "~/.config/kodachi/conky/config/user-commands.json" }, { "command": "./conky-status user init", "description": "Create template registry if missing", "expectedOutput": "created: or existing: " }, { "command": "./conky-status user list --json-pretty", "description": "List registered custom command names", "expectedOutput": "JSON list with command count" }, { "command": "./conky-status user run hostname_short", "description": "Execute one configured command directly", "expectedOutput": "Single Conky-safe value", "notes": "Failed commands retry once and can fall back to stale cache/default" }, { "command": "./conky-status get user.hostname_short --default Unknown", "description": "Conky-friendly key path for custom user command", "expectedOutput": "Scalar value from registry-backed command", "notes": "Also accepts custom. as alias" }, { "command": "${exec ./conky-status get user.hostname_short --default Unknown}", "description": "Direct Conky call without exposing command logic in bash", "expectedOutput": "Rendered value in panel" } ], "id": "7_user_command_registry", "title": "User Command Registry" }, { "description": "Binary self-signature verification diagnostics and enforcement", "examples": [ { "command": "KODACHI_FORCE_VERIFY=1 ./conky-status -v", "description": "Force signature check in debug builds", "expectedOutput": "Version output if signature verifies", "notes": "Fails with SECURITY error when signature is missing/invalid" }, { "command": "KODACHI_SIG_DIR=./results/signatures ./conky-status snapshot --json", "description": "Use custom signature directory", "expectedOutput": "Snapshot output with successful startup" }, { "command": "KODACHI_BUILD_TEST=1 ./conky-status -v", "description": "Skip signature check in controlled build-test mode", "expectedOutput": "Version output", "notes": "Intended for build pipeline self-tests only" }, { "command": "./conky-status -v", "description": "Release behavior with mandatory signature verification", "expectedOutput": "Version output or SECURITY failure message" } ], "id": "8_signature_verification", "title": "Signature Verification" } ], "description": "Usage examples for conky-status", "name": "conky-status", "quickReference": [ "sudo conky-status --help", "sudo conky-status --version", "sudo conky-status --info --json", "sudo conky-status --examples --json" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:16.763209374Z", "version": "9.0.1", "warnings": [] } }, { "name": "ai-gateway", "path": "/home/kodachi/k900/dashboard/hooks/ai-gateway", "timestamp": "2026-04-02T13:42:17Z", "file_info": { "size": 4735816, "sha256": "46f971773221d8f329db7573318fdd7c3cb7550755964b5914f2b6bb31c8b5cb" }, "flag_n": { "status": "success", "timestamp": "2026-04-02T13:42:17.030471959Z", "command": "info", "version": "9.0.1", "data": { "name": "ai-gateway", "version": "9.0.1", "author": "Warith Al Maawali", "description": "Unified AI gateway for command catalog, policy firewall, and safe execution", "copyright": "© 2026 Linux Kodachi", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "Embedded command catalog with 800+ commands from 15+ services", "TF-IDF + substring hybrid search across all services", "Three-tier risk classification (Passive/Active/Dangerous)", "Policy firewall with allowlist enforcement", "Workspace confinement and path validation", "Failure cooldown to prevent cascading degradation", "Per-agent identity, rate limiting, and audit trail for executions", "Approval ticket workflow for agent-to-human authorization", "Configurable per-operation timeouts with env var override", "Full JSON/JSON-pretty/JSON-human output support" ], "securityFeatures": { "inputValidation": "All inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for network operations", "authentication": "Secure authentication with certificate pinning", "encryption": "TLS 1.3 for all network communications" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_v": { "status": "success", "timestamp": "2026-04-02T13:42:17.098479307Z", "command": "version", "version": "9.0.1", "data": { "name": "ai-gateway", "version": "9.0.1", "buildDate": "2026-04-02T13:42:17.097936192Z", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_h": { "status": "success", "timestamp": "2026-04-02T13:42:17.166223769Z", "command": "help", "version": "9.0.1", "data": { "name": "ai-gateway", "description": "Unified AI gateway for command catalog, policy firewall, and safe execution", "usage": "ai-gateway [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Administration", "commands": [ { "name": "index", "description": "Rebuild the search index from the embedded registry", "usage": "ai-gateway ai-gateway index rebuild", "options": [], "requires_sudo": false, "examples": [ "ai-gateway index rebuild", "ai-gateway index rebuild --json", "ai-gateway index rebuild --json-pretty" ] }, { "name": "policy", "description": "Show the current safety policy configuration", "usage": "ai-gateway ai-gateway policy show", "options": [], "requires_sudo": false, "examples": [ "ai-gateway policy show", "ai-gateway policy show --json", "ai-gateway policy show --json-pretty" ] }, { "name": "doctor", "description": "Health check that verifies all registered binaries exist and respond", "usage": "ai-gateway ai-gateway doctor", "options": [], "requires_sudo": false, "examples": [ "ai-gateway doctor", "ai-gateway doctor --json", "ai-gateway doctor --json-pretty" ] }, { "name": "approve", "description": "Issue or verify human approval tickets for agent execution", "usage": "ai-gateway ai-gateway approve issue [--agent-id ] [--ttl ]\nai-gateway approve verify --ticket [--agent-id ]", "options": [], "requires_sudo": false, "examples": [ "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json", "ai-gateway approve verify --ticket \"$TICKET\" health-control block-internet --agent-id kodachi-claw --json" ] } ] }, { "category": "Discovery", "commands": [ { "name": "list", "description": "List all services and their commands from the embedded registry", "usage": "ai-gateway ai-gateway list [--service ] [--category ]", "options": [ { "flag": "--service", "description": "Filter by service name" }, { "flag": "--category", "description": "Filter by category name" } ], "requires_sudo": false, "examples": [ "ai-gateway list", "ai-gateway list --json", "ai-gateway list --service tor-switch", "ai-gateway list --service health-control --json", "ai-gateway list --category passive" ] }, { "name": "search", "description": "Search across all services and commands using TF-IDF + substring matching", "usage": "ai-gateway ai-gateway search [--limit ]", "options": [ { "flag": "--limit", "description": "Maximum number of results to return", "default": "20" } ], "requires_sudo": false, "examples": [ "ai-gateway search \"tor status\"", "ai-gateway search \"dns leak\" --json", "ai-gateway search \"network check\" --limit 5", "ai-gateway search \"panic\" --json-pretty" ] }, { "name": "help", "description": "Show detailed help for a service or specific command", "usage": "ai-gateway ai-gateway help [command]", "options": [], "requires_sudo": false, "examples": [ "ai-gateway help tor-switch", "ai-gateway help tor-switch tor-status --json", "ai-gateway help health-control --json-pretty", "ai-gateway help dns-leak test", "ai-gateway help zeroclaw --json" ] }, { "name": "capabilities", "description": "Show effective capabilities for an AI agent identity", "usage": "ai-gateway ai-gateway capabilities [--agent-id ] [--agent-token ]", "options": [ { "flag": "--agent-id", "description": "Agent profile (kodachi-claw/nullclaw/agentzero/openclaw/picoclaw/nanoclaw/claude-code/gpt/gemini/open-interpreter; aliases: zeroclaw, nanclaw, \"claude code\", \"open interpreter\")", "default": "anonymous" }, { "flag": "--agent-token", "description": "Optional token for authenticated agent profiles" } ], "requires_sudo": false, "examples": [ "ai-gateway capabilities --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --json", "ai-gateway capabilities --agent-id nullclaw --agent-token $KODACHI_AGENT_TOKEN_NULLCLAW", "ai-gateway capabilities --agent-id openclaw --agent-token $KODACHI_AGENT_TOKEN_OPENCLAW --json", "ai-gateway capabilities --agent-id picoclaw --agent-token $KODACHI_AGENT_TOKEN_PICOCLAW --json", "ai-gateway capabilities --agent-id nanoclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "ai-gateway capabilities --agent-id nanclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "ai-gateway capabilities --agent-id claude-code --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "ai-gateway capabilities --agent-id \"claude code\" --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "ai-gateway capabilities --agent-id gpt --agent-token $KODACHI_AGENT_TOKEN_GPT --json", "ai-gateway capabilities --agent-id gemini --agent-token $KODACHI_AGENT_TOKEN_GEMINI --json", "ai-gateway capabilities --agent-id open-interpreter --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "ai-gateway capabilities --agent-id \"open interpreter\" --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "ai-gateway capabilities --agent-id anonymous --json" ] } ] }, { "category": "Execution", "commands": [ { "name": "run", "description": "Validate and execute a binary command through the safety layer", "usage": "ai-gateway ai-gateway run --command [--args ...] [--args-json ] [--dry-run] [--timeout ] [--agent-id ] [--agent-token ] [--approval-ticket ] OR ai-gateway run --batch-json --agent-id --agent-token ", "options": [ { "flag": "--command", "description": "Command to execute (required)", "required": true }, { "flag": "--args", "description": "Command arguments (multiple)" }, { "flag": "--args-json", "description": "Command arguments as JSON object/array" }, { "flag": "--batch-json", "description": "Batch execution payload for trusted agents (JSON array, sequential mode only)" }, { "flag": "--dry-run", "description": "Validate without executing" }, { "flag": "--timeout", "description": "Execution timeout in seconds", "default": "60" }, { "flag": "--confirm", "description": "Approval token for commands requiring confirmation" }, { "flag": "--approval-ticket", "description": "Human-issued approval ticket for Active/Dangerous commands" }, { "flag": "--agent-id", "description": "Agent profile (trusted profiles require token auth)", "default": "anonymous" }, { "flag": "--agent-token", "description": "Agent auth token for token-required profiles" } ], "requires_sudo": false, "examples": [ "ai-gateway run health-control --command net-check --dry-run", "ai-gateway run ip-fetch --command fetch --dry-run --json", "ai-gateway run tor-switch --command tor-status --timeout 60 --json", "ai-gateway run tor-switch --command set-exit-node --args-json '{\"country\":\"de\"}' --dry-run --json", "ai-gateway run dns-leak --command test --dry-run --json-pretty", "ai-gateway run kodachi-claw --command status --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --dry-run --json", "KODACHI_TRUSTED_BATCH_MODE=true ai-gateway run --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --batch-json '[{\"service\":\"kodachi-claw\",\"command\":\"status\"},{\"service\":\"kodachi-claw\",\"command\":\"doctor\",\"dry_run\":true}]' --json", "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" }, { "flag": "--timeout ", "description": "Set timeout (default: 30)" }, { "flag": "--retry ", "description": "Retry attempts (default: 3)" } ], "environmentVariables": [ { "name": "RUST_LOG", "description": "Set logging level", "default": "info", "values": "error|warn|info|debug|trace" }, { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "1": "General error", "5": "File not found", "2": "Invalid arguments", "4": "Network error", "0": "Success", "3": "Permission denied" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_e": { "status": "success", "timestamp": "2026-04-02T13:42:17.296563280Z", "command": "examples", "version": "9.0.1", "data": { "name": "ai-gateway", "description": "Usage examples for ai-gateway", "categories": [ { "id": "1_discovery", "title": "Service Discovery", "description": "Discover and explore all available Kodachi services and commands", "examples": [ { "command": "ai-gateway list --json", "description": "List all services with their commands in JSON format", "expectedOutput": "JSON array of all discovered services with metadata" }, { "command": "ai-gateway list --service tor-switch --json", "description": "List commands for a specific service", "expectedOutput": "Commands for tor-switch with descriptions and risk tiers" }, { "command": "ai-gateway list --service health-control", "description": "List health-control commands in text format", "expectedOutput": "Formatted list of health-control commands" } ] }, { "id": "2_search", "title": "Command Search", "description": "Search across all services using TF-IDF + substring hybrid search engine", "examples": [ { "command": "ai-gateway search \"tor exit node\" --json", "description": "Search for Tor exit node commands", "expectedOutput": "Ranked results with relevance scores", "notes": "Uses TF-IDF cosine similarity + substring matching" }, { "command": "ai-gateway search \"dns leak\" --limit 5 --json", "description": "Search with limited results", "expectedOutput": "Top 5 matching commands for DNS leak operations" }, { "command": "ai-gateway search \"network check\"", "description": "Search for network check commands in text format", "expectedOutput": "Numbered list of matching commands with scores" }, { "command": "ai-gateway search \"panic\" --json", "description": "Find all panic/emergency commands", "expectedOutput": "Emergency commands with Dangerous risk tier", "notes": "Dangerous commands are blocked unless pentest mode" } ] }, { "id": "3_help", "title": "Service Help", "description": "Get detailed help for any service or specific command", "examples": [ { "command": "ai-gateway help tor-switch --json", "description": "Full specification for tor-switch service", "expectedOutput": "JSON with all commands, options, examples, features, requirements" }, { "command": "ai-gateway help health-control security-status --json", "description": "Help for a specific command", "expectedOutput": "Detailed command spec with parameters and examples" }, { "command": "ai-gateway help dns-switch", "description": "Text help for dns-switch service", "expectedOutput": "Formatted help output for dns-switch" }, { "command": "ai-gateway help ip-fetch --json-pretty", "description": "Pretty-printed JSON help for ip-fetch", "expectedOutput": "Indented JSON with full service specification" } ] }, { "id": "4_execution", "title": "Safe Command Execution", "description": "Validate first, then execute when appropriate. No env var is needed for passive/active commands.", "examples": [ { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Step 1 (validate): preview a passive command", "expectedOutput": "Validation result without actual execution", "notes": "Always use --dry-run first for safety" }, { "command": "ai-gateway run tor-switch --command tor-status --json", "description": "Step 2 (apply): execute passive command (no env needed)", "expectedOutput": "Live command execution result", "notes": "Passive commands execute without KODACHI_PENTEST_MODE" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args-json '{\"country\":\"de\"}' --confirm --dry-run --json", "description": "Active command flow (no env needed): validate with explicit confirmation", "expectedOutput": "Validated active operation with parsed args-json", "notes": "For active commands, remove --dry-run to apply changes" }, { "command": "ai-gateway run dns-leak --command test --dry-run --timeout 60 --json", "description": "Dry-run DNS leak test with custom timeout", "expectedOutput": "Validation result for dns-leak test", "notes": "Timeout can be overridden with KODACHI_TOOL_TIMEOUT_MS env var" }, { "command": "ai-gateway run ip-fetch --command fetch --dry-run --json", "description": "Dry-run ip-fetch fetch command", "expectedOutput": "Validation result for ip-fetch fetch", "notes": "Dry-run keeps examples deterministic in offline/auth-restricted environments" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args-json '{\"country\":\"de\"}' --dry-run --json", "description": "Pass structured JSON arguments for agent-safe invocation", "expectedOutput": "Dry-run validation with args expanded from JSON", "notes": "`--args-json` avoids brittle shell quoting in agent pipelines" } ] }, { "id": "5_policy", "title": "Safety Policy", "description": "View and understand the safety policy configuration", "examples": [ { "command": "ai-gateway policy show --json", "description": "Show current safety policy as JSON", "expectedOutput": "Policy with risk tiers, allowlists, and pentest mode status" }, { "command": "ai-gateway policy show", "description": "Show safety policy in text format", "expectedOutput": "Formatted policy display" }, { "command": "ai-gateway policy show --json-pretty", "description": "Pretty-printed policy configuration", "expectedOutput": "Indented JSON with complete policy details", "notes": "Run with inline env: KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --confirm --json" }, { "command": "KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --confirm \"I understand\" --dry-run --json", "description": "Dangerous command flow: env var required in addition to explicit confirm", "expectedOutput": "Dangerous command validated in dry-run mode with explicit confirmation token", "notes": "KODACHI_PENTEST_MODE is required only for dangerous commands" } ] }, { "id": "6_administration", "title": "Administration", "description": "Index management and system health checks", "examples": [ { "command": "ai-gateway index rebuild --json", "description": "Rebuild the search index", "expectedOutput": "Index statistics with service and command counts" }, { "command": "ai-gateway doctor --json", "description": "Check health of all registered binaries", "expectedOutput": "Health report for each binary (exists, responds, version, size)" }, { "command": "ai-gateway doctor", "description": "Health check in text format", "expectedOutput": "Table showing binary health status" } ] }, { "id": "7_output_formats", "title": "Output Formats", "description": "All commands support multiple output formats", "examples": [ { "command": "ai-gateway list --json", "description": "Standard JSON output (compact)", "expectedOutput": "Compact JSON response" }, { "command": "ai-gateway list --json-pretty", "description": "Pretty-printed JSON with indentation", "expectedOutput": "Indented JSON for readability" }, { "command": "ai-gateway list --json-human", "description": "Enhanced human-friendly JSON (like jq)", "expectedOutput": "Color-highlighted JSON output" }, { "command": "ai-gateway --version", "description": "Show version information", "expectedOutput": "ai-gateway version 9.0.1" }, { "command": "ai-gateway --info --json", "description": "Show detailed program info as JSON", "expectedOutput": "JSON with features, security, requirements" } ] }, { "id": "8_ai_agent_integration", "title": "AI Agent Integration", "description": "How Kodachi AI standardizes execution for agentzero/openclaw/picoclaw/kodachi-claw/nullclaw/nanoclaw/open-interpreter via one gateway contract", "examples": [ { "command": "ai-gateway search \"check tor status\" --limit 1 --json", "description": "AI agent finds the best matching command", "expectedOutput": "Top matching command with service and invocation", "notes": "ai-cmd delegates execution through ai-gateway; pipe to jq externally if needed" }, { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "AI agent validates before executing", "expectedOutput": "Validation passes, shows what would run", "notes": "Safety layer prevents dangerous commands from AI agents" }, { "command": "ai-gateway run tor-switch --command tor-status --json", "description": "AI agent executes passive command (no env required)", "expectedOutput": "Live tor-status execution result", "notes": "Passive command execution does not require KODACHI_PENTEST_MODE" }, { "command": "ai-gateway run kodachi-claw --command status --dry-run --json", "description": "Kodachi Claw integration path through ai-gateway", "expectedOutput": "Validation for kodachi-claw status command", "notes": "Kodachi AI gives the same JSON execution contract to all agents" }, { "command": "ai-gateway run agentzero --command status --dry-run --json", "description": "AgentZero integration template (must be in allowlist)", "expectedOutput": "Policy + invocation validation for agentzero", "notes": "Add agentzero to the default allowlist in policy_engine.rs" }, { "command": "ai-gateway run openclaw --command status --dry-run --json", "description": "OpenClaw integration template", "expectedOutput": "Policy + invocation validation for openclaw", "notes": "Use --dry-run first, then remove --dry-run to execute" }, { "command": "ai-gateway run picoclaw --command status --dry-run --json", "description": "PicoClaw integration template", "expectedOutput": "Policy + invocation validation for picoclaw", "notes": "Same API shape as ai-cmd and zeroclaw integrations" }, { "command": "ai-gateway run kodachi-claw --command status --json", "description": "Kodachi Claw live execution path (no allow-all env required when installed/allowlisted)", "expectedOutput": "Live kodachi-claw command output through gateway safety layer" }, { "command": "ai-gateway run nullclaw --command status --dry-run --json", "description": "NullClaw integration template", "expectedOutput": "Policy + invocation validation for nullclaw", "notes": "Ensure nullclaw is in the policy engine allowlist" }, { "command": "ai-gateway run nanoclaw --command status --dry-run --json", "description": "NanoClaw integration template", "expectedOutput": "Policy + invocation validation for nanoclaw", "notes": "Consistent gateway contract keeps agent integrations simple" }, { "command": "ai-gateway help tor-switch tor-status --json", "description": "AI agent gets command specification", "expectedOutput": "Full command spec for AI to understand parameters", "notes": "Use jq in your shell after this command for field extraction" } ] }, { "id": "9_agent_security", "title": "Agent Security", "description": "Identity verification, capability discovery, and approval-ticket workflow", "examples": [ { "command": "ai-gateway capabilities --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --json", "description": "Discover what kodachi-claw is allowed to do", "expectedOutput": "Effective services, max risk tier, and per-minute rate limit" }, { "command": "ai-gateway capabilities --agent-id gpt --agent-token $KODACHI_AGENT_TOKEN_GPT --json", "description": "Discover trusted GPT agent capabilities", "expectedOutput": "Trusted profile details for gpt" }, { "command": "ai-gateway capabilities --agent-id claude-code --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "description": "Discover trusted Claude Code agent capabilities", "expectedOutput": "Trusted profile details for claude-code" }, { "command": "ai-gateway capabilities --agent-id gemini --agent-token $KODACHI_AGENT_TOKEN_GEMINI --json", "description": "Discover trusted Gemini agent capabilities", "expectedOutput": "Trusted profile details for gemini" }, { "command": "ai-gateway capabilities --agent-id open-interpreter --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "description": "Discover trusted Open Interpreter agent capabilities", "expectedOutput": "Trusted profile details for open-interpreter" }, { "command": "ai-gateway capabilities --agent-id openclaw --agent-token $KODACHI_AGENT_TOKEN_OPENCLAW --json", "description": "Discover trusted OpenClaw agent capabilities", "expectedOutput": "Trusted profile details for openclaw" }, { "command": "ai-gateway capabilities --agent-id picoclaw --agent-token $KODACHI_AGENT_TOKEN_PICOCLAW --json", "description": "Discover trusted PicoClaw agent capabilities", "expectedOutput": "Trusted profile details for picoclaw" }, { "command": "ai-gateway capabilities --agent-id nanoclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "description": "Discover trusted NanoClaw agent capabilities", "expectedOutput": "Trusted profile details for nanoclaw" }, { "command": "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json", "description": "Human issues time-limited approval ticket for an active/dangerous operation", "expectedOutput": "Signed approval ticket string", "notes": "Requires KODACHI_GATEWAY_APPROVAL_SECRET; extract .data.ticket with jq externally" }, { "command": "ai-gateway run health-control --command block-internet --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --approval-ticket \"$TICKET\" --json", "description": "Agent executes command using identity + approval workflow", "expectedOutput": "Execution gated by identity policy, rate limit, and ticket verification", "notes": "Without valid ticket, execution returns requires_approval" } ] } ], "quickReference": [ "sudo ai-gateway --help", "sudo ai-gateway --version", "sudo ai-gateway --info --json", "sudo ai-gateway --examples --json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } } }, { "name": "ai-trainer", "path": "/home/kodachi/k900/dashboard/hooks/ai-trainer", "timestamp": "2026-04-02T13:42:17Z", "file_info": { "size": 3000976, "sha256": "556fc3511d4f76e4531a2f30d8c0724ec395ac83a62e2a61f028013e686e42cb" }, "flag_n": { "status": "success", "timestamp": "2026-04-02T13:42:17.569226534Z", "command": "info", "version": "9.0.1", "data": { "name": "ai-trainer", "version": "9.0.1", "author": "Warith Al Maawali ", "description": "AI model training and validation for Kodachi OS command intelligence", "copyright": "© 2026 Linux Kodachi", "website": "https://www.digi77.com", "license": "LicenseRef-Kodachi-SAN-1.0", "features": [ "TF-IDF based command embeddings", "Incremental model updates", "Model validation and accuracy testing" ], "securityFeatures": { "inputValidation": "All inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for network operations", "authentication": "Secure authentication with certificate pinning", "encryption": "TLS 1.3 for all network communications" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_v": { "status": "success", "timestamp": "2026-04-02T13:42:17.631699252Z", "command": "version", "version": "9.0.1", "data": { "name": "ai-trainer", "version": "9.0.1", "buildDate": "2026-04-02T13:42:17.631165216Z", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_h": { "status": "success", "timestamp": "2026-04-02T13:42:17.707519955Z", "command": "help", "version": "9.0.1", "data": { "name": "ai-trainer", "description": "AI model training and validation for Kodachi OS command intelligence", "usage": "ai-trainer [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Model Management", "commands": [ { "name": "export", "description": "Export model embeddings and metadata to JSON file", "usage": "ai-trainer export --output [--format ]", "options": [], "requires_sudo": false, "examples": [ "ai-trainer export --output model_export.json" ] }, { "name": "snapshot", "description": "Save current model as versioned snapshot", "usage": "ai-trainer snapshot --snapshot-version ", "options": [], "requires_sudo": false, "examples": [ "ai-trainer snapshot --snapshot-version 1.0.0", "ai-trainer snapshot -s 1.1.0-beta" ] }, { "name": "list-snapshots", "description": "List all saved model snapshots", "usage": "ai-trainer list-snapshots", "options": [], "requires_sudo": false, "examples": [ "ai-trainer list-snapshots" ] }, { "name": "status", "description": "Display current model status and statistics", "usage": "ai-trainer status", "options": [], "requires_sudo": false, "examples": [ "ai-trainer status" ] }, { "name": "download-model", "description": "Download ONNX model, tokenizer, or GGUF model for AI engine tiers", "usage": "ai-trainer download-model [--llm [default|small|large]] [--show-models] [--all] [--output-dir ] [--force]", "options": [], "requires_sudo": false, "examples": [ "ai-trainer download-model", "ai-trainer download-model --llm", "ai-trainer download-model --llm small", "ai-trainer download-model --all", "ai-trainer download-model --show-models", "ai-trainer download-model --force" ] } ] }, { "category": "Model Training", "commands": [ { "name": "train", "description": "Train AI model from command metadata (full retraining)", "usage": "ai-trainer train --data [--database ]", "options": [], "requires_sudo": false, "examples": [ "ai-trainer train --data commands.json", "ai-trainer train --data commands.json --json" ] }, { "name": "incremental", "description": "Update model incrementally with new command data", "usage": "ai-trainer incremental --new-data [--database ]", "options": [], "requires_sudo": false, "examples": [ "ai-trainer incremental --new-data new_commands.json" ] } ] }, { "category": "Validation & Testing", "commands": [ { "name": "validate", "description": "Validate model accuracy against test dataset", "usage": "ai-trainer validate --test-data [--threshold ]", "options": [], "requires_sudo": false, "examples": [ "ai-trainer validate --test-data test_cases.json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" }, { "flag": "--timeout ", "description": "Set timeout (default: 30)" }, { "flag": "--retry ", "description": "Retry attempts (default: 3)" } ], "environmentVariables": [ { "name": "RUST_LOG", "description": "Set logging level", "default": "info", "values": "error|warn|info|debug|trace" }, { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "4": "Network error", "5": "File not found", "1": "General error", "2": "Invalid arguments", "3": "Permission denied" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } }, "flag_e": { "status": "success", "timestamp": "2026-04-02T13:42:17.856064736Z", "command": "examples", "version": "9.0.1", "data": { "name": "ai-trainer", "description": "Usage examples for ai-trainer", "categories": [ { "id": "1_model_training", "title": "Model Training", "description": "Full model training operations", "examples": [ { "command": "sudo ai-trainer train --data commands.json", "description": "Train model with command data", "expectedOutput": "Training statistics and embeddings metrics", "notes": "Creates new model from scratch" }, { "command": "sudo ai-trainer train --data commands.json --database custom.db", "description": "Train with custom database", "expectedOutput": "Training results with custom DB location", "notes": "Allows custom database path specification" }, { "command": "sudo ai-trainer train --data commands.json --json", "description": "Train and output results as JSON", "expectedOutput": "JSON-formatted training metrics", "notes": "Structured output for automation" } ] }, { "id": "2_incremental_training", "title": "Incremental Training", "description": "Update existing models with new data", "examples": [ { "command": "sudo ai-trainer incremental --new-data updates.json", "description": "Incrementally train with new data", "expectedOutput": "New embeddings added to existing model", "notes": "Requires existing trained model" }, { "command": "sudo ai-trainer incremental --new-data updates.json --database custom.db --json", "description": "Incremental training with custom DB and JSON output", "expectedOutput": "JSON-formatted incremental training results", "notes": "Combines custom DB path with structured output" } ] }, { "id": "3_validation", "title": "Validation", "description": "Model accuracy testing and validation", "examples": [ { "command": "sudo ai-trainer validate --test-data test_commands.json", "description": "Validate model with test data", "expectedOutput": "Validation results with accuracy metrics", "notes": "Tests model against known test cases" }, { "command": "sudo ai-trainer validate --test-data test_commands.json --threshold 0.90", "description": "Validate with custom accuracy threshold", "expectedOutput": "Pass/fail validation with 90% threshold", "notes": "Default threshold is 0.85" }, { "command": "sudo ai-trainer validate --test-data test_commands.json --database custom.db --json", "description": "Validate with custom DB and JSON output", "expectedOutput": "JSON-formatted validation metrics", "notes": "Structured validation results" }, { "command": "sudo ai-trainer validate --test-data tests.json --threshold 0.90 --database custom.db --json", "description": "Validate with all parameters combined", "expectedOutput": "JSON validation with custom test data, 90% threshold, and custom DB", "notes": "Full parameter example for CI/CD pipelines" } ] }, { "id": "4_model_export", "title": "Model Export", "description": "Export trained models and statistics", "examples": [ { "command": "sudo ai-trainer export --output model_export.json", "description": "Export trained model", "expectedOutput": "Complete model export with embeddings", "notes": "Default format includes all embeddings" }, { "command": "sudo ai-trainer export --output model_compact.json --format compact", "description": "Export in compact format", "expectedOutput": "Compact model export without full embeddings", "notes": "Reduces export file size" }, { "command": "sudo ai-trainer export --output model_stats.json --format stats --json", "description": "Export statistics as JSON", "expectedOutput": "Model statistics without embeddings", "notes": "Lightweight statistics export" }, { "command": "sudo ai-trainer export --output model.json --format full --json", "description": "Full export with JSON envelope output", "expectedOutput": "Complete model export with JSON status envelope", "notes": "Combines full embeddings export with structured output" } ] }, { "id": "5_snapshots", "title": "Snapshots", "description": "Model versioning and snapshot management", "examples": [ { "command": "sudo ai-trainer snapshot --snapshot-version 1.0.0", "description": "Create model snapshot with version", "expectedOutput": "Versioned snapshot created successfully", "notes": "Preserves model state at specific version" }, { "command": "sudo ai-trainer list-snapshots", "description": "List all model snapshots", "expectedOutput": "List of saved model versions", "notes": "Shows snapshot metadata and versions" }, { "command": "sudo ai-trainer list-snapshots --json", "description": "List snapshots as JSON", "expectedOutput": "JSON-formatted snapshot listing", "notes": "Structured snapshot information" }, { "command": "sudo ai-trainer snapshot --snapshot-version 1.0.0 --json", "description": "Create snapshot with JSON output", "expectedOutput": "JSON with snapshot name, version, and embedding count", "notes": "Structured output for automation" } ] }, { "id": "6_download", "title": "Model Download", "description": "Download ONNX and GGUF model files for AI engine tiers", "examples": [ { "command": "sudo ai-trainer download-model", "description": "Download ONNX embeddings model to default models/ directory", "expectedOutput": "Model files downloaded successfully", "notes": "Downloads all-MiniLM-L6-v2 ONNX model and tokenizer" }, { "command": "sudo ai-trainer download-model --llm", "description": "Download default GGUF model (Qwen2.5-3B-Instruct Q4_K_M, ~1.8GB)", "expectedOutput": "GGUF model downloaded to models/ directory", "notes": "Best balance of quality, speed, and size for CPU inference" }, { "command": "sudo ai-trainer download-model --llm small", "description": "Download small GGUF model (Qwen2.5-1.5B, ~0.9GB)", "expectedOutput": "Small GGUF model downloaded", "notes": "For systems with <4GB available RAM" }, { "command": "sudo ai-trainer download-model --llm large", "description": "Download large GGUF model (Phi-3.5-mini, ~2.3GB)", "expectedOutput": "Large GGUF model downloaded", "notes": "Better reasoning, 128K trained context" }, { "command": "sudo ai-trainer download-model --all", "description": "Download both ONNX embeddings and default GGUF model", "expectedOutput": "All model files downloaded", "notes": "Complete setup for all AI tiers" }, { "command": "sudo ai-trainer download-model --show-models", "description": "List downloaded and available models", "expectedOutput": "Model inventory with sizes and status", "notes": "Shows what's installed and what can be downloaded" }, { "command": "sudo ai-trainer download-model --show-models --json", "description": "Model inventory as JSON", "expectedOutput": "JSON with downloaded and available model details" }, { "command": "sudo ai-trainer download-model --force", "description": "Force re-download of ONNX model", "expectedOutput": "Model files re-downloaded", "notes": "Overwrites existing files" } ] }, { "id": "7_status", "title": "Status", "description": "Model status and health checks", "examples": [ { "command": "sudo ai-trainer status", "description": "Show training status", "expectedOutput": "Current model status and statistics", "notes": "Displays model readiness and metrics" }, { "command": "sudo ai-trainer status --json", "description": "Show training status as JSON", "expectedOutput": "JSON-formatted status information", "notes": "Structured status output for automation" } ] }, { "id": "8_ai_tiers", "title": "AI Tier Integration", "description": "Training operations related to the 6-tier AI engine (TF-IDF, ONNX, Mistral.rs, GenAI/Ollama, Legacy LLM, Claude)", "examples": [ { "command": "sudo ai-trainer validate --test-data tests.json --json", "description": "Validate model against all tier responses", "expectedOutput": "Validation results covering all active AI tiers", "notes": "Tests model accuracy across available tiers" }, { "command": "sudo ai-trainer train --data commands.json --json", "description": "Train model with feedback from all tiers", "expectedOutput": "Training metrics including multi-tier feedback data", "notes": "Includes feedback from mistral.rs and GenAI tier executions" } ] }, { "id": "9_intent_classifier", "title": "ONNX Intent Classifier", "description": "Evaluate the ONNX intent classifier used for fast-path routing (12 categories, <5ms inference)", "examples": [ { "command": "sudo ai-trainer validate --test-data intent_tests.json --json", "description": "Evaluate ONNX intent classifier accuracy", "expectedOutput": "JSON with per-intent precision, recall, and F1-score", "notes": "Target: 95%+ accuracy on held-out test set" }, { "command": "sudo ai-trainer download-model --show-models --json", "description": "Check if intent classifier model is downloaded", "expectedOutput": "JSON showing classifier model status", "notes": "Model: kodachi-intent-classifier.onnx (~65MB)" } ] } ], "quickReference": [ "sudo ai-trainer --help", "sudo ai-trainer --version", "sudo ai-trainer --info --json", "sudo ai-trainer --examples --json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" } } }, { "name": "permission-guard", "path": "/home/kodachi/k900/dashboard/hooks/permission-guard", "timestamp": "2026-04-02T13:42:18Z", "file_info": { "size": 1696992, "sha256": "e7d8291bbfd28744540f8e9ea5e23e836b6ad4fe54c202e3352df6c2a3bc8677" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "A robust permission management service for Kodachi OS that monitors and corrects file ownership to prevent root-owned files in user directories", "features": [ "Real-time file permission monitoring", "Automatic permission correction", "Configurable watch directories", "Pattern-based exclusions", "Daemon mode for background operation", "JSON and text output formats", "Field filtering and pagination", "Comprehensive error handling" ], "license": "Proprietary", "name": "permission-guard", "securityFeatures": { "authentication": "Integrates with system user permissions", "encryption": "Secure configuration storage", "inputValidation": "All paths and inputs are sanitized and validated", "rateLimiting": "Configurable scan intervals prevent resource exhaustion" }, "systemRequirements": { "dependencies": [ "systemd", "inotify support" ], "os": "Linux (Debian-based)", "privileges": "root/sudo" }, "version": "9.0.1", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.123215386Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2025-01-28T00:00:00Z", "gitCommit": "unknown", "name": "permission-guard", "rustVersion": "unknown", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.190765707Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Monitoring Commands", "commands": [ { "description": "Start continuous monitoring with auto-fix", "examples": [ "permission-guard watch /path/to/dir", "permission-guard watch /dir1 /dir2 --scan-interval 60", "permission-guard watch /path --json", "permission-guard watch /path --no-auto-fix --json" ], "name": "watch", "options": [ { "default": "true", "description": "Enable automatic fixing", "flag": "--auto-fix" }, { "description": "Disable automatic fixing", "flag": "--no-auto-fix" }, { "default": "30", "description": "Scan interval in seconds", "flag": "--scan-interval " }, { "default": "true", "description": "Enable recursive monitoring", "flag": "--recursive" }, { "description": "Disable recursive monitoring", "flag": "--no-recursive" } ], "requires_sudo": true, "usage": "permission-guard watch [OPTIONS] " }, { "description": "Perform one-time scan", "examples": [ "permission-guard scan /path/to/dir", "permission-guard scan /path/to/dir --dry-run", "permission-guard scan /path/to/dir --fix", "permission-guard scan /path --fix --json", "permission-guard scan /path --no-recursive" ], "name": "scan", "options": [ { "description": "Fix permissions automatically", "flag": "--fix" }, { "description": "Preview changes without applying", "flag": "--dry-run" }, { "default": "true", "description": "Enable recursive scanning", "flag": "--recursive" }, { "description": "Disable recursive scanning", "flag": "--no-recursive" } ], "requires_sudo": true, "usage": "permission-guard scan [OPTIONS] " } ] }, { "category": "Management Commands", "commands": [ { "description": "Show current status and configuration", "examples": [ "permission-guard status", "permission-guard status --detailed", "permission-guard status --json", "permission-guard status --detailed --json" ], "name": "status", "options": [ { "description": "Show detailed information", "flag": "--detailed" } ], "requires_sudo": false, "usage": "permission-guard status [OPTIONS]" }, { "description": "Manage configuration", "examples": [ "permission-guard config show", "permission-guard config show --json", "permission-guard config init", "permission-guard config set scan_interval 60", "permission-guard config add-watch /new/path", "permission-guard config remove-watch /old/path", "permission-guard config add-exclude /tmp", "permission-guard config remove-exclude /tmp", "permission-guard config add-pattern '*.log'", "permission-guard config remove-pattern '*.bak'" ], "name": "config", "options": [ { "description": "Display current embedded configuration", "flag": "show" }, { "description": "Show initialization info (config is embedded)", "flag": "init" }, { "description": "Set configuration value (read-only, use CLI args)", "flag": "set " }, { "description": "Add directory to watch list (read-only, use CLI args)", "flag": "add-watch " }, { "description": "Remove directory from watch list (read-only, use CLI args)", "flag": "remove-watch " }, { "description": "Add directory to exclude list (read-only, use CLI args)", "flag": "add-exclude " }, { "description": "Remove directory from exclude list (read-only, use CLI args)", "flag": "remove-exclude " }, { "description": "Add exclude pattern (read-only, built-in patterns optimized)", "flag": "add-pattern " }, { "description": "Remove exclude pattern (read-only, built-in patterns optimized)", "flag": "remove-pattern " } ], "requires_sudo": false, "usage": "permission-guard config " } ] } ], "description": "A robust permission management service for Kodachi OS", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "unset", "description": "HTTP proxy for network requests", "name": "HTTP_PROXY", "values": "http://proxy:port" }, { "default": "unset", "description": "HTTPS proxy for secure requests", "name": "HTTPS_PROXY", "values": "https://proxy:port" }, { "default": "~/.config/permission-guard/config.json", "description": "Path to configuration file", "name": "PERMISSION_GUARD_CONFIG", "values": "/path/to/config.json" } ], "exitCodes": { "0": "Success", "1": "General error", "10": "Command error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found", "6": "Timeout", "7": "Authentication error", "8": "Internal error", "9": "Validation error" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (default: text)", "flag": "-o, --output-format " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " }, { "description": "Use custom configuration file", "flag": "-c, --config " }, { "description": "Return only specified fields in JSON output", "flag": "--json-filter " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Select specific fields to include in output", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Override target user (username or UID)", "flag": "--user-override " }, { "description": "Run as daemon (background process)", "flag": "-d, --daemon" }, { "description": "Custom PID file location", "flag": "--pid-file " }, { "description": "Stop running daemon", "flag": "--stop-daemon" }, { "description": "Show daemon status", "flag": "--daemon-status" } ], "name": "permission-guard", "usage": "permission-guard [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.264265767Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Common operations", "examples": [ { "command": "sudo permission-guard watch /path/to/hooks", "description": "Start monitoring with auto-fix", "expectedOutput": "Starts continuous monitoring of the directory" }, { "command": "sudo permission-guard scan /path/to/dir --fix", "description": "One-time scan and fix", "expectedOutput": "Scans directory and fixes permission issues" }, { "command": "sudo permission-guard scan /path/to/dir --dry-run", "description": "Preview changes without applying", "expectedOutput": "Shows what would be changed without making modifications" }, { "command": "sudo permission-guard status --json", "description": "Get status in JSON format", "expectedOutput": "JSON response with current status" }, { "command": "sudo permission-guard status", "description": "Check current runtime status", "expectedOutput": "Shows current daemon status and active configuration" }, { "command": "sudo permission-guard --json", "description": "Default operation with JSON output", "expectedOutput": "JSON formatted help information" } ], "id": "1_basic_usage", "title": "Basic Usage" }, { "description": "Complex operations", "examples": [ { "command": "sudo permission-guard watch /hooks --scan-interval 30", "description": "Custom scan interval", "expectedOutput": "Monitors directory with 30 second scan interval" }, { "command": "sudo permission-guard watch /dir1 /dir2 --scan-interval 60", "description": "Monitor multiple directories with custom interval", "expectedOutput": "Monitors both directories, scanning every 60 seconds", "notes": "Useful for less frequently changing directories" }, { "command": "sudo permission-guard scan /dir1 /dir2 --fix", "description": "Scan multiple directories", "expectedOutput": "Scans and fixes permissions in multiple directories" }, { "command": "sudo permission-guard --user-override myuser scan /path --fix", "description": "Override target user", "expectedOutput": "Scans and fixes permissions for specific user" }, { "command": "sudo permission-guard scan /path/to/dir --no-recursive", "description": "Non-recursive scan", "expectedOutput": "Scans only the specified directory, not subdirectories" }, { "command": "sudo permission-guard watch /path --no-auto-fix", "description": "Watch without auto-fix", "expectedOutput": "Monitors directory but doesn't automatically fix permissions" }, { "command": "sudo permission-guard --daemon watch /hooks", "description": "Run as background daemon", "expectedOutput": "Starts daemon process and returns", "notes": "Use --daemon-status to check if running" } ], "id": "2_advanced_usage", "title": "Advanced Usage" }, { "description": "Debug and error handling", "examples": [ { "command": "sudo permission-guard --verbose scan /path --dry-run", "description": "Preview changes with verbose output", "expectedOutput": "Detailed scan results without making changes", "notes": "Use to understand what would be changed" }, { "command": "sudo permission-guard --daemon-status", "description": "Check daemon status", "expectedOutput": "Shows if daemon is running and its PID" }, { "command": "sudo permission-guard --timeout 60 scan /large/dir --fix", "description": "Scan with extended timeout", "expectedOutput": "Scans large directory with 60 second timeout", "notes": "Useful for large directory structures" } ], "id": "3_troubleshooting", "title": "Troubleshooting" }, { "description": "Using JSON format for automation", "examples": [ { "command": "sudo permission-guard --json status", "description": "Runtime status in JSON format", "expectedOutput": "JSON response with current runtime status and active configuration" }, { "command": "sudo permission-guard --json config show", "description": "Embedded config template in JSON", "expectedOutput": "JSON formatted embedded configuration defaults and constraints", "notes": "Shows embedded defaults, not runtime configuration" }, { "command": "sudo permission-guard --json scan /path --dry-run", "description": "Scan results in JSON", "expectedOutput": "JSON array of permission issues found", "notes": "Dry-run shows what would be changed" }, { "command": "sudo permission-guard --json scan /path --fix", "description": "Fix permissions with JSON output", "expectedOutput": "JSON response with fix results" }, { "command": "sudo permission-guard --json watch /path", "description": "Watch with JSON logging (no terminal output)", "expectedOutput": "JSON events written to stdout", "notes": "Useful for piping to log processors" }, { "command": "sudo permission-guard --json status --detailed", "description": "Detailed runtime status in JSON", "expectedOutput": "Comprehensive JSON with runtime status, active config, and system info", "notes": "Shows actual runtime state, not embedded defaults" }, { "command": "sudo permission-guard --json --user-override myuser scan /path", "description": "Override user with JSON", "expectedOutput": "JSON scan results with custom user", "notes": "Useful for multi-user systems" }, { "command": "sudo permission-guard --json-pretty --fields scan_results,configuration scan /path --fix", "description": "Pretty JSON with field filtering", "expectedOutput": "Formatted JSON with only specified fields", "notes": "Use --fields to limit output to relevant data" }, { "command": "sudo permission-guard --json-filter files_scanned,files_corrected scan /path --fix", "description": "Filter JSON output fields", "expectedOutput": "JSON with only files_scanned and files_corrected fields", "notes": "Reduces output size for automated processing" }, { "command": "sudo permission-guard --json --limit 10 --offset 5 status", "description": "Paginated JSON output", "expectedOutput": "JSON response with pagination (skip 5, return 10)", "notes": "Useful for large result sets" } ], "id": "4_json_output", "title": "JSON Output Examples" }, { "description": "Managing service configuration", "examples": [ { "command": "sudo permission-guard config show", "description": "Display embedded configuration template", "expectedOutput": "Shows embedded configuration defaults and security constraints", "notes": "Use 'status --detailed' to see runtime configuration" } ], "id": "5_configuration_management", "title": "Configuration Management" }, { "description": "Running as background service", "examples": [ { "command": "sudo permission-guard --daemon watch /hooks", "description": "Start as background daemon", "expectedOutput": "Starts daemon process and returns control", "notes": "Use --daemon-status to check if running" }, { "command": "sudo permission-guard --daemon-status", "description": "Check if daemon is running", "expectedOutput": "Shows daemon status and PID if running" }, { "command": "sudo permission-guard --daemon-status --json", "description": "Daemon status in JSON format", "expectedOutput": "JSON response with daemon status, PID, and PID file location", "notes": "Useful for automated monitoring scripts" }, { "command": "sudo permission-guard --stop-daemon", "description": "Stop running daemon", "expectedOutput": "Stops the background daemon process" }, { "command": "sudo permission-guard --stop-daemon --json", "description": "Stop daemon with JSON response", "expectedOutput": "JSON confirmation of daemon stop operation" }, { "command": "sudo permission-guard --daemon --pid-file /custom/path.pid watch", "description": "Custom PID file", "expectedOutput": "Daemon with custom PID file location", "notes": "Useful for multiple instances" }, { "command": "sudo permission-guard --daemon scan /path --fix", "description": "Daemon mode for one-time scan", "expectedOutput": "Runs scan in background and keeps daemon alive", "notes": "Daemon stays running after command completion" }, { "command": "sudo permission-guard --daemon --pid-file /var/run/pg-instance1.pid watch /path1", "description": "Multiple daemon instances", "expectedOutput": "First daemon instance with unique PID file", "notes": "Run multiple instances by using different PID files" }, { "command": "sudo permission-guard --daemon-status --pid-file /var/run/pg-instance1.pid", "description": "Check specific daemon instance", "expectedOutput": "Status of daemon using specified PID file" }, { "command": "sudo permission-guard --stop-daemon --pid-file /var/run/pg-instance1.pid", "description": "Stop specific daemon instance", "expectedOutput": "Stops daemon using specified PID file" } ], "id": "6_daemon_operations", "title": "Daemon Operations" }, { "description": "Using advanced CLI features and error handling", "examples": [ { "command": "sudo permission-guard --timeout 120 --retry 5 scan /large/dir --fix", "description": "Extended timeout with retry attempts", "expectedOutput": "Scan with 120s timeout and up to 5 retry attempts", "notes": "Useful for unreliable environments or large directories" }, { "command": "sudo permission-guard --verbose --no-color scan /path --dry-run", "description": "Verbose output without colors", "expectedOutput": "Detailed scan information in plain text", "notes": "Good for logging to files or piping to other tools" }, { "command": "sudo permission-guard --quiet --json status", "description": "Minimal output with JSON", "expectedOutput": "JSON status without extra logging messages", "notes": "Reduces noise for automated processing" }, { "command": "sudo permission-guard --user-override 1001 scan /path --fix", "description": "Override with numeric UID", "expectedOutput": "Scans and fixes permissions for user ID 1001", "notes": "Useful when username is not available" }, { "command": "sudo permission-guard --user-override nonexistent scan /path", "description": "Invalid user override handling", "expectedOutput": "Error response: User 'nonexistent' not found", "notes": "Shows input validation in action" }, { "command": "sudo permission-guard watch /invalid/path/that/does/not/exist", "description": "Path validation example", "expectedOutput": "Error response about invalid or unsafe path", "notes": "Demonstrates security path validation" }, { "command": "sudo permission-guard --output-format json status", "description": "Explicit JSON output format", "expectedOutput": "Status in JSON format (same as --json)", "notes": "Alternative way to specify JSON output" } ], "id": "7_advanced_options", "title": "Advanced Options and Validation" } ], "description": "Usage examples for permission-guard", "name": "permission-guard", "quickReference": [ "sudo permission-guard --help", "sudo permission-guard --version", "sudo permission-guard --info --json", "sudo permission-guard --examples --json", "sudo permission-guard watch /path", "sudo permission-guard scan /path --fix", "sudo permission-guard status", "sudo permission-guard config show", "sudo permission-guard --daemon-status", "sudo permission-guard --stop-daemon" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.394671572Z", "version": "9.0.1", "warnings": [] } }, { "name": "routing-switch", "path": "/home/kodachi/k900/dashboard/hooks/routing-switch", "timestamp": "2026-04-02T13:42:18Z", "file_info": { "size": 8340896, "sha256": "f510f5f3388c466db78087701445d50a3d19440d77d19aeeed8d36f4c7650f77" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "configuration": "Uses online-auth get-card for paid VPN credentials; VPNGate servers are free and require no authentication", "connection_limit": "One active connection at a time", "copyright": "© 2026 Linux Kodachi", "description": "System-wide traffic routing through various proxy protocols", "features": [ "System-wide traffic routing through proxy protocols", "Support for OpenVPN, WireGuard, and Dante SOCKS5", "Support for Tor, Shadowsocks, V2Ray, and Xray protocols", "Support for Mieru/Mita and Hysteria2 protocols", "Automatic protocol scoring and selection", "DNS leak prevention with multiple modes", "Metric-based and direct routing options", "External configuration file support", "IPv4/IPv6 dual-stack support", "QR code generation for mobile clients", "VPNGate free VPN integration (100+ public servers, no auth required)", "Comprehensive logging and monitoring" ], "license": "Proprietary", "name": "routing-switch", "security_features": [ "Input validation: All inputs are validated and sanitized", "Rate limiting: Built-in rate limiting for network operations", "Authentication: Secure authentication with certificate pinning", "Encryption: TLS 1.3 for all network communications", "Kill switch: Direct routing mode prevents leaks on failure", "DNS protection: Multiple DNS modes to prevent leaks" ], "state_file": "./results/routing-switch-state.json", "supported_protocols": [ "OpenVPN", "WireGuard", "Dante", "Tor", "Shadowsocks", "V2Ray", "Xray-VLESS", "Xray-VLESS-Reality", "Xray-Trojan", "Xray-VMess", "Mita/Mieru", "Hysteria2", "VPNGate (free public servers)" ], "system_requirements": { "dependencies": "OpenSSL, libcurl, tun2socks (for most protocols), redsocks (for Tor)", "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.0.1", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.694632105Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T13:42:18.759667673Z", "gitCommit": "unknown", "name": "routing-switch", "rustVersion": "1.70.0", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.759674786Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "CONNECTION COMMANDS", "commands": [ { "description": "Connect to a proxy protocol (openvpn, wireguard use native routing; tor uses redsocks; dante, shadowsocks, v2ray, xray-*, mita use tun2socks)", "name": "connect", "options": [], "requires_sudo": true, "usage": "routing-switch connect [OPTIONS]" }, { "description": "Disconnect current proxy connection", "name": "disconnect", "options": [], "requires_sudo": true, "usage": "routing-switch disconnect [OPTIONS]" }, { "description": "Show current connection status", "name": "status", "options": [], "requires_sudo": false, "usage": "routing-switch status [OPTIONS]" } ] }, { "category": "INFORMATION COMMANDS", "commands": [ { "description": "Display current DNS server information", "name": "dns-info", "options": [], "requires_sudo": false, "usage": "routing-switch dns-info [OPTIONS]" }, { "description": "List available protocols with scores", "name": "list-protocols", "options": [], "requires_sudo": false, "usage": "routing-switch list-protocols [OPTIONS]" } ] }, { "category": "TESTING COMMANDS", "commands": [ { "description": "Test a specific protocol connectivity", "name": "test-protocol", "options": [], "requires_sudo": false, "usage": "routing-switch test-protocol [OPTIONS]" }, { "description": "Benchmark all available protocols", "name": "benchmark", "options": [], "requires_sudo": false, "usage": "routing-switch benchmark [OPTIONS]" } ] }, { "category": "CONFIGURATION COMMANDS", "commands": [ { "description": "Export protocol configurations to files", "name": "export-config", "options": [], "requires_sudo": false, "usage": "routing-switch export-config [PROTOCOL] [OPTIONS]" }, { "description": "Show protocol configuration", "name": "showconfig", "options": [], "requires_sudo": false, "usage": "routing-switch showconfig [PROTOCOL] [OPTIONS]" }, { "description": "Show protocol configuration as URL", "name": "showconfigurl", "options": [], "requires_sudo": false, "usage": "routing-switch showconfigurl [PROTOCOL] [OPTIONS]" }, { "description": "Show protocol configuration as QR code", "name": "showconfigqr", "options": [], "requires_sudo": false, "usage": "routing-switch showconfigqr [PROTOCOL] [OPTIONS]" } ] }, { "category": "MANAGEMENT COMMANDS", "commands": [ { "description": "Auto-select and connect to best protocol", "name": "auto-select", "options": [], "requires_sudo": true, "usage": "routing-switch auto-select [OPTIONS]" }, { "description": "Reset all routing to default state", "name": "reset", "options": [], "requires_sudo": true, "usage": "routing-switch reset [OPTIONS]" }, { "description": "Clean up orphaned processes and resources", "name": "cleanup", "options": [], "requires_sudo": true, "usage": "routing-switch cleanup [OPTIONS]" }, { "description": "Recover from partial failure state", "name": "recover", "options": [], "requires_sudo": true, "usage": "routing-switch recover [OPTIONS]" } ] }, { "category": "MICROSOCKS SERVER MANAGEMENT", "commands": [ { "description": "Enable microsocks SOCKS5 server for other devices", "name": "microsocks-enable", "options": [], "requires_sudo": true, "usage": "routing-switch microsocks-enable -u USERNAME -p PASSWORD [--port PORT]" }, { "description": "Disable microsocks SOCKS5 server", "name": "microsocks-disable", "options": [], "requires_sudo": true, "usage": "routing-switch microsocks-disable" }, { "description": "Show microsocks server status", "name": "microsocks-status", "options": [], "requires_sudo": false, "usage": "routing-switch microsocks-status [OPTIONS]" } ] }, { "category": "VPNGATE FREE VPN", "commands": [ { "description": "Fetch VPNGate free public VPN server list", "name": "vpngate-fetch", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-fetch [OPTIONS]" }, { "description": "List cached VPNGate servers with filtering and sorting", "name": "vpngate-list", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-list [OPTIONS]" }, { "description": "Connect to a VPNGate free VPN server by index (no auth required)", "name": "vpngate-connect", "options": [], "requires_sudo": true, "usage": "sudo routing-switch vpngate-connect [OPTIONS]" }, { "description": "Export a VPNGate server's OpenVPN config as .ovpn file", "name": "vpngate-export", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-export [OPTIONS]" }, { "description": "Export all cached VPNGate servers as .ovpn files", "name": "vpngate-export-all", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-export-all [OPTIONS]" } ] } ], "description": "System-wide traffic routing through various proxy protocols", "environmentVariables": [ { "default": "info", "description": "Set logging level (default: info)", "name": "RUST_LOG", "values": "error, warn, info, debug, trace" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" } ], "name": "routing-switch", "usage": "routing-switch [OPTIONS] " }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.826571051Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Connect to various proxy protocols", "examples": [ { "command": "sudo routing-switch connect openvpn", "description": "Connect via OpenVPN", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Requires OpenVPN configuration in auth card" }, { "command": "sudo routing-switch connect wireguard", "description": "Connect via WireGuard", "expectedOutput": "Successfully connected to WireGuard server", "notes": "Ultra-fast, modern VPN protocol" }, { "command": "sudo routing-switch connect dante", "description": "Connect via Dante SOCKS5 proxy", "expectedOutput": "Successfully connected to Dante server" }, { "command": "sudo routing-switch connect tor", "description": "Route ALL traffic through Tor network (uses redsocks)", "expectedOutput": "Successfully routing traffic through Tor", "notes": "Maximum anonymity, slower speeds. Uses redsocks for stability instead of tun2socks" }, { "command": "sudo routing-switch connect shadowsocks", "description": "Connect via Shadowsocks", "expectedOutput": "Successfully connected to Shadowsocks server", "notes": "Optimized for bypassing censorship" }, { "command": "sudo routing-switch connect v2ray", "description": "Connect via V2Ray VMess", "expectedOutput": "Successfully connected to V2Ray server" }, { "command": "sudo routing-switch connect xray-vless", "description": "Connect via Xray VLESS TLS", "expectedOutput": "Successfully connected to Xray VLESS server", "notes": "Lightweight, fast protocol with TLS" }, { "command": "sudo routing-switch connect xray-vless-reality", "description": "Connect via Xray VLESS Reality", "expectedOutput": "Successfully connected to Xray VLESS Reality server", "notes": "Most advanced censorship resistance" }, { "command": "sudo routing-switch connect xray-trojan", "description": "Connect via Xray Trojan", "expectedOutput": "Successfully connected to Xray Trojan server", "notes": "Mimics HTTPS traffic" }, { "command": "sudo routing-switch connect xray-vmess", "description": "Connect via Xray VMess", "expectedOutput": "Successfully connected to Xray VMess server" }, { "command": "sudo routing-switch connect mita", "description": "Connect via Mieru/Mita protocol", "expectedOutput": "Successfully connected to Mita server", "notes": "Anti-censorship protocol" }, { "command": "sudo routing-switch connect hysteria2", "description": "Connect via Hysteria2 protocol", "expectedOutput": "Successfully connected to Hysteria2 server", "notes": "UDP-based, high-performance anti-censorship protocol" } ], "id": "basic_connections", "title": "BASIC CONNECTIONS" }, { "description": "Connect using external configuration files instead of auth card", "examples": [ { "command": "sudo routing-switch connect openvpn --config /home/user/vpn.ovpn", "description": "Connect using external OpenVPN config file", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Supports standard .ovpn configuration files" }, { "command": "sudo routing-switch connect wireguard --config /path/to/wg0.conf", "description": "Connect using external WireGuard config", "expectedOutput": "Successfully connected to WireGuard server", "notes": "Uses standard WireGuard .conf format" }, { "command": "sudo routing-switch connect shadowsocks --config /path/to/ss-config.json", "description": "Connect using Shadowsocks JSON config", "expectedOutput": "Successfully connected to Shadowsocks server", "notes": "Standard Shadowsocks JSON format with server, port, password, method" }, { "command": "sudo routing-switch connect v2ray --config /path/to/v2ray-config.json", "description": "Connect using V2Ray JSON config", "expectedOutput": "Successfully connected to V2Ray server", "notes": "Full V2Ray JSON configuration with inbounds/outbounds" }, { "command": "sudo routing-switch connect xray-vless --config /path/to/xray.json", "description": "Connect using Xray config file", "expectedOutput": "Successfully connected to Xray VLESS server", "notes": "Xray JSON config format similar to V2Ray" }, { "command": "sudo routing-switch connect openvpn --config ./vpn.ovpn --force", "description": "Force connection with external config", "expectedOutput": "Disconnecting existing... Connected via external config", "notes": "Combines --config with other flags like --force" }, { "command": "sudo routing-switch connect shadowsocks --config ~/configs/ss.json --no-tun", "description": "External config in no-TUN mode", "expectedOutput": "Shadowsocks SOCKS5 proxy ready at localhost:30000", "notes": "Use external config for manual proxy setup" } ], "id": "external_config", "title": "EXTERNAL CONFIGURATION FILES" }, { "description": "Explicitly choose IPv4 or IPv6 connections", "examples": [ { "command": "sudo routing-switch connect dante --ipv4", "description": "Force IPv4 connection to Dante", "expectedOutput": "Connected via IPv4" }, { "command": "sudo routing-switch connect dante --ipv6", "description": "Force IPv6 connection to Dante", "expectedOutput": "Connected via IPv6", "notes": "Requires IPv6 support" }, { "command": "sudo routing-switch connect shadowsocks --ipv4", "description": "Connect Shadowsocks over IPv4", "expectedOutput": "Shadowsocks connected via IPv4" }, { "command": "sudo routing-switch connect tor --ipv6", "description": "Connect Tor over IPv6", "expectedOutput": "Tor connected via IPv6" }, { "command": "sudo routing-switch connect xray-vless --ipv6", "description": "Use IPv6 for Xray VLESS", "expectedOutput": "Xray VLESS connected via IPv6" }, { "command": "sudo routing-switch connect hysteria2 --ipv4", "description": "Connect Hysteria2 over IPv4", "expectedOutput": "Hysteria2 connected via IPv4" }, { "command": "sudo routing-switch connect hysteria2 --ipv6", "description": "Connect Hysteria2 over IPv6", "expectedOutput": "Hysteria2 connected via IPv6", "notes": "Requires IPv6 support" } ], "id": "ip_version", "title": "IPV4/IPV6 SELECTION" }, { "description": "Check and manage network prerequisites for VPN connections", "examples": [ { "command": "sudo routing-switch check-prerequisites", "description": "Check and fix network prerequisites", "expectedOutput": "✓ IPv4 forwarding: Already enabled (correct)\n✗→✓ NAT MASQUERADE: Fixed", "notes": "Fixes only what's wrong, preserves correct settings" }, { "command": "sudo routing-switch check-prerequisites --ipv6", "description": "Check prerequisites for IPv6 connections", "expectedOutput": "✓ IPv6 forwarding: Enabled", "notes": "Only enables IPv6 if system supports it" }, { "command": "sudo routing-switch check-prerequisites --json", "description": "Get prerequisites status in JSON format", "expectedOutput": "{\"prerequisites\": {\"checks\": [...], \"ready\": true}}" }, { "command": "sudo routing-switch connect shadowsocks", "description": "Connect with automatic prerequisites check", "expectedOutput": "Checking network prerequisites...\n✓ All checks passed\n\nConnecting to shadowsocks...", "notes": "Prerequisites are checked by default" }, { "command": "sudo routing-switch connect shadowsocks --skip-prerequisites", "description": "Connect without prerequisites check", "expectedOutput": "Connecting to shadowsocks...", "notes": "Skips prerequisites for backward compatibility" }, { "command": "sudo routing-switch connect wireguard --force", "description": "Force reconnection with prerequisites check", "expectedOutput": "Checking network prerequisites...\nForcing new connection...", "notes": "Prerequisites persist after disconnect for other VPN tools" } ], "id": "prerequisites", "title": "NETWORK PREREQUISITES" }, { "description": "Check and monitor connection status", "examples": [ { "command": "sudo routing-switch status", "description": "Show current connection status", "expectedOutput": "Protocol: wireguard, Status: Connected", "notes": "Requires sudo for accurate results (reads privileged system state)" }, { "command": "sudo routing-switch status --json", "description": "Get status in JSON format", "expectedOutput": "{\"protocol\": \"wireguard\", \"status\": \"connected\"}" }, { "command": "sudo routing-switch status --json-pretty", "description": "Pretty-printed JSON status", "expectedOutput": "Formatted JSON with connection details" }, { "command": "sudo routing-switch status --json-human", "description": "Human-readable JSON status", "expectedOutput": "Enhanced JSON output with descriptions" } ], "id": "status", "title": "CONNECTION STATUS" }, { "description": "Control DNS routing for security and compatibility (DEFAULT: auto mode)", "examples": [ { "command": "sudo routing-switch connect wireguard", "description": "DEFAULT: Auto mode (no special DNS routing)", "expectedOutput": "DNS handled naturally through tunnel", "notes": "DEFAULT safe mode - DNS flows through tunnel like all traffic. Note: May not work with all protocols" }, { "command": "sudo routing-switch connect wireguard --dns-mode hybrid", "description": "Hybrid mode: VPN server DNS bypasses tunnel", "expectedOutput": "Using hybrid DNS mode: VPN server DNS bypasses, others through tunnel", "notes": "⚠️ WARNING: May cause internet loss! Use 'sudo routing-switch recover' to restore connectivity. Good balance of security and reliability for home/office use when you need LAN access" }, { "command": "sudo routing-switch connect wireguard --dns-mode strict", "description": "Strict mode: ALL DNS through tunnel", "expectedOutput": "Using strict DNS mode: Maximum security", "notes": "Most secure, may fail if VPN server uses hostname" }, { "command": "sudo routing-switch connect wireguard --dns-mode system", "description": "System mode: DNS bypasses tunnel", "expectedOutput": "WARNING: System DNS mode - DNS queries will leak!", "notes": "⚠️ NOT SECURE - DNS leaks! Use only for debugging" }, { "command": "sudo routing-switch connect wireguard --exclude-private", "description": "Exclude private networks from VPN", "expectedOutput": "Private networks will bypass VPN tunnel", "notes": "Keep LAN access while using VPN" }, { "command": "sudo routing-switch connect wireguard --dns-mode hybrid --exclude-private", "description": "Hybrid DNS with private network exclusion", "expectedOutput": "Using hybrid DNS mode with local network access", "notes": "Good for home/office use when you need LAN access" } ], "id": "dns_modes", "title": "DNS MODES AND SECURITY" }, { "description": "Choose between Direct (secure) or Metric (with fallback) routing", "examples": [ { "command": "sudo routing-switch connect tor", "description": "DEFAULT: Direct routing mode (MOST SECURE)", "expectedOutput": "Using DIRECT routing: Traffic goes ONLY through TUN, no fallback", "notes": "✅ RECOMMENDED - Acts as kill switch, no leaks if VPN fails" }, { "command": "sudo routing-switch connect tor --metric", "description": "Metric routing mode (LESS SECURE, has fallback)", "expectedOutput": "Using METRIC routing: Original route kept as backup", "notes": "⚠️ WARNING: Can leak traffic if TUN fails! Use only if you need failover" }, { "command": "sudo routing-switch connect shadowsocks", "description": "Direct mode for Shadowsocks (default)", "expectedOutput": "Direct routing: No internet if Shadowsocks stops", "notes": "Perfect privacy - connection drops if proxy fails" }, { "command": "sudo routing-switch connect dante --metric", "description": "Metric mode for corporate VPN scenarios", "expectedOutput": "Metric routing: Fallback to original connection if VPN drops", "notes": "Use for work VPNs where you need automatic failover" }, { "command": "sudo routing-switch connect xray-vless --metric --exclude-private", "description": "Metric mode with LAN access preserved", "expectedOutput": "Failover routing with local network bypass", "notes": "Corporate setup: VPN with failover + LAN access" } ], "id": "routing_modes", "title": "ROUTING MODES - SECURITY vs FAILOVER" }, { "description": "Disconnect and restore normal routing", "examples": [ { "command": "sudo routing-switch disconnect", "description": "Disconnect current proxy", "expectedOutput": "Successfully disconnected" }, { "command": "sudo routing-switch disconnect --force", "description": "Force disconnect even if issues", "expectedOutput": "Force disconnected", "notes": "Kills all processes forcefully" }, { "command": "sudo routing-switch disconnect --clean-firewall", "description": "Disconnect and clean all firewall rules", "expectedOutput": "Disconnected and firewall rules cleaned", "notes": "Use when network is stuck after disconnect due to lingering iptables rules" }, { "command": "sudo routing-switch disconnect --force --clean-firewall", "description": "Force disconnect with complete firewall cleanup", "expectedOutput": "Force disconnected, all firewall rules flushed", "notes": "Emergency recovery - resets all iptables rules (preserves Docker/KVM chains)" }, { "command": "sudo routing-switch disconnect --json", "description": "Disconnect with JSON output", "expectedOutput": "{\"status\": \"disconnected\"}" } ], "id": "disconnect", "title": "DISCONNECTION" }, { "description": "Understanding --force behavior and which protocols can layer together", "examples": [ { "command": "sudo routing-switch connect wireguard\n $ sudo routing-switch connect tor --force", "description": "Creates LAYERED connection: Tor-over-WireGuard ✓", "expectedOutput": "→ Traffic flows through BOTH protocols (double encryption)\n → WireGuard's wg0 interface remains active\n → Tor's iptables rules redirect traffic on top", "notes": "LAYERED: Both protocols remain active. Traffic: App → Tor (redsocks) → WireGuard → Internet" }, { "command": "sudo routing-switch connect openvpn\n $ sudo routing-switch connect tor --force", "description": "Creates LAYERED connection: Tor-over-OpenVPN ✓", "expectedOutput": "→ Traffic: Your App → Tor (redsocks) → OpenVPN (tun0) → Internet\n → Both protocols active simultaneously", "notes": "Works because Tor uses iptables NAT, no interface conflict with OpenVPN's tun0" }, { "command": "sudo routing-switch connect shadowsocks\n $ sudo routing-switch connect dante --force", "description": "FAILS: Interface conflict ✗", "expectedOutput": "→ ERROR: Both protocols need the same tun_routing interface\n → Cannot have two tun2socks instances\n → Must disconnect first", "notes": "All tun2socks protocols (shadowsocks, dante, v2ray, xray-*, mita, hysteria2) share the same TUN device" }, { "command": "sudo routing-switch connect shadowsocks\n $ sudo routing-switch connect tor --force", "description": "May create complex routing (untested)", "expectedOutput": "→ Shadowsocks tun_routing remains\n → Tor adds iptables rules on top\n → Behavior depends on routing priorities", "notes": "Different architectures (tun2socks vs iptables) - may work but not recommended" }, { "command": "# PROTOCOL TYPES AND COMPATIBILITY:", "description": "Understanding protocol architectures", "expectedOutput": "→ Native VPNs (own interfaces): openvpn (tun0), wireguard (wg0)\n → Redsocks (iptables NAT): tor\n → Tun2socks (shared tun_routing): shadowsocks, dante, v2ray,\n xray-vless, xray-vless-reality, xray-trojan, xray-vmess,\n mita, hysteria2", "notes": "Compatible: Native+Tor. Incompatible: Any two tun2socks protocols" }, { "command": "# RECOMMENDED LAYERING:", "description": "Best practices for using --force", "expectedOutput": "→ ✓ WireGuard/OpenVPN first, then Tor --force for double VPN\n → ✗ Never layer two tun2socks protocols\n → Test connectivity after layering", "notes": "--force allows connection despite existing protocol, but compatibility depends on architecture" } ], "id": "force_reconnect", "title": "FORCE FLAG & PROTOCOL COMPATIBILITY" }, { "description": "Check DNS configuration", "examples": [ { "command": "routing-switch dns-info", "description": "Show current DNS servers", "expectedOutput": "IPv4: :53, IPv6: []:53" }, { "command": "routing-switch dns-info --json", "description": "DNS info in JSON format", "expectedOutput": "{\"ipv4\": {\"host\": \"\", \"port\": 53}}" } ], "id": "dns_info", "title": "DNS INFORMATION" }, { "description": "Check Tor DNS and SOCKS configuration", "examples": [ { "command": "routing-switch tor-dns-info", "description": "Show Tor DNS and SOCKS endpoints", "expectedOutput": "DNS: dns://:9054#Tor-DNS", "notes": "Resolves both regular and .onion domains" }, { "command": "routing-switch tor-dns-info --json", "description": "Tor DNS info in JSON format", "expectedOutput": "{\"ipv4\": {\"dns_url\": \"dns://...\", \"socks_url\": \"socks5://...\"}}" } ], "id": "tor_dns_info", "title": "TOR DNS INFORMATION" }, { "description": "Display VPS server details and statistics", "examples": [ { "command": "routing-switch vps-info", "description": "Show basic VPS information", "expectedOutput": "Hostname: -, IPv4: " }, { "command": "routing-switch vps-info --detailed", "description": "Show detailed VPS stats", "expectedOutput": "CPU Load, Memory Usage, Uptime, Network Connections", "notes": "Includes CPU load, memory, uptime, and connection stats" }, { "command": "routing-switch vps-info --json", "description": "VPS info in JSON format", "expectedOutput": "{\"hostname\": \"...\", \"cpu_load\": {...}, \"memory\": {...}}" } ], "id": "vps_info", "title": "VPS SERVER INFORMATION" }, { "description": "List available protocols with scores", "examples": [ { "command": "routing-switch list-protocols", "description": "List all available protocols", "expectedOutput": "WireGuard (Score: 96.5), OpenVPN (Score: 94.0)..." }, { "command": "routing-switch list-protocols --json", "description": "Protocol list in JSON", "expectedOutput": "[{\"name\": \"wireguard\", \"score\": 96.5}]" }, { "command": "routing-switch list-protocols --available-only", "description": "Show only available protocols", "expectedOutput": "Available: WireGuard, Tor, Shadowsocks", "notes": "Based on auth card" }, { "command": "routing-switch list-protocols --sort-by-security", "description": "Sort by security score", "expectedOutput": "1. WireGuard (98.0), 2. OpenVPN (95.0)..." }, { "command": "routing-switch list-protocols --sort-by-speed", "description": "Sort by speed score", "expectedOutput": "1. WireGuard (99.0), 2. Shadowsocks (85.0)..." } ], "id": "list_protocols", "title": "PROTOCOL LISTING" }, { "description": "Automatically select best protocol", "examples": [ { "command": "sudo routing-switch auto-select", "description": "Auto-select best protocol", "expectedOutput": "Selected WireGuard (best overall score)" }, { "command": "sudo routing-switch auto-select --min-security 90", "description": "Auto-select with minimum security", "expectedOutput": "Selected OpenVPN (security: 95.0)" }, { "command": "sudo routing-switch auto-select --prefer-speed", "description": "Prioritize speed in selection", "expectedOutput": "Selected WireGuard (fastest protocol)" }, { "command": "sudo routing-switch auto-select --json", "description": "Auto-select with JSON output", "expectedOutput": "{\"selected\": \"wireguard\", \"reason\": \"best_score\"}" } ], "id": "auto_select", "title": "AUTO-SELECTION" }, { "description": "Local SOCKS5 port allocation reference for protocols", "examples": [ { "command": "# Port allocation for tun2socks-based protocols", "description": "Each protocol uses specific port ranges", "expectedOutput": "When connecting, protocols allocate ports automatically:\n\nShadowsocks: 30000-30004\nV2Ray: 30005-30009\nXray VMess: 30010-30014\nXray VLESS: 30015-30019\nVLESS Reality: 30020-30024\nXray Trojan: 30025-30029\nMieru/Mita: 30030-30034\nTor: 30035-30039\nDante: 30040-30044\nHysteria2: 30045-30049", "notes": "High port numbers (30000+) avoid conflicts with system services" }, { "command": "# Traffic flow for SOCKS5-based protocols", "description": "How traffic flows through local SOCKS5 proxy", "expectedOutput": "Application → tun_routing interface → tun2socks → localhost:PORT → proxy_client → remote_server", "notes": "The local SOCKS5 proxy listens on 127.0.0.1:PORT where PORT is from the allocated range" }, { "command": "ss -tlnp | grep 300", "description": "Check which local ports are in use", "expectedOutput": "tcp LISTEN 0 128 127.0.0.1:30000 *:* users:((\"ss-local\",pid=12345,fd=3))", "notes": "Use this command to verify which proxy ports are active" }, { "command": "# WireGuard and OpenVPN port usage", "description": "Native VPN protocols use different approaches", "expectedOutput": "WireGuard: Uses UDP port specified in config (typically 51820)\nOpenVPN: Uses TCP/UDP port specified in config (typically 1194)", "notes": "These protocols don't use tun2socks or local SOCKS5 proxies - they connect directly" } ], "id": "port_usage", "title": "PORT USAGE INFORMATION" }, { "description": "Different JSON output options", "examples": [ { "command": "sudo routing-switch status --json", "description": "Compact JSON output", "expectedOutput": "{\"status\":\"connected\",\"protocol\":\"tor\"}", "notes": "Requires sudo for accurate results" }, { "command": "sudo routing-switch status --json-pretty", "description": "Pretty-printed JSON", "expectedOutput": "{\n \"status\": \"connected\",\n \"protocol\": \"tor\"\n}" }, { "command": "sudo routing-switch status --json-human", "description": "Human-enhanced JSON", "expectedOutput": "JSON with descriptions and metadata" }, { "command": "routing-switch list-protocols --json --json-pretty", "description": "Pretty JSON protocol list", "expectedOutput": "Formatted JSON array of protocols" } ], "id": "json_formats", "title": "JSON OUTPUT FORMATS" }, { "description": "Test protocol performance", "examples": [ { "command": "routing-switch benchmark", "description": "Benchmark all protocols (3 iterations default)", "expectedOutput": "WireGuard: 95Mbps, OpenVPN: 75Mbps...", "notes": "Tests actual throughput" }, { "command": "routing-switch benchmark --iterations 5", "description": "Benchmark with custom iteration count", "expectedOutput": "Running 5 iterations... WireGuard: 95Mbps...", "notes": "More iterations = more accurate results" }, { "command": "routing-switch benchmark --json", "description": "Benchmark results in JSON", "expectedOutput": "{\"wireguard\": {\"download\": 95.5, \"upload\": 90.2}}" } ], "id": "benchmark", "title": "BENCHMARKING" }, { "description": "Test protocol connectivity without routing", "examples": [ { "command": "routing-switch test-protocol tor", "description": "Test Tor connectivity", "expectedOutput": "Tor: SOCKS5 proxy responding at 127.0.0.1:9050", "notes": "Doesn't change routing" }, { "command": "routing-switch test-protocol shadowsocks --extended", "description": "Extended protocol test", "expectedOutput": "Shadowsocks: Connected, Latency: 45ms, Throughput: OK" }, { "command": "routing-switch test-protocol all", "description": "Test all available protocols", "expectedOutput": "Testing: Tor [OK], Shadowsocks [OK], V2Ray [FAIL]..." }, { "command": "routing-switch test-protocol wireguard --json", "description": "Test with JSON output", "expectedOutput": "{\"protocol\": \"wireguard\", \"status\": \"ok\", \"latency\": 12}" } ], "id": "test_protocol", "title": "TESTING PROTOCOLS" }, { "description": "Run proxy without TUN interface for manual configuration", "examples": [ { "command": "sudo routing-switch connect shadowsocks --no-tun", "description": "Start Shadowsocks SOCKS5 proxy without TUN", "expectedOutput": "Shadowsocks SOCKS5 proxy ready at localhost:30000", "notes": "Configure browser/app manually with localhost:30000" }, { "command": "sudo routing-switch connect dante --no-tun", "description": "Connect to Dante SOCKS5 without routing traffic", "expectedOutput": "Dante proxy: host:port, username, password", "notes": "Direct connection to remote Dante server" }, { "command": "sudo routing-switch connect tor --no-tun", "description": "Use Tor SOCKS5 proxy without system routing", "expectedOutput": "Tor SOCKS5 proxy: 127.0.0.1:9050", "notes": "Tor must be running. Apps connect to port 9050" }, { "command": "sudo routing-switch connect v2ray --no-tun --json", "description": "V2Ray proxy in manual mode with JSON output", "expectedOutput": "{\"local_proxy_address\":\"127.0.0.1\",\"local_proxy_port\":30005}", "notes": "V2Ray client runs, no system routing" }, { "command": "sudo routing-switch connect xray-vless --no-tun", "description": "Xray VLESS proxy for manual configuration", "expectedOutput": "Xray SOCKS5 proxy ready at localhost:30015" }, { "command": "# Configure Firefox with no-TUN proxy:", "description": "Firefox proxy settings example", "expectedOutput": "Settings → Network → Manual proxy → SOCKS5: localhost, Port: 30000", "notes": "Each protocol uses different port ranges" }, { "command": "# Chrome with no-TUN proxy:", "description": "Chrome command line example", "expectedOutput": "chrome --proxy-server=\"socks5://localhost:30000\"" }, { "command": "sudo routing-switch disconnect", "description": "Stop the proxy (works for both TUN and no-TUN modes)", "expectedOutput": "Proxy stopped" } ], "id": "no_tun_mode", "title": "NO-TUN MODE (MANUAL PROXY)" }, { "description": "Export and display protocol configurations", "examples": [ { "command": "routing-switch export-config", "description": "Export all configurations to default location", "expectedOutput": "Exported 9 configuration(s) to ./results/configs/", "notes": "Creates timestamped config files" }, { "command": "routing-switch export-config wireguard", "description": "Export specific protocol configuration", "expectedOutput": "Exported 1 configuration(s) to ./results/configs/\n - wireguard: wireguard_20250817_143022.conf" }, { "command": "routing-switch export-config all --path /tmp/vpn-configs/", "description": "Export all configs to custom path", "expectedOutput": "Exported 9 configuration(s) to /tmp/vpn-configs/", "notes": "Creates directory if it doesn't exist" }, { "command": "routing-switch export-config shadowsocks --include-credentials", "description": "Export with credentials included", "expectedOutput": "Exported 1 configuration(s) to ./results/configs/", "notes": "⚠️ WARNING: Contains sensitive passwords" }, { "command": "routing-switch export-config --json", "description": "Export with JSON output showing results", "expectedOutput": "{\"exported_count\": 9, \"export_directory\": \"./results/configs/\", \"files\": [...]}" }, { "command": "routing-switch showconfig wireguard", "description": "Display WireGuard configuration", "expectedOutput": "Protocol Configurations:\n{\"available\": true, \"config_file\": \"wg0.conf\"...}", "notes": "Masks sensitive data by default" }, { "command": "routing-switch showconfig all --json-pretty", "description": "Show all protocol configs in pretty JSON", "expectedOutput": "Formatted JSON with all available protocol configurations" }, { "command": "routing-switch showconfig dante --mask-sensitive", "description": "Show config with passwords hidden", "expectedOutput": "{\"username\": \"dante_user\", \"password\": \"***REDACTED***\"}", "notes": "Safe for sharing/logging" }, { "command": "routing-switch showconfigurl shadowsocks", "description": "Get Shadowsocks connection URL", "expectedOutput": "ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTp6TDQ4cVYx...@:8388#Shadowsocks-IPv4", "notes": "URL can be imported into mobile apps" }, { "command": "routing-switch showconfigurl dante --json", "description": "Get SOCKS5 URLs in JSON format", "expectedOutput": "{\"ipv4\": \"socks5://user:pass@:1080\", \"ipv6\": \"socks5://user:pass@[]:1080\"}" }, { "command": "routing-switch showconfigurl all", "description": "Get URLs for all available protocols", "expectedOutput": "Protocol Connection URLs:\n\nshadowsocks:\n ipv4: ss://...\n\ndante:\n ipv4: socks5://..." }, { "command": "routing-switch showconfigqr wireguard", "description": "Generate QR code for WireGuard config", "expectedOutput": "[QR Code ASCII Art]\n\nURL: wireguard://base64_encoded_config", "notes": "Scan with WireGuard mobile app" }, { "command": "routing-switch showconfigqr shadowsocks", "description": "Generate IPv4 QR code for Shadowsocks (default)", "expectedOutput": "[QR Code ASCII Art]\n\nURL: ss://...", "notes": "Shows IPv4 QR code by default for dual-stack protocols" }, { "command": "routing-switch showconfigqr shadowsocks --ipv6", "description": "Generate IPv6 QR code for Shadowsocks", "expectedOutput": "[QR Code ASCII Art]\n\nURL: ss://...", "notes": "Use --ipv6 flag to show IPv6 QR for dual-stack protocols" }, { "command": "routing-switch showconfigqr shadowsocks --skip-validation", "description": "Generate QR without validation (faster)", "expectedOutput": "[QR Code ASCII Art]\n\n⚠ Validation skipped", "notes": "Skips automatic QR validation for debugging" }, { "command": "routing-switch showconfigqr all --strict-validation", "description": "Generate all QR codes with strict validation", "expectedOutput": "✓ Shadowsocks QR validated\n✓ WireGuard QR validated...", "notes": "Fails if any QR code validation fails" }, { "command": "routing-switch showconfigqr dante --json", "description": "Get QR data in JSON format", "expectedOutput": "{\"dante\": {\"url\": \"socks5://...\", \"qr_available\": true}}", "notes": "JSON includes the URL for QR generation" }, { "command": "routing-switch showconfigqr shadowsocks --save-files", "description": "Generate QR code and save as PNG file", "expectedOutput": "[QR Code ASCII Art]\n\n✓ IPv4 QR code files saved to ./results/qr-codes/", "notes": "Saves clean PNG file: shadowsocks_ipv4.png" }, { "command": "routing-switch showconfigqr shadowsocks --ipv6 --save-files", "description": "Generate IPv6 QR code and save as PNG file", "expectedOutput": "[QR Code ASCII Art]\n\n✓ IPv6 QR code files saved to ./results/qr-codes/", "notes": "Saves clean PNG file: shadowsocks_ipv6.png" }, { "command": "routing-switch showconfigqr shadowsocks --ipv4 --ipv6 --save-files", "description": "Generate both IPv4 and IPv6 QR codes", "expectedOutput": "[QR Code ASCII Art]\n\n✓ IPv4 and IPv6 QR code files saved to ./results/qr-codes/", "notes": "Saves both shadowsocks_ipv4.png and shadowsocks_ipv6.png" }, { "command": "routing-switch showconfigqr all --save-files --json-pretty", "description": "Generate all QR codes with pretty JSON output", "expectedOutput": "Pretty-formatted JSON with QR data and file paths", "notes": "Creates clean PNG files for all available protocols, supports all JSON formats" }, { "command": "routing-switch showconfigqr wireguard --save-files --json-human", "description": "Save QR file with human-enhanced JSON output", "expectedOutput": "{\"qr_code\": \"base64data...\", \"saved_file_path\": \"./results/qr-codes/wireguard.png\"}", "notes": "VPN protocols use single filename (no IP version suffix)" } ], "id": "config_export", "title": "CONFIGURATION EXPORT AND DISPLAY" }, { "description": "Validate QR codes against auth card", "examples": [ { "command": "routing-switch validate-qr shadowsocks_ipv4.png", "description": "Validate QR code from image file (NEW: direct filename)", "expectedOutput": "✓ QR valid: Shadowsocks (confidence: 98.5%)", "notes": "Smart detection: automatically finds file in current dir or results/qr-codes/" }, { "command": "routing-switch validate-qr dante_ipv4.png", "description": "Validate QR code from results/qr-codes directory", "expectedOutput": "✓ QR valid: Dante (confidence: 96.2%)", "notes": "Automatically looks in ./results/qr-codes/ if not found in current directory" }, { "command": "routing-switch validate-qr --file shadowsocks_qr.png", "description": "Validate QR code using explicit --file flag (legacy syntax)", "expectedOutput": "✓ QR valid: Shadowsocks (confidence: 98.5%)", "notes": "Both direct filename and --file flag work identically" }, { "command": "echo 'ss://...' | routing-switch validate-qr --stdin", "description": "Validate QR URL from stdin", "expectedOutput": "✓ Protocol: shadowsocks\n✓ Config matches auth card", "notes": "Useful for clipboard validation" }, { "command": "routing-switch validate-qr all", "description": "Validate all generated QR codes", "expectedOutput": "Validating all QR codes...\n✓ shadowsocks_ipv4.png: valid\n✓ wireguard.png: valid", "notes": "Checks all QR codes in results/qr-codes/" }, { "command": "routing-switch validate-qr --test-readability shadowsocks", "description": "Test QR code readability", "expectedOutput": "Testing QR readability...\n✓ QR code is readable", "notes": "Round-trip test of QR generation" }, { "command": "routing-switch validate-qr qr_code.png --json", "description": "JSON validation output", "expectedOutput": "{\"is_valid\": true, \"protocol\": \"shadowsocks\", \"confidence_score\": 0.985}", "notes": "Machine-readable validation results" } ], "id": "qr_validation", "title": "QR CODE VALIDATION" }, { "description": "Recover from connection issues", "examples": [ { "command": "sudo routing-switch disconnect --force", "description": "Force disconnect stuck connection", "expectedOutput": "Force killed all processes, routes restored", "notes": "Use when normal disconnect fails" }, { "command": "sudo routing-switch reset", "description": "Reset all routing to default", "expectedOutput": "Routing reset to system defaults", "notes": "Emergency recovery command" }, { "command": "sudo routing-switch cleanup", "description": "Clean up orphaned processes", "expectedOutput": "Cleaned up 2 orphaned tun2socks processes" }, { "command": "sudo routing-switch recover", "description": "Automatically diagnose and fix routing issues, restore network settings", "expectedOutput": "System recovered, ready for new connection", "notes": "Performs comprehensive recovery including cleanup, route restoration, and DNS reset" } ], "id": "error_recovery", "title": "ERROR RECOVERY" }, { "description": "Turn Kodachi into a SOCKS5 proxy server for other devices on your network", "examples": [ { "command": "sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'", "description": "Enable microsocks server with auto port detection", "expectedOutput": "Microsocks server started on port 30050, listening on all interfaces", "notes": "Automatically selects available port from 30050-30054 range. Used when Kodachi acts as a server. After connecting routing-switch to any service (WireGuard, V2Ray, etc.), enable microsocks so other PCs on your network can connect through this machine using the listening microsocks port. Strong credentials recommended for security." }, { "command": "sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds' --port 30051", "description": "Enable with specific port", "expectedOutput": "Microsocks server started on port 30051", "notes": "Use when you need a specific port number within the 30050-30054 range" }, { "command": "sudo routing-switch microsocks-status", "description": "Check microsocks server status", "expectedOutput": "Status: Running, Port: 30050, PID: 12345", "notes": "Requires sudo for accurate results (reads privileged state)" }, { "command": "sudo routing-switch microsocks-status --json", "description": "Check status in JSON format", "expectedOutput": "{\"status\":\"running\",\"port\":30050,\"pid\":12345}" }, { "command": "sudo routing-switch microsocks-disable", "description": "Stop microsocks server", "expectedOutput": "Microsocks server stopped successfully" }, { "command": "# Complete server workflow:", "description": "Full example of using Kodachi as a proxy server", "expectedOutput": "Step 1: sudo routing-switch connect wireguard\nStep 2: sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'\nStep 3: Other PCs connect to socks5://microkodachi-8273:S@Cur9P@s@Wo-Ds@YOUR_IP:30050", "notes": "WORKFLOW: First connect routing-switch to any service (WireGuard, V2Ray, Shadowsocks, Hysteria2, etc.). Then enable microsocks to create a SOCKS5 proxy server. Other devices on your network can now connect through YOUR_IP:PORT using the provided credentials. All their traffic will flow through your active routing-switch connection." }, { "command": "# Port range information:", "description": "Microsocks uses dedicated port range", "expectedOutput": "Microsocks: 30050-30054\nOther services use different ranges to avoid conflicts", "notes": "High port numbers (30000+) avoid conflicts with system services. Each protocol has its own dedicated range." }, { "command": "# Client connection example:", "description": "How other devices connect", "expectedOutput": "Protocol: SOCKS5\nAddress: YOUR_KODACHI_IP (e.g., 192.168.1.100)\nPort: 30050\nUsername: microkodachi-8273\nPassword: S@Cur9P@s@Wo-Ds", "notes": "Configure client device browsers/applications to use this SOCKS5 proxy. All traffic from client will be routed through Kodachi's active connection." } ], "id": "microsocks_server", "title": "MICROSOCKS SERVER MODE" }, { "description": "Connect to free VPNGate public servers (no authentication required)", "examples": [ { "command": "routing-switch vpngate-fetch", "description": "Fetch VPNGate server list from public API", "expectedOutput": "Fetched 150 VPNGate servers", "notes": "Downloads and caches server list (refreshes every hour)" }, { "command": "routing-switch vpngate-list", "description": "List all cached VPNGate servers", "expectedOutput": "Index Flag Country IP Speed Ping Score Sessions", "notes": "Shows servers sorted by score (default)" }, { "command": "routing-switch vpngate-list --country JP --sort speed -l 10", "description": "List top 10 Japanese servers by speed", "expectedOutput": "10 servers shown, filtered by country: JP", "notes": "Filter by country name or code, sort by speed/ping/score/sessions" }, { "command": "routing-switch vpngate-list --country US --sort ping", "description": "List US servers sorted by lowest ping", "expectedOutput": "Servers sorted by ping latency" }, { "command": "sudo routing-switch vpngate-connect 5", "description": "Connect to VPNGate server at index 5", "expectedOutput": "Successfully connected to via openvpn", "notes": "Uses OpenVPN with free vpn/vpn credentials" }, { "command": "sudo routing-switch vpngate-connect 12 --force", "description": "Force connect to server 12 (disconnect existing first)", "expectedOutput": "Force connected to VPNGate server" }, { "command": "routing-switch vpngate-fetch --json", "description": "Fetch servers with JSON output", "expectedOutput": "{\"status\":\"success\",\"server_count\":150}" }, { "command": "routing-switch vpngate-list --json-pretty", "description": "List servers in pretty JSON format", "expectedOutput": "Pretty-printed JSON array of servers" }, { "command": "routing-switch vpngate-export 1", "description": "Export top server's OpenVPN config as .ovpn file", "expectedOutput": "Exported: JP Japan (1.2.3.4) -> results/vpngate-configs/1_jp_1-2-3-4.ovpn", "notes": "Includes embedded vpn/vpn credentials for standalone use" }, { "command": "routing-switch vpngate-export-all", "description": "Export all cached servers as .ovpn files", "expectedOutput": "Exported 99 VPNGate configs to results/vpngate-configs", "notes": "Bulk export for use in external OpenVPN clients" }, { "command": "routing-switch vpngate-export 5 --json", "description": "Export server #5 config with JSON output", "expectedOutput": "{\"status\":\"success\",\"action\":\"vpngate-export\",\"file\":\"...\"}" } ], "id": "vpngate_free_vpn", "title": "VPNGATE FREE VPN" } ], "description": "System-wide traffic routing through various proxy protocols", "name": "routing-switch", "quickReference": [ "sudo routing-switch connect [PROTOCOL] - Connect to proxy", "sudo routing-switch disconnect - Disconnect current proxy", "sudo routing-switch status - Check connection status (needs sudo for accurate results)", "routing-switch list-protocols - Show available protocols", "Use --json for JSON output, --verbose for details", "Paid connections require authentication via online-auth", "VPNGate connections (vpngate-*) are free and do not require authentication" ] }, "errors": [], "metadata": { "executionTime": 1, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:18.953952421Z", "version": "9.0.1", "warnings": [] } }, { "name": "logs-hook", "path": "/home/kodachi/k900/dashboard/hooks/logs-hook", "timestamp": "2026-04-02T13:42:19Z", "file_info": { "size": 1442496, "sha256": "b6f3596565ddc0266af51f32ea113c0a6f4f2e5c7848f1fadc5e6cffb5a7f829" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "A robust, secure, and configurable logging system for Kodachi OS", "features": [ "Centralized logging system", "Log rotation with configurable limits", "Secure log wiping", "Multiple log levels support", "JSON output format", "Embedded configuration system" ], "license": "Proprietary", "name": "logs-hook", "securityFeatures": { "authentication": "Integrates with online-auth service", "encryption": "Supports encrypted log storage", "inputValidation": "Sanitizes script names and messages", "rateLimiting": "Built-in protection against log spam" }, "systemRequirements": { "dependencies": [ "tokio runtime", "filesystem access" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system logs" }, "version": "9.0.1", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:19.246432099Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2026-04-02T13:42:19.310849372Z", "gitCommit": "unknown", "name": "logs-hook", "rustVersion": "1.88.0", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-M3", "user": "kodachi" }, "status": "success", "timestamp": "2026-04-02T13:42:19.310850441Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Logging Commands", "commands": [ { "description": "Log a message", "examples": [ "logs-hook log --script 'my-script' --level info 'Script started'", "logs-hook log -s 'backup' -l warn 'Low disk space'", "logs-hook log --script 'app' --level error 'Connection failed' --json" ], "name": "log", "options": [ { "description": "Script name for the log entry", "flag": "--script, -s