{"id":25399128,"url":"https://github.com/kaalpanikh/file-integrity-checker","last_synced_at":"2026-05-04T05:31:27.342Z","repository":{"id":277528291,"uuid":"932690872","full_name":"kaalpanikh/file-integrity-checker","owner":"kaalpanikh","description":"A Python-based file integrity checker using SHA-256 to detect unauthorized modifications and ensure data security","archived":false,"fork":false,"pushed_at":"2025-02-14T11:51:06.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-14T12:29:03.197Z","etag":null,"topics":["cli-tool","cryptography","cybersecurity","file-integrity","file-monitoring","hash-verification","python","security","sha256","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaalpanikh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-14T10:43:27.000Z","updated_at":"2025-02-14T12:05:33.000Z","dependencies_parsed_at":"2025-02-14T12:29:21.180Z","dependency_job_id":"3aced14f-7988-4519-9cae-91e7ec411f57","html_url":"https://github.com/kaalpanikh/file-integrity-checker","commit_stats":null,"previous_names":["kaalpanikh/file-integrity-checker"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaalpanikh%2Ffile-integrity-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaalpanikh%2Ffile-integrity-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaalpanikh%2Ffile-integrity-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaalpanikh%2Ffile-integrity-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaalpanikh","download_url":"https://codeload.github.com/kaalpanikh/file-integrity-checker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248412093,"owners_count":21099048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli-tool","cryptography","cybersecurity","file-integrity","file-monitoring","hash-verification","python","security","sha256","yaml"],"created_at":"2025-02-15T23:29:14.841Z","updated_at":"2026-05-04T05:31:22.316Z","avatar_url":"https://github.com/kaalpanikh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# File Integrity Checker\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.8%2B-blue\" alt=\"Python Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/security-SHA--256-orange\" alt=\"Security\"\u003e\n\u003c/div\u003e\n\n## 📖 Project Description\n\nA robust command-line tool for monitoring and verifying file integrity using cryptographic hashing. This security tool helps detect unauthorized modifications to files by maintaining and comparing SHA-256 hashes.\n\n### 🎯 Project Goals\n\n- Learn about cryptographic hashing and file integrity verification\n- Implement secure file monitoring system\n- Understand CLI application development in Python\n- Practice secure coding and data storage\n\n### 🔍 Project Source\n\nThis project is based on the [File Integrity Checker](https://roadmap.sh/projects/file-integrity-checker) from roadmap.sh's project collection.\n\n## 🛠️ Technologies Used\n\n- **Python**: Core programming language\n- **Click**: CLI framework for command handling\n- **PyYAML**: YAML-based hash storage\n- **hashlib**: Cryptographic hash functions\n- **pathlib**: File system operations\n\n## 🎯 Features\n\n- **File \u0026 Directory Support**: Process individual files or entire directories\n- **SHA-256 Hashing**: Industry-standard cryptographic hash function\n- **Secure Storage**: YAML-based persistent hash storage\n- **Change Detection**: Accurate identification of file modifications\n- **Clear Reporting**: User-friendly status messages\n- **Manual Updates**: Support for legitimate file changes\n\n## 🏗️ Architecture\n\n```mermaid\nflowchart TD\n    subgraph User[\"User Interface\"]\n        A[User Input] --\u003e B[CLI Interface]\n        B --\u003e C{Command Router}\n    end\n\n    subgraph Commands[\"Command Processing\"]\n        C --\u003e|\"init\"| D[Hash Calculator]\n        C --\u003e|\"check\"| E[Hash Verifier]\n        C --\u003e|\"update\"| F[Hash Updater]\n    end\n\n    subgraph Storage[\"Data Management\"]\n        G[(Hash Storage)]\n        H[YAML File\u003cbr/\u003e.file_hashes.yml]\n    end\n\n    subgraph FileOps[\"File Operations\"]\n        I[File Reader] --\u003e J[Binary Processing]\n        J --\u003e K[Chunk Handler\u003cbr/\u003e4KB blocks]\n    end\n\n    D --\u003e I\n    E --\u003e I\n    F --\u003e I\n    K --\u003e D\n    K --\u003e E\n    K --\u003e F\n    D --\u003e G\n    E --\u003e G\n    F --\u003e G\n    G \u003c--\u003e H\n\n    style User fill:#f9f,stroke:#333,stroke-width:2px\n    style Commands fill:#bbf,stroke:#333,stroke-width:2px\n    style Storage fill:#bfb,stroke:#333,stroke-width:2px\n    style FileOps fill:#fbb,stroke:#333,stroke-width:2px\n```\n\nKey Components:\n1. **User Interface Layer**:\n   - Handles user input through CLI\n   - Parses commands using Click framework\n   - Routes commands to appropriate handlers\n\n2. **Command Processing Layer**:\n   - Init: Creates initial file hashes\n   - Check: Verifies file integrity\n   - Update: Refreshes stored hashes\n\n3. **File Operations Layer**:\n   - Reads files in binary mode\n   - Processes in 4KB chunks\n   - Handles large files efficiently\n\n4. **Data Management Layer**:\n   - Stores hashes in YAML format\n   - Manages hash retrieval\n   - Ensures data persistence\n\nData Flow:\n1. User enters command through CLI\n2. Command router directs to appropriate handler\n3. File operations read and process files\n4. Hash calculations performed on file chunks\n5. Results stored in or compared with YAML storage\n6. Status reported back to user\n\n## 📋 Prerequisites\n\n- Python 3.8 or higher\n- pip (Python package manager)\n- Git (optional, for cloning)\n\n## 🚀 Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/kaalpanikh/file-integrity-checker.git\ncd file-integrity-checker\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n3. Make the script executable (Unix-like systems):\n```bash\nchmod +x integrity-check\n```\n\n## 💻 Usage\n\n### Basic Commands\n\n```bash\n# Initialize file/directory hashes\n./integrity-check init \u003cpath\u003e\n\n# Check file/directory integrity\n./integrity-check check \u003cpath\u003e\n\n# Update file hash after legitimate changes\n./integrity-check update \u003cpath\u003e\n```\n\n### Example Workflow\n\n```bash\n# Initialize a directory\n./integrity-check init /var/log\n\u003e Hashes stored successfully.\n\n# Check a specific file\n./integrity-check check /var/log/syslog\n\u003e Status: Modified (Hash mismatch)\n\n# Update after legitimate changes\n./integrity-check update /var/log/syslog\n\u003e Hash updated successfully.\n```\n\n## 📁 Project Structure\n\n```\nfile-integrity-checker/\n├── integrity_checker.py  # Main implementation\n├── integrity-check      # Executable script\n├── requirements.txt     # Project dependencies\n├── README.md           # Project documentation\n├── DEVELOPMENT_GUIDE.md # Detailed development guide\n└── .file_hashes.yml    # Hash storage (created on first run)\n```\n\n## 🔒 Security Features\n\n1. **Cryptographic Security**\n   - SHA-256 hashing algorithm\n   - Collision resistance\n   - Pre-image resistance\n\n2. **Safe File Operations**\n   - Binary mode file reading\n   - Chunk-based processing\n   - Path validation\n\n3. **Secure Storage**\n   - Local YAML storage\n   - No network transmission\n   - Clear error reporting\n\n## 📚 Learning Outcomes\n\n1. **Cryptography**\n   - Hash function properties\n   - Data integrity verification\n   - Security considerations\n\n2. **Python Development**\n   - CLI application creation\n   - File system operations\n   - Type hints and documentation\n\n3. **Best Practices**\n   - Modular code organization\n   - Error handling\n   - Security-first thinking\n\n## 🔄 Development Workflow\n\n1. **Setup Environment**\n   - Install Python 3.8+\n   - Install dependencies\n   - Configure development tools\n\n2. **Implementation**\n   - Core hash functions\n   - CLI commands\n   - Storage management\n\n3. **Testing**\n   - Functionality testing\n   - Edge case handling\n   - Security validation\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit pull requests.\n\n1. Fork the repository\n2. Create your feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Additional Resources\n\n- [Project Requirements](https://roadmap.sh/projects/file-integrity-checker)\n- [Python hashlib Documentation](https://docs.python.org/3/library/hashlib.html)\n- [Click Documentation](https://click.palletsprojects.com/)\n- [PyYAML Documentation](https://pyyaml.org/wiki/PyYAMLDocumentation)\n\n## 👤 Author\n\nNikhil Mishra (@kaalpanikh)\n\n## 🙏 Acknowledgments\n\n- [roadmap.sh](https://roadmap.sh) for the project idea and requirements\n- Python community for excellent libraries and tools\n- Contributors and users of this project\n\n## 🔍 Proof of Implementation\n\n### Test Scenario 1: Basic File Monitoring\n```bash\n# Create a test file\n$ echo \"This is a test file to demonstrate the file integrity checker.\" \u003e test.txt\n\n# Initialize the hash\n$ python integrity_checker.py init test.txt\n\u003e Hashes stored successfully.\n\n# Verify the file (unmodified)\n$ python integrity_checker.py check test.txt\n\u003e Status: Unmodified\n```\n\n### Test Scenario 2: Hash Storage Format\nLet's examine our `.file_hashes.yml` file after initialization:\n```yaml\n# Content of .file_hashes.yml\ntest.txt: \"d5579c46dfcc7f18207013e65b44e4cb4e2c2298f4ac457ba8f82743f31e930b\"\n```\nThis shows:\n- Relative path storage for portability\n- Full SHA-256 hash (64 characters)\n- YAML format for readability\n\n### Test Scenario 3: Project Structure\n```bash\nfile-integrity-checker/\n├── integrity_checker.py     # Main implementation\n├── integrity-check         # Executable script\n├── requirements.txt        # Dependencies\n├── README.md              # Documentation\n├── DEVELOPMENT_GUIDE.md   # Development details\n├── FIRST_PRINCIPLES.md    # Beginner's guide\n├── LICENSE                # MIT License\n└── .file_hashes.yml      # Hash storage\n```\n\n### Implementation Details\n\n1. **Dependencies**\n```python\n# From requirements.txt\nclick==8.1.7      # CLI framework\npathlib==1.0.1    # File operations\nPyYAML==6.0.1     # Hash storage\n```\n\n2. **Core Hash Function**\n```python\ndef calculate_file_hash(file_path: str) -\u003e str:\n    sha256_hash = hashlib.sha256()\n    with open(file_path, \"rb\") as f:\n        for byte_block in iter(lambda: f.read(4096), b\"\"):\n            sha256_hash.update(byte_block)\n    return sha256_hash.hexdigest()\n```\n\n### Security Features\n1. **Cryptographic Security**\n   - SHA-256 hashing algorithm\n   - 256-bit (32-byte) hash length\n   - Collision-resistant design\n\n2. **File Handling**\n   - Binary mode file reading\n   - Chunk-based processing (4KB blocks)\n   - Safe file path handling\n\n3. **Data Storage**\n   - Human-readable YAML format\n   - Local file system storage\n   - Path-based organization\n\n### Verified Capabilities\n1. ✅ **File Operations**\n   - Create and read files\n   - Process binary content\n   - Handle various file sizes\n\n2. ✅ **Hash Management**\n   - Generate SHA-256 hashes\n   - Store hashes securely\n   - Compare hash values\n\n3. ✅ **User Interface**\n   - Clear command structure\n   - Informative status messages\n   - Error handling\n\n4. ✅ **Documentation**\n   - Comprehensive README\n   - Development guide\n   - First principles explanation\n\nThese test results demonstrate that our implementation successfully meets all project requirements from [roadmap.sh](https://roadmap.sh/projects/file-integrity-checker) while maintaining security and usability.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaalpanikh%2Ffile-integrity-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaalpanikh%2Ffile-integrity-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaalpanikh%2Ffile-integrity-checker/lists"}