@xaccefy/pi-casefile 0.3.1 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # pi-casefile
 
-Local-first security case ledger for Pi Agent. Tracks hypotheses → confirmed findings with a hard PoC gate, SQLite storage, and an isolated PoC runner.
+Local security case book for Pi Agent. Keeps your guesses → proven findings behind a PoC gate, saved in SQLite, run in a sandbox.
 
 ## Install
 
@@ -12,7 +12,7 @@ Or via the XPI umbrella package: `pi install npm:@xaccefy/pi-xpi`
 
 ## XP mode (default OFF)
 
-The cyber-workflow context injection is **quiet by default** so normal dev work is not flooded with security process text.
+The attack-mode text stays **quiet by default** so your normal coding isn't buried in security talk.
 
 | Control | Effect |
 |---------|--------|
@@ -21,7 +21,7 @@ The cyber-workflow context injection is **quiet by default** so normal dev work
 | `PI_XP_MODE=on` | Force ON for this process (overrides file) |
 | `PI_XP_MODE=off` | Force OFF |
 
-When **ON**, every prompt injects the attacker-oriented cyber workflow plus any active (non-killed/non-reported) cases. When **OFF**, nothing is injected; tools remain available.
+When **ON**, every prompt gets the attacker-minded workflow plus any open cases. When **OFF**, nothing is added; tools still work.
 
 State is persisted next to the ledger as `xp-mode` (e.g. `.pi/xp-mode`).
 
@@ -42,12 +42,12 @@ hypothesis → investigating → confirmed → reported
               blocked         killed (terminal)
 ```
 
-- **investigating** requires `evidence` + `confidence`
-- **confirmed** only via `PromoteFinding` (PoC exit 0) — `CaseUpdate(status:"confirmed")` is rejected
-- **reported** requires `CaseReport` first
-- **killed** / **reported** are terminal (no further field edits)
+- **investigating** needs `evidence` + `confidence`
+- **confirmed** only by running the PoC (`PromoteFinding`, exit 0) — you can't just set status to confirmed
+- **reported** needs `CaseReport` first
+- **killed** / **reported** are final (no more edits)
 
-There is **no** `impact_proof` tool field. Put proof text in `impact` or `evidence`.
+There is **no** `impact_proof` field. Put proof in `impact` or `evidence`.
 
 ## Tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaccefy/pi-casefile",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "description": "Offensive security case tracker for Pi Agent — bug bounties, CTFs, security audits",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -487,6 +487,43 @@ Keep killed reasons explicit in assumptions/blockers:
 - \`environmental_issue\`
 - \`not_applicable\` (true bug / interesting behavior, no realistic attacker value)
 Documenting kills prevents re-opening dead ends.
+
+---
+
+## 9. Tool Ecosystem (USE PROACTIVELY)
+
+You have offensive tools beyond casefile. Use them — do not rely on memory or guesswork.
+
+| Tool | When to use | Do NOT skip it when... |
+|------|------------|------------------------|
+| **ExploitSearch** | Before writing any PoC. Search for known techniques, bypasses, and attack primitives relevant to the target stack/vuln class. | ...you are investigating a hypothesis or building a PoC. Ground your approach in real write-ups, not memory. |
+| **engage** | When testing a live web target that requires authentication. Add a session (cookie/OAuth/mTLS) then run curl/httpx/ffuf with auth injected. | ...the user has supplied credentials or a target URL for authenticated testing. |
+| **web_search** | To find CVEs, advisories, prior bug reports, documentation, or any live information about the target. | ...you need to check if a vulnerability is known, find version-specific issues, or research a technology. |
+| **web_fetch** | To read full page content from a URL you already have (advisory, write-up, target page). | ...you have a specific URL to inspect. |
+| **context7** | To look up current library/framework API docs and behavior. | ...you need to understand how a framework feature works (auth, parsing, routing). |
+| **deepwiki** | To ask questions about a public GitHub repository's architecture and internals. | ...the target is an open-source project and you need to understand its design. |
+| **codebase-memory-mcp** | To index a codebase and trace source-to-sink paths. index_repository, get_architecture, search_graph, trace_path. | ...you have access to the target source code and need structural reachability analysis. |
+
+**pdtm CLI tools** (run via bash; each takes auth/flags differently — read the flags, do not guess):
+- subfinder -d host (-silent, -t threads) — passive subdomain enum from API sources; no target auth. Pipe to httpx, not straight to nuclei.
+- httpx -u <url> / -l hosts.txt (-t threads, -td tech-detect, -mc match-status, -H "Name: Value") — fast probe of authed endpoints; supports Header/Cookie/Bearer.
+- ffuf -u <url> -w wordlist (-t threads, -rate, -H "..." -b "c=v", -mc/-fs filters) — authed fuzzing / content discovery.
+- whatweb <url> (-a aggression 1-4, -t threads, --cookie) — tech fingerprint; positional URL, no -u.
+- naabu -host <ip> / -l (-p ports, -rate, -c top-ports) — port scan; hosts, not web-auth.
+- katana -u <url> / -list (-d depth, -jc js-crawl, -H "...") — crawl (engage spider already does authed crawl).
+- nuclei -l hosts.txt / -u <url> (-tags, -severity, -type http, -silent; -c threads -bs host-batch -rl rate-limit -timeout 5 -retries 0): FAST when filtered, slow only if naive.
+  - Do not run all 9000+ templates. Filter: -tags cve,exposure,rce -severity critical,high -type http -t http/misconfiguration/.
+  - Pre-filter targets: subfinder -> httpx -mc 200,403 -> nuclei (cuts ~80% of work).
+  - Tune: -c 100-200 -bs 50-100 -rl 300 (avoid Cloudflare tarpit) -timeout 5 -retries 0 -mhe 10.
+  - Many hosts: -scan-strategy host-spray (v3). Few hosts many templates: template-spray.
+- engage is auth/session/creds only (cookie/OAuth/mTLS, signup/login) — not a general scanner.
+
+**Default behavior when XP mode is ON:**
+1. Start recon with ExploitSearch + web_search before diving into code.
+2. Use engage for any authenticated web target the user has set up.
+3. Use context7/deepwiki to understand framework internals before claiming a vuln.
+4. Use codebase-memory-mcp (if available) to prove reachability structurally.
+5. Log everything to casefile (CaseAdd/CaseUpdate). Do not skip the ledger.
 `.trim();
 
 function sanitizeContextText(v?: string, max = 160): string | undefined {