{
  "report_info": {
    "version": "10.0.3",
    "generated_at": "2026-10-09T09:10:44Z",
    "binary_name": "integrity-check"
  },
  "binary": {
    "name": "integrity-check",
    "path": "/opt/kodachi/dashboard/hooks/integrity-check",
    "timestamp": "2026-10-09T09:10:44Z",
    "file_info": {
      "size": 4080576,
      "sha256": "b996298336e47521f8accbcc124795b78e21900c522fea887ce4e59116c33fb0"
    },
    "flag_n": {
      "command": "info",
      "data": {
        "author": "Warith Al Maawali",
        "copyright": "© 2026 Kodachi OS",
        "description": "A system integrity checker for verifying script and configuration files",
        "features": [
          "File integrity verification using SHA-256 hashes",
          "Cryptographic signature verification",
          "Version checking against remote repositories",
          "Configuration file validation",
          "Offline mode support",
          "Comprehensive logging and reporting"
        ],
        "license": "Proprietary",
        "name": "integrity-check",
        "securityFeatures": {
          "authentication": "Certificate pinning for secure connections",
          "encryption": "TLS 1.3 for all network communications",
          "inputValidation": "All inputs validated and sanitized",
          "rateLimiting": "Maximum 3 retries with configurable timeouts"
        },
        "systemRequirements": {
          "dependencies": [
            "OpenSSL",
            "curl"
          ],
          "os": "Linux (Debian-based)",
          "privileges": "sudo for 'generate', 'check-signatures' and 'check-all'. The read-only checks run as your normal user, but anything that writes into the install directory (the generated and remote hash manifests) needs write access to it"
        },
        "version": "10.0.3",
        "website": "https://digi77.com"
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-10-09T09:10:44.154567456Z",
      "version": "10.0.3",
      "warnings": []
    },
    "flag_v": {
      "command": "version",
      "data": {
        "buildDate": "REDACTED-BUILD-TIME",
        "gitCommit": "unknown",
        "name": "integrity-check",
        "rustVersion": "1.82.0",
        "version": "10.0.3"
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-10-09T09:10:44.231457239Z",
      "version": "10.0.3",
      "warnings": []
    },
    "flag_h": {
      "command": "help",
      "data": {
        "commandCategories": [
          {
            "category": "Integrity Operations",
            "commands": [
              {
                "description": "Online hash comparison (version-aware, advisory). Compares tracked files against the published manifest for the CURRENT build. If your build is behind/ahead of the latest published build, the test does not apply and is reported as an advisory, not a failure. For authoritative tamper detection use check-signatures.",
                "examples": [
                  "integrity-check check-integrity",
                  "integrity-check check-integrity --json"
                ],
                "name": "check-integrity",
                "options": [
                  {
                    "description": "Run against a different install root instead of the detected one",
                    "flag": "--base-dir <DIR>"
                  },
                  {
                    "description": "Offline mode: compare against the cached local manifest, no remote fetch",
                    "flag": "--no-network"
                  },
                  {
                    "description": "Force the online comparison to count even when your build differs from the latest published build",
                    "flag": "--strict"
                  },
                  {
                    "description": "Report local-only files absent from the remote manifest without failing; hash mismatches and missing local files still fail",
                    "flag": "--lenient"
                  },
                  {
                    "description": "Network timeout for fetching the remote manifest [default: 30]",
                    "flag": "--timeout <SECS>"
                  },
                  {
                    "description": "Retry attempts for the remote fetch, 1-20 [default: 3]",
                    "flag": "--retry <COUNT>"
                  },
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  }
                ],
                "requires_sudo": false,
                "usage": "integrity-check check-integrity [OPTIONS]"
              },
              {
                "description": "Generate new hash file for all tracked files",
                "examples": [
                  "integrity-check generate",
                  "integrity-check generate --json"
                ],
                "name": "generate",
                "options": [
                  {
                    "description": "Run against a different install root instead of the detected one",
                    "flag": "--base-dir <DIR>"
                  },
                  {
                    "description": "Offline mode: hash local files only, do not contact the server",
                    "flag": "--no-network"
                  },
                  {
                    "description": "Enable strict validation while hashing",
                    "flag": "--strict"
                  },
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  }
                ],
                "requires_sudo": true,
                "usage": "integrity-check generate [OPTIONS]"
              },
              {
                "description": "AUTHORITATIVE tamper check. Verifies every expected binary against its detached RSA signature using a pinned public key, fully offline (works on Tor/airgapped). Fails on a bad signature, a missing expected binary or signature, a duplicate, or a signature for a file not in the trusted inventory. This is the verdict to trust for 'is my install authentic'.",
                "examples": [
                  "integrity-check check-signatures",
                  "integrity-check check-signatures --json"
                ],
                "name": "check-signatures",
                "options": [
                  {
                    "description": "Run against a different install root instead of the detected one",
                    "flag": "--base-dir <DIR>"
                  },
                  {
                    "description": "Fail on any signature mismatch instead of only reporting it",
                    "flag": "--strict"
                  },
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  }
                ],
                "requires_sudo": true,
                "usage": "integrity-check check-signatures [OPTIONS]"
              }
            ]
          },
          {
            "category": "Verification Operations",
            "commands": [
              {
                "description": "Compare local package versions against remote repositories",
                "examples": [
                  "integrity-check check-version",
                  "integrity-check check-version --json"
                ],
                "name": "check-version",
                "options": [
                  {
                    "description": "Offline mode. Version checking needs the network, so this leaves nothing to compare",
                    "flag": "--no-network"
                  },
                  {
                    "description": "Network timeout for the remote version lookup [default: 30]",
                    "flag": "--timeout <SECS>"
                  },
                  {
                    "description": "Retry attempts for the remote lookup, 1-20 [default: 3]",
                    "flag": "--retry <COUNT>"
                  },
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  }
                ],
                "requires_sudo": false,
                "usage": "integrity-check check-version [OPTIONS]"
              },
              {
                "description": "Verify the integrity and format of configuration files",
                "examples": [
                  "integrity-check check-config",
                  "integrity-check check-config --json"
                ],
                "name": "check-config",
                "options": [
                  {
                    "description": "Run against a different install root instead of the detected one",
                    "flag": "--base-dir <DIR>"
                  },
                  {
                    "description": "Enable strict validation of the configuration files",
                    "flag": "--strict"
                  },
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  }
                ],
                "requires_sudo": false,
                "usage": "integrity-check check-config [OPTIONS]"
              },
              {
                "description": "Comprehensive check. Runs the AUTHORITATIVE offline signature verification FIRST (its verdict decides pass/fail), then the version-aware online hash comparison as an advisory. A bad signature fails; being behind the latest published build does not.",
                "examples": [
                  "integrity-check check-all",
                  "integrity-check check-all --json"
                ],
                "name": "check-all",
                "options": [
                  {
                    "description": "Run against a different install root instead of the detected one",
                    "flag": "--base-dir <DIR>"
                  },
                  {
                    "description": "Offline mode: run the local integrity pass only, skip the remote manifest",
                    "flag": "--no-network"
                  },
                  {
                    "description": "Require an applicable current-build online comparison to pass",
                    "flag": "--strict"
                  },
                  {
                    "description": "Report local-only files absent from the remote manifest without failing the online comparison",
                    "flag": "--lenient"
                  },
                  {
                    "description": "Network timeout, raise it for a slow link [default: 30]",
                    "flag": "--timeout <SECS>"
                  },
                  {
                    "description": "Retry attempts for the remote fetch, 1-20 [default: 3]",
                    "flag": "--retry <COUNT>"
                  },
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  }
                ],
                "requires_sudo": true,
                "usage": "integrity-check check-all [OPTIONS]"
              }
            ]
          },
          {
            "category": "Utility Operations",
            "commands": [
              {
                "description": "Display the most recent integrity check logs",
                "examples": [
                  "integrity-check view-logs",
                  "integrity-check view-logs --json"
                ],
                "name": "view-logs",
                "options": [
                  {
                    "description": "Detail level 0-3 [default: 1]",
                    "flag": "-V, --verbosity <LEVEL>"
                  },
                  {
                    "description": "Machine readable output for scripting or the dashboard",
                    "flag": "--json / --json-pretty / --json-human"
                  },
                  {
                    "description": "Show at most N log records",
                    "flag": "--limit <N>"
                  }
                ],
                "requires_sudo": false,
                "usage": "integrity-check view-logs [OPTIONS]"
              }
            ]
          }
        ],
        "description": "A system integrity checker for verifying script and configuration files",
        "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"
          }
        ],
        "exitCodes": {
          "0": "Success",
          "1": "General error",
          "10": "Check failure - tampering (offline signature failure) or, when your build is the current published build, a real hash mismatch. Being behind the latest published build is NOT a failure (exit 0 with an advisory).",
          "2": "Invalid arguments",
          "3": "Permission denied",
          "4": "Network error",
          "5": "File not found",
          "6": "Timeout error",
          "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": "Pretty-print JSON output",
            "flag": "--json-pretty"
          },
          {
            "description": "Filter JSON output fields",
            "flag": "--json-filter <FIELDS>"
          },
          {
            "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 <FILE>"
          },
          {
            "description": "Set timeout (default: 30)",
            "flag": "--timeout <SECS>"
          },
          {
            "description": "Retry attempts, 1-20 [default: 3]. This is the flag that actually sets the retry count",
            "flag": "--retry <COUNT>"
          },
          {
            "description": "Colorized, jq-style JSON output",
            "flag": "--json-human"
          },
          {
            "description": "Select which fields to keep in JSON output",
            "flag": "--fields <FIELDS>"
          },
          {
            "description": "Limit the number of records in JSON output",
            "flag": "--limit <N>"
          },
          {
            "description": "Skip the first N records in JSON output",
            "flag": "--offset <N>"
          },
          {
            "description": "Output format (text|json) [default: text]",
            "flag": "-o, --output-format <FORMAT>"
          },
          {
            "description": "Base directory for the application. Rejects '..', shell metacharacters and the system prefixes /etc, /sys, /proc, /dev, /root",
            "flag": "--base-dir <DIR>"
          },
          {
            "description": "Working directory for the process",
            "flag": "-d, --work-dir <DIR>"
          },
          {
            "description": "Override the network port used for remote lookups",
            "flag": "--port <PORT>"
          },
          {
            "description": "Verbosity level (0-3) [default: 1]",
            "flag": "-V, --verbosity <LEVEL>"
          },
          {
            "description": "Logging level (error|warn|info|debug|trace)",
            "flag": "--log-level <LEVEL>"
          },
          {
            "description": "Offline mode: skip every remote call, verify against the local manifest only",
            "flag": "--no-network"
          },
          {
            "description": "Require the online comparison to count when it applies to the current build",
            "flag": "--strict"
          },
          {
            "description": "Treat local-only files missing from the remote manifest as advisory; hash mismatches and missing local files still fail",
            "flag": "--lenient"
          }
        ],
        "name": "integrity-check",
        "usage": "integrity-check [OPTIONS] [COMMAND] [ARGS]"
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-10-09T09:10:44.303475430Z",
      "version": "10.0.3",
      "warnings": []
    },
    "flag_e": {
      "command": "examples",
      "data": {
        "categories": [
          {
            "description": "Core integrity checking. check-integrity is the version-aware ONLINE hash comparison against the current published build; for the authoritative 'is my install authentic' answer use check-signatures (offline).",
            "examples": [
              {
                "command": "integrity-check check-integrity",
                "description": "Online hash comparison (version-aware)",
                "expectedOutput": "If your build equals the latest published build: a per-file pass/fail list and exit 10 on a real mismatch. If your build is behind/ahead/unknown: 'Online hash comparison: NOT APPLICABLE' with an advisory and exit 0. Rely on check-signatures for tamper detection.",
                "notes": "This refreshes the cached remote manifest inside the install directory, so on a root-owned install (for example /opt) prefix it with sudo or pass --no-network."
              },
              {
                "command": "integrity-check check-integrity --json",
                "description": "Online hash comparison with JSON output",
                "expectedOutput": "JSON with success (post version-gate), version_gate (current|behind|ahead|unknown-local-build|current-build-unavailable|online-manifest-not-refreshed), online_applicable, advisory, and the mismatch/missing lists"
              },
              {
                "command": "integrity-check check-integrity --lenient",
                "description": "Report known local-only legacy files without failing",
                "expectedOutput": "Local-only files remain listed, but only hash mismatches or files missing locally fail the comparison",
                "notes": "The default is fail-closed. Use this only after reviewing every local-only file."
              },
              {
                "command": "integrity-check check-integrity --base-dir /opt/kodachi/dashboard/hooks",
                "description": "Check a second Kodachi install instead of the detected one",
                "expectedOutput": "Integrity results for the files under that directory",
                "notes": "--base-dir is validated: '..', shell metacharacters (* ? { } ( ) ; | & $ ` < >) and the system prefixes /etc, /sys, /proc, /dev and /root are all rejected."
              },
              {
                "command": "integrity-check check-integrity --base-dir /opt/kodachi/dashboard/hooks --json",
                "description": "Same check against a custom install root, as JSON",
                "expectedOutput": "JSON envelope with the results for that directory"
              }
            ],
            "id": "1_basic_usage",
            "title": "Basic Usage"
          },
          {
            "description": "check-all runs the authoritative offline signature verification FIRST, then the version-aware online hash comparison as an advisory, and writes the refreshed remote manifest into the install directory, which is why it wants root.",
            "examples": [
              {
                "command": "sudo integrity-check check-all",
                "description": "Complete system verification (offline-authoritative)",
                "expectedOutput": "'Offline signature verification (authoritative): PASS/FAIL' first; a signature failure fails the run. Then the online hash comparison, shown as NOT APPLICABLE with an advisory when your build is not the latest published one. Exit 10 only on a real tamper (or a strict online mismatch).",
                "notes": "Needs root because it rewrites the cached manifest inside a root-owned install directory."
              },
              {
                "command": "sudo integrity-check check-all --timeout 300",
                "description": "Full system verification over a slow or Tor-routed link",
                "expectedOutput": "The same report, with up to 300 seconds allowed per network call",
                "notes": "--timeout accepts 1 to 300 seconds. The default of 30 is often too short over Tor."
              },
              {
                "command": "sudo integrity-check check-all --strict --json",
                "description": "Strict: also fail on an applicable current-build online mismatch",
                "expectedOutput": "JSON envelope. Offline signatures still decide tamper; with --strict an applicable current-build online mismatch fails the run. Local-only files fail unless --lenient is also passed",
                "notes": "Without --strict, an online mismatch on the current build is a publish-consistency advisory (exit 0), not a failure."
              }
            ],
            "id": "2_comprehensive_checks",
            "title": "Comprehensive System Checks"
          },
          {
            "description": "Creating and managing file integrity hashes",
            "examples": [
              {
                "command": "sudo integrity-check generate",
                "description": "Create a new hash manifest covering all tracked files",
                "expectedOutput": "The generated hash manifest is written into the install directory, replacing the previous one",
                "notes": "Needs root. This OVERWRITES the existing manifest: whatever is on disk right now becomes the new baseline, so only run it when you trust the current state of the system. Running it on a tampered system makes the tampering the reference."
              },
              {
                "command": "sudo integrity-check generate --json",
                "description": "Hash generation with JSON output for automation",
                "expectedOutput": "JSON envelope reporting how many files were hashed and where the manifest was written"
              }
            ],
            "id": "3_hash_generation",
            "title": "Hash Generation"
          },
          {
            "description": "Package version verification against remote repositories",
            "examples": [
              {
                "command": "integrity-check check-version",
                "description": "Compare local package versions against remote repositories",
                "expectedOutput": "A per-package comparison of the local version against the remote one, and a list of any mismatches",
                "notes": "Needs network access. With --no-network there is nothing to compare against."
              },
              {
                "command": "integrity-check check-version --json",
                "description": "Version check with JSON output for scripting",
                "expectedOutput": "JSON envelope with the local and remote version of each tracked package"
              }
            ],
            "id": "4_version_checking",
            "title": "Version Checking"
          },
          {
            "description": "Configuration file verification and validation",
            "examples": [
              {
                "command": "integrity-check check-config",
                "description": "Verify the integrity and format of configuration files",
                "expectedOutput": "A pass/fail line per configuration file, with the parse error shown for any file that is malformed"
              },
              {
                "command": "integrity-check check-config --json",
                "description": "Configuration check with JSON output",
                "expectedOutput": "JSON envelope listing each configuration file and whether it validated"
              }
            ],
            "id": "5_configuration_management",
            "title": "Configuration Management"
          },
          {
            "description": "Authoritative offline tamper detection. Verifies every expected binary against a pinned public key and fails on coverage gaps.",
            "examples": [
              {
                "command": "sudo integrity-check check-signatures",
                "description": "Authoritative 'is my install authentic' check (offline)",
                "expectedOutput": "A verified/failed line per binary, checked against the pinned public key, plus any coverage gap (an expected binary or signature missing), duplicate signature, or signature for a file outside the trusted inventory. Any of these fails the run.",
                "notes": "Works with no network (Tor/airgapped). Only a key whose fingerprint is pinned into the tool is trusted. Needs root to read the protected signature material."
              },
              {
                "command": "sudo integrity-check check-signatures --json",
                "description": "Signature verification with JSON output",
                "expectedOutput": "JSON with success and per-file status plus inventory_missing, duplicate_signatures and unexpected_signatures lists"
              },
              {
                "command": "sudo integrity-check check-signatures --strict",
                "description": "Strict signature verification",
                "expectedOutput": "The same report, but the command exits non-zero on the first signature that does not verify",
                "notes": "Use this in automation: without --strict a mismatch is reported but does not fail the run."
              }
            ],
            "id": "6_signature_verification",
            "title": "Signature Verification"
          },
          {
            "description": "Viewing and managing integrity check logs",
            "examples": [
              {
                "command": "integrity-check view-logs",
                "description": "Display the most recent integrity check logs",
                "expectedOutput": "The most recent log entries, newest last"
              },
              {
                "command": "integrity-check view-logs --json",
                "description": "View logs in JSON format for parsing",
                "expectedOutput": "JSON envelope with one object per log record",
                "notes": "Useful for log analysis tools"
              }
            ],
            "id": "7_log_management",
            "title": "Log Management"
          },
          {
            "description": "--no-network is the headline offline mode: it skips every remote call so the check runs entirely against the local manifest, which is what you want on an air-gapped machine or when you do not want the box reaching out at all. --strict tightens what counts as a failure, and --verbosity controls how much detail is printed.",
            "examples": [
              {
                "command": "integrity-check check-integrity --no-network",
                "description": "Verify files offline, against the manifest already on disk",
                "expectedOutput": "The usual pass/fail list, with no remote fetch and no manifest rewrite",
                "notes": "Nothing leaves the machine. The cached remote manifest is not refreshed, so results are only as current as the last online run."
              },
              {
                "command": "sudo integrity-check generate --no-network --strict",
                "description": "Rebuild the hash manifest from local files only",
                "expectedOutput": "A regenerated hash file covering every tracked file",
                "notes": "Needs root: it writes the manifest into the install directory. Run it after a deliberate system update, otherwise a later check-integrity will report your own changes as tampering."
              },
              {
                "command": "integrity-check check-integrity --verbosity 2",
                "description": "Show more detail about each file as it is checked",
                "expectedOutput": "Per-file progress lines in addition to the summary",
                "notes": "Levels are 0 (quiet) to 3 (most detail). Default is 1."
              },
              {
                "command": "sudo integrity-check check-all --output-format json --timeout 60 --retry 5",
                "description": "Automation-friendly run with an explicit retry budget",
                "expectedOutput": "A single JSON envelope, retrying each failed network call up to 5 times",
                "notes": "--retry accepts 1 to 20. The older --max-retries flag is deprecated and ignored: only --retry changes the retry count."
              }
            ],
            "id": "8_offline_and_hardened",
            "title": "Offline and Hardened Operation"
          }
        ],
        "description": "Usage examples for integrity-check",
        "name": "integrity-check",
        "quickReference": [
          "integrity-check check-integrity",
          "sudo integrity-check check-all",
          "sudo integrity-check generate",
          "integrity-check check-version",
          "integrity-check check-config",
          "sudo integrity-check check-signatures",
          "integrity-check view-logs",
          "integrity-check --help",
          "integrity-check --version",
          "integrity-check --info",
          "integrity-check --examples"
        ]
      },
      "errors": [],
      "metadata": {
        "executionTime": 11,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-10-09T09:10:44.488117200Z",
      "version": "10.0.3",
      "warnings": []
    }
  }
}