Metadata-Version: 2.4
Name: kalibur
Version: 0.1.6
Summary: The AI pentesting assistant, built by pentesters for engagement workflows
Author-email: Scapin Ltd <contact@scapin.co.uk>
License: MIT
Project-URL: Homepage, https://kalibur.ai
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.0.0

# kalibur

The AI pentesting assistant, built by pentesters for engagement workflows.

Kalibur helps security professionals move through an engagement from discovery to reporting. Use `kalibur scan` to review a codebase and produce curated whitebox findings, `kalibur audit` to run an interactive blackbox audit against an authorized HTTP(S) target, and `kalibur report` to turn validated findings into a polished client PDF.

Work stays portable across sessions and teammates: `kalibur push` saves your local `kalibur/` workspace, `kalibur pull` restores a previous snapshot, and `kalibur end` cleanly closes an engagement by deleting its associated remote and local data.

## Requirements

- Python 3.9 or later
- A Kalibur API key ([kalibur.ai](https://kalibur.ai))
- Docker Desktop for `kalibur audit`

## Installation

```bash
pip install kalibur
```

Use `pip3` or `python3 -m pip` if `pip` points to Python 2 on your system:

```bash
pip3 install kalibur
# or
python3 -m pip install kalibur
```

If the `kalibur` command is not found after installation, run it as `python3 -m kalibur`.

## Authentication

```bash
kalibur login
```

Prompts for your API key, validates it, and saves it to `~/.config/kalibur/key`. You can also pass `-k <key>` to any command or set the `KALIBUR_API_KEY` environment variable.

## Commands

### `kalibur scan`

Run a whitebox security assessment of a codebase.

```bash
kalibur scan
kalibur scan -t /path/to/project
```

| Flag | Description |
|------|-------------|
| `-t PATH` | Directory to scan (default: `.`) |
| `-k KEY` | API key |

Results are written to a timestamped folder inside a `kalibur/` directory in the scanned project:

```
<target>/kalibur/
  2026-05-03_14-23-45/
    report.md
```

Add `kalibur/` to your `.gitignore` to keep scan output out of version control.

### `kalibur report`

Generate a branded PDF pentest report from a completed `report.md`.

```bash
kalibur report \
  -r ./kalibur/2026-05-03_14-23-45/report.md \
  -f "Scapin Ltd" \
  -a "Jane Doe" \
  -c "Acme Corp" \
  -l ./logo.png \
  -v "1.0"
```

| Flag | Description |
|------|-------------|
| `-r FILE` | Path to `report.md` (required) |
| `-f NAME` | Assessor firm name (required) |
| `-a NAME` | Assessor name (required) |
| `-c NAME` | Client name (required) |
| `-l FILE` | Logo file, `.png` or `.jpg` (required) |
| `-v VER` | Report version, e.g. `1.0` (required) |
| `-d` | Dark theme (default: light) |
| `-k KEY` | API key |

The PDF is saved alongside `report.md` as `report-<timestamp>.pdf`.

Before generating, review findings in `report.md` and set each triage status:

```
# Triage
Status: Open       # finding needs fixing
Status: Accepted   # risk accepted, no fix planned
Status: Resolved   # finding has been fixed
```

### `kalibur audit`

Run an interactive blackbox security audit against an authorized HTTP(S) target.

```bash
kalibur audit -t https://example.com -s program-scope.md -u hackerone_handle
kalibur audit -t http://target.htb -s lab-scope.md -u hackerone_handle -hn target.htb:10.10.11.42
kalibur audit -t https://example.com -s program-scope.md -u hackerone_handle -r
```

| Flag | Description |
|------|-------------|
| `-t URL` | HTTP(S) target, for example `https://example.com` or `http://192.168.1.1` |
| `-s FILE` | Required bug bounty program scope or policy file (`.txt` or `.md`) |
| `-u HANDLE` | Required researcher handle used for program headers and test-account rules |
| `-hn HOST:IP` | Optional host mapping for lab targets, for example `target.htb:10.10.11.42` |
| `-r` | Rebuild the audit sandbox before starting |
| `-k KEY` | API key |

Use only on targets where you have explicit written permission to test. Kalibur
suggests one command at a time and asks for approval before running it in the
sandbox.

Kalibur requires `-s` so every audit starts from explicit written scope. It
extracts the program scope into structured rules and feeds them to the audit
assistant. Header names are extracted from the scope, while `-u` fills researcher
identity placeholders such as `<your-hackerone-handle>`. In-scope and
out-of-scope assets, required researcher headers, rate limits, excluded
vulnerability classes, testing windows, and forbidden actions are treated as
audit constraints.

Kalibur starts a fresh sandbox for every audit run. The built sandbox is reused
when it matches the current tool definition, and rebuilt when the tool definition
changes or when `-r` is passed.

If an unfinished audit exists for the same target, Kalibur asks whether to
continue it or start a new one.

Logs are written to:

```text
./kalibur/audit/<timestamp>/audit.md
./kalibur/audit/<timestamp>/map.md
./kalibur/audit/<timestamp>/report.md
```

`Ctrl+C`, declined termination, and errors clean up the active sandbox before
exiting.

### `kalibur push`

Save a snapshot of your local `kalibur/` folder to the cloud.

```bash
kalibur push
```

### `kalibur pull`

Restore a saved snapshot to your local `kalibur/` folder.

```bash
kalibur pull
kalibur pull -e <project>
```

| Flag | Description |
|------|-------------|
| `-e PROJECT` | Project name (skip interactive picker) |

### `kalibur end`

End an engagement and permanently delete all its data: remote scans, snapshots, and the local `kalibur/` folder. This cannot be undone.

```bash
kalibur end
```
