Metadata-Version: 2.5
Name: agenticvulhunter
Version: 1.1.2
Summary: AgenticVulHunter secure code review tool
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# AgenticVulHunter

AgenticVulHunter is a four-stage secure code review tool. It reviews your current Git changes and reports security issues that pass the validation threshold.

## Step 1: Install

Install AgenticVulHunter using:

```bash
pipx install agenticvulhunter
```

## Step 2: LLM Setup

You only need:

* Endpoint
* API key
* Model

You can configure them using `avh_setup.toml` or environment variables.

### Option 1: avh_setup.toml

Create `avh_setup.toml` inside the repository you want to review:

```toml
[llm]

endpoint = "http://localhost:11434/v1"
api_key = ""
model = "qwen3-coder:30b"
```

### Option 2: Environment Variables

```bash
export AVH_ENDPOINT="http://localhost:11434/v1"
export AVH_API_KEY="your-key"
export AVH_MODEL="qwen3-coder:30b"
```

Environment variables take priority over `avh_setup.toml`.

## Step 3: Run

Run AgenticVulHunter inside your Git repository:

```bash
agenticvulhunter review
```

The terminal shows live progress for all four review stages. BM25 retrieval runs
internally against the packaged static rule corpus, but is kept out of the user
interface to avoid mixing internal ranking signals with validated findings.

The visible workflow follows the research pipeline:

1. Select potentially vulnerable changed lines.
2. Build repository knowledge around each line.
3. Search for matching CWE knowledge.
4. Validate the evidence and apply the requested threshold.

Every accepted finding also includes a repository-verified attack path. Source,
propagation, control, and sink citations are checked against the referenced code
before the finding is shown. If a citation or path link is inconsistent, the
validator automatically sends a focused follow-up prompt; incomplete paths are
kept in the run artifacts but are not promoted to findings.

The initial result shows the review and a small suggested code fix. In an
interactive terminal, enter a finding number to reveal only its plain-language
attack path, or press Enter to finish. Suggested fixes are never applied
automatically.

To reopen the most recent result later, run:

```bash
agenticvulhunter findings
```

To browse all previous reviews, their findings, attack-path trees, diffs, stage
artifacts, and logs in the terminal, run:

```bash
agenticvulhunter runs
```

Choose a run and finding by number. Source locations are clickable in terminals
that support hyperlinks; `d`, `a`, `s1`–`s4`, and `l` open the reviewed diff,
annotated diff, individual pipeline stages, and run log respectively.

The default validation threshold is `0.6`.

To use another threshold:

```bash
agenticvulhunter review 0.7
```
