---
title: How it works
description: A persistent security index tells the hacker exactly what changed. It ranks what to attack, but never decides what to skip.
---

Every review runs the same four-stage loop. The first stage is deterministic code; the rest is an agent working inside a sandbox that holds your code and nothing else.

## 1. Index

`ghh-index` reads the repository without running it and records security facts: entry points and the guards on them, untrusted sources, dangerous sinks and the call paths between them, what each module is capable of, and supply-chain facts from lockfiles and CI config.

The index persists between runs. On a new commit it only re-reads changed files, so a review starts from a full map of the repo in seconds.

## 2. Diff

Instead of a raw text diff, grayhat compares the index before and after the change and ranks what moved in security terms:

```json
{
  "kind": "guard_removed",
  "route": "GET /invoices/:id",
  "guard": "requireOwner",
  "reach": "authenticated",
  "rank": 0.97
}
```

A removed guard, a new route that reaches a sink, a dependency that gained network access: each becomes a first-class event at the top of the target list.

:::note
**Prioritize, never gate.** The index decides what to look at first, never what to skip. Many real bugs have no sink, so everything not provably harmless still gets read.
:::

## 3. Hunt

An open-weight model with its refusal training removed reads the ranked targets and writes exploits for them: IDORs, broken auth, races, business-logic abuse. A second, skeptical pass throws out anything it can't justify.

Then it boots your app in an isolated virtual machine and runs each exploit. A lead becomes a finding only if the attack works.

## 4. Fix

For each confirmed finding, grayhat writes a patch and re-runs two checks in the same sandbox:

| Check | Must be |
| --- | --- |
| The original exploit | Failing |
| Your test suite | Passing |

Only then does the fix PR open. If either check fails, you still get the finding and its reproduction, without a patch.