Kekkai Documentation
Kekkai is a local-first security CLI that wraps Trivy, Semgrep, and Gitleaks. It normalizes their outputs, provides an interactive terminal UI for triage, and integrates with CI/CD pipelines — without requiring a proprietary rules engine or SaaS account.
The Suite
Kekkai is made up of a core scanner orchestrator, an interactive triage TUI, and several opt-in integrations. All core workflows run entirely on your machine.
Unified Scanning
One command runs Trivy, Semgrep, and Gitleaks, normalizing all outputs into kekkai-report.json.
- Trivy: CVEs
- Semgrep: code vulnerabilities
- Gitleaks: secrets
Interactive Triage
Keyboard-driven TUI to review findings, mark false positives, and persist decisions with .kekkaiignore.
- Severity filtering
- State management
- Audit logging
CI/CD Integration
Severity-based exit codes, GitHub Actions workflows, and pre-commit hooks with zero YAML required.
- Structured exit codes
- PR comments
- Pre-commit hook
ThreatFlow (opt-in)
STRIDE-aligned threat modeling via a local LLM. No API keys needed when using Ollama.
- Ollama support
- THREATS.md output
- Secret redaction
DefectDojo (opt-in)
Spin up a local DefectDojo vulnerability management dashboard with one command.
- Docker Compose managed
- Auto-credentials
- Kekkai import preset
Compliance Reporting
Generate HTML and PDF reports with framework mappings from unified scan output.
- PCI-DSS
- SOC 2
- OWASP
- HIPAA
Installation
Requires Python 3.12+ and Docker. Kekkai uses Docker to run scanners in isolated containers — Docker must be running before scanning.
Recommended for local development. Installs in an isolated environment.
macOS and Linux users who prefer native package managers.
Windows users via the Scoop package manager.
Traditional Python environments — manage dependencies manually.
CI/CD pipelines where no local Python install is available.
Quick Start
1. Verify dependencies
Checks Docker availability and scanner image accessibility.
2. Scan the current repository
Runs Trivy, Semgrep, and Gitleaks. Outputs kekkai-report.json.
3. Review findings interactively
Opens the terminal UI. Navigate with j/k, mark false positives with f.
kekkai scan
Run security scanners on a repository. By default, runs Trivy, Semgrep, and Gitleaks in isolated Docker containers and writes a unified kekkai-report.json.
Core options
--repo PATH | Path to repository to scan (default: current directory) |
--scanners LIST | Comma-separated scanners: trivy, semgrep, gitleaks, zap |
--output PATH | Custom output path for policy result JSON |
--run-id ID | Override run ID (alphanumeric with . _ -) |
--config PATH | Path to config file |
CI mode
--ci | Enable CI mode: fail on policy violations |
--fail-on LEVELS | Severity levels to fail on (e.g. critical,high or medium) |
Examples
kekkai triage
Open an interactive terminal UI to review findings, mark false positives, and generate a .kekkaiignore file. All decisions are logged to .kekkai-audit.json for compliance purposes.
--input PATH | Path to findings JSON (from kekkai scan output) |
--output PATH | Output path for .kekkaiignore (default: .kekkaiignore) |
Keyboard controls
j / k or arrow keys | Navigate findings up and down |
Enter | View detailed finding information |
c | Mark as confirmed (valid issue requiring remediation) |
f | Mark as false positive (added to .kekkaiignore) |
d | Defer finding (tracked for later) |
n | Add notes to a finding |
Ctrl+O | Open in editor at vulnerable line ($EDITOR) |
Ctrl+S / s | Save decisions and write .kekkaiignore |
q | Quit |
Severity levels
| Severity | Description |
|---|---|
Critical | Immediate action required |
High | Should be fixed soon |
Medium | Fix when possible |
Low | Consider fixing |
Info | Informational only |
kekkai report
Generate compliance-ready reports from a unified kekkai-report.json. Outputs include HTML, PDF, and compliance matrix formats with executive summaries and framework mappings.
--input PATH | Path to kekkai-report.json [required] |
--format FORMAT | Output format: html, pdf, json, compliance-matrix |
--output PATH | Output directory for report files |
--project NAME | Project name used in report headers |
--frameworks LIST | Comma-separated frameworks: PCI-DSS, OWASP, HIPAA, SOC2 |
Examples
kekkai fix
Generate AI-powered code patches for findings (experimental). Runs in dry-run mode by default — use --apply to write changes to disk. Backups are created automatically unless disabled.
--input PATH | Path to scan results JSON [required] |
--repo PATH | Repository path (default: current directory) |
--dry-run | Preview fixes without applying (default: true) |
--apply | Apply fixes to files |
--model-mode MODE | LLM backend: local, ollama, openai, anthropic, gemini, mock |
--model-name NAME | Specific model name to use |
--api-key KEY | API key (prefer KEKKAI_FIX_API_KEY env var) |
--max-fixes N | Maximum fixes per run (default: 10) |
--no-backup | Disable backup creation when applying |
kekkai doctor
Verify that all prerequisites are available: Docker daemon, scanner image accessibility, Python version, and configuration validity. Run this before your first scan.
CI/CD Integration
Kekkai CI mode runs scanners, evaluates severity thresholds, and returns structured exit codes so your pipeline can distinguish scan errors from policy violations. Generate a ready-to-use workflow file with kekkai init --ci.
GitHub Actions
Pre-commit hook
GitHub PR Comments
Post security findings directly as pull request review comments. In GitHub Actions, the PR number and repository are auto-detected from the event payload.
--pr-comment | Enable PR comment posting |
--github-token TOKEN | GitHub token (or set GITHUB_TOKEN env var) |
--pr-number NUM | PR number (auto-detected in GitHub Actions) |
--github-repo REPO | owner/repo (auto-detected in GitHub Actions) |
--max-comments NUM | Maximum comments to post (default: 50) |
--comment-severity LEVEL | Minimum severity for comments (default: medium) |
DefectDojo
Spin up a local DefectDojo vulnerability management dashboard with one command. Credentials are generated automatically and stored in ~/.kekkai/dojo/.env.
dojo up options
--port PORT | HTTP port for the UI (default: 8080) |
--tls-port PORT | HTTPS port (default: 8443) |
--wait | Wait for UI readiness before returning |
--open | Open the UI in a browser after starting |
--project-name NAME | Docker Compose project name |
ThreatFlow
Generate STRIDE-aligned threat models from your codebase using a local or remote LLM. With Ollama (recommended), your code never leaves your machine. Remote providers (OpenAI, Anthropic, Gemini) are explicitly opt-in.
With Ollama (recommended)
All options
--repo PATH | Path to repository to analyze |
--output-dir PATH | Output directory for artifacts |
--model-mode MODE | local (default), ollama, openai, anthropic, gemini, mock |
--model-name NAME | Model name (e.g. mistral, gpt-4o, claude-3-5-sonnet) |
--api-key KEY | API key for remote provider (prefer env var) |
--max-files NUM | Maximum files to analyze (default: 500) |
--timeout SECS | Timeout for model calls (default: 300) |
--no-redact | Disable secret redaction (NOT RECOMMENDED) |
Output artifacts
THREATS.md | Identified threats with STRIDE categorization |
DATAFLOWS.md | Data flow diagram description |
ASSUMPTIONS.md | Analysis assumptions and limitations |
threat-model.json | Machine-readable threat model |
DAST with OWASP ZAP
Run a baseline DAST scan against a running HTTP service. On Linux, 127.0.0.1 and localhost targets are rewritten to host.docker.internal automatically so the container can reach your application.
--allow-private-ips is required for scanning localhost or internal IPs. Do not use this flag against production or external systems without authorization.Configuration
Kekkai loads configuration in this order (later sources override earlier):
- Built-in defaults
- Config file:
~/.config/kekkai/config.toml(Linux/macOS) or%APPDATA%\kekkai\config.toml(Windows) - Environment variables with
KEKKAI_prefix - CLI flags
Minimal config.toml
Full configuration reference
Environment Variables
KEKKAI_REPO_PATH | Default repository path |
KEKKAI_RUN_BASE_DIR | Base directory for run outputs |
KEKKAI_TIMEOUT_SECONDS | Scanner timeout in seconds |
KEKKAI_DOJO_URL | DefectDojo base URL |
KEKKAI_DOJO_API_KEY | DefectDojo API key |
KEKKAI_DOJO_PORT | DefectDojo HTTP port |
KEKKAI_ZAP_TARGET_URL | ZAP target URL |
KEKKAI_ENABLE_FALCO | Enable Falco runtime security (1 to enable) |
KEKKAI_THREATFLOW_MODE | ThreatFlow model mode |
KEKKAI_THREATFLOW_API_KEY | ThreatFlow API key |
KEKKAI_THREATFLOW_MODEL_NAME | ThreatFlow model name |
KEKKAI_FIX_API_KEY | API key for fix engine LLM |
GITHUB_TOKEN | GitHub token for PR comments |
GITHUB_REPOSITORY | GitHub repository (auto-detected in Actions) |
Exit Codes
0 | Success — all checks passed |
1 | General error or policy passed with warnings |
2 | Policy violation — findings exceed configured thresholds |
3 | Scan error — scanner failed to execute |
Ignore File Format
The .kekkaiignore file is generated by the triage TUI when you mark findings as false positives. It is read automatically by kekkai scan from the repository root.
Commit .kekkaiignore to your repository to share triage decisions with your team. Re-triage periodically when dependencies update.