# rhoexploit

**Repository Path**: williamoxton/rhoexploit

## Basic Information

- **Project Name**: rhoexploit
- **Description**: rhoexploit
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rhoexploit

- `memconfig/`: repo-level DRAM memconfig loader, physical-address translator, preset catalog, and CLI
- `llm-fuzzer/`: Python-side pattern generation, mutation, orchestration, result aggregation, and analysis
- `exploit/`: C++ execution engine, configuration, kernel module, and low-level attack/testing code
- `sync_test/`: standalone sync interval experiment runner
- `sbdr_timing/`: standalone SBDR timing, threshold calibration, and memconfig-check runners

## Repository Layout

### `memconfig/`

This directory is the shared source of truth for DRAM geometry in the repo.

Important files:

- `config.json`: repo-root memconfig source used by new shared tooling
- `memconfig/presets.json`: built-in preset catalog
- `memconfig/src/memconfig.cpp`: loader and address-translation implementation
- `memconfig/src/memconfig_translate.cpp`: local CLI for translating physical addresses

### `llm-fuzzer/`

This directory is responsible for:

- defining the hammer pattern format
- writing `runtime/pattern.json`
- launching `exploit/build/rhohammer_exploit`
- driving the C++ daemon via the `READY -> RUN -> DONE` protocol
- reading `runtime/result.json`
- merging outputs into `runtime/result_context.json`

Important files:

- `HammerPattern.py`: pattern data model with the `tuples + schedule` contract
- `Hammerer.py`: Python-to-C++ execution bridge
- `workflow.py`: recommended modular CLI entry point for generation, mutation, execution, analysis, and experiment loops
- `main.py`: single-run entry point for quick end-to-end validation
- `Mutator.py` and `mutation_tools.py`: mutation logic and tool-backed transformations
- `analyze_result_context.py`, `draw_patterns.py`, `draw_result_context.py`: post-processing and visualization helpers

For more detail on the Python workflow, see `llm-fuzzer/README.md`.

### `exploit/`

This directory is responsible for:

- reading configuration and pattern files
- executing hammer tests in `batch_templating_daemon` mode
- writing raw bit-flip results
- providing the kernel module, configuration tooling, and low-level implementation

Important files:

- `src/CLI.cpp`: C++ command dispatch entry point
- `src/llm_tools.cpp`: batch execution logic used by the Python workflow
- `config.json`: runtime configuration source
- `scripts/generate_input_define.py`: generates compile-time header values
- `rho_mod/`: kernel module source and build artifacts

## Default Execution Flow

The main closed loop currently looks like this:

1. Python writes `llm-fuzzer/runtime/pattern.json`.
2. `Hammerer.py` launches `exploit/build/rhohammer_exploit`.
3. The C++ side runs `batch_templating_daemon` and reads the pattern file.
4. The C++ side writes `llm-fuzzer/runtime/result.json`.
5. Python merges patterns and results into `llm-fuzzer/runtime/result_context.json`.

The subprocess protocol depends on three signals:

- `READY`
- `RUN`
- `DONE`

If any of those steps fail, the automation chain is broken.

## Quick Start

### 1. Set the repo memconfig

Before running `sync_test` or `memconfig_translate`, set the repo-root `config.json` for the current machine.

Preset example:

```json
{
  "memconfig": {
    "preset": "zen5_ddr5_32g_1ch_1d_2r_32b"
  }
}
```

Custom-definition example:

```json
{
  "memconfig": {
    "definition": {
      "bank_func_mask": ["0x88989000", "0x44448000", "0x22223000", "0x11008000", "0x2800"],
      "sub_chan_mask": [],
      "row_shift": 18,
      "row_mask": "0xffff",
      "col_shift": 0,
      "col_mask": "0x1fff",
      "total_size": "0x400000000"
    }
  }
}
```

### 2. Build the C++ engine

```bash
cd exploit
mkdir -p build
cd build
cmake ..
make -j"$(nproc)"
```

### 3. Verify required files

At minimum, confirm these paths exist:

- `config.json`
- `exploit/build/rhohammer_exploit`
- `exploit/config.json`
- `llm-fuzzer/runtime/pattern.json`

### 4. Run one batch end to end

```bash
cd llm-fuzzer
sudo python3 main.py
```

This entry point will:

- start the C++ daemon
- read the current `runtime/pattern.json`
- generate `runtime/result.json`
- append aggregated results to `runtime/result_context.json`

## Prerequisites and Constraints

- Real execution typically requires `sudo` or root.
- Some flows depend on `exploit/build/` already containing the compiled binary.
- Some experiments depend on `rho_mod` being built and loaded.
- Repo-root `config.json` is the memconfig source for `sync_test` and `memconfig_translate`.
- `exploit/config.json` contains machine-specific settings and should not be assumed portable.
- `llm-fuzzer/runtime/` stores current run artifacts, while `llm-fuzzer/archive/` stores historical snapshots.

## Common Misreadings

- The old root README structure from upstream does not match the current active workspace.
- `llm-fuzzer/` contains core workflow code, analysis helpers, archived data, and some older experimental entry points in the same directory.
- `workflow.py` and `main.py` are the safest starting points; some legacy entry points still depend on optional tooling such as LangGraph.
- File-name casing matters on Linux. Imports around `Mutator.py` were previously a source of breakage.

## Commit Logging

This repository now supports automatic commit-summary logging through a Git `post-commit` hook.

- The hook appends one JSON record per commit to `llm-fuzzer/runtime/commit_log.jsonl`.
- The log is intentionally ignored by Git so that commits do not leave the working tree dirty.
- The hook is activated through the repository-local `core.hooksPath` setting and the tracked `.githooks/` directory.

Useful commands:

```bash
./scripts/setup_git_hooks.sh
python3 llm-fuzzer/summarize_commit_log.py --limit 20
```

## License

See `LICENSE` in the repository root.