kalibur 0.1.0__tar.gz

kalibur-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: kalibur
+Version: 0.1.0
+Summary: AI whitebox pentest assistant
+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
+
+AI-powered whitebox security scanner. Run `kalibur scan` against any local codebase.
+
+## Requirements
+
+- Python 3.9 or later
+- A Kalibur API key (get one at kalibur.ai)
+
+## Installation
+
+**macOS**
+```bash
+brew install kalibur
+```
+
+**Linux / Windows**
+```bash
+pip install kalibur
+```
+
+## Usage
+
+```bash
+export KALIBUR_API_KEY=your_api_key
+
+# Scan current directory
+kalibur scan
+
+# Scan a specific directory
+kalibur scan -t /path/to/project
+```
+
+## Configuration
+
+| Flag | Env var | Description |
+|------|---------|-------------|
+| `-k KEY` | `KALIBUR_API_KEY` | API key (required) |
+| `-t PATH` | | Directory to scan (default: `.`) |
+
+## Output
+
+Results are written to a timestamped subfolder inside a `kalibur/` directory in the scanned project:
+
+```
+<target>/kalibur/
+  2026-05-03_14-23-45/
+    report.md
+```
+
+Nothing is written if no findings are detected.
+
+Add `kalibur/` to your `.gitignore` to keep scan output out of version control.
+
+## Generating a PDF report
+
+After reviewing and triaging findings in `report.md`, generate a branded PDF:
+
+```bash
+kalibur report \
+  -r ~/project/kalibur/2026-05-03_14-23-45/report.md \
+  -f "Your Firm" \
+  -c "Client Name" \
+  -a "Your Name" \
+  -l ./logo.png \
+  -v "1.0"
+```
+
+| Flag | Description |
+|------|-------------|
+| `-r FILE` | Path to `report.md` (required) |
+| `-f NAME` | Assessor firm name (required) |
+| `-c NAME` | Client name (required) |
+| `-a NAME` | Assessor name (required) |
+| `-l FILE` | Logo file, `.png` or `.jpg` (required) |
+| `-v VER` | Report version, e.g. `1.0` (required) |
+
+The PDF is saved as `report.pdf` alongside `report.md`. Valid triage statuses in `report.md` are `Open` and `Resolved`.

kalibur-0.1.0/README.md

@@ -0,0 +1,78 @@
+# kalibur
+
+AI-powered whitebox security scanner. Run `kalibur scan` against any local codebase.
+
+## Requirements
+
+- Python 3.9 or later
+- A Kalibur API key (get one at kalibur.ai)
+
+## Installation
+
+**macOS**
+```bash
+brew install kalibur
+```
+
+**Linux / Windows**
+```bash
+pip install kalibur
+```
+
+## Usage
+
+```bash
+export KALIBUR_API_KEY=your_api_key
+
+# Scan current directory
+kalibur scan
+
+# Scan a specific directory
+kalibur scan -t /path/to/project
+```
+
+## Configuration
+
+| Flag | Env var | Description |
+|------|---------|-------------|
+| `-k KEY` | `KALIBUR_API_KEY` | API key (required) |
+| `-t PATH` | | Directory to scan (default: `.`) |
+
+## Output
+
+Results are written to a timestamped subfolder inside a `kalibur/` directory in the scanned project:
+
+```
+<target>/kalibur/
+  2026-05-03_14-23-45/
+    report.md
+```
+
+Nothing is written if no findings are detected.
+
+Add `kalibur/` to your `.gitignore` to keep scan output out of version control.
+
+## Generating a PDF report
+
+After reviewing and triaging findings in `report.md`, generate a branded PDF:
+
+```bash
+kalibur report \
+  -r ~/project/kalibur/2026-05-03_14-23-45/report.md \
+  -f "Your Firm" \
+  -c "Client Name" \
+  -a "Your Name" \
+  -l ./logo.png \
+  -v "1.0"
+```
+
+| Flag | Description |
+|------|-------------|
+| `-r FILE` | Path to `report.md` (required) |
+| `-f NAME` | Assessor firm name (required) |
+| `-c NAME` | Client name (required) |
+| `-a NAME` | Assessor name (required) |
+| `-l FILE` | Logo file, `.png` or `.jpg` (required) |
+| `-v VER` | Report version, e.g. `1.0` (required) |
+
+The PDF is saved as `report.pdf` alongside `report.md`. Valid triage statuses in `report.md` are `Open` and `Resolved`.

kalibur-0.1.0/kalibur/__main__.py

@@ -0,0 +1,320 @@
+import argparse
+import getpass
+import os
+import ssl
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import certifi
+
+from .end import run_end
+from .pull import run_pull
+from .push import run_push, _detect_project
+from .report import run_report
+from .scan import run_scan, print_banner, _USE_COLOR, _DIM, _RESET
+
+API_URL = os.environ.get("KALIBUR_API_URL", "https://kalibur.ai")
+_CONFIG_PATH = Path.home() / ".config" / "kalibur" / "key"
+
+_RED = "\033[31m" if _USE_COLOR else ""
+_RST = "\033[0m" if _USE_COLOR else ""
+
+
+def _error(message: str) -> None:
+    print(f"{_RED}Error: {message}{_RST}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _load_saved_key() -> str | None:
+    try:
+        if _CONFIG_PATH.exists():
+            key = _CONFIG_PATH.read_text().strip()
+            return key if key else None
+    except OSError:
+        pass
+    return None
+
+
+def _resolve_api_key(flag_value: str | None) -> str | None:
+    return flag_value or os.environ.get("KALIBUR_API_KEY") or _load_saved_key()
+
+
+_KEY_ERROR = "No API key found. Run 'kalibur login' to save your key, or pass it with -k <key>."
+
+
+def _print_usage(desc: str, usage: str, flags: list[tuple[str, str]]) -> None:
+    lines: list[tuple[str, str]] = [("Usage:", usage), ("", "")] + flags
+    if _USE_COLOR:
+        print(f"{desc}\n")
+        for flag, desc_text in lines:
+            if flag == "Usage:":
+                print(f"{_DIM}{flag}{_RESET} {desc_text}")
+            elif flag == "":
+                print()
+            else:
+                print(f"  \033[1m{flag}{_RESET}  {desc_text}")
+    else:
+        print(f"{desc}\n")
+        for flag, desc_text in lines:
+            if flag == "":
+                print()
+            elif flag == "Usage:":
+                print(f"{flag} {desc_text}")
+            else:
+                print(f"  {flag}  {desc_text}")
+    print()
+
+
+_KEY_FLAG = ("-k", "Kalibur API key (overrides saved key and KALIBUR_API_KEY)")
+_PROJECT_FLAG = ("-e", "Project name (skip interactive picker)")
+
+_COMMAND_HELP: dict[str, tuple[str, str, list[tuple[str, str]]]] = {
+    "login": (
+        "Save your Kalibur API key locally so you do not need to pass -k or set KALIBUR_API_KEY on every command.",
+        "kalibur login",
+        [],
+    ),
+    "scan": (
+        "Analyse the codebase in the current directory for security vulnerabilities. Kalibur thinks like an attacker, finds complex exploitable paths most scanners would miss, and generates a full markdown report ready for manual validation.",
+        "kalibur scan [-t <path>] [-k <key>]",
+        [
+            ("-t", "Directory to scan (default: .)"),
+            _KEY_FLAG,
+        ],
+    ),
+    "report": (
+        "Generate a PDF pentest report from a completed report.md. Kalibur proofreads the findings, generates a relevant executive summary automatically, and produces a client-ready branded PDF.",
+        "kalibur report -r <report.md> -f <firm> -a <assessor> -c <client> -l <logo> -v <version>",
+        [
+            ("-r", "Path to report.md"),
+            ("-f", "Assessor firm name"),
+            ("-a", "Assessor name"),
+            ("-c", "Client name"),
+            ("-l", "Logo file (.png or .jpg)"),
+            ("-v", "Report version (e.g. 1.0)"),
+            _KEY_FLAG,
+        ],
+    ),
+    "push": (
+        "Save a snapshot of your local ./kalibur/ folder. Use this to back up your local edits between sessions or share them with teammates.",
+        "kalibur push [-k <key>]",
+        [_KEY_FLAG],
+    ),
+    "pull": (
+        "Restore a previously saved snapshot to your local ./kalibur/ folder. Useful for resuming work on another machine or recovering a backup.",
+        "kalibur pull [-e <project>] [-k <key>]",
+        [_PROJECT_FLAG, _KEY_FLAG],
+    ),
+    "end": (
+        "End an engagement and permanently delete all its data: remote scans, findings, snapshots, and the local ./kalibur/ folder. This cannot be undone.",
+        "kalibur end [-e <project>] [-k <key>]",
+        [_PROJECT_FLAG, _KEY_FLAG],
+    ),
+}
+
+
+def _print_report_usage() -> None:
+    desc, usage, flags = _COMMAND_HELP["report"]
+    _print_usage(desc, usage, flags)
+
+
+def _print_help() -> None:
+    commands = [
+        ("login",  "Save your API key locally"),
+        ("scan",   "Run a whitebox security assessment of the current directory"),
+        ("report", "Generate a PDF pentest report from a report.md file"),
+        ("push",   "Create a snapshot of your local kalibur folder"),
+        ("pull",   "Restore a snapshot to your local kalibur folder"),
+        ("end",    "End an engagement and permanently delete all its data"),
+    ]
+    if _USE_COLOR:
+        print(f"{_DIM}Usage:{_RESET} kalibur <command> [options]\n")
+        print("Commands:\n")
+        for name, desc in commands:
+            print(f"  \033[1m{name:<8}{_RESET}  {desc}")
+        print(f"\n{_DIM}Run 'kalibur <command> --help' for options.{_RESET}")
+    else:
+        print("Usage: kalibur <command> [options]\n")
+        print("Commands:\n")
+        for name, desc in commands:
+            print(f"  {name:<8}  {desc}")
+        print("\nRun 'kalibur <command> --help' for options.")
+    print()
+
+
+def _validate_key(key: str) -> str | None:
+    ssl_ctx = ssl.create_default_context(cafile=certifi.where())
+    req = urllib.request.Request(
+        f"{API_URL}/api/cli/me",
+        method="GET",
+        headers={"Authorization": f"Bearer {key}", "User-Agent": "kalibur-cli"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10, context=ssl_ctx) as resp:
+            import json
+            data = json.loads(resp.read())
+            return data.get("name")
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            return None
+        raise
+    except Exception:
+        raise
+
+
+def run_login() -> None:
+    _GREEN = "\033[32m" if _USE_COLOR else ""
+    try:
+        key = getpass.getpass("Kalibur API key: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        print(f"{_RED}Cancelled.{_RST}", file=sys.stderr)
+        sys.exit(130)
+    if not key:
+        _error("API key cannot be empty")
+    print()
+    try:
+        name = _validate_key(key)
+    except Exception as e:
+        _error(f"Could not reach Kalibur API: {e}")
+    if name is None:
+        _error("Invalid API key")
+    _CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _CONFIG_PATH.write_text(key)
+    _CONFIG_PATH.chmod(0o600)
+    print(f"{_GREEN}Logged in. API key saved to {_CONFIG_PATH}{_RST}")
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        sys.stdout.flush()
+        self.print_usage(sys.stderr)
+        print(f"\n{_RED}Error: {message}{_RST}", file=sys.stderr)
+        sys.exit(2)
+
+
+def main() -> None:
+    print_banner(Path(".").resolve())
+    sys.stdout.flush()
+
+    if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] in ("-h", "--help")):
+        _print_help()
+        sys.exit(0)
+
+    if (
+        len(sys.argv) >= 3
+        and sys.argv[1] in _COMMAND_HELP
+        and sys.argv[2] in ("-h", "--help")
+    ):
+        desc, usage, flags = _COMMAND_HELP[sys.argv[1]]
+        _print_usage(desc, usage, flags)
+        sys.exit(0)
+
+    if len(sys.argv) == 2 and sys.argv[1] == "login":
+        run_login()
+        sys.exit(0)
+
+    parser = _Parser(prog="kalibur", description="AI whitebox pentest assistant")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("login", help="Save your API key locally")
+
+    scan_cmd = sub.add_parser("scan", help="Run a whitebox assessment of the current directory")
+    scan_cmd.add_argument("-t", default=".", metavar="PATH", dest="target", help="Directory to scan (default: .)")
+    scan_cmd.add_argument("-k", metavar="KEY", dest="api_key", help="Kalibur API key")
+
+    report_cmd = sub.add_parser("report", help="Generate a pentest report from a report.md")
+    report_cmd.add_argument("-r", metavar="FILE", dest="report", help="Path to report.md")
+    report_cmd.add_argument("-f", metavar="NAME", dest="firm", help="Assessor firm name")
+    report_cmd.add_argument("-a", metavar="NAME", dest="assessor", help="Assessor name")
+    report_cmd.add_argument("-c", metavar="NAME", dest="client", help="Client name")
+    report_cmd.add_argument("-l", metavar="FILE", dest="logo", help="Logo file (.png or .jpg)")
+    report_cmd.add_argument("-v", metavar="VER", dest="version", help="Report version (e.g. 1.0)")
+    report_cmd.add_argument("-k", metavar="KEY", dest="api_key", help="Kalibur API key")
+
+    push_cmd = sub.add_parser("push", help="Push local kalibur folders")
+    push_cmd.add_argument("-k", metavar="KEY", dest="api_key", help="Kalibur API key")
+
+    pull_cmd = sub.add_parser("pull", help="Pull a saved snapshot")
+    pull_cmd.add_argument("-e", metavar="PROJECT", dest="project", help="Project name (skip interactive picker)")
+    pull_cmd.add_argument("-k", metavar="KEY", dest="api_key", help="Kalibur API key")
+
+    end_cmd = sub.add_parser("end", help="End an engagement and permanently delete all its data")
+    end_cmd.add_argument("-e", metavar="PROJECT", dest="project", help="Project name (skip interactive picker)")
+    end_cmd.add_argument("-k", metavar="KEY", dest="api_key", help="Kalibur API key")
+
+    args = parser.parse_args()
+
+    if args.command == "login":
+        run_login()
+        sys.exit(0)
+
+    api_key = _resolve_api_key(args.api_key)
+
+    if args.command == "scan":
+        if not api_key:
+            _error(_KEY_ERROR)
+
+        target = Path(args.target).resolve()
+        if not target.exists():
+            _error(f"target directory does not exist: {target}")
+
+        output_dir = target / "kalibur"
+
+        try:
+            run_scan(
+                target_dir=target,
+                api_key=api_key,
+                api_url=API_URL,
+                output_dir=output_dir,
+                project=_detect_project(),
+            )
+        except KeyboardInterrupt:
+            print("\nInterrupted, quitting.", file=sys.stderr)
+            sys.exit(130)
+
+    elif args.command == "report":
+        required_flags = [("-r", "report"), ("-f", "firm"), ("-a", "assessor"), ("-c", "client"), ("-l", "logo"), ("-v", "version")]
+        missing = [flag for flag, attr in required_flags if not getattr(args, attr, None)]
+        if missing:
+            _print_report_usage()
+            sys.stdout.flush()
+            if len(missing) < len(required_flags):
+                print(f"\n{_RED}Error: missing required option(s): {', '.join(missing)}{_RST}", file=sys.stderr)
+                sys.exit(1)
+            sys.exit(0)
+        if not api_key:
+            _print_report_usage()
+            sys.stdout.flush()
+            _error(_KEY_ERROR)
+        run_report(
+            report_path=Path(args.report).resolve(),
+            firm=args.firm,
+            assessor=args.assessor,
+            client=args.client,
+            logo_path=Path(args.logo).resolve(),
+            version=args.version,
+            api_key=api_key,
+            api_url=API_URL,
+        )
+
+    elif args.command == "push":
+        if not api_key:
+            _error(_KEY_ERROR)
+        run_push(api_key=api_key, api_url=API_URL)
+
+    elif args.command == "pull":
+        if not api_key:
+            _error(_KEY_ERROR)
+        run_pull(project_flag=getattr(args, "project", None), api_key=api_key, api_url=API_URL)
+
+    elif args.command == "end":
+        if not api_key:
+            _error(_KEY_ERROR)
+        run_end(project_flag=getattr(args, "project", None), api_key=api_key, api_url=API_URL)
+
+
+if __name__ == "__main__":
+    main()