sica-fondt/knowledge/cyber-skills/skills/validating-backup-integrity-for-recovery/references/api-reference.md

API Reference: Validating Backup Integrity for Recovery

CLI Usage

# Generate SHA-256 hash manifest for a directory
python agent.py --generate-manifest /data/production -o manifest.json

# Generate manifest with SHA-512
python agent.py --generate-manifest /data/production --algorithm sha512 -o manifest.json

# Compare baseline vs restored manifest
python agent.py --compare baseline_manifest.json restored_manifest.json

# Run full backup validation suite
python agent.py --validate /restore-test --baseline baseline_manifest.json -o report.json

# Scan for ransomware artifacts in restored data
python agent.py --ransomware-scan /restore-test

# Scan for high-entropy (possibly encrypted) files
python agent.py --entropy-scan /restore-test --entropy-threshold 7.9

Hash Algorithms Supported

Algorithm	Digest Size	Use Case
sha256	256 bits	Default; standard integrity verification
sha512	512 bits	Higher security; larger files
sha3_256	256 bits	NIST post-quantum recommendation
blake2b	512 bits	Faster alternative; high performance

Manifest Format

{
  "directory": "/data/production",
  "algorithm": "sha256",
  "generated_at": "2026-03-19T04:00:00+00:00",
  "total_files": 1523,
  "errors": 0,
  "hashes": {
    "config/app.yaml": "a3f2b8c9d1e4f5a6...",
    "data/users.db": "1b2c3d4e5f6a7b8c...",
    "logs/access.log": "ERROR:Permission denied"
  }
}

Comparison Result Format

{
  "baseline_files": 1523,
  "restored_files": 1520,
  "missing_files": ["logs/audit.log", "tmp/cache.db", "data/session.bin"],
  "missing_count": 3,
  "modified_files": [
    {
      "file": "config/app.yaml",
      "baseline": "a3f2b8c9...",
      "restored": "7e8f9a0b..."
    }
  ],
  "modified_count": 1,
  "added_files": [],
  "added_count": 0,
  "integrity_pass": false
}

Entropy Scan Output

{
  "directory": "/restore-test",
  "threshold": 7.9,
  "files_scanned": 1200,
  "suspicious_count": 3,
  "suspicious_files": [
    {
      "file": "data/report.docx.encrypted",
      "entropy": 7.98,
      "size_bytes": 524288
    }
  ]
}

Entropy Reference Values

Entropy Range	Interpretation
0.0 - 1.0	Highly repetitive data (empty files, padding)
1.0 - 5.0	Structured text (config files, logs, source code)
5.0 - 7.0	Binary data (executables, images, databases)
7.0 - 7.8	Compressed data (zip, gzip, jpg)
7.8 - 8.0	Encrypted or fully random data (ransomware indicator)

Ransomware Scan Output

{
  "ransomware_extensions": [
    "documents/report.docx.locked",
    "data/backup.sql.encrypted"
  ],
  "ransom_notes": [
    "HOW_TO_RECOVER_YOUR_FILES.txt"
  ],
  "total_scanned": 1523,
  "clean": false
}

Known Ransomware Extensions Detected

.encrypted, .locked, .crypt, .ransom, .pay, .wncry, .wcry, .cerber, .locky, .zepto, .osiris, .aesir, .thor, .odin, .crypz, .crypted, .enc, .crypto, .lockbit

Full Validation Report Schema

{
  "timestamp": "2026-03-19T04:30:00+00:00",
  "directory": "/restore-test",
  "checks": {
    "file_stats": {
      "total_files": 1523,
      "total_size_bytes": 1073741824,
      "total_size_mb": 1024.0,
      "pass": true
    },
    "integrity": {
      "integrity_pass": true,
      "missing_count": 0,
      "modified_count": 0
    },
    "ransomware_scan": {
      "clean": true,
      "total_scanned": 1523
    },
    "entropy_scan": {
      "files_scanned": 1200,
      "suspicious_count": 0
    }
  },
  "overall_pass": true
}

References

• NIST SP 800-184: Guide for Cybersecurity Event Recovery
• NIST CSF 2.0 RC.RP-03: Backup Integrity Verification
• CIS Controls v8: Control 11 - Data Recovery
• Restic Documentation: https://restic.readthedocs.io/en/stable/045_working_with_repos.html
• BorgBackup Verification: https://borgbackup.readthedocs.io/en/stable/usage/check.html