Integrity Check Guide
Confirm your Kodachi system files are authentic. The authoritative check is offline cryptographic signature verification of every binary against a pinned key; a version-aware hash comparison against the current published release runs as an advisory (so an older-than-latest build is never misreported as tampered). This guide is scenario-first: how to verify authenticity, run audits, and read the results.
v9.8.4 (build 320) · 7 commands · 3.65 MB · BLAKE3 primary, SHA-256 fallback
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | integrity-check |
| Version | 9.8.4 (build 320) |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 3.6MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Security & Authentication |
| Description | A system integrity checker for verifying script and configuration files |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Integrity Verification
| Feature | Description |
|---|---|
| Hash Verification | BLAKE3 checksums for all tracked files (with SHA256 fallback for compatibility) |
| Signature Validation | Cryptographic signatures prevent forgery |
| Version Tracking | Compares local vs remote package versions |
| Configuration Auditing | Validates config file syntax and security |
Why Integrity Check is Essential
| Benefit | Description |
|---|---|
| Tamper Detection | Offline signature verification (the authoritative check) identifies any binary that is not authentically signed |
| Malware Prevention | Detects unauthorized changes to binaries |
| Security Auditing | Regular verification ensures system integrity |
| Compliance | Maintains audit trail of system modifications |
TL;DR - Essential Commands
# Verify integrity of all tracked files
sudo integrity-check check-integrity
# Generate new baseline hashes
sudo integrity-check generate
# Verify cryptographic signatures
integrity-check check-signatures
# Run comprehensive check (integrity + versions + signatures)
sudo integrity-check check-all
# View recent integrity logs
integrity-check view-logs
Understanding System Integrity
How Integrity Checking Works
The authoritative check verifies each binary against its cryptographic signature offline. Separately, check-integrity compares file hashes against the manifest for the current published release; because that manifest only describes the latest build, a hash difference is a failure only when your build is the latest one, otherwise it is an advisory:
What Gets Checked:
| Location | Description |
|---|---|
| System Binaries | /usr/bin, /usr/sbin |
| Dashboard Scripts | dashboard/hooks/ |
| Configuration Files | /etc/ |
| Kodachi Binaries | Kodachi-specific binaries and tools |
Generating Baselines
After fresh installation or verified updates:
This creates a baseline of all file hashes that future checks compare against.
Signature Verification
Verify cryptographic signatures on signed files:
Signatures ensure files haven't been modified since signing by Kodachi developers.
Version Checking
Compare local package versions with remote repositories:
Identifies outdated packages that may have security vulnerabilities.
Configuration Validation
Verify configuration file integrity and syntax:
Ensures configuration files haven't been corrupted or maliciously modified.
Comprehensive Security Audit
Run all checks in sequence:
This performs: 1. File integrity verification 2. Signature validation 3. Version checking 4. Configuration auditing
Viewing Audit Logs
# View recent integrity check results
integrity-check view-logs
# View logs with verbose details
integrity-check view-logs -V 2
Interpreting Results
Result Status:
| Status | Meaning |
|---|---|
| PASS | File matches known-good hash |
| FAIL | Signature did not verify (authentic-install failure), or a hash mismatch while you are on the latest published build. A hash difference when you are behind the latest build is an advisory, not a FAIL. |
| WARNING | File missing or new file detected |
| SIGNED | Valid cryptographic signature |
JSON Output Examples:
# Get results in JSON format for automation
integrity-check check-integrity --json
integrity-check check-signatures --json
# Parse results with jq
sudo integrity-check check-all --json | jq '.failed_files[]'
sudo integrity-check check-all --json | jq '.summary.total_failures'
Common Modifications to Investigate:
| Type | Description |
|---|---|
| Binary Files | Modified binaries in system directories |
| Script Changes | Script modifications in hooks directory |
| Config Changes | Unexpected configuration changes |
| New Files | New files in sensitive locations |
Advanced Commands
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Custom Paths | Custom file path specifications |
| Hash Algorithms | Hash algorithm selection |
| Incremental Checks | Incremental checking options |
| Network Verification | Network verification settings |
| Validation Modes | Strict validation modes |
| JSON Formatting | JSON output formatting |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Post-Update Checks | Run integrity checks after system updates |
| Trusted Baselines | Generate new baselines only on trusted systems |
| Immediate Investigation | Investigate a signature verification failure immediately (that is the authoritative tamper signal). A hash advisory shown because you are behind the latest release just means an update is available. |
| Key Updates | Keep signature keys updated |
| Regular Audits | Run comprehensive checks regularly |
| Log Retention | Save logs for security audits |
Performance
| Metric | Value |
|---|---|
| Check Time | 10-30 seconds for full scan |
| Memory Usage | ~40MB during scanning |
| CPU Usage | < 20% during checks |
| Database Size | ~10MB for hash storage |
| Network Usage | Minimal (version checks only) |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Post-Installation Baseline Hash Generation
Generate baseline hashes immediately after fresh OS installation or verified system updates.
# Step 1: Verify authentication status before generating baselines
sudo online-auth check-login
# Expected: Authentication confirmed - system is trusted
# Step 2: Generate comprehensive hash database for all tracked files
sudo integrity-check generate
# Expected: Hash database created with all system binaries, scripts, and configs
# Step 3: Verify generated hashes immediately
sudo integrity-check check-integrity
# Expected: All files pass - establishing clean baseline
# Step 4: Create signature verification baseline
sudo integrity-check check-signatures
# Expected: All signatures valid on fresh install
# Step 5: Document baseline creation in logs
integrity-check view-logs --json
# Expected: Baseline generation logged with timestamp
# Step 6: Run initial security score
sudo health-control security-score
# Expected: High security score on fresh install
# Step 7: Store baseline timestamp for future reference
echo "Baseline created: $(date)" | sudo tee -a /var/log/kodachi-baseline.log
# Expected: Timestamp logged for audit trail
Cross-binary workflow: integrity-check + online-auth + health-control + global-launcher
When to run: Immediately after fresh installation or major system updates. Automate this with workflow-manager using the security-full-audit profile for post-update verification.
Scenario 2: Scheduled Monthly System Integrity Audit
Perform comprehensive monthly integrity audits to detect unauthorized modifications.
# Step 1: Create timestamped backup of current hash database
sudo cp -a /path/to/hash-db /path/to/hash-db.backup-$(date +%Y%m%d)
# Expected: Backup created for rollback capability
# Step 2: Run comprehensive integrity check
sudo integrity-check check-all --timeout 300
# Expected: Full audit of integrity, versions, signatures, and configs
# Step 3: Export results to JSON for analysis
sudo integrity-check check-all --json > /tmp/integrity-audit-$(date +%Y%m%d).json
# Expected: Structured audit data saved for trending
# Step 4: Verify no integrity failures
sudo integrity-check check-integrity --strict
# Expected: Zero failures on properly maintained system
# Step 5: Check for version drift
integrity-check check-version --json
# Expected: Package versions match remote repositories
# Step 6: Log audit completion
integrity-check view-logs --verbose
# Expected: Detailed audit trail visible
# Step 7: Cross-reference with security score
sudo health-control security-score --json
# Expected: Security score reflects integrity status
Cross-binary workflow: integrity-check + health-control + logs-hook
When to run: First of every month at 4:00 AM. Automate this with workflow-manager scheduling the base-security-verification profile monthly.
Scenario 3: Post-Update Signature and Version Verification
Verify system integrity immediately after package updates or system patches.
# Step 1: Check package version changes
integrity-check check-version --json
# Expected: Shows updated packages vs remote versions
# Step 2: Verify cryptographic signatures on updated files
sudo integrity-check check-signatures --strict
# Expected: All updated files have valid signatures
# Step 3: Regenerate hashes for updated files only
sudo integrity-check generate
# Expected: New hashes computed for modified packages
# Step 4: Verify new hashes immediately
sudo integrity-check check-integrity
# Expected: All files pass with new baseline
# Step 5: Check system dependencies are satisfied
cd /opt/kodachi/dashboard/hooks/rust/deps-checker && cargo run -- check
# Expected: All required dependencies present
# Step 6: Validate configuration files not corrupted
integrity-check check-config --json
# Expected: All config files syntactically valid
# Step 7: Run full system verification
cd /opt/kodachi/dashboard/hooks && ./global-launcher verify --detailed --json
# Expected: Complete system verification passes
# Step 8: Log post-update verification
integrity-check view-logs --json > /tmp/post-update-verify-$(date +%Y%m%d).json
# Expected: Audit trail of update verification
Cross-binary workflow: integrity-check + deps-checker + global-launcher
When to run: Immediately after running apt upgrade or installing new packages. Automate this with workflow-manager's post-update hooks.
Scenario 4: Detecting Unauthorized File Modifications
Investigate integrity check failures and identify unauthorized changes.
# Step 1: Run comprehensive integrity check to identify failures
sudo integrity-check check-all --json > /tmp/integrity-failures.json
# Expected: JSON output showing which files failed verification
# Step 2: Parse failures for detailed analysis
cat /tmp/integrity-failures.json | jq '.failed_files[]'
# Expected: List of modified files with expected vs actual hashes
# Step 3: Check modification timestamps on failed files
stat $(cat /tmp/integrity-failures.json | jq -r '.failed_files[].path') 2>/dev/null
# Expected: Timestamps revealing when modifications occurred
# Step 4: Verify signatures on suspicious files
sudo integrity-check check-signatures --strict --json
# Expected: Invalid signatures on tampered files
# Step 5: Cross-reference with system logs
integrity-check view-logs --verbose
# Expected: Historical integrity check results showing when failure started
# Step 6: Log security incident
sudo logs-hook log --script 'integrity-check' --level fatal "Integrity check failures detected: $(cat /tmp/integrity-failures.json | jq -r '.summary.total_failures') files modified"
# Expected: Emergency log entry created
# Step 7: Calculate security score impact
sudo health-control security-score --json
# Expected: Security score reduced due to integrity failures
# Step 8: Trigger security alert if critical files affected
sudo health-control security-verify --json
# Expected: Security verification shows failed modules
Cross-binary workflow: integrity-check + logs-hook + health-control
When to run: Immediately when integrity-check reports failures. Investigate before taking action like re-imaging system.
Scenario 5: Configuration Integrity Verification
Verify configuration file integrity and syntax for critical system components.
# Step 1: Verify all configuration files are syntactically valid
integrity-check check-config --json
# Expected: All config files pass validation
# Step 2: Check DNS configuration integrity
cd /opt/kodachi/dashboard/hooks/rust/dns-switch && cargo run -- verify-config
# Expected: DNS config files valid and consistent
# Step 3: Verify hash integrity of config files
sudo integrity-check check-integrity --base-dir /opt/kodachi/dashboard/hooks/config
# Expected: Config directory files match known-good hashes
# Step 4: Validate security-critical configs
integrity-check check-config --strict --json | jq '.security_configs[]'
# Expected: Security configs (VPN, Tor, DNS) validated
# Step 5: Cross-check with health-control security verification
sudo health-control security-verify --json
# Expected: Configuration modules validated by health-control
# Step 6: Check for config drift from defaults
diff -r /opt/kodachi/dashboard/hooks/config /path/to/default-configs 2>&1 | tee /tmp/config-drift.txt
# Expected: Intentional modifications documented, unexpected changes flagged
# Step 7: Log configuration verification
integrity-check view-logs --json > /tmp/config-verification-$(date +%Y%m%d).json
# Expected: Config verification logged for compliance
Cross-binary workflow: integrity-check + dns-switch + health-control
When to run: Before and after configuration changes, or weekly as part of maintenance. Automate this with workflow-manager's verification profile using --verify-type security.
Scenario 6: Version Drift Detection Across Services
Detect version inconsistencies and outdated packages across all Kodachi services.
# Step 1: Check all package versions against remote repositories
integrity-check check-version --json > /tmp/version-check.json
# Expected: Version comparison for all tracked packages
# Step 2: Identify outdated packages
cat /tmp/version-check.json | jq '.outdated_packages[]'
# Expected: List of packages with available updates
# Step 3: Get system version information
cd /opt/kodachi/dashboard/hooks/rust/online-info-switch && cargo run -- version
# Expected: Current Kodachi OS version
# Step 4: Check Rust service versions
for dir in /opt/kodachi/dashboard/hooks/rust/*/; do (cd "$dir" && basename "$dir" && cargo pkgid | grep -oP '#\K.*'); done
# Expected: All Rust services with version numbers
# Step 5: Verify dependency versions
cd /opt/kodachi/dashboard/hooks/rust/deps-checker && cargo run -- check --verbose
# Expected: Dependency version matrix
# Step 6: Cross-reference with integrity hashes
sudo integrity-check check-integrity --json | jq '.version_info'
# Expected: Hash database version information
# Step 7: Generate version drift report
integrity-check check-version --verbose > /tmp/version-drift-report-$(date +%Y%m%d).txt
# Expected: Comprehensive version drift analysis
# Step 8: Log version verification
integrity-check view-logs --json
# Expected: Version check results logged
Cross-binary workflow: integrity-check + online-info-switch + deps-checker
When to run: Weekly or before planning system updates. Use output to prioritize package updates.
Scenario 7: Logging Integrity for Audit Compliance
Maintain comprehensive audit logs of all integrity verification operations for compliance.
# Step 1: View recent integrity check logs
integrity-check view-logs --verbose
# Expected: Detailed log entries with timestamps and results
# Step 2: Export logs to JSON for compliance reporting
integrity-check view-logs --json > /tmp/integrity-audit-logs-$(date +%Y%m%d).json
# Expected: Structured log data in JSON format
# Step 3: Parse logs for failed checks
cat /tmp/integrity-audit-logs-$(date +%Y%m%d).json | jq '.failed_checks[]'
# Expected: All integrity failures with timestamps
# Step 4: Cross-reference with system logs
sudo logs-hook log --script 'integrity-check' --level info 'Querying integrity-check logs for audit'
# Expected: Centralized logging triggered
# Step 5: Generate compliance report
sudo integrity-check check-all --json | jq '{timestamp: .timestamp, summary: .summary, failed_files: .failed_files}' > /tmp/compliance-report-$(date +%Y%m%d).json
# Expected: Compliance-ready report with key metrics
# Step 6: Verify log integrity (logs themselves not tampered)
sudo health-control security-verify --json | jq '.log_integrity'
# Expected: Log files themselves verified as intact
# Step 7: Archive audit logs
mkdir -p /var/log/kodachi-audit/integrity && sudo cp /tmp/integrity-audit-logs-*.json /var/log/kodachi-audit/integrity/
# Expected: Audit logs archived for long-term retention
# Step 8: Log archival completion
sudo logs-hook log --script 'integrity-check' --level info "Integrity audit logs archived for compliance: $(date)"
# Expected: Archival logged in centralized logs
Cross-binary workflow: integrity-check + logs-hook + health-control
When to run: End of every month for compliance reporting, or before security audits. Automate this with workflow-manager scheduling monthly archival tasks.
Related Workflows
- Health Control, System Health, Security scoring and verification
- DNS Switch, DNS Management, Configuration integrity for DNS
- Logs Hook, Centralized Logging, Audit trail management
- Global Launcher, Workflow Automation, Automated verification profiles
- Deps Checker, Dependency Management, System dependency verification
- Full CLI Reference: integrity-check commands