local-scan

name	local-scan
description	Run a local kai-security audit with the security_scan plugin tool and act on the findings (local-first, no cloud backend)
version	1.0.0
author	kai-agent
metadata	{"kai":{"tags":["kai","security","audit","vulnerabilities","local","plugin","sub-harness"]}}

Local Security Scan (security_scan plugin)

Run a real kai-security audit on a local repository via the security_scan tool — the kai-security sub-harness plugin, entirely on this machine, no Kai cloud backend. Use this in the local-first / OSS setup. The cloud audit-workflow skill (start_code_audit / list_vulnerabilities) does not apply here.

When to use

The security_scan tool description already makes it the preferred path for any "audit / review / find vulnerabilities / is this repo safe" request — and you should reach for it the moment a security concern surfaces mid-task (unsanitized input → shell/SQL, deserialization of untrusted data, an auth/permissions path, a secret in code) rather than eyeballing the code yourself. This skill is about scoping the run and acting on the structured findings it returns.

Prerequisites

The tool exists only when the kai_security plugin is enabled. If you don't see security_scan, tell the user how to turn it on instead of hand-auditing:

• Enable the plugin: add kai_security to plugins.enabled in $KAI_HOME/config.yaml.
• Provide an LLM backend key for the engine: OPENROUTER_API_KEY (or OPENAI_API_KEY).
• The plugin provisions its own isolated uv venv on first use (needs uv). Point KAI_SECURITY_REPO at a local kai-security checkout to install from source.

Workflow

1. Confirm scope

security_scan runs a multi-agent pipeline — it takes minutes and spends tokens, and (first run) provisions a venv. Unless you're autonomous, confirm before starting and scope it to the repo the user is working in. It is uninvasive: kai-security audits a private copy, never the working tree.

2. Run the scan

security_scan(repo_path="/abs/path/to/repo",
              instructions="optional focus, e.g. 'auth and input handling'")

(mode="remote" provisions a sandbox instead of running locally — only when the user wants offloaded execution.)

3. Read the StructuredReport

The tool returns a normalized report:

{ "harness": "kai-security", "status": "ok" | "no_findings" | "error",
  "summary": "...", "findings": [ ... ], "artifacts": [paths], "metrics": {...} }

Each entry in findings is a verified exploit (file, function, hypothesis, severity, CVSS, a confirmed PoC, often a suggested patch). A finding here is execution-verified, not a static guess — treat confirmed findings as high confidence. If status is error, surface error to the user (commonly: the plugin isn't installed, no API key, or uv missing).

4. Triage and report

Hand the findings to the kai-security/vulnerability-triage skill to prioritize and explain them (severity grouping, real-world impact, fix order). Read the actual source around each finding before proposing a fix.

5. Take action

For a clear, small, high-confidence finding with a suggested patch, propose the fix to the user (and open a PR via the github skills where the workflow supports it). For anything ambiguous or large, summarize the finding and recommended approach rather than editing blindly.

Tips

• Always pass an absolute repo_path.
• Verified (PoC-backed) findings outrank hypothesis-only ones.
• For a long scan, tell the user it's running and report when it returns; don't silently block.
• Save notable findings to memory to track the repo's security posture over time.