Automated backup system with cryptographic integrity verification for Windows environments
FileGuardian is a robust, modular PowerShell-based backup solution designed to automate file backups while ensuring data integrity through SHA256 cryptographic verification. The system helps prevent data loss and undetected file corruption by validating every backup operation and maintaining detailed audit trails through digitally signed reports.
FileGuardian offers flexible backup strategies, automated scheduling via Windows Task Scheduler and comprehensive reporting capabilities. All through a unified command-line interface.
-
Multiple Backup Strategies
- Full backups: Complete snapshots of source directories
- Incremental backups: Efficient delta-based backups tracking only changed files
- Automated fallback: Incremental operations automatically perform full backups when no baseline exists
-
Cryptographic Integrity Verification
- SHA256 hash-based file validation
- State tracking with
latest.jsonandprev.jsonfor change detection - Automatic corruption detection across all backup operations
- Verification of previous backups during each backup cycle
-
Automated Scheduling
- Integration with Windows Task Scheduler
- Event-driven retention cleanup (executes automatically after successful backups)
- Flexible scheduling: daily, weekly, hourly frequencies
-
Comprehensive Reporting
- Multiple output formats: JSON, HTML or CSV
- Digital signatures (HMACSHA256) for tamper detection
- Detailed backup statistics and change summaries
- Previous backup verification results included in reports
-
Optional Data Compression
- ZIP archive creation with configurable compression levels
- Compression ratio tracking
- Space-saving for long-term storage
-
Intelligent Retention Management
- Configurable retention periods per backup
- Safe deletion logic (prevents accidental removal of all backups)
-
Restore Capabilities
- Restore from full and incremental backup chains
- Support for both compressed (ZIP) and uncompressed backups
- Automatic deletion application for incremental restores
- Metadata validation during restore operations
- Exclusion Patterns: Filter files using glob patterns (e.g.,
*.tmp,node_modules/**) - Parallel Hashing: Multi-threaded file integrity calculation for improved performance
- State Caching: Smart hash reuse for unchanged files to optimize incremental operations
- Detailed Logging: Comprehensive timestamped logs with automatic rotation
- Backup Verification: Validate any backup's integrity against saved state
- Report Signature Verification: Confirm report authenticity via
.sigfiles
- Operating System: Windows 11
- PowerShell: Version 5.1 or later
- Permissions: Administrator rights (required for scheduled task registration)
- Disk Space: Sufficient storage for source data + backups
-
Clone the repository
git clone https://github.com/Youmni/FileGuardian.git cd FileGuardian
-
Set configuration path (optional - recommended for scheduled tasks)
# Set environment variable to absolute path of your config file [Environment]::SetEnvironmentVariable('FILEGUARDIAN_CONFIG_PATH', <PATH>, 'User')
-
Set credential storage Install and use the CredentialManager module to securely store the report signing secret:
Install-Module -Name CredentialManager -Scope CurrentUser
$bytes = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$secret = [Convert]::ToBase64String($bytes)
New-StoredCredential -Target "FileGuardian.ReportSigning" -UserName "FileGuardian" -Password $secret -Persist LocalMachine
Get-StoredCredential -Target "FileGuardian.ReportSigning"Comprehensive guides are available in the docs/ directory:
- UserGuide.md - Complete usage documentation with examples for all operations (Backup, Verify, Report, Restore, Schedule and Cleanup)
- DeveloperGuide.md - System Overview, Project Structure, Architecture Design, Module Breakdown, Data Flow & State Management
- AI Assistance - Used prompts and Generative AI disclosure (see below)
Core Technologies:
- PowerShell 5.1+
- Windows Credential Manager
- Windows Task Scheduler
- Pester
- Project Structure
- MVP Approach
- Better Hashing Approach
- Temp Cleanup
- AI Project Suggestions
- Refactor Config
- Cache & Parallel Hashing
- Incremental Backup Deletion Problem
- Architecture Documentation
- Powershell Commands
- The slides from 'System automation & scripting'
- HMACSHA256
- Example HMACSHA256
- Scheduled Tasks
- Backup Video
- Backups Explanation
- Powershell Documentation
- Manifest Documentation
- Pester Documentation
- CI Workflow
- Trigger task on event
- Splatting
- Windows Credential Manager
I have noticed that when I sign a report, I currently only store a hash. If someone were to modify the report and then include the new hash in the signature, this would go unnoticed.
To prevent this, I would like to use an HMAC, specifically HMAC‑SHA256. The hash should be calculated over the report content including the metadata and the report number bytes and the HMAC should be stored together with the signature
I would like you to implement this approach for the reports. Additionally, I want this to work with the Credential Manager, so that the secret key used for the HMAC is stored securely rather than hard‑coded or stored in configuration files.
Please also provide the command needed to store the secret in the Credential Manager.
Based on my main orchestrator, Invoke-FileGuardian, create a comprehensive user guide that explains the structure and workflow in detail. The guide should provide step-by-step instructions for effective usage, with a professional layout featuring clear headings, subheadings and sections. Include examples illustrating typical usage scenarios, along with notes, tips and best practices to enhance understanding. Make sure to clearly explain all parameters, inputs and outputs. Including the data structures, so that the guide is readable and accessible for both beginners and advanced technical users.
How to implement a restore process for full and incremental backups. Focus on explaining the overall workflow.
Refactor the tests to dot-source dependencies instead of importing modules for .ps1 files.
AI tools were used to assist with this project, as referenced in the links and VS Code prompts above. All content produced with AI was carefully reviewed to ensure full understanding and accuracy. Most of the comment-based help, was initially generated with the help of auto-completion, but every section was thoroughly read and verified. While pushing in VS Code, the 'Generate Commit Message' feature was used.
FileGuardian includes comprehensive test coverage using Pester.
CI/CD:
Automated testing runs via GitHub Actions on every push to feature/*, fix/*, improvement/* and main branches, with results published as test artifacts.
Youmni Malha
@Youmni