kekkai-cli 1.0.0__py3-none-any.whl

kekkai_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: kekkai-cli
+Version: 1.0.0
+Summary: Kekkai/Regulon monorepo (local-first AppSec orchestration + compliance checker)
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=13.0.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: textual>=0.50.0
+Requires-Dist: httpx>=0.24.0
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kademoslabs/assets/main/logos/kekkai-slim.png" alt="Kekkai CLI Logo" width="250"/>
+</p>
+<p align="center"><i>One command. Clean AppSec reports.</i></p>
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  <img src="https://img.shields.io/badge/status-active-brightgreen"/>
+</p>
+
+# Kekkai 🛡️
+
+**Security that moves at developer speed.**
+*Local-first orchestration for Trivy, Semgrep, and DefectDojo.*
+
+![Hero GIF](https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/kekkai-recording.gif)
+
+---
+
+## ⚡ Quick Start
+
+Stop fighting with Docker Compose. Start scanning in 30 seconds.
+
+### Installation
+
+**Option 1: pipx (Recommended - Isolated Environment)**
+
+```bash
+pipx install kekkai-cli
+```
+
+**Option 2: Homebrew (macOS/Linux)**
+
+```bash
+brew tap kademoslabs/tap
+brew install kekkai
+```
+
+**Option 3: Docker (No Python Required)**
+
+```bash
+# Build image
+docker build -t kademoslabs/kekkai:latest -f apps/kekkai/Dockerfile .
+
+# Run via wrapper script
+./scripts/kekkai-docker --help
+
+# Or set up alias
+alias kekkai="$(pwd)/scripts/kekkai-docker"
+```
+
+**Option 4: Scoop (Windows)**
+
+```powershell
+scoop bucket add kademoslabs https://github.com/kademoslabs/scoop-bucket
+scoop install kekkai
+```
+
+**Option 5: pip (Traditional)**
+
+```bash
+pip install kekkai-cli
+```
+
+
+
+### 1. Scan your project (Local)
+
+Run industry-standard scanners (Trivy, Semgrep, Gitleaks) in unified Docker containers without installing them individually.
+
+```bash
+cd your-repo
+kekkai scan
+
+```
+
+### 2. Spin up DefectDojo
+
+Launch a full local vulnerability management platform (Nginx, Postgres, Redis, Celery) with one command.
+
+```bash
+kekkai dojo up --wait --open
+
+```
+
+### 3. Generate a Threat Model (AI)
+
+Generate a STRIDE threat model and Data Flow Diagram using your local LLM.
+
+```bash
+kekkai threatflow --repo . --model-mode local
+
+```
+
+---
+
+## 🛑 The Problem vs. Kekkai
+
+| Feature | The Old Way | The Kekkai Way |
+| --- | --- | --- |
+| **Tooling** | Manually install/update 5+ tools (Trivy, Semgrep, etc.) | **One Binary.** `kekkai scan` auto-pulls and runs the latest scanner containers. |
+| **Reporting** | Parse 5 different JSON formats manually. | **Unified Output.** One deduplicated `kekkai-report.json` for all findings. |
+| **DefectDojo** | Write a 200-line `docker-compose.yml` and debug networking. | **One Command.** `kekkai dojo up` automates the entire stack setup. |
+| **Threat Modeling** | Expensive consultants or manual whiteboarding. | **AI Agent.** `kekkai threatflow` generates `THREATS.md` locally. |
+| **CI/CD** | Write complex bash scripts to break builds. | **Policy Engine.** `kekkai scan --ci --fail-on high`. |
+
+---
+
+## 🔒 Enterprise Features (Portal)
+
+For teams that need centralized management, **Kekkai Portal** offers:
+
+* **SAML 2.0 SSO** with Replay Protection
+* **Role-Based Access Control (RBAC)**
+* **Cryptographically Signed Audit Logs**
+
+*Built by Kademos Labs.*
+
+---
+
+## 📚 Documentation
+
+- **[Automated Distribution Updates](docs/ci/automated-distributions.md)** - CI/CD distribution triggers
+- **[CI Architecture](/.docs/development/ci-architecture.md)** - Developer guide for distribution automation
+- **[Homebrew Maintenance](docs/ci/homebrew-maintenance.md)** - Homebrew tap management

kekkai_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,90 @@
+kekkai/__init__.py,sha256=_VrBvJRyqHiXs31S8HOhATk_O2iy-ac0_9X7rHH75j8,143
+kekkai/cli.py,sha256=u-5GHXUT9G8Np-5SOLbSTtebQDv8yFYYCFZAjiDAAWU,35903
+kekkai/config.py,sha256=LE7bKsmv5dim5KnZya0V7_LtviNQ1V0pMN_6FyAsMpc,13084
+kekkai/dojo.py,sha256=DchLaTnDBwX0D14lTRdCtwql_II8aDEZ0JEq9F-n4MI,15887
+kekkai/dojo_import.py,sha256=oI-vwpLITA7-U2_MxhaTp_PYfr5HqvcFy3VzKsWA6IY,6911
+kekkai/manifest.py,sha256=Ph5xGDKuVxMW1GVIisRhxUelaiVZQe-W5sZWsq4lHqs,1887
+kekkai/output.py,sha256=oEt-T49wXUvmhyAwnsdxPGrw3Ql5jUWApdXpzhlKRN8,6008
+kekkai/paths.py,sha256=EcyG3CEOQFQygowu7O5Mp85dKkXWWvnm1h0j_BetGxY,1190
+kekkai/policy.py,sha256=0XCUH-SbnO1PsM-exjSFHYHRnLkiNa50QfkyPakwNko,9792
+kekkai/runner.py,sha256=MBFUiJ4sSVEGNbJ6cv-8p1WHaHqjio6yWEfr_K4GuTs,2037
+kekkai/github/__init__.py,sha256=3EQ7LkRqgQwr5uTt7hNvVXLiKTpzE47woc8lZQjy5cE,386
+kekkai/github/commenter.py,sha256=v19pEctYJvUvA7e-t6eOA5dZaNIt16ocCxC92IUxQeM,5906
+kekkai/github/models.py,sha256=baW5prDEVncKrfC8aLoKjaTpPKYtRzZOBOg4Zje3qug,1340
+kekkai/github/sanitizer.py,sha256=GWvVRHH_EGdhnHZi4rLWQDWTOrxw_U74Fi9fT5qUfBs,3239
+kekkai/installer/__init__.py,sha256=pgUELK_2JzSGtzQuRzclF7M5FK9EulKmgFH5Xr8kxZI,858
+kekkai/installer/errors.py,sha256=4SsTmcjIiQUmXDZVfeS2H2GCtpcMqEskN-9EyzFbBJc,561
+kekkai/installer/extract.py,sha256=r4wYGCZ7zV2lIki5kns7t9bFRV1fahqOral8Jl7LZcQ,5232
+kekkai/installer/manager.py,sha256=FqHTmHvTc2YkWWISvdS1uW7IZV6bHqyEg33TDb4Ldtc,7881
+kekkai/installer/manifest.py,sha256=oZFquI9pUtgtB4ZXontQND5D7m4WzjjJuybhlePk3k4,5544
+kekkai/installer/verify.py,sha256=ThtWfKnjrdx90_XBJclBGiw4yzTFs5HKoFJ0IyVPsMM,2186
+kekkai/scanners/__init__.py,sha256=uKJqnBgcf47eJlDB3mvHpLsobR6M6N6uO2L0Dor1MaE,1552
+kekkai/scanners/base.py,sha256=uy7HgOaQxNcp6-X1gfXAecSYpKXaEsuVeluf6SwkbwM,2678
+kekkai/scanners/container.py,sha256=OhD0Meld_Zm4YcTuON91kx08Cj5h4R1FR0ABGbx7kQI,4197
+kekkai/scanners/falco.py,sha256=Y0kjg9QArIZnXw8Q-EEZv8o7iUOehOY3jTKh3AMR1yU,7384
+kekkai/scanners/gitleaks.py,sha256=8hRWXsH_EMhkqGcP2AtJdaMWHmQa91XdG2oVnq8g-kI,7159
+kekkai/scanners/semgrep.py,sha256=v4RDV_mHv1UXqdhV7FSyQUCu0EUCOoERGzDVowqwgVA,6758
+kekkai/scanners/trivy.py,sha256=E0B31eomyNF0k3ULnDkqfFoQM54UtrIIFPm3jqgE9VA,7788
+kekkai/scanners/url_policy.py,sha256=0V4ESDd2R1MSyI1bs_WtFZxZpKX33O154qFIrD6uk5U,5209
+kekkai/scanners/zap.py,sha256=64NHzM-GF3oOV4UZ_W9N2v55mz91FPPg_k6hgcwlX1I,10932
+kekkai/scanners/backends/__init__.py,sha256=Rdo17FeCPGTI-1QeKtBSkg4NrW26RnvX9vgzdsxY5fg,372
+kekkai/scanners/backends/base.py,sha256=bFvY0qLvawTKOSgmGyEfTm7OlFJwfivzNMUexPZD2Z0,1698
+kekkai/scanners/backends/docker.py,sha256=mLrYL8MxM7cbhX_-po00hTLV6DtSi1bP9c6RfE3tStQ,5867
+kekkai/scanners/backends/native.py,sha256=3kwmwHMkB1AY57ZWOYpw8CtxuK2yMET49MgH9OV1ns8,7409
+kekkai/threatflow/__init__.py,sha256=J07MqRdIYMIIBq3TevZk6gQ43y-kJetDPItgafB2pe4,2113
+kekkai/threatflow/artifacts.py,sha256=8h3IGk798U4Wkco4x0uKgzUsZCh7VfTOufwrxs7rTTo,17119
+kekkai/threatflow/chunking.py,sha256=0FNVnaQoU3FEmtjYHVaiLsKBSzHx6Vo4oozVwwWkOHM,9981
+kekkai/threatflow/core.py,sha256=CYLUI38n30zEq3DbUNI_H9mqBwwlPoL7TtFOiiwC3wI,15421
+kekkai/threatflow/mermaid.py,sha256=Brp-x-LUHMRjC7OBh4Vxzlk3NeCcdmWfWXlv7WL1ZdE,11579
+kekkai/threatflow/model_adapter.py,sha256=xqVPYc0rDys5RgvqJwR2VULJyzx8eToLQsOtKO1fKRE,15394
+kekkai/threatflow/prompts.py,sha256=lgbj7FJ1c3UYj4ofGnlLoRmywYBfdAKY0QEHmIB_JFw,8525
+kekkai/threatflow/redaction.py,sha256=mGUcNQB6YPVKArtMrEYcXCWslgUiCkloiowY9IlZ1iY,7622
+kekkai/threatflow/sanitizer.py,sha256=uQsxYZ5VDXutZoj-WMl7fo5T07uHuQZqgVzoVMoaKec,22688
+kekkai/triage/__init__.py,sha256=5La5HUnO6ehoUoRbOfZ_QvRj0U4ud4W2o79oraBhpCg,798
+kekkai/triage/app.py,sha256=MU2tBI50d8sOdDKESGNrWYiREG9bBtrSccaMoiMv5gM,5027
+kekkai/triage/audit.py,sha256=UVaSKKC6tZkHxEoMcnIZkMOT_ngj7QzHWYuDAHas_sc,5842
+kekkai/triage/ignore.py,sha256=uBKM7zKyzORj9LJ5AAnoYWZQTRy57P0ZofSapiDWcfI,7305
+kekkai/triage/models.py,sha256=nRmWtELMqHWHX1NqZ2upH2ZAJVeBxa3Wh8f3kkB9WYo,5384
+kekkai/triage/screens.py,sha256=6eEiHvuuS_gGESS_K3NjPiQx8G7CR18-j9upU1p5nRg,11004
+kekkai/triage/widgets.py,sha256=eOF6Qoo5uBqjxiEkbpgcO1tbIOGBQBKn75wP9Jw_AaE,4733
+kekkai_core/__init__.py,sha256=gREN4oarM0azTkSTWTnlDnPZGgv1msai2Deq9Frj3gc,122
+kekkai_core/redaction.py,sha256=EeWYPjAs2hIXlLKGmGn_PRdK08G4KcOBmbRCoFklbHc,2893
+kekkai_core/ci/__init__.py,sha256=uldVoVW4HNdAOq0X5k4NAMOUxbue73zqOvd1BbiywGQ,328
+kekkai_core/ci/benchmarks.py,sha256=9sVVObk3tqKKukH3i2g9voPKN1NFIuzOEUmjoiW6Q0o,11013
+kekkai_core/ci/metadata.py,sha256=7NACmqzQQzSsfjDLR5cl6m7R2T3i-8frUihs8rkitic,2801
+kekkai_core/ci/validators.py,sha256=j9KMsAauGWVArXFeWouACTjFgn7PlUTFUuAqIhI8DNo,2330
+kekkai_core/docker/__init__.py,sha256=WnuDHW7JP0dPdV95a8L5SxAI6OJHh9umzVgRE-ZkaGQ,585
+kekkai_core/docker/metadata.py,sha256=OE7C0NYSHZqpciyoRqCvdb2YcbiW4Y7KR8weC5FrsOE,4103
+kekkai_core/docker/sbom.py,sha256=hAJtHqYRNSsjes9lrE7cHPYnX3elOdXhX7tXyo9kf7c,4644
+kekkai_core/docker/security.py,sha256=EpjAUUp5kf-wy-sRbRosR4RerJKkKQcUIFYAxM7x02A,4439
+kekkai_core/docker/signing.py,sha256=kH2F4ibXAqbPGJ483cSP1kh_cNiJM6rUHImMrfqOV1k,3362
+kekkai_core/slsa/__init__.py,sha256=_MrP7YX10UYbYclD9qCqisIYdG5h1yzKZQQZoqtUIpQ,260
+kekkai_core/slsa/verify.py,sha256=jOqROy6Q57Xwv9yj31_cgZ51dePxA9NRAsELuj0WtiY,3579
+kekkai_core/windows/__init__.py,sha256=taJXYcLYTPucwhJw0rR4NJbNQIrDbIN6cheRPBMkOA4,770
+kekkai_core/windows/chocolatey.py,sha256=tF5S5eN-HeENRt6yQ4TZgwng0oRMX_ScskQ3-ebEIUg,10187
+kekkai_core/windows/installer.py,sha256=MePAywHH3JTIAENv52XtkUMOGqmYqZqkH77VW5PST8o,6945
+kekkai_core/windows/scoop.py,sha256=lvothICrAoB3lGfkvhqVeNTB50eMmVGA0BE7JNCfHdI,5284
+kekkai_core/windows/validators.py,sha256=45xUuAbHcKc0WLIZ-0rByPeDD88MAV8KvopngyYBHpQ,6525
+portal/__init__.py,sha256=vLjCqUgIqzHbT-oIMMWuWQ-lDA5jvuOOEa9qdBRLcIY,507
+portal/api.py,sha256=4_hQwkUnP8P3EjCdB5Tb7uRcuH3H7M6GxTvwTTmhLv4,4066
+portal/auth.py,sha256=4K_Ya9W_2sZl2MF0FNVr9QASjTOKAO3CMdgGUuYbb9s,3102
+portal/tenants.py,sha256=91SOqzjGefcHXodfN8LIHER8boeSB-Jb-WoHPTWI5GI,11394
+portal/uploads.py,sha256=WhosreaTKFYHNKXW9F4jOmB_OwUl1YGtT5DeaXnRMqk,7352
+portal/web.py,sha256=nW9ShBI18TitVFxaN0OmGgqtMdUnv5UPZcBMT12VuvM,14173
+portal/enterprise/__init__.py,sha256=djxFlSUZ5-YwhT9SXJsAOaD1rRHDL14BXigh6l4WDC4,763
+portal/enterprise/audit.py,sha256=VTm-M4gVKOxcBREqIJBs4r5wyqqqf1eCOsHi3FFiDcI,13772
+portal/enterprise/licensing.py,sha256=M8PFfE_v73UJL6Lfr4qhqfAGrvtJyPwDPb4SMRMGfV0,11002
+portal/enterprise/rbac.py,sha256=vrZoyIVmWM0C90CIgZaprwqhiDbAM-ggNNg36Zu-5lU,8548
+portal/enterprise/saml.py,sha256=TXHBbILI7qMe0ertcFPnuSUSPbJzEeBiHmZzhY9-Ix8,20367
+portal/ops/__init__.py,sha256=ZyEYmFM_4LFWfQfgp9Kh2vqmolSjVKFdk1vX1vkhjqc,1391
+portal/ops/backup.py,sha256=eLUnZcUtS0svEoagb0jQQmT7TcAGjBA3fUlM2YoCfLg,20102
+portal/ops/log_shipper.py,sha256=Age3YfvsJ5YWrPQYdHELr4Qa9jJCATHiwv3Q-rMJwJs,15237
+portal/ops/monitoring.py,sha256=xhLbKjVaob709K4x0dEsOo4lh7Ddm2A4UE2ZmhfmMtI,17908
+portal/ops/restore.py,sha256=rgzKoBIilgoPPv5gZhSSBuLKG1skKw5ryoCRR3d7CPQ,17058
+portal/ops/secrets.py,sha256=wu2bUfJGctbGjyuGUgvUc_Y6IH1SCW16dExtqcKu_kg,14338
+portal/ops/upgrade.py,sha256=fXsIXCJYYABdWDECDXkt7F2PidzNtO6Zr-g0Y5PLlVU,20106
+kekkai_cli-1.0.0.dist-info/METADATA,sha256=htJH1nyVjsze_4rHWPSQ4_AVSDbZJzZYltPh-krm0pY,3660
+kekkai_cli-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+kekkai_cli-1.0.0.dist-info/entry_points.txt,sha256=WUEX6IISnRcwlQAdhisPfIIV3Us2MYCwtJoyPpLJO44,75
+kekkai_cli-1.0.0.dist-info/top_level.txt,sha256=u0J4T-Rnb0cgs0LfzZAUNt6nx1d5l7wKn8vOuo9FBEY,26
+kekkai_cli-1.0.0.dist-info/RECORD,,

kekkai_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kekkai_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+kekkai = kekkai.cli:main
+kekkai-portal = portal.web:main

kekkai_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+kekkai
+kekkai_core
+portal

kekkai_core/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["redact", "redact_extended", "detect_secrets"]
+
+from .redaction import detect_secrets, redact, redact_extended

kekkai_core/ci/__init__.py

@@ -0,0 +1,11 @@
+"""CI/CD automation utilities for distribution triggers."""
+
+from kekkai_core.ci.metadata import calculate_sha256, extract_version_from_tag
+from kekkai_core.ci.validators import validate_semver, verify_checksum
+
+__all__ = [
+    "extract_version_from_tag",
+    "calculate_sha256",
+    "validate_semver",
+    "verify_checksum",
+]

kekkai_core/ci/benchmarks.py

@@ -0,0 +1,354 @@
+"""Performance benchmarking utilities for cross-platform testing."""
+
+import json
+import platform
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+try:
+    import psutil  # type: ignore[import-untyped]
+
+    PSUTIL_AVAILABLE = True
+except ImportError:
+    PSUTIL_AVAILABLE = False
+
+
+@dataclass
+class BenchmarkResult:
+    """Results from a performance benchmark."""
+
+    name: str
+    duration_seconds: float
+    memory_peak_mb: float | None = None
+    memory_start_mb: float | None = None
+    memory_end_mb: float | None = None
+    platform: str = field(default_factory=lambda: sys.platform)
+    python_version: str = field(default_factory=lambda: platform.python_version())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "name": self.name,
+            "duration_seconds": self.duration_seconds,
+            "memory_peak_mb": self.memory_peak_mb,
+            "memory_start_mb": self.memory_start_mb,
+            "memory_end_mb": self.memory_end_mb,
+            "platform": self.platform,
+            "python_version": self.python_version,
+            "metadata": self.metadata,
+        }
+
+
+class PerformanceBenchmark:
+    """Context manager for performance benchmarking."""
+
+    def __init__(self, name: str, metadata: dict[str, Any] | None = None):
+        """Initialize benchmark.
+
+        Args:
+            name: Name of the benchmark
+            metadata: Additional metadata to include
+        """
+        self.name = name
+        self.metadata = metadata or {}
+        self.start_time: float | None = None
+        self.end_time: float | None = None
+        self.memory_start: float | None = None
+        self.memory_end: float | None = None
+        self.memory_peak: float | None = None
+
+    def __enter__(self) -> "PerformanceBenchmark":
+        """Start benchmarking."""
+        self.start_time = time.perf_counter()
+
+        if PSUTIL_AVAILABLE:
+            process = psutil.Process()
+            self.memory_start = process.memory_info().rss / (1024 * 1024)  # MB
+
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """End benchmarking."""
+        self.end_time = time.perf_counter()
+
+        if PSUTIL_AVAILABLE:
+            process = psutil.Process()
+            self.memory_end = process.memory_info().rss / (1024 * 1024)  # MB
+            self.memory_peak = self.memory_end  # Simplified; real peak tracking needs monitoring
+
+    def get_result(self) -> BenchmarkResult:
+        """Get benchmark result."""
+        if self.start_time is None or self.end_time is None:
+            raise RuntimeError("Benchmark not completed")
+
+        duration = self.end_time - self.start_time
+
+        return BenchmarkResult(
+            name=self.name,
+            duration_seconds=duration,
+            memory_peak_mb=self.memory_peak,
+            memory_start_mb=self.memory_start,
+            memory_end_mb=self.memory_end,
+            metadata=self.metadata,
+        )
+
+
+def benchmark_function(
+    func: Callable[..., Any],
+    name: str | None = None,
+    iterations: int = 1,
+    warmup: int = 0,
+    metadata: dict[str, Any] | None = None,
+) -> BenchmarkResult:
+    """Benchmark a function.
+
+    Args:
+        func: Function to benchmark
+        name: Name for the benchmark (defaults to function name)
+        iterations: Number of times to run the function
+        warmup: Number of warmup iterations (not measured)
+        metadata: Additional metadata
+
+    Returns:
+        Benchmark result
+    """
+    benchmark_name = name or func.__name__
+
+    # Warmup
+    for _ in range(warmup):
+        func()
+
+    # Measure
+    with PerformanceBenchmark(benchmark_name, metadata=metadata) as bench:
+        for _ in range(iterations):
+            func()
+
+    result = bench.get_result()
+
+    # Adjust for iterations
+    if iterations > 1:
+        result.duration_seconds /= iterations
+        result.metadata["iterations"] = iterations
+
+    return result
+
+
+class BenchmarkRunner:
+    """Runner for multiple benchmarks."""
+
+    def __init__(self, output_dir: Path | None = None):
+        """Initialize benchmark runner.
+
+        Args:
+            output_dir: Directory to store benchmark results
+        """
+        self.output_dir = output_dir or Path(".benchmarks")
+        self.results: list[BenchmarkResult] = []
+
+    def run_benchmark(
+        self,
+        func: Callable[..., Any],
+        name: str | None = None,
+        iterations: int = 1,
+        metadata: dict[str, Any] | None = None,
+    ) -> BenchmarkResult:
+        """Run a benchmark and store result.
+
+        Args:
+            func: Function to benchmark
+            name: Benchmark name
+            iterations: Number of iterations
+            metadata: Additional metadata
+
+        Returns:
+            Benchmark result
+        """
+        result = benchmark_function(func, name=name, iterations=iterations, metadata=metadata)
+        self.results.append(result)
+        return result
+
+    def save_results(self, filename: str | None = None) -> Path:
+        """Save benchmark results to file.
+
+        Args:
+            filename: Output filename (default: benchmark_{timestamp}.json)
+
+        Returns:
+            Path to saved file
+        """
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        if filename is None:
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            filename = f"benchmark_{timestamp}.json"
+
+        output_path = self.output_dir / filename
+
+        results_data = {
+            "timestamp": time.time(),
+            "platform": {
+                "system": platform.system(),
+                "release": platform.release(),
+                "machine": platform.machine(),
+                "python_version": platform.python_version(),
+            },
+            "results": [r.to_dict() for r in self.results],
+        }
+
+        output_path.write_text(json.dumps(results_data, indent=2))
+
+        return output_path
+
+    def load_results(self, filepath: Path) -> list[BenchmarkResult]:
+        """Load benchmark results from file.
+
+        Args:
+            filepath: Path to results file
+
+        Returns:
+            List of benchmark results
+        """
+        data = json.loads(filepath.read_text())
+
+        loaded_results = []
+        for result_dict in data.get("results", []):
+            result = BenchmarkResult(
+                name=result_dict["name"],
+                duration_seconds=result_dict["duration_seconds"],
+                memory_peak_mb=result_dict.get("memory_peak_mb"),
+                memory_start_mb=result_dict.get("memory_start_mb"),
+                memory_end_mb=result_dict.get("memory_end_mb"),
+                platform=result_dict.get("platform", "unknown"),
+                python_version=result_dict.get("python_version", "unknown"),
+                metadata=result_dict.get("metadata", {}),
+            )
+            loaded_results.append(result)
+
+        return loaded_results
+
+    def compare_with_baseline(
+        self, baseline_file: Path, threshold_percent: float = 20.0
+    ) -> dict[str, Any]:
+        """Compare current results with baseline.
+
+        Args:
+            baseline_file: Path to baseline results file
+            threshold_percent: Threshold for regression detection (e.g., 20.0 = 20%)
+
+        Returns:
+            Comparison report
+        """
+        baseline_results = self.load_results(baseline_file)
+
+        # Create lookup by name
+        baseline_by_name = {r.name: r for r in baseline_results}
+
+        regressions: list[dict[str, Any]] = []
+        improvements: list[dict[str, Any]] = []
+
+        for current in self.results:
+            if current.name not in baseline_by_name:
+                continue
+
+            baseline = baseline_by_name[current.name]
+
+            # Calculate percentage change
+            percent_change = (
+                (current.duration_seconds - baseline.duration_seconds)
+                / baseline.duration_seconds
+                * 100.0
+            )
+
+            comparison = {
+                "name": current.name,
+                "baseline_duration": baseline.duration_seconds,
+                "current_duration": current.duration_seconds,
+                "percent_change": percent_change,
+            }
+
+            if percent_change > threshold_percent:
+                regressions.append(comparison)
+            elif percent_change < -threshold_percent:
+                improvements.append(comparison)
+
+        return {
+            "threshold_percent": threshold_percent,
+            "regressions": regressions,
+            "improvements": improvements,
+            "total_benchmarks": len(self.results),
+        }
+
+
+def get_system_info() -> dict[str, Any]:
+    """Get system information for benchmarking context.
+
+    Returns:
+        Dictionary with system information
+    """
+    info = {
+        "platform": {
+            "system": platform.system(),
+            "release": platform.release(),
+            "version": platform.version(),
+            "machine": platform.machine(),
+            "processor": platform.processor(),
+        },
+        "python": {
+            "version": platform.python_version(),
+            "implementation": platform.python_implementation(),
+            "compiler": platform.python_compiler(),
+        },
+    }
+
+    if PSUTIL_AVAILABLE:
+        info["memory"] = {
+            "total_gb": psutil.virtual_memory().total / (1024**3),
+            "available_gb": psutil.virtual_memory().available / (1024**3),
+        }
+        info["cpu"] = {
+            "physical_cores": psutil.cpu_count(logical=False),
+            "logical_cores": psutil.cpu_count(logical=True),
+        }
+
+    return info
+
+
+def format_benchmark_report(results: list[BenchmarkResult]) -> str:
+    """Format benchmark results as human-readable report.
+
+    Args:
+        results: List of benchmark results
+
+    Returns:
+        Formatted report string
+    """
+    lines = ["# Performance Benchmark Report", ""]
+
+    # System info
+    sys_info = get_system_info()
+    lines.append("## System Information")
+    lines.append(f"- Platform: {sys_info['platform']['system']} {sys_info['platform']['release']}")
+    lines.append(f"- Machine: {sys_info['platform']['machine']}")
+    lines.append(
+        f"- Python: {sys_info['python']['version']} ({sys_info['python']['implementation']})"
+    )
+    lines.append("")
+
+    # Results table
+    lines.append("## Benchmark Results")
+    lines.append("")
+    lines.append("| Benchmark | Duration (s) | Memory Peak (MB) |")
+    lines.append("|-----------|--------------|------------------|")
+
+    for result in results:
+        memory_str = f"{result.memory_peak_mb:.2f}" if result.memory_peak_mb else "N/A"
+        lines.append(f"| {result.name} | {result.duration_seconds:.4f} | {memory_str} |")
+
+    lines.append("")
+
+    return "\n".join(lines)