Metadata-Version: 2.4
Name: kekkai-cli
Version: 1.1.1
Summary: Kekkai 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"><strong>Security orchestration at developer speed.</strong></p>
<p align="center"><i>One tool for the entire AppSec lifecycle: Predict, Detect, Triage, Manage.</i></p>

<p align="center">
  <img src="https://img.shields.io/github/actions/workflow/status/kademoslabs/kekkai/docker-publish.yml?logo=github"/>
  <img src="https://img.shields.io/circleci/build/github/kademoslabs/kekkai?logo=circleci"/>
  <img src="https://img.shields.io/pypi/v/kekkai-cli?pypiBaseUrl=https%3A%2F%2Fpypi.org&logo=pypi"/>
</p>

---

# Kekkai

Stop juggling security tools. **Kekkai orchestrates your entire AppSec lifecycle** — from AI-powered threat modeling to vulnerability management — in a single CLI.

![Hero GIF](https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/kekkai-start.gif)

---

## The Five Pillars

| Pillar | Feature | Command | Description |
|--------|---------|---------|-------------|
| 🔮 **Predict** | AI Threat Modeling | `kekkai threatflow` | Generate STRIDE threat models before writing code |
| 🔍 **Detect** | Unified Scanning | `kekkai scan` | Run Trivy, Semgrep, Gitleaks in isolated containers |
| ✅ **Triage** | Interactive Review | `kekkai triage` | Review findings in a terminal UI, mark false positives |
| 🚦 **Gate** | CI/CD Policy | `kekkai scan --ci` | Break builds on severity thresholds |
| 📊 **Manage** | DefectDojo | `kekkai dojo up` | Spin up vulnerability management in 60 seconds |

---

## Quick Start (60 Seconds)

### 1. Install

```bash
pipx install kekkai-cli
```

### 2. Predict (Threat Model)

```bash
kekkai threatflow --repo . --model-mode local
# Generates THREATS.md with STRIDE analysis and Data Flow Diagram
```

### 3. Detect (Scan)

```bash
kekkai scan
# Runs Trivy (CVEs), Semgrep (code), Gitleaks (secrets)
# Outputs unified kekkai-report.json
```

### 4. Triage (Review)

```bash
kekkai triage
# Interactive TUI to accept, reject, or ignore findings
```

### 5. Manage (DefectDojo)

```bash
kekkai dojo up --wait
kekkai upload
# Full vulnerability management platform + automated import
```

---

## Why Kekkai?

| Capability | Manual Approach | Kekkai |
|------------|-----------------|--------|
| **Tooling** | Install/update 5+ tools individually | One binary, auto-pulls scanner containers |
| **Output** | Parse 5 different JSON formats | Unified `kekkai-report.json` |
| **Threat Modeling** | Expensive consultants or whiteboarding | AI-generated `THREATS.md` locally |
| **DefectDojo** | 200-line docker-compose + debugging | `kekkai dojo up` (one command) |
| **Triage** | Read JSON files manually | Interactive terminal UI |
| **CI/CD** | Complex bash scripts | `kekkai scan --ci --fail-on high` |
| **PR Feedback** | Manual security review comments | Auto-comments on GitHub PRs |

---

## Feature Deep Dives

### 🔮 ThreatFlow — AI-Powered Threat Modeling

Generate STRIDE-aligned threat models and Mermaid.js Data Flow Diagrams from your codebase.

![Hero GIF](https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/kekkai-threatflow.gif)

```bash
# Ollama (recommended - easy setup, privacy-preserving)
ollama pull mistral
kekkai threatflow --repo . --model-mode ollama --model-name mistral

# Local GGUF model (requires llama-cpp-python)
kekkai threatflow --repo . --model-mode local --model-path ./mistral-7b.gguf

# Remote API (faster, requires API key)
export KEKKAI_THREATFLOW_API_KEY="sk-..."
kekkai threatflow --repo . --model-mode openai
```

**Output:** `THREATS.md` containing:
- Attack surface analysis
- STRIDE threat classification
- Mermaid.js architecture diagram
- Recommended mitigations

[Full ThreatFlow Documentation →](docs/threatflow/README.md)

---

### 🔍 Unified Scanning

Run industry-standard scanners without installing them individually. Each scanner runs in an isolated Docker container with security hardening.

```bash
kekkai scan                          # Scan current directory
kekkai scan --repo /path/to/project  # Scan specific path
kekkai scan --output results.json    # Custom output path
```

**Scanners Included:**
| Scanner | Finds | Image |
|---------|-------|-------|
| Trivy | CVEs in dependencies | `aquasec/trivy:latest` |
| Semgrep | Code vulnerabilities | `semgrep/semgrep:latest` |
| Gitleaks | Hardcoded secrets | `zricethezav/gitleaks:latest` |

**Container Security:**
- Read-only filesystem
- No network access
- Memory limited (2GB)
- No privilege escalation

---

### ✅ Interactive Triage TUI

Stop reading JSON. Review security findings in your terminal.

```bash
kekkai triage
```

**Features:**
- Navigate findings with keyboard
- Mark as: Accept, Reject, False Positive, Ignore
- Filter by severity, scanner, or status
- Persist decisions in `.kekkai-ignore`
- Export triaged results

<!-- Screenshot placeholder: ![Triage TUI](https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/triage-tui.png) -->

[Full Triage Documentation →](docs/triage/README.md)

---

### 🚦 CI/CD Policy Gate

Automate security enforcement in your pipelines.

<p align="center">
  <img src="https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/kekkai-scan.png" alt="Kekkai Scanning" width="650"/>
</p>

```bash
# Fail on any critical or high findings
kekkai scan --ci --fail-on high

# Fail only on critical
kekkai scan --ci --fail-on critical

# Custom threshold: fail on 5+ medium findings
kekkai scan --ci --fail-on medium --max-findings 5
```

**Exit Codes:**
| Code | Meaning |
|------|---------|
| 0 | No findings above threshold |
| 1 | Findings exceed threshold |
| 2 | Scanner error |

**GitHub Actions Example:**

```yaml
- name: Security Scan
  run: |
    pipx install kekkai-cli
    kekkai scan --ci --fail-on high
```

[Full CI Documentation →](docs/ci/ci-mode.md)

---

### 📊 DefectDojo Integration

Spin up a complete vulnerability management platform locally.

<p align="center">
  <img src="https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/kekkai-dojo.png" alt="Kekkai Dojo" width="650"/>
</p>

```bash
kekkai dojo up --wait    # Start DefectDojo (Nginx, Postgres, Redis, Celery)
kekkai dojo status       # Check service health
kekkai upload            # Import scan results
kekkai dojo down         # Stop and clean up (removes volumes)
```

**What You Get:**
- DefectDojo web UI at `http://localhost:8080`
- Automatic credential generation
- Pre-configured for Kekkai imports
- Clean teardown (no orphaned volumes)

<p align="center">
  <img src="https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/Active-Engagements-kekkai-dojo.png" alt="Kekkai Dojo" width="850"/>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/kademoslabs/assets/main/screenshots/kekkai-dojo-dashboard-findings.png" alt="Kekkai Dojo" width="850"/>
</p

[Full Dojo Documentation →](docs/dojo/dojo.md)

---

### 🔔 GitHub PR Comments

Get security feedback directly in pull requests.

```bash
export GITHUB_TOKEN="ghp_..."
kekkai scan --github-comment
```

Kekkai will:
1. Run all scanners
2. Post findings as PR review comments
3. Annotate specific lines with inline comments

---

## Installation

### pipx (Recommended)

Isolated environment, no conflicts with system Python.

```bash
pipx install kekkai-cli
```

### Homebrew (macOS/Linux)

```bash
brew install kademoslabs/tap/kekkai
```

### Scoop (Windows)

```bash
scoop bucket add kademoslabs https://github.com/kademoslabs/scoop-bucket
scoop install kekkai
```

### Docker (No Python Required)

```bash
docker pull kademoslabs/kekkai:latest
alias kekkai='docker run --rm -v "$(pwd):/repo" kademoslabs/kekkai:latest'
```

### pip (Traditional)

```bash
pip install kekkai-cli
```

---

## Enterprise Features

For organizations that need advanced capabilities, **Kekkai Enterprise** provides:

| Feature | Description |
|---------|-------------|
| **Multi-Tenant Portal** | Web dashboard for managing multiple teams/projects ([Learn More](docs/portal/README.md)) |
| **SAML 2.0 SSO** | Integrate with Okta, Azure AD, Google Workspace |
| **Role-Based Access Control** | Fine-grained permissions per team/project |
| **Advanced Operations** | Automated backup/restore, monitoring, zero-downtime upgrades ([Learn More](docs/ops/README.md)) |
| **Compliance Reporting** | Map findings to OWASP, PCI-DSS, HIPAA, SOC 2 |
| **Audit Logging** | Cryptographically signed compliance trails |

**Architecture:**
- Open-source CLI remains fully functional standalone
- Enterprise features available in separate private repository for licensed customers
- Optional integration: CLI can sync results to enterprise portal
- Self-hosted or Kademos-managed deployment options

[Contact us for enterprise access →](mailto:sales@kademos.org)

---

## Security

Kekkai is designed with security as a core principle:

- **Container Isolation**: Scanners run in hardened Docker containers
- **No Network Access**: Containers cannot reach external networks
- **Local-First AI**: ThreatFlow can run entirely on your machine
- **SLSA Level 3**: Release artifacts include provenance attestations
- **Signed Images**: Docker images are Cosign-signed

For vulnerability reports, see [SECURITY.md](SECURITY.md).

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Installation](docs/README.md#installation-methods) | All installation methods |
| [ThreatFlow](docs/threatflow/README.md) | AI threat modeling setup |
| [Dojo Quick Start](docs/dojo/dojo-quickstart.md) | DefectDojo in 5 minutes |
| [CI Mode](docs/ci/ci-mode.md) | Pipeline integration |
| [Portal](docs/portal/README.md) | Enterprise features overview |
| [Portal SSO](docs/portal/saml-setup.md) | SAML 2.0 SSO configuration |
| [Portal RBAC](docs/portal/rbac.md) | Role-based access control |
| [Portal Deployment](docs/portal/deployment.md) | Self-hosted deployment |
| [Security](docs/security/slsa-provenance.md) | SLSA provenance verification |

---

## CI/CD Status

[![Kekkai Security Scan](https://github.com/kademoslabs/kekkai/actions/workflows/kekkai-pr-scan.yml/badge.svg)](https://github.com/kademoslabs/kekkai/actions/workflows/kekkai-pr-scan.yml)
[![Docker Image Publish](https://github.com/kademoslabs/kekkai/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/kademoslabs/kekkai/actions/workflows/docker-publish.yml)
[![Docker Security Scan](https://github.com/kademoslabs/kekkai/actions/workflows/docker-security-scan.yml/badge.svg)](https://github.com/kademoslabs/kekkai/actions/workflows/docker-security-scan.yml)
[![Cross-Platform Tests](https://github.com/kademoslabs/kekkai/actions/workflows/test-cross-platform.yml/badge.svg)](https://github.com/kademoslabs/kekkai/actions/workflows/test-cross-platform.yml)
[![Release with SLSA Provenance](https://github.com/kademoslabs/kekkai/actions/workflows/release-slsa.yml/badge.svg)](https://github.com/kademoslabs/kekkai/actions/workflows/release-slsa.yml)

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

Apache-2.0 — See [LICENSE](LICENSE) for details.

---

<p align="center"><i>Built by <a href="https://kademos.org">Kademos Labs</a></i></p>
