feat: report + CLI + examples + umbrella (rolled-up remaining stack → master)#102
Open
aktasbatuhan wants to merge 7 commits into
Open
feat: report + CLI + examples + umbrella (rolled-up remaining stack → master)#102aktasbatuhan wants to merge 7 commits into
aktasbatuhan wants to merge 7 commits into
Conversation
aktasbatuhan
force-pushed
the
kai/examples
branch
from
aef5c13 to
77ef80c
Compare
aktasbatuhan
force-pushed
the
kai/umbrella
branch
from
e689c65 to
8f057e2
Compare
Collaborator
|
maybe a small change add the docs/umbrella.md it references in code and pyproject.toml but never includes; and document/pin the plugin handler contract (main(argv: list[str]) -> int | None, group kai.plugins, reserved verbs audit/view/report/pipeline/agent). Right now a sibling tool has to reverse-engineer the interface |
aktasbatuhan
force-pushed
the
kai/umbrella
branch
from
8f057e2 to
98e4e9d
Compare
andthattoo
previously approved these changes
Jun 9, 2026
aktasbatuhan
force-pushed
the
kai/examples
branch
from
77ef80c to
33d6620
Compare
aktasbatuhan
force-pushed
the
kai/umbrella
branch
from
98e4e9d to
8ae1a12
Compare
The no-browser companion to kai.viewer: same on-disk source (<run_dir>/exploits.json) rendered as a plain-text Markdown report you can pipe into CI, paste into a PR, or read over SSH. - render_markdown(): a sorted summary table (confirmed/critical first) plus per-finding sections -- facts, why-exploitable, exploit sketch, CVSS 3.1 breakdown table, fenced PoC, and the patch as a ```diff - render_run(): load a run dir's findings and render - python -m kai.report <run_dir> [-o OUT] (stdout by default) Reuses kai.viewer.findings.load_findings; no live state backend.
kai report --format html renders a self-contained, fully-expanded report document that shares the viewer's design system (kai.viewer.style) -- same palette, severity dots, CVSS tables, and +/- patch diff as kai view, so the two surfaces never drift. Markdown stays the default (-f md); --open opens the rendered file. Unlike the interactive viewer (master-detail + trace tabs), this is a linear document meant to be printed, attached, or shared. Static HTML with all dynamic values escaped server-side. --format scales to sarif/json later.
Match the viewer fix (#98): 'kai report -o some/new/dir/report.md' (and --format html) now mkdir the parent instead of raising FileNotFoundError.
Add a unified `kai` console entry point that dispatches the friendly verbs over the existing modules: kai audit <repo> -> setup -> exploit pipeline (kai.main pipeline) kai view <run_dir> -> interactive HTML run viewer (kai.viewer) kai report <run_dir> -> findings report, Markdown or --format html (kai.report) `kai pipeline` / `kai agent` remain as direct aliases into kai.main. Packaging: publish the distribution as `kai-security` while keeping the import package and the command named `kai` (uv build-backend module-name override). The bare `kai` name on PyPI is reserved for the future umbrella dispatcher. Document the CLI in the README and add dispatcher tests.
- examples/vulnerable-vault: a tiny, self-contained, intentionally-vulnerable Solidity target (reentrancy + unchecked ERC-20 return) with a ready-made threat_context.yaml and a README documenting the planted bugs, the run command, and the expected findings. Lets anyone try the full audit -> view/report loop without a private repo or large spend. - examples/README.md indexes the targets with a responsible-use note. - README: add a top-of-file Quickstart (install -> audit the example -> view/report), an Examples section, and a Benchmarking pointer that makes the evaluation/ harness discoverable while keeping it secondary to the product.
…EADME A real kai audit showed the original withdraw(amount) reentrancy was NOT exploitable under Solidity 0.8.x: the checked '-= amount' underflows and reverts during the reentrant unwind, and kai correctly disproved it. Switch to the canonical drainable form (zero the balance with '= 0' AFTER the external call) so the bug is real. Rewrite the example README to match verified output instead of a fabricated findings table: show the actual confirmed Critical (CVSS 9.8) reentrancy and its Check-Effects-Interaction patch, and state plainly that kai is non-deterministic — which bugs are confirmed and their scores vary by run and model.
aktasbatuhan
force-pushed
the
kai/examples
branch
from
33d6620 to
f0e8529
Compare
Make the kai command plugin-aware: beyond its built-in verbs it discovers commands registered by other installed packages under the kai.plugins entry-point group and dispatches 'kai <name> ...' to them. Built-in verbs always win, so a plugin can't shadow audit/view/report. Plugins follow the standard console-script convention: kai sets sys.argv to 'kai <name> <args>' and calls the registered zero-arg callable (which reads sys.argv), exactly as if its own console script were invoked. This means any package that already ships a [project.scripts] entry can register the SAME callable as a kai plugin with no code changes -- verified end to end against a real installed plugin and against openevolve's own openevolve.cli:main. kai-security registers itself as the 'security' plugin, so 'kai security audit' re-dispatches to the built-in audit. A sibling tool (e.g. kai-evolve) lights up 'kai evolve ...' just by registering kai.plugins.evolve. Documented in docs/umbrella.md. Additive and independently rejectable: nothing in the viewer/report/packaging work depends on it, and kai audit/view/report are unchanged.
aktasbatuhan
force-pushed
the
kai/umbrella
branch
from
8ae1a12 to
eea9dea
Compare
Member
Author
|
@eren23 One correction worth flagging: the handler is not |
aktasbatuhan
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Retargeted to
masterto land the rest of the stack in one approval + one merge. Because the branches are linear, this PR's diff is the union of the already-reviewed #99 + #100 + #101 + #102. Merging it puts their exact commits on master, so #99/#100/#101 will auto-close as merged. (#98 — thera/viewermove — is already merged.)What's in here
kai report: Markdown (default) +--format htmlstyled doc reusing the viewer's design system;-ocreates parent dirs.kaiCLI + packaging:kai audit/view/reportdispatcher (full pass-through tokai.main); distribution renamed tokai-security; wheel ships bothkaiandra(module-name = ["kai","ra"]— the fix for the wheel that previously omittedra).vulnerable-vaulttarget + product-first README, written against a real verified run.kaidiscoverskai.pluginsentry points (kai <tool> …) via the console-script convention;docs/umbrella.mdpins the contract.Verified
ty/ruffclean; 606 passed; wheel build confirmed to containkai+ra(incl.ra/viewer).kai view(Findings + Trace) andpython -m ra.viewer(Trace only); umbrella dispatch verified against openevolve + a second installed plugin.All prior review comments (Copilot sort/mkdir on #98, andthattoo params on #100) addressed and threads resolved.