zombocoder · zombocoder · Sep 21, 2025 · Sep 21, 2025 · Sep 21, 2025 · Sep 21, 2025
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,7 @@
 zig-out/
 zig-cache/
 .zig-cache/
+docs/
 
 # OS files
 .DS_Store

diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 
-.PHONY: all build clean test fmt fmt-check download_zig
+.PHONY: all build build-release clean test fmt fmt-check docs download_zig
 
 # Default target
 all: build
@@ -20,6 +20,11 @@ build: download_zig
 	@echo "Building IntegrityZ..."
 	@./zig/zig build
 
+# Build optimized release version
+build-release: download_zig
+	@echo "Building IntegrityZ (Release)..."
+	@./zig/zig build -Doptimize=ReleaseFast
+
 # Clean build artifacts
 clean:
 	@echo "Cleaning build artifacts..."
@@ -42,6 +47,13 @@ fmt-check: download_zig
 	@echo "Checking code formatting..."
 	@./zig/zig fmt --check src/
 
+# Generate documentation
+docs: download_zig
+	@echo "Generating documentation..."
+	@rm -rf docs zig-out/docs
+	@mkdir -p docs
+	@./zig/zig test src/main.zig -femit-docs=docs/ --test-no-exec 2>/dev/null || echo "Documentation generated with warnings"
+
 # Stop the running cluster
 stop:
 	@echo "Stopping IntegrityZ cluster..."
@@ -51,11 +63,13 @@ stop:
 help:
 	@echo "IntegrityZ Makefile targets:"
 	@echo "  make                      - Build the project (same as 'make build')"
-	@echo "  make build                - Build the IntegrityZ binary"
+	@echo "  make build                - Build the IntegrityZ binary (debug)"
+	@echo "  make build-release        - Build optimized release version"
 	@echo "  make clean                - Remove build artifacts and database files"
 	@echo "  make test                 - Run the complete test suite"
 	@echo "  make fmt                  - Format all source code using Zig formatter"
 	@echo "  make fmt-check            - Check if source code is properly formatted"
+	@echo "  make docs                 - Generate documentation"
 	@echo "  make stop                 - Stop the running cluster"
 	@echo "  make download_zig         - Download the Zig compiler if not present"
 	@echo "  make help                 - Display this help message"

diff --git a/README.md b/README.md
@@ -16,6 +16,8 @@ IntegrityZ is a modern alternative to classic tools like Tripwire or AIDE, but w
 - 🧩 **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
 
 ---
 
@@ -26,10 +28,12 @@ IntegrityZ is a modern alternative to classic tools like Tripwire or AIDE, but w
   - File additions / deletions / renames
   - Content changes (via BLAKE3 checksums)
   - Permission / ownership / POSIX metadata changes
-- Export **JSON reports** for integration with other tools
+- Export **JSON reports** with timestamps and checksums for integration
 - **Configuration file support** with include/exclude patterns
-- **Realtime monitoring** with `inotify` (Linux), `kqueue` (BSD/macOS), and `ReadDirectoryChangesW` (Windows)
-- Signed **audit logs** to ensure integrity of the monitor itself
+- **Real-time monitoring** with `inotify` (Linux), `kqueue` (BSD/macOS)
+- **HTTP webhook notifications** for instant alerts
+- **Web dashboard** for visualizing integrity reports
+- **Comprehensive test suite** with 169+ unit tests
 
 ---
 
@@ -40,7 +44,13 @@ IntegrityZ is a modern alternative to classic tools like Tripwire or AIDE, but w
 ```bash
 git clone https://github.com/yourname/integrityz.git
 cd integrityz
-zig build -Drelease-safe
+make build
+```
+
+Or for optimized release build:
+
+```bash
+make build-release
 ```
 
 Resulting binary will be at:
@@ -69,10 +79,10 @@ integrityz check
 integrityz check --json /etc /usr/bin
 ```
 
-**Watch for changes (realtime):**
+**Watch for changes (real-time monitoring):**
 
 ```bash
-integrityz watch
+integrityz watch /etc /usr/bin
 ```
 
 **Manage configuration:**
@@ -107,7 +117,7 @@ integrityz check --json > report.json
 ```bash
 integrityz init <paths...>        # Create baseline for specified paths
 integrityz check [--json] [paths] # Check filesystem against baseline
-integrityz watch                  # Watch for realtime changes (not yet implemented)
+integrityz watch [paths]          # Watch for real-time changes with webhooks
 integrityz config [--init]        # Show or initialize configuration
 ```
 
@@ -134,10 +144,19 @@ exclude=*.log
 exclude=.git/*
 exclude=node_modules/*
 
-# Other settings
+# 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
@@ -149,20 +168,33 @@ default_scan_path=/usr/bin
 
 ```json
 {
-  "added": ["/etc/new.conf"],
-  "deleted": ["/etc/unused.conf"],
-  "modified": [
+  "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",
-      "old_checksum": "a1b2c3...",
-      "new_checksum": "d4e5f6..."
-    }
-  ],
-  "meta_changed": [
+      "details": "Content changed (checksum mismatch); Size changed from 1024 to 1152 bytes",
+      "old_checksum": "a1b2c3d4e5f6789...",
+      "new_checksum": "d4e5f6a1b2c3789..."
+    },
     {
-      "path": "/etc/passwd",
-      "old_mode": "0644",
-      "new_mode": "0666"
+      "type": "deleted",
+      "path": "/etc/unused.conf",
+      "details": "File deleted",
+      "old_checksum": null,
+      "new_checksum": null
     }
   ]
 }
@@ -174,10 +206,15 @@ default_scan_path=/usr/bin
 
 ```
 integrityz/
-├── src/         # Core Zig modules
-├── tests/       # Unit & integration tests
-├── docs/        # Technical docs, design notes
-├── build.zig    # Zig build script
+├── 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
+├── web-dashboard/   # Visualization dashboard
+├── build.zig        # Zig build script with comprehensive tests
+├── Makefile         # Build automation
 └── README.md
 ```
 
@@ -188,9 +225,49 @@ integrityz/
 - [x] MVP: Baseline + scan + JSON report
 - [x] Configuration file support with patterns
 - [x] Web dashboard for JSON report visualization
-- [ ] Windows platform support
-- [ ] HTTP webhook integration for 3rd party systems
-- [ ] Realtime monitoring (inotify/kqueue/Windows API)
+- [x] HTTP webhook integration for 3rd party systems
+- [x] Real-time monitoring (inotify/kqueue)
+- [x] Comprehensive test suite (169+ tests)
+- [x] Enhanced JSON reports with timestamps and checksums
+- [ ] Windows platform support (ReadDirectoryChangesW)
+- [ ] Performance optimization for large filesystems
+
+---
+
+## 🧪 Testing & Development
+
+IntegrityZ includes a comprehensive test suite with 169+ unit tests covering all modules:
+
+### Run Tests
+
+```bash
+# 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
+- **All core modules**: Crypto, records, database, scanner, utilities
+
+### Available Make Targets
+
+```bash
+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
+```
 
 ---
 

diff --git a/build.zig b/build.zig
@@ -51,6 +51,7 @@ pub fn build(b: *std.Build) void {
         "src/checker.zig", // Integrity checking logic and tests
         "src/reporter.zig", // Reporting and output formatting tests
         "src/config.zig", // Configuration parsing and validation tests
+        "src/watcher.zig", // Filesystem watching and monitoring tests
     };
 
     // Create test step that runs all unit tests across modules