Skip to content

verify_policy_integrity

Verify that governance and policy configuration files haven't been tampered with using cryptographic hash verification.

Quick Reference

verify_policy_integrity(
    policy_dir: str = None,          # Policy directory
    manifest_source: str = "file"    # Manifest source
) -> PolicyIntegrityResult

User Stories

Persona Story Tool Value
🛡️ Marcus (Security Engineer) "Cryptographically verify policy files haven't been tampered with" Policy integrity assurance
🏢 Jennifer (Enterprise Architect) "Ensure policy files haven't been modified (cryptographic verification)" Audit integrity
👥 David (Team Lead) "Verify governance configurations are authentic before enforcement" Trust verification

→ See all user stories

Parameters

Parameter Type Required Default Description
policy_dir string No .code-scalpel Directory containing policy files
manifest_source string No "file" Where to read manifest ("file" or "remote")

Response Schema

{
  "data": {
    "verification_results": {
      "config.json": {
        "status": "string",
        "expected_hash": "string",
        "actual_hash": "string",
        "last_modified": "string"
      },
      "limits.toml": {
        "status": "string",
        "expected_hash": "string",
        "actual_hash": "string"
      }
    },
    "all_valid": "boolean",
    "tampered_files": ["string"],
    "missing_files": ["string"],
    "new_files": ["string"],
    "manifest_version": "string"
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Status Values

Status Meaning
VALID Hash matches manifest
TAMPERED Hash doesn't match (modified)
MISSING File in manifest but not on disk
NEW File on disk but not in manifest
ERROR Could not read/hash file

Examples

Verify Policy Directory

Verify the integrity of our governance configuration files

{
  "policy_dir": "/project/.code-scalpel"
}

codescalpel verify-policy-integrity --policy-dir /project/.code-scalpel

{
  "data": {
    "verification_results": {
      "config.json": {
        "status": "VALID",
        "expected_hash": "sha256:abc123...",
        "actual_hash": "sha256:abc123...",
        "last_modified": "2025-01-15T10:30:00Z"
      },
      "limits.toml": {
        "status": "VALID",
        "expected_hash": "sha256:def456...",
        "actual_hash": "sha256:def456...",
        "last_modified": "2025-01-15T10:30:00Z"
      },
      "governance.yaml": {
        "status": "VALID",
        "expected_hash": "sha256:ghi789...",
        "actual_hash": "sha256:ghi789...",
        "last_modified": "2025-01-15T10:30:00Z"
      }
    },
    "all_valid": true,
    "tampered_files": [],
    "missing_files": [],
    "new_files": [],
    "manifest_version": "1.0.0"
  },
  "tier_applied": "community",
  "duration_ms": 25
}

Detect Tampering

Check if anyone modified the governance files

{
  "policy_dir": "/project/.code-scalpel"
}

codescalpel verify-policy-integrity --policy-dir /project/.code-scalpel

{
  "data": {
    "verification_results": {
      "config.json": {
        "status": "VALID"
      },
      "limits.toml": {
        "status": "TAMPERED",
        "expected_hash": "sha256:def456...",
        "actual_hash": "sha256:xyz999...",
        "last_modified": "2025-02-01T14:20:00Z"
      },
      "governance.yaml": {
        "status": "VALID"
      }
    },
    "all_valid": false,
    "tampered_files": ["limits.toml"],
    "warning": "⚠️ Policy file tampering detected! limits.toml has been modified since last manifest update."
  }
}

Missing Files

{
  "data": {
    "verification_results": {
      "config.json": {
        "status": "VALID"
      },
      "governance.yaml": {
        "status": "MISSING",
        "expected_hash": "sha256:ghi789..."
      }
    },
    "all_valid": false,
    "missing_files": ["governance.yaml"],
    "warning": "⚠️ Expected policy file(s) missing: governance.yaml"
  }
}

New Untracked Files

{
  "data": {
    "verification_results": {
      "config.json": {"status": "VALID"},
      "limits.toml": {"status": "VALID"},
      "custom_rules.yaml": {
        "status": "NEW",
        "actual_hash": "sha256:new123..."
      }
    },
    "all_valid": true,
    "new_files": ["custom_rules.yaml"],
    "info": "New file detected: custom_rules.yaml. Consider adding to manifest."
  }
}

Policy Files Checked

File Purpose
config.json Main configuration
limits.toml Tier-based limits
governance.yaml Governance policies
architecture.toml Dependency rules
budget.yaml Agent budgets
policy.yaml OPA rules

Manifest File

The manifest file (.code-scalpel/manifest.json) tracks expected hashes:

{
  "version": "1.0.0",
  "generated_at": "2025-01-15T10:30:00Z",
  "files": {
    "config.json": {
      "hash": "sha256:abc123...",
      "size": 1250
    },
    "limits.toml": {
      "hash": "sha256:def456...",
      "size": 850
    }
  }
}

Tier Limits

verify_policy_integrity capabilities vary by tier:

Feature Community Pro Enterprise
Max policy files 50 200 Unlimited
Basic verification ✅ ✅ ✅
SHA-256 hashing ✅ ✅ ✅
Tampering detection ✅ ✅ ✅
Signature validation ❌ ✅ ✅
Tamper detection ❌ ✅ ✅
Remote manifest ❌ ❌ ✅ Signed
Audit logging ❌ ❌ ✅ Full trail
Auto-remediation ❌ ❌ ✅ Restore from manifest

Community Tier

  • ✅ Verify up to 50 policy files
  • ✅ SHA-256 hash verification
  • ✅ Detect tampering by hash mismatch
  • ✅ Basic manifest support (file-based)
  • ⚠️ Limited to 50 files - Small policy sets only
  • ❌ No cryptographic signature validation
  • ❌ No tamper detection beyond hash checks
  • ❌ No audit logging

Pro Tier

  • ✅ All Community features
  • ✅ 200 policy files - Larger policy sets
  • ✅ Signature validation - Cryptographic signatures
  • ✅ Tamper detection - Advanced integrity checks
  • ✅ Enhanced manifest - Metadata tracking

Enterprise Tier

  • ✅ All Pro features
  • ✅ Unlimited policy files - No size restrictions
  • ✅ Remote signed manifest - Central policy distribution
  • ✅ Full audit trail - Track all verification events
  • ✅ Auto-remediation - Restore from trusted manifest
  • ✅ Policy versioning - Track changes over time
  • ✅ Multi-tenant support - Organization-wide policies

Key Difference: Signature Validation and Audit - Community: 50 files, hash-only - Basic integrity - Pro: 200 files, signatures, tamper detection - Production integrity - Enterprise: Unlimited, signed manifests, audit trail - Compliance-ready

→ See tier comparison

Creating/Updating Manifest

1. CI/CD Validation

# GitHub Actions
- name: Verify Policy Integrity
  run: |
    code-scalpel policy verify
    if [ $? -ne 0 ]; then
      echo "Policy files have been tampered with!"
      exit 1
    fi

2. Startup Check

# Application startup
result = verify_policy_integrity()
if not result.all_valid:
    logger.critical(f"Policy tampering detected: {result.tampered_files}")
    sys.exit(1)

3. Compliance Audit

# Regular audit
result = verify_policy_integrity()
audit_log.record({
    "timestamp": datetime.now(),
    "all_valid": result.all_valid,
    "tampered": result.tampered_files,
    "verified_by": "automated_audit"
})

Creating/Updating Manifest

# Generate manifest from current files
code-scalpel policy manifest --generate

# Update manifest after authorized changes
code-scalpel policy manifest --update

# Sign manifest (Enterprise)
code-scalpel policy manifest --sign

Best Practices

  1. Run on startup - Detect tampering early
  2. Include in CI - Prevent unauthorized changes
  3. Update manifest after changes - Keep hashes current
  4. Alert on tampering - Notify security team
  5. Audit regularly - Enterprise compliance