Reverse Engineering / Authorized Penetration Testing / Security Research Skill Router Pack AI-powered routing + On-demand toolchain bootstrapping + Self-evolving knowledge base Supports Claude Code, Kiro, Cursor, Cline, and other AI coding clients 逆向/渗透/安全技能路由包 - AI 自动路由 + 按需自举工具链 + 自动进化经验库 | 支持 Claude Code / Kiro / Cursor / Cline 等代码 AI 客户端
Shell
docs: design complete Kali pwntools discovery
zhaoxuya520ab0a24845f18
diff --git a/docs/superpowers/specs/2026-09-21-pwntools-kali-discovery-design.md b/docs/superpowers/specs/2026-09-21-pwntools-kali-discovery-design.mdnew file mode 100644index 0000000..f2c9544--- /dev/null+++ b/docs/superpowers/specs/2026-09-21-pwntools-kali-discovery-design.md@@ -0,0 +1,78 @@+# Kali pwntools discovery integration design++## Context++Pull request #144 adds `pwntools` to the Kali tool catalog, but only as a single catalog row. The current change cannot report a version, does not expose `pwntools` in the capability status table, and does not list it through the Kali bootstrap discovery interfaces. Existing CI has no regression that exercises the Kali refresh output with an installed `pwn` command.++## Goal++Integrate #144 while preserving its contributor commit, then complete the Kali-facing discovery path so that:++1. `pwn` is detected as the executable supplied by pwntools.+2. The generated tool index records its resolved path and version.+3. The generated capability table includes `pwntools`, reports runtime availability through `pwn`, and identifies its installer as `pip-package`.+4. `bootstrap-reverse.sh --list` and its human-readable help include `pwntools`.+5. Both bootstrap manifests use the executable command `pwn` for post-install verification.+6. CI exercises these behaviours without installing pwntools or touching the host environment.++## Non-goals++- Do not install the real pwntools package during tests.+- Do not change routing rules or the pwntools package/version pin.+- Do not refactor every duplicated capability list into generated data.+- Do not change unrelated bootstrap behaviour.++## Design++### Tool catalog++Keep the #144 catalog entry but use `--version` and the executable fallback `pwn`. The logical tool name remains `pwntools`; the resolved executable is `pwn`.++Expected generated record:++```text+pwntools|reverse-engineering|CTF pwn 利用开发框架|yes|<stub>/pwn|Pwntools 4.15.0|command+```++### Capability status++Add `pwntools` to `CAPABILITY_NAMES`. Its availability check is a dedicated `command -v pwn`, because `command -v pwntools` is not valid. Its bootstrap kind is `pip-package`, matching both manifests and the existing installer branch.++### Bootstrap discovery++Add `pwntools` to the machine-readable `--list` output and to the CTF/reverse-analysis help section. Change `verifyCommand` from the nonexistent `pwntools` executable to `pwn` in both platform manifests.++### Regression test++Add a hermetic Bash test under `kali/scripts/` that:++1. Creates a temporary `PATH` with only required system-command links and a stub `pwn` command.+2. Runs `kali/scripts/refresh-tool-index.sh` into temporary Markdown/JSON outputs.+3. Asserts exactly one pwntools tool record, available status, canonical stub path, and version text.+4. Asserts the Markdown capability row reports pwntools as available and `pip-package` installable.+5. Asserts `bootstrap-reverse.sh --list` advertises pwntools.+6. Parses both manifests and asserts `verifyCommand == "pwn"`.++The test must not invoke package installation, network access, client configuration, or repository output paths.++### CI wiring++Run the new regression in the existing Ubuntu Bash CI job after shell syntax validation. It is a Kali-script behaviour test but remains host-independent through command stubs, so a Kali container is unnecessary.++## TDD sequence++1. Add the regression test and CI invocation.+2. Run it against the current main plus the unmodified #144 commit and confirm failure for the missing version/capability/list/manifest behaviour.+3. Apply the smallest production changes required for the assertions.+4. Re-run the focused test until green.+5. Run Bash syntax, bootstrap-manifest, routing, repository-security, document-link, JSON, YAML, UTF-8/BOM and mojibake checks.++## Integration and provenance++Create a merge commit whose second parent is the original #144 head, preserving contributor provenance. Add the completion changes as a separate maintainer commit. Push only after local verification; wait for GitHub CI before fast-forwarding `main`. No force-push is permitted.++## Failure handling++- A missing `pwn` command must produce an unavailable pwntools record without aborting refresh.+- A failing `pwn --version` command may leave the version empty, consistent with existing discovery behaviour, but detection remains based on executable presence.+- Any CI failure blocks integration into `main`.