docs(examples): vulnerable-vault example + product-first README#101
Closed
aktasbatuhan wants to merge 3 commits into
Closed
docs(examples): vulnerable-vault example + product-first README#101aktasbatuhan wants to merge 3 commits into
aktasbatuhan wants to merge 3 commits into
Conversation
aktasbatuhan
force-pushed
the
kai/examples
branch
from
aef5c13 to
77ef80c
Compare
Collaborator
|
this one lgtm |
aktasbatuhan
force-pushed
the
kai/examples
branch
from
77ef80c to
33d6620
Compare
andthattoo
approved these changes
Jun 9, 2026
- 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
Follows the console-script rename (`kai` → `kai-security`, which avoids shadowing kai-agent's `kai`). Updates the copy-pasteable example commands in the walkthrough docs; the import package / module names are unchanged.
Member
Author
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.
Stacked on #100 (
kai/cli) — uses thekai audit/view/reportcommands. Retarget tomasteras the stack lands.What this does
Makes the README a "run this in 60s" experience instead of "trust me," and gives newcomers something real to point Kai at.
examples/vulnerable-vault/A tiny, self-contained, intentionally-vulnerable Solidity target:
src/Vault.sol— a reentrancy inwithdraw()and an unchecked ERC-20 return insweepToken().threat_context.yaml— a ready-made threat context for the target.README.md— documents the planted bugs, the exactkai auditcommand, and the expected findings.Lets anyone run the full audit → view/report loop without a private repo or large API spend. Clearly marked intentionally-insecure / authorized-demo-only.
README reframe (product-first)
kai audit examples/vulnerable-vault→kai view/kai report.evaluation/harness discoverable but secondary ("most users don't need it") — it wasn't mentioned in the main README before.The deep reference docs (model/env tables, threat-context schema, full Usage) are unchanged, just below the quickstart.
Verification
pytest592 passed / 6 skipped (no code changed);ruffclean.src/Vault.sol,foundry.toml,threat_context.yaml,README.md.Follow-up (asset, not code)
A short screencast/GIF of
kai viewwould strengthen the README top — a design/asset task for whoever owns the repo's media.