Open Kritt

open-kritt — Local AI Vulnerability Scanner (Hermes integration)

> What it is: open-kritt is a self-hosted Docker stack (frontend + backend + engine + Postgres), not a CLI binary and not a public SaaS. There is no API key and no npm/pip package — you run it yourself. This skill drives its local backend REST API so Hermes can launch scans and pull findings the same way it uses pentest-ai, but over HTTP to localhost instead of MCP.

> Do NOT waste turns trying to install it as a package. Confirmed dead ends > (Aug 2026): no kritt/open-kritt/open-kritt-ai on PyPI, nothing on the > npm registry, no GitHub release binary (releases/latest/download/... → 404), > and npx github:Kritt-ai/open-kritt fails with ENOENT ... package.json > because the repo ROOT has no package.json (the JS lives under backend/, > frontend/, engine/). pip install git+https://... also fails — no > setup.py/pyproject.toml at root. The ONLY supported install is the Docker > stack (git clone → ./kritt setup → ./kritt start). This is the general > rule for any tool whose README quick-start is git clone && ./ > start rather than pip/npm/brew install: treat it as a self-hosted > service, point the skill at its local API, and don't go package-hunting.

> pentest-ai = MCP server, open-kritt = local HTTP API. pentest-ai > (ptai) is wired in via hermes mcp add (config mcp_servers.pentest-ai: > {command: ptai, args: [mcp]}), which is why Hermes can call its tools every > turn as first-class tools. open-kritt has no mcp subcommand — it's a web > stack — so it can't be an MCP server. The equivalent "callable during bug > hunting" integration is: a skill whose description triggers on scan/audit > requests + a scripts/ REST client that hits the local backend. Don't try to > hermes mcp add a tool that doesn't speak MCP.

---

1. One-time install (you do this once, outside Hermes)

Needs Git, Docker + Docker Compose, and Node.js 20+.

git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt
./kritt setup      # guided: pick model access (Codex login / OpenAI / Anthropic / OpenRouter)
./kritt start      # brings up the Docker stack

When it's up:

• Backend API: http://127.0.0.1:3002/api
• Web UI: http://127.0.0.1:5173

> ⚠️ The backend has no application auth and binds to 127.0.0.1. Keep it > private. If you need it on your phone, front it with the existing Tailscale > Serve setup — don't expose 3002/5173 to the public internet.

---

2. How Hermes calls it

All calls go through scripts/kritt_runner.py, which hits the local backend. Override the base URL with KRITT_BACKEND_URL if you changed the port.

Discover what's available first (workflow IDs are required to scan)

python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py --list-workflows
python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py --list-post-scripts
python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py --list-local-repos

Scan a remote GitHub repo (auto-picks first workflow, waits, returns findings)

python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py \
  --target https://github.com/org/target-contracts

Scan with an explicit workflow + post-script (validate/PoC step)

python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py \
  --target org/target-contracts \
  --workflow-id 1 \
  --post-script-id 2

Launch without blocking (return a scan id + UI link immediately)

python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py \
  --target org/repo --no-wait

Pull findings for a scan that's already finished

python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py --scan-id 42 --results

Scan a local folder (register it in the UI first, then reference by name)

python3 ~/.hermes/skills/open-kritt/scripts/kritt_runner.py \
  --target my-local-repo-folder --repo-kind local

---

3. Backend REST API (reference)

Base: http://127.0.0.1:3002/api

| Method | Path | Purpose | |---|---|---| | GET | /health | {status:"ok"} liveness | | GET | /workflows | list workflows (need an id to scan) | | GET | /post-scripts | list post-scripts (validate / PoC / report steps) | | GET | /local-repos | list registered local repos | | POST | /scans | create a scan (body below) | | GET | /scans/:id | scan status | | GET | /scans/:id/vulnerabilities | ranked findings | | PATCH | /scans/:id | pause / stop / resume | | DELETE | /scans/:id | delete a finished scan |

POST /scans body:

{
  "workflowId": 1,
  "repo": { "kind": "remote", "repo_full": "org/repo", "commit_sha": "HEAD" },
  "postScriptId": 2,
  "launchPolicy": "immediate"
}

kind is remote (GitHub) or local (a folder registered via the UI). launchPolicy immediate starts now; queue waits behind a running scan (the API returns 409 scan_launch_policy_required if one is active and you didn't choose).

---

4. Bug-hunting workflow

1. ./kritt start                      # (once) bring the stack up
2. --list-workflows                   # find the workflow id you want
3. --target                     # launch + wait + pull findings
4. Feed findings → web3-audit / bug-bounty skill
5. Validate exploitability with Foundry/Echidna PoC
6. Write report → report-writing skill → submit

Pair with: web3-audit, smart-contract-audit-toolkit, surgical-drain-pattern, report-writing.

---

5. Files in this skill

| File | Purpose | |---|---| | scripts/kritt_runner.py | Local-backend REST client (list / scan / poll / findings) | | references/kritt-bug-class-cheatsheet.md | Bug-class → severity / bounty map | | references/default-workflows.md | Seeded workflow + post-script ID map (wf 1 = generic external-flow, wf 2 = Cosmos ABCI) | | templates/scan-request.json | POST /scans body schema |

---

6. Troubleshooting

| Symptom | Fix | |---|---| | _conn_error: Connection refused | Stack not running → ./kritt start in the repo | | no workflows found | Open the UI (:5173), seed/create a workflow, or check --list-workflows | | 409 scan_launch_policy_required | Another scan is active; pass a different launch policy or wait | | Want phone access | Front :5173 with Tailscale Serve — don't public-expose | | Different port | export KRITT_BACKEND_URL=http://127.0.0.1:/api |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sekolah76
• Source: Sekolah76/syadagentic
• License: MIT
• Homepage: https://github.com/Sekolah76/syadagentic

Install and usage instructions live in the source repository linked above.