Metadata-Version: 2.4
Name: kalibur
Version: 0.1.3
Summary: The AI whitebox 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 whitebox pentesting assistant, built by pentesters for engagement workflows.

Kalibur scans a codebase the way a skilled pentester would: reading every file, tracing data flows from entry points to sinks, and identifying complex exploitable paths across authentication, authorisation, injection, and cryptographic weaknesses. Findings are significantly deeper than what automated scanners surface.

Results land in an editable `report.md`, structured and ready for manual review. Kalibur does not replace the pentester: it handles the time-consuming groundwork so you can focus on validation, context, and client communication. Triage findings, add notes, mark issues resolved. When you are done, `kalibur report` proofreads the content, generates an executive summary, and produces a branded PDF in seconds.

The full engagement lifecycle is covered: save and restore snapshots between sessions or across teammates with `push` and `pull`, and cleanly close out an engagement with `end`, which permanently deletes all associated data.

## Requirements

- Python 3.9 or later
- A Kalibur API key ([kalibur.ai](https://kalibur.ai))

## 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) |
| `-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 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
```
