From e19340c99da7e0c6304b6de65954ae7d8cde52a2 Mon Sep 17 00:00:00 2001
From: webbrain-one <295484252+webbrain-one@users.noreply.github.com>
Date: Tue, 28 Jul 2026 10:29:36 +0300
Subject: [PATCH] docs: add README

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a75b31
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# hvICE
+
+hvICE is a research project focused on kernel memory introspection and protection using **libVMI**. It provides a set of tools to monitor kernel text and read-only data for unauthorized modifications, as well as a collection of "Icebreaker" kernel modules designed to test and bypass such protections.
+
+## Features
+
+- **Memory Introspection**: Uses libVMI to set EPT (Extended Page Table) write protections on kernel text (`_text` to `_etext`) and read-only data.
+- **Violation Detection**: Detects and pauses the VM when a write attempt is made to protected kernel memory, distinguishing between legitimate kernel self-modifications and potential attacks.
+- **Analysis Tools**: Includes a helper module to find kernel GVA/GPA ranges and generate configuration offsets for libVMI.
+- **Icebreaker Suite**: A collection of kernel modules that attempt to bypass memory protections using various techniques:
+    - **CR0 Manipulation**: Disabling the write-protect bit in the `CR0` register.
+    - **PTE Manipulation**: Directly flipping write-protection bits in Page Table Entries.
+    - **KASLR Spoofing**: Manipulating page tables to spoof the kernel's KASLR offset to confuse introspection tools.
+
+## Components
+
+### 1. hvICE Main (`ICE.c`)
+The core userspace application that interfaces with libVMI. It:
+- Connects to a target VM domain.
+- Identifies kernel text and rodata ranges via symbols.
+- Sets EPT write violations on those ranges.
+- Listens for events and pauses the VM upon a violation.
+
+### 2. find_ranges (`find_ranges/`)
+A kernel module used to identify the exact Guest Virtual Addresses (GVA) and Guest Physical Addresses (GPA) of the kernel code and essential `task_struct` offsets required for libVMI configuration.
+
+### 3. Icebreaker (`icebreaker/`)
+A suite of "adversarial" modules:
+- **cr0_write_test**: Tests the ability to overwrite the system call table by disabling `CR0.WP`.
+- **KASLR_spoof**: Attempts to trick libVMI's KASLR detection by allocating dummy pages at a spoofed kernel text start address.
+
+## Installation & Usage
+
+### Prerequisites
+- **libVMI**: Installed and configured on the host machine.
+- **KVM/Xen**: A supported hypervisor with VMI capabilities.
+- **Kernel Headers**: Matching headers for the target guest kernel to compile the modules.
+
+### Running hvICE
+1. Compile `ICE.c` linking against `libvmi` and `glib`.
+2. Run the binary providing the target domain name:
+   ```bash
+   ./ICE <domain_name>
+   ```
+
+### Using find_ranges
+1. Compile the kernel module in `find_ranges/`.
+2. Load the module into the guest:
+   ```bash
+   insmod find_ranges.ko
+   ```
+3. Check `dmesg` for the generated libVMI configuration and kernel address ranges.
+
+### Testing with Icebreaker
+1. Compile the desired module in `icebreaker/`.
+2. Load it into the guest while `hvICE` is monitoring:
+   ```bash
+   insmod KASLR_spoof.ko
+   ```
+3. Observe the output of the `ICE` application to see if the memory violation was detected.