🔒 IntegrityZ

IntegrityZ is a cross-platform filesystem integrity monitoring tool written in Zig.
It detects unauthorized changes to files, permissions, and metadata — helping you secure your system against tampering, malware, and insider threats.

IntegrityZ is a modern alternative to classic tools like Tripwire or AIDE, but with:

• ⚡ BLAKE3 hashing with adaptive buffer sizing for ultra-fast checksum validation
• 🚀 Performance optimizations including parallel scanning and string pooling
• 🧩 Modular design with clear CLI commands
• 📊 JSON output support for automation and integration
• 🖥️ Cross-compilation (build once, run anywhere)
• 👁️ Real-time monitoring with filesystem events (inotify/kqueue)
• 🔗 Webhook integration for instant notifications

---

✨ Features

• Create a baseline snapshot of directories
• Detect:
  • File additions / deletions / renames
  • Content changes (via BLAKE3 checksums)
  • Permission / ownership / POSIX metadata changes
• Export JSON reports with timestamps and checksums for integration
• Configuration file support with include/exclude patterns
• Real-time monitoring with inotify (Linux), kqueue (BSD/macOS)
• HTTP webhook notifications for instant alerts
• Web dashboard for visualizing integrity reports
• Performance optimizations for large filesystems:
  • Adaptive buffer sizing based on storage type (SSD/HDD/Network)
  • Parallel directory traversal with worker pools
  • String interning for memory optimization
  • Batched database I/O operations
• Comprehensive test suite with 190+ unit tests

---

🚀 Getting Started

Build

git clone https://github.com/zombocoder/IntegrityZ.git
cd integrityz
make build

Or for optimized release build:

make build-release

Resulting binary will be at:

./zig-out/bin/integrityz

Basic Usage

Initialize baseline:

integrityz init /etc /usr/bin

Check filesystem:

integrityz check

Check specific paths with JSON output:

integrityz check --json /etc /usr/bin

Watch for changes (real-time monitoring):

integrityz watch /etc /usr/bin

Manage configuration:

# Show current configuration
integrityz config

# Create default configuration file
integrityz config --init

Visualize results with the web dashboard:

# Generate JSON report
integrityz check --json > report.json

# Option 1: Use the live dashboard
# Visit https://integrityz.linkzip.app and drag your report.json file

# Option 2: Use locally
# Open web-dashboard/index.html in browser and drag the report file

---

📋 CLI Commands

Available Commands

integrityz init <paths...>        # Create baseline for specified paths
integrityz check [--json] [paths] # Check filesystem against baseline
integrityz watch [paths]          # Watch for real-time changes with webhooks
integrityz config [--init]        # Show or initialize configuration

Command Options

• --json - Output results in JSON format for automation
• --init - Create default configuration file

Configuration File

IntegrityZ supports configuration via integrityz.conf:

# IntegrityZ Configuration File
baseline_path=integrityz.db

# Include patterns (glob style)
include=*.conf
include=/etc/*

# Exclude patterns (glob style)  
exclude=*.tmp
exclude=*.log
exclude=.git/*
exclude=node_modules/*

# File scanning settings
max_file_size=0
follow_symlinks=false

# Webhook settings for real-time notifications
webhook_url=https://your-webhook-endpoint.com/integrityz
webhook_timeout=30

# Watch mode settings
watch_check_interval=5
watch_max_event_batch=10
watch_recursive=true

# Default paths to scan if none specified
default_scan_path=/etc
default_scan_path=/usr/bin

---

📊 Example Report

{
  "timestamp": 1727777284,
  "has_changes": true,
  "total_files_checked": 1250,
  "baseline_records": 1248,
  "current_records": 1250,
  "changes_count": 3,
  "changes": [
    {
      "type": "added",
      "path": "/etc/new.conf",
      "details": "File added",
      "old_checksum": null,
      "new_checksum": null
    },
    {
      "type": "modified",
      "path": "/usr/bin/ssh",
      "details": "Content changed (checksum mismatch); Size changed from 1024 to 1152 bytes",
      "old_checksum": "a1b2c3d4e5f6789...",
      "new_checksum": "d4e5f6a1b2c3789..."
    },
    {
      "type": "deleted",
      "path": "/etc/unused.conf",
      "details": "File deleted",
      "old_checksum": null,
      "new_checksum": null
    }
  ]
}

---

🛠 Project Structure

integrityz/
├── src/             # Core Zig modules
│   ├── main.zig     # CLI entry point
│   ├── watcher.zig  # Real-time filesystem monitoring
│   ├── checker.zig  # Integrity checking logic
│   ├── reporter.zig # JSON reporting with timestamps
│   ├── config.zig   # Configuration management
│   ├── crypto.zig   # BLAKE3 hashing with adaptive optimizations
│   ├── scanner.zig  # Parallel filesystem scanning
│   ├── string_pool.zig # String interning for memory optimization
│   └── database.zig # Batched I/O operations
├── web-dashboard/   # Visualization dashboard
├── build.zig        # Zig build script with comprehensive tests
├── Makefile         # Build automation
└── README.md

---

📅 Roadmap

• [x] MVP: Baseline + scan + JSON report
• [x] Configuration file support with patterns
• [x] Web dashboard for JSON report visualization
• [x] HTTP webhook integration for 3rd party systems
• [x] Real-time monitoring (inotify/kqueue)
• [x] Comprehensive test suite (190+ tests)
• [x] Enhanced JSON reports with timestamps and checksums
• [x] Performance optimization for large filesystems
  • [x] Adaptive buffer sizing based on storage type detection
  • [x] Parallel directory traversal with configurable worker pools
  • [x] String interning and memory pooling for path optimization
  • [x] Batched database I/O operations
  • [x] Large file handling optimizations
• [ ] Windows platform support (ReadDirectoryChangesW)
• [ ] Advanced performance profiling and benchmarking tools

---

🧪 Testing & Development

IntegrityZ includes a comprehensive test suite with 190+ unit tests covering all modules:

Run Tests

# Run all tests
make test

# Run tests for specific modules
./zig/zig test src/watcher.zig
./zig/zig test src/checker.zig
./zig/zig test src/config.zig

Test Coverage

• watcher.zig: Real-time monitoring, event handling, webhook integration
• checker.zig: Integrity comparison, consolidated change detection
• reporter.zig: JSON generation, timestamp handling, checksum formatting
• config.zig: Configuration parsing, webhook settings, memory management
• crypto.zig: Adaptive hashing, storage type detection, buffer optimization
• scanner.zig: Parallel traversal, worker pools, string pooling integration
• string_pool.zig: String interning, path optimization, memory management
• database.zig: Batched I/O operations, performance optimization
• All core modules: Records, baseline management, utilities

Available Make Targets

make build           # Debug build
make build-release   # Optimized release build  
make test           # Run comprehensive test suite
make clean          # Clean build artifacts
make fmt            # Format source code
make fmt-check      # Check code formatting

---

🤝 Contributing

Pull requests are welcome! Please open an issue first to discuss major changes. This project is in early development — design discussions are encouraged.