security: verify deploy manifest integrity at startup

[benvinegar]

Summary

• add startup deploy-manifest verification via bin/verify-manifest.sh
• support integrity modes: off, warn, strict
• write startup result to ~/.pi/agent/manifest-integrity-status.json
• run verifier during startup and surface status in doctor/security-audit flows
• ship verifier in deploy/runtime and add shell tests + docs updates

Validation

• npm run lint:shell
• npm run test:shell
• Real DigitalOcean smoke validation using DO_API_TOKEN on an ephemeral Ubuntu droplet:
  • warn mode + intentional manifest-tracked tamper => warning + non-blocking startup behavior
  • strict mode + same tamper => verifier failure (exit 1) and fail status
  • redeploy restore => strict verification pass

Closes #120

[greptile-apps]

Greptile Summary

Implements startup integrity verification that checks deployed runtime files against SHA256 hashes in the deploy manifest. The feature adds defense-in-depth against file tampering between deployments.

Key changes:

• Added bin/verify-manifest.sh with three modes: off (skip), warn (log but continue), strict (fail on mismatch)
• Integrated verification into start.sh before agent launch, with graceful fallback if verifier missing
• Status tracking via ~/.pi/agent/manifest-integrity-status.json surfaced in doctor.sh and security-audit.sh
• Excludes mutable paths (sessions, memory, logs) via regex pattern
• Comprehensive test coverage in verify-manifest.test.sh
• Clear documentation in .env.schema and CONFIGURATION.md

Implementation quality:

• Proper error handling for missing jq, invalid manifest format, and missing files
• Secure permissions (600) on status file
• Uses set -euo pipefail for safe shell execution
• Test suite validates all three modes and edge cases
• Default warn mode provides good security/usability balance

Confidence Score: 5/5

• This PR is safe to merge with no identified issues
• The implementation demonstrates strong security engineering practices with comprehensive error handling, thorough test coverage, clear documentation, and graceful degradation. The verifier properly handles edge cases (missing jq, invalid manifest, missing files) and provides appropriate behavior for each mode. The regex-based exclusion of mutable paths prevents false positives. Integration points are well-designed with fallback behavior when the verifier is missing.
• No files require special attention

Important Files Changed

Filename	Overview
bin/verify-manifest.sh	Adds comprehensive startup integrity verification script with three modes (off/warn/strict), SHA256 hash checking, and proper exclusion of mutable paths
bin/verify-manifest.test.sh	Comprehensive test suite covering all three integrity modes, mutable path exclusion, and status file generation
start.sh	Integrates manifest verification before agent startup with proper fallback behavior when verifier is missing
bin/doctor.sh	Adds manifest integrity status reporting with appropriate severity levels (pass/warn/fail/skipped)
bin/security-audit.sh	Extends security audit with startup integrity status checks and detailed failure reporting

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent Startup] --> B{verify-manifest.sh exists?}
    B -->|No| C[⚠️ Warning: verifier missing]
    B -->|Yes| D[Run verify-manifest.sh]
    D --> E{Check MODE}
    E -->|off| F[Skip verification]
    E -->|warn/strict| G{Manifest exists?}
    G -->|No| H{MODE=strict?}
    H -->|Yes| I[❌ Exit 1]
    H -->|No| J[⚠️ Warn & Continue]
    G -->|Yes| K{jq available?}
    K -->|No| H
    K -->|Yes| L[Parse manifest files]
    L --> M{Check each file}
    M --> N[Skip if matches EXCLUDE_REGEX]
    M --> O[Compute SHA256 hash]
    O --> P{Hash matches?}
    P -->|Yes| Q[Continue]
    P -->|No| R[Record mismatch]
    R --> S{All files checked?}
    Q --> S
    S -->|Issues found| T{MODE=strict?}
    S -->|No issues| U[✅ Write pass status]
    T -->|Yes| V[❌ Write fail status & Exit 1]
    T -->|No| W[⚠️ Write warn status & Exit 0]
    U --> X[Continue startup]
    F --> X
    J --> X
    C --> X
    W --> X

Loading

_{Last reviewed commit: 05e356f}