@gpzhang2001/sharpkit-skills 0.2.1

package/skills/tooling/httpx.md

@@ -0,0 +1,82 @@
+---
+name: httpx
+description: ProjectDiscovery httpx probing syntax, exact probe flags, and automation-safe output patterns.
+---
+
+# httpx CLI Playbook
+
+Official docs:
+- https://docs.projectdiscovery.io/opensource/httpx/usage
+- https://docs.projectdiscovery.io/opensource/httpx/running
+- https://github.com/projectdiscovery/httpx
+
+Canonical syntax:
+`httpx [flags]`
+
+High-signal flags:
+- `-u, -target <url>` single target
+- `-l, -list <file>` target list
+- `-nf, -no-fallback` probe both HTTP and HTTPS
+- `-nfs, -no-fallback-scheme` do not auto-switch schemes
+- `-sc` status code
+- `-title` page title
+- `-server, -web-server` server header
+- `-td, -tech-detect` technology detection
+- `-fr, -follow-redirects` follow redirects
+- `-mc <codes>` / `-fc <codes>` match or filter status codes
+- `-path <path_or_file>` probe specific paths
+- `-p, -ports <ports>` probe custom ports
+- `-proxy, -http-proxy <url>` proxy target requests
+- `-tlsi, -tls-impersonate` experimental TLS impersonation
+- `-j, -json` JSONL output
+- `-sr, -store-response` store request/response artifacts
+- `-srd, -store-response-dir <dir>` custom directory for stored artifacts
+- `-silent` compact output
+- `-rl <n>` requests/second cap
+- `-t <n>` threads
+- `-timeout <seconds>` request timeout
+- `-retries <n>` retry attempts
+- `-o <file>` output file
+
+Agent-safe baseline for automation:
+`httpx -l hosts.txt -sc -title -server -td -fr -timeout 10 -retries 1 -rl 50 -t 25 -silent -j -o httpx.jsonl`
+
+Common patterns:
+- Quick live+fingerprint check:
+  `httpx -l hosts.txt -sc -title -server -td -silent -o httpx.txt`
+- Probe known admin paths:
+  `httpx -l hosts.txt -path /,/login,/admin -sc -title -silent -j -o httpx_paths.jsonl`
+- Probe both schemes explicitly:
+  `httpx -l hosts.txt -nf -sc -title -silent`
+- Vhost detection pass:
+  `httpx -l hosts.txt -vhost -sc -title -silent -j -o httpx_vhost.jsonl`
+- Proxy-instrumented probing:
+  `httpx -l hosts.txt -sc -title -proxy http://127.0.0.1:48080 -silent -j -o httpx_proxy.jsonl`
+- Response-storage pass for downstream content parsing:
+  `httpx -l hosts.txt -fr -sr -srd recon/httpx_store -sc -title -server -cl -ct -location -probe -silent`
+
+Critical correctness rules:
+- For machine parsing, prefer `-j -o <file>`.
+- Keep `-rl` and `-t` explicit for reproducible throughput.
+- Use `-nf` when you need dual-scheme probing from host-only input.
+- When using `-path` or `-ports`, keep scope tight to avoid accidental scan inflation.
+- Use `-sr -srd <dir>` when later steps need raw response artifacts (JS/route extraction, grepping, replay).
+
+Usage rules:
+- Use `-silent` for pipeline-friendly output.
+- Use `-mc/-fc` when downstream steps depend on specific response classes.
+- Prefer `-proxy` flag over global proxy env vars when only httpx traffic should be proxied.
+- Do not use `-h`/`--help` for routine runs unless absolutely necessary.
+
+Failure recovery:
+- If too many timeouts occur, reduce `-rl/-t` and/or increase `-timeout`.
+- If output is noisy, add `-fc` filters or `-fd` duplicate filtering.
+- If HTTPS-only probing misses HTTP services, rerun with `-nf` (and avoid `-nfs`).
+
+If uncertain, query web_search with:
+`site:docs.projectdiscovery.io httpx <flag> usage`
+
+Companion: `wafw00f <url>` fingerprints the WAF/CDN in front of a target
+(Cloudflare, Akamai, AWS WAF, etc.). Run it once after httpx confirms the
+host is live — the WAF identity decides whether to throttle fuzzing,
+swap to evasion payload sets, or assume blocking and route differently.

package/skills/tooling/hurl.md

@@ -0,0 +1,99 @@
+---
+name: hurl
+description: Reproducible, reviewable HTTP request chains and response assertions with Hurl for authorized multi-step security validation, vulnerable-versus-fixed regression cases, captured values, and low-rate semantic oracles
+---
+
+# Hurl Security Regression Playbook
+
+Use [Hurl](https://hurl.dev/) when a security proof requires an ordered HTTP session whose requests, captured values, and assertions should be code-reviewed and replayed. It is well suited to authentication flows, redirects, cookies, CSRF tokens, upload lifecycles, patch regression, and paired semantic-differential cases.
+
+Hurl sends exactly what the file describes. It does not make state-changing requests safe. Review scope, methods, targets, and captured secrets before every run.
+
+## Install
+
+Prefer an official release binary or package. On macOS:
+
+```bash
+brew install hurl
+hurl --version
+```
+
+Official alternatives include release packages and `cargo install --locked hurl`; see [installation](https://hurl.dev/docs/installation.html). Record the tool version with results.
+
+## Minimal Chain
+
+```hurl
+# lab-regression.hurl
+GET {{base_url}}/session
+HTTP 200
+[Captures]
+csrf: xpath "string(//input[@name='csrf']/@value)"
+[Asserts]
+header "Content-Type" startsWith "text/html"
+
+POST {{base_url}}/action
+Content-Type: application/x-www-form-urlencoded
+[FormParams]
+csrf: {{csrf}}
+operation: noop
+HTTP 204
+```
+
+Hurl keeps cookies across requests in the same file, so an explicit `Cookie` header is unnecessary here.
+
+Run one reviewed case against one authorized target first:
+
+```bash
+hurl --test --jobs 1 --connect-timeout 5s --max-time 15s \
+  --variable base_url=https://lab.example lab-regression.hurl
+```
+
+When credentials are required, pass them with `--secrets-file local-secrets.env`, keep that file outside version control, and avoid verbose/debug output that could expose headers or bodies. Use `--variables-file` only for non-secret environment values.
+
+## Designing a Security Regression
+
+- Assert the security invariant, not only a status code: denied identity, final normalized location, absence/presence of a structural field, unchanged object state, or exact benign result.
+- Capture only values needed by later requests. Do not write tokens, personal data, or response bodies into committed reports.
+- Encode a malformed but non-triggering control alongside the suspected case.
+- Run the same file against vulnerable and fixed builds through `base_url` or other explicit variables.
+- Keep state-changing methods in a clearly labeled lab/staging file; prefer no-op actions, inert markers, and cleanup requests.
+- Check every redirect step when the vulnerability crosses routing, origin, or authentication boundaries. Blindly following redirects can hide the relevant transition.
+- Use unique canaries so cached or pre-existing state cannot create a false positive.
+
+## Chain Structure
+
+Organize longer files around capability transitions:
+
+```text
+fingerprint -> establish session -> reach boundary -> prove primitive -> verify state -> cleanup
+```
+
+At each response, assert the condition required by the next request. A final success assertion cannot explain which earlier assumption failed.
+
+Useful Hurl features include:
+
+- captures from headers, cookies, JSONPath, XPath, and regex queries
+- assertions over status, headers, body, JSON/XML, redirects, and timing
+- request-local options and variables
+- `--test` plus JSON, JUnit, TAP, or HTML reports
+
+Consult the [Hurl manual](https://hurl.dev/docs/manual.html) for version-specific syntax instead of guessing an option.
+
+## Safety Rules
+
+- Use an explicit `base_url`; never derive the destination from untrusted response data without validating scheme, host, and port.
+- Review POST/PUT/PATCH/DELETE requests and server-side side effects before replay.
+- Set bounded timeouts and retries for the target; do not use polling as an unbounded brute-force loop.
+- Do not use Hurl for raw HTTP parser/smuggling cases when its HTTP stack normalizes the bytes being tested; use an appropriate raw harness in an isolated lab.
+- Use `--path-as-is` when literal `/../` or `/./` path segments are the behavior under test; otherwise Hurl's underlying URL handling can normalize them.
+- Redact reports. HTML/JSON/JUnit artifacts may contain request URLs, headers, captured variables, and response snippets.
+- Keep authentication material in local secret storage and use dedicated test accounts with minimum privilege.
+
+## Validation Deliverable
+
+1. reviewed `.hurl` file with variableized target and no embedded secrets
+2. vulnerable, fixed, and negative-control environment descriptions
+3. assertion at every capability transition
+4. deterministic results with tool version and timestamps
+5. side effects, cleanup, and residual-state check
+6. redacted report appropriate for sharing

package/skills/tooling/hypothesis.md

@@ -0,0 +1,100 @@
+---
+name: hypothesis
+description: Property-based local differential testing with Hypothesis for parsers, canonicalizers, serializers, validators, routers, and other pure functions, emphasizing explicit invariants, shrinking, reproducibility, and bounded resource use
+---
+
+# Hypothesis Differential Testing
+
+Use [Hypothesis](https://hypothesis.readthedocs.io/) when a security property can be expressed over local code and failures are likely to hide in combinations of encoding, normalization, structure, or parser recovery. It is especially useful for comparing two implementations or checking that validation and consumption preserve the same meaning.
+
+Do not point unrestricted generators at a live service. Hypothesis is safest and most useful against pure local adapters with no network, subprocess, filesystem, or persistent-state side effects.
+
+## Install
+
+Use an isolated virtual environment and install a reviewed pinned version:
+
+```bash
+python -m pip install 'hypothesis==<reviewed-version>'
+```
+
+Official project: [Hypothesis](https://github.com/HypothesisWorks/hypothesis)
+
+## Start From an Invariant
+
+Write the security relationship before writing strategies. Examples:
+
+```text
+allowlist(raw) implies sink(canonicalize(raw)) remains inside the allowed origin/path
+validator(raw) accepts implies consumer(raw) assigns the same media type/structure
+parse_A(raw) and parse_B(raw) agree on message boundaries and authoritative fields
+serialize(parse(raw)) cannot introduce a delimiter, wildcard, traversal, or new field
+```
+
+A test that only checks “does not crash” can find robustness bugs but does not establish a security differential.
+
+## Minimal Differential Harness
+
+```python
+from hypothesis import given, settings, strategies as st
+
+
+def outcome(parser, raw):
+    try:
+        return ("accept", parser(raw))
+    except ExpectedParseError as exc:
+        return ("reject", type(exc).__name__)
+
+
+@settings(max_examples=250, deadline=500)
+@given(st.text(max_size=128))
+def test_security_boundary(raw: str) -> None:
+    checked = outcome(security_parser, raw)
+    consumed = outcome(sink_parser, raw)
+    assert equivalent_security_meaning(checked, consumed)
+```
+
+- Bound string/list/binary sizes, recursion, examples, and deadline.
+- Build structured inputs from relevant tokens rather than generating unrestricted noise.
+- Normalize expected accept/reject/error outcomes explicitly so ordinary parser rejection is not mistaken for a property-test failure.
+- Use `st.one_of`, `st.sampled_from`, `st.lists`, `st.binary`, `st.text`, and composite strategies to represent the actual grammar.
+- Add explicit edge seeds with `@example` for known delimiters and regressions.
+- Let Hypothesis shrink failures; the minimal counterexample is often the clearest explanation of the parser disagreement.
+
+## High-Value Strategy Axes
+
+- percent and double encoding, malformed escapes, mixed separators
+- Unicode normalization, replacement characters, surrogates, case folding, IDNA
+- dot segments, slash/backslash, absolute/relative paths, sibling-prefix collisions
+- duplicate, empty, first/last, comma-joined, or differently cased fields
+- declared length versus actual bytes, truncation, padding, and terminators
+- nested objects, parser depth, ordering, unknown keys, and error recovery
+- serialize/deserialize round trips and version-to-version behavior
+
+Generate only axes supported by the target's transformation graph. Cartesian payload spraying obscures causality.
+
+## Reproducibility
+
+- Keep the minimized failing example as a normal regression test.
+- Preserve code revision, dependency lock, locale, platform, and parser/library versions.
+- Keep Hypothesis's example database in a task-specific artifact directory when replay across runs matters.
+- For CI, rely on stored explicit regressions for critical cases; randomized discovery supplements them.
+- Classify nondeterminism before suppressing health checks. Timing, global state, environment, and shared caches can create flaky false differentials.
+
+## Safety and Resource Controls
+
+- Adapt target functions so tests cannot reach the network or execute commands.
+- Use temporary directories and non-secret corpora for parsers that require files.
+- Put native parsers in a disposable, networkless process/container with CPU, memory, file-size, and process ceilings.
+- Do not disable deadlines globally to hide hangs; isolate and bound intentionally slow examples.
+- A crash, timeout, or excessive allocation is a robustness result. Prove a security boundary or exploitability separately.
+- Never reuse captured credentials, customer content, or production requests as generative corpora without sanitization.
+
+## Validation Deliverable
+
+1. stated invariant and why it protects a security boundary
+2. adapters and exact component/version pair compared
+3. bounded strategies and resource settings
+4. minimized counterexample and both interpretations
+5. stable explicit regression test
+6. impact trace from disagreement to privileged consumer
+7. fixed-version or corrected-invariant result

package/skills/tooling/katana.md

@@ -0,0 +1,102 @@
+---
+name: katana
+description: Katana crawler syntax, depth/js/known-files behavior, and stable concurrency controls.
+---
+
+# Katana CLI Playbook
+
+Official docs:
+- https://docs.projectdiscovery.io/opensource/katana/usage
+- https://docs.projectdiscovery.io/opensource/katana/running
+- https://github.com/projectdiscovery/katana
+
+Canonical syntax:
+`katana [flags]`
+
+High-signal flags:
+- `-u, -list <url|file>` target URL(s)
+- `-d, -depth <n>` crawl depth
+- `-jc, -js-crawl` parse JavaScript-discovered endpoints
+- `-jsl, -jsluice` deeper JS parsing (memory intensive)
+- `-kf, -known-files <all|robotstxt|sitemapxml>` known-file crawling mode
+- `-proxy <http|socks5 proxy>` explicit proxy setting
+- `-c, -concurrency <n>` concurrent fetchers
+- `-p, -parallelism <n>` concurrent input targets
+- `-rl, -rate-limit <n>` request rate limit
+- `-timeout <seconds>` request timeout
+- `-ct, -crawl-duration <s|m|h|d>` maximum time to crawl the target
+- `-retry <n>` retry count
+- `-mdp, -max-domain-pages <n>` cap pages crawled per domain (default: unlimited)
+- `-fsu, -filter-similar` collapse similar URLs (e.g. /users/123 and /users/456)
+- `-fs, -field-scope <dn|rdn|fqdn|regex>` crawl scope (default `rdn` = root domain + ALL subdomains)
+- `-f, -field <url|path|...>` emit only one field (e.g. `-f url` for a plain URL list)
+- `-or, -omit-raw` omit raw request/response from JSONL output
+- `-ob, -omit-body` omit response body from JSONL output
+- `-mrs, -max-response-size <bytes>` cap per-response bytes read (default 4194304)
+- `-ef, -extension-filter <list>` extension exclusions
+- `-tlsi, -tls-impersonate` experimental JA3/TLS impersonation
+- `-hl, -headless` enable hybrid headless crawling
+- `-sc, -system-chrome` use local Chrome for headless mode
+- `-ho, -headless-options <csv>` extra Chrome options (for example proxy-server)
+- `-nos, -no-sandbox` run Chrome headless with no-sandbox
+- `-noi, -no-incognito` disable incognito in headless mode
+- `-cdd, -chrome-data-dir <dir>` persist browser profile/session
+- `-xhr, -xhr-extraction` include XHR endpoints in JSONL output
+- `-silent`, `-j, -jsonl`, `-o <file>` output controls
+
+Agent-safe baseline for automation:
+`mkdir -p crawl && katana -u https://target.tld -d 3 -ct 10m -mdp 2000 -fsu -jc -kf robotstxt -c 10 -p 10 -rl 50 -timeout 10 -retry 1 -ef png,jpg,jpeg,gif,svg,css,woff,woff2,ttf,eot,map -silent -j -o crawl/katana.jsonl`
+
+Common patterns:
+- Fast crawl baseline:
+  `katana -u https://target.tld -d 3 -jc -silent`
+- Deeper JS-aware crawl (narrowed target; keep it time-bounded):
+  `katana -u https://target.tld -d 5 -ct 15m -jc -jsl -kf all -c 10 -p 10 -rl 50 -o katana_urls.txt`
+- Multi-target run with JSONL output:
+  `katana -list urls.txt -d 3 -jc -silent -j -o katana.jsonl`
+- Headless crawl with local Chrome:
+  `katana -u https://target.tld -hl -sc -nos -xhr -j -o crawl/katana_headless.jsonl`
+- Headless crawl through proxy:
+  `katana -u https://target.tld -hl -sc -ho proxy-server=http://127.0.0.1:48080 -j -o crawl/katana_proxy.jsonl`
+
+Critical correctness rules:
+- `-kf` must be followed by one of `all`, `robotstxt`, or `sitemapxml`.
+- Use documented `-hl` for headless mode.
+- `-proxy` expects a single proxy URL string (for example `http://127.0.0.1:8080`).
+- `-ho` expects comma-separated Chrome options (example: `-ho --disable-gpu,proxy-server=http://127.0.0.1:8080`).
+- For `-kf`, keep depth at least `-d 3` so known files are fully covered.
+- If writing to a file, ensure parent directory exists before `-o`.
+
+Keeping output small (katana has NO default page cap, so plan for volume):
+- Bound scope and volume: `-fs fqdn` (or `-cs`/`-cos` regex) so the crawl doesn't wander across every subdomain, `-mdp <n>` to cap pages per domain, `-fsu` to collapse near-identical URLs, and `-ct`/`-d` to bound time and depth.
+- Shrink each record: default JSONL is verbose. If you only need endpoints, emit a plain URL list with `-f url` instead of `-j`. If you need JSONL, drop the heavy parts with `-or` (omit raw) and `-ob` (omit body), and lower `-mrs` to cap per-response bytes.
+- Reserve `-jsl` / `-kf all` / higher `-d` for a specific narrowed target — they multiply output fast on large sites.
+- Reduce, then delete: once the crawl finishes, extract just what you need (e.g. `katana ... -f url -o urls.txt` or `sort -u` a URL list, or a short note of interesting paths) and remove the raw crawl file/dir. Don't keep large raw crawls around after you've distilled them.
+- Sanity-check size (`du -sh <out>`); if it's outsized for the scope, tighten `-fs`/`-mdp`/`-fsu`/`-d`/`-ct` and re-run rather than keeping it.
+
+Usage rules:
+- Keep `-d`, `-c`, `-p`, and `-rl` explicit for reproducible runs.
+- Use `-ef` early to reduce static-file noise before fuzzing.
+- Prefer `-proxy` over environment proxy variables when proxying only Katana traffic.
+- Use `-hc` only for one-time diagnostics, not routine crawling loops.
+- Do not use `-h`/`--help` for routine runs unless absolutely necessary.
+
+Failure recovery:
+- If crawl runs too long, lower `-d` and optionally add `-ct`.
+- If memory spikes, disable `-jsl` and lower `-c/-p`.
+- If headless fails with Chrome errors, drop `-sc` or install system Chrome.
+- If output is noisy, tighten scope and add `-ef` filters.
+
+If uncertain, query web_search with:
+`site:docs.projectdiscovery.io katana <flag> usage`
+
+Complementary crawlers / JS endpoint extractors in the sandbox:
+- `gospider -s https://target.tld -d 3 -c 10 -t 20` — alternate crawler;
+  picks up things Katana misses on weird sites; use it as a second
+  pass when Katana output looks thin.
+- `~/tools/JS-Snooper/js_snooper.sh <domain>` and
+  `~/tools/jsniper.sh/jsniper.sh <domain>` — both take a bare domain and
+  run their own JS-file discovery internally (jsniper drives httpx +
+  katana + nuclei file templates). Reach for them when you want a quick
+  "find endpoints/keys/secrets in any JS this domain serves" sweep
+  without wiring it up yourself.

package/skills/tooling/naabu.md

@@ -0,0 +1,68 @@
+---
+name: naabu
+description: Naabu port-scanning syntax with host input, scan-type, verification, and rate controls.
+---
+
+# Naabu CLI Playbook
+
+Official docs:
+- https://docs.projectdiscovery.io/opensource/naabu/usage
+- https://docs.projectdiscovery.io/opensource/naabu/running
+- https://github.com/projectdiscovery/naabu
+
+Canonical syntax:
+`naabu [flags]`
+
+High-signal flags:
+- `-host <host>` single host
+- `-list, -l <file>` hosts list
+- `-p <ports>` explicit ports (supports ranges)
+- `-top-ports <n|full>` top ports profile
+- `-exclude-ports <ports>` exclusions
+- `-scan-type <s|c|syn|connect>` SYN or CONNECT scan
+- `-Pn` skip host discovery
+- `-rate <n>` packets per second
+- `-c <n>` worker count
+- `-timeout <ms>` per-probe timeout in milliseconds
+- `-retries <n>` retry attempts
+- `-proxy <socks5://host:port>` SOCKS5 proxy
+- `-verify` verify discovered open ports
+- `-j, -json` JSONL output
+- `-silent` compact output
+- `-o <file>` output file
+
+Agent-safe baseline for automation:
+`naabu -list hosts.txt -top-ports 100 -scan-type c -Pn -rate 300 -c 25 -timeout 1000 -retries 1 -verify -silent -j -o naabu.jsonl`
+
+Common patterns:
+- Top ports with controlled rate:
+  `naabu -list hosts.txt -top-ports 100 -scan-type c -rate 300 -c 25 -timeout 1000 -retries 1 -verify -silent -o naabu.txt`
+- Focused web-ports sweep:
+  `naabu -list hosts.txt -p 80,443,8080,8443 -scan-type c -rate 300 -c 25 -timeout 1000 -retries 1 -verify -silent`
+- Single-host quick check:
+  `naabu -host target.tld -p 22,80,443 -scan-type c -rate 300 -c 25 -timeout 1000 -retries 1 -verify`
+- Root SYN mode (if available):
+  `sudo naabu -list hosts.txt -top-ports 100 -scan-type syn -rate 500 -c 25 -timeout 1000 -retries 1 -verify -silent`
+
+Critical correctness rules:
+- Use `-scan-type connect` when running without root/privileged raw socket access.
+- Always set `-timeout` explicitly; it is in milliseconds.
+- Set `-rate` explicitly to avoid unstable or noisy scans.
+- `-timeout` is in milliseconds, not seconds.
+- Keep port scope tight: prefer explicit important ports or a small `-top-ports` value unless broader coverage is explicitly required.
+- Do not spam traffic; start with the smallest useful port set and conservative rate/worker settings.
+- Prefer `-verify` before handing ports to follow-up scanners.
+
+Usage rules:
+- Keep host discovery behavior explicit (`-Pn` or default discovery).
+- Use `-j -o <file>` for automation pipelines.
+- Prefer `-p 22,80,443,8080,8443` or `-top-ports 100` before considering larger sweeps.
+- Do not use `-h`/`--help` for normal flow unless absolutely necessary.
+
+Failure recovery:
+- If privileged socket errors occur, switch to `-scan-type c`.
+- If scans are slow or lossy, lower `-rate`, lower `-c`, and tighten `-p`/`-top-ports`.
+- If many hosts appear down, compare runs with and without `-Pn`.
+
+If uncertain, query web_search with:
+`site:docs.projectdiscovery.io naabu <flag> usage`

package/skills/tooling/nmap.md

@@ -0,0 +1,66 @@
+---
+name: nmap
+description: Canonical Nmap CLI syntax, two-pass scanning workflow, and sandbox-safe bounded scan patterns.
+---
+
+# Nmap CLI Playbook
+
+Official docs:
+- https://nmap.org/book/man-briefoptions.html
+- https://nmap.org/book/man.html
+- https://nmap.org/book/man-performance.html
+
+Canonical syntax:
+`nmap [Scan Type(s)] [Options] {target specification}`
+
+High-signal flags:
+- `-n` skip DNS resolution
+- `-Pn` skip host discovery when ICMP/ping is filtered
+- `-sS` SYN scan (root/privileged)
+- `-sT` TCP connect scan (no raw-socket privilege)
+- `-sV` detect service versions
+- `-sC` run default NSE scripts
+- `-p <ports>` explicit ports (`-p-` for all TCP ports)
+- `--top-ports <n>` quick common-port sweep
+- `--open` show only hosts with open ports
+- `-T<0-5>` timing template (`-T4` common)
+- `--max-retries <n>` cap retransmissions
+- `--host-timeout <time>` give up on very slow hosts
+- `--script-timeout <time>` bound NSE script runtime
+- `-oA <prefix>` output in normal/XML/grepable formats
+
+Agent-safe baseline for automation:
+`nmap -n -Pn --open --top-ports 100 -T4 --max-retries 1 --host-timeout 90s -oA nmap_quick <host>`
+
+Common patterns:
+- Fast first pass:
+  `nmap -n -Pn --top-ports 100 --open -T4 --max-retries 1 --host-timeout 90s <host>`
+- Very small important-port pass:
+  `nmap -n -Pn -p 22,80,443,8080,8443 --open -T4 --max-retries 1 --host-timeout 90s <host>`
+- Service/script enrichment on discovered ports:
+  `nmap -n -Pn -sV -sC -p <comma_ports> --script-timeout 30s --host-timeout 3m -oA nmap_services <host>`
+- No-root fallback:
+  `nmap -n -Pn -sT --top-ports 100 --open --host-timeout 90s <host>`
+
+Critical correctness rules:
+- Always set target scope explicitly.
+- Prefer two-pass scanning: discovery pass, then enrichment pass.
+- Always set a timeout boundary with `--host-timeout`; add `--script-timeout` whenever NSE scripts are involved.
+- Keep discovery scans tight: use explicit important ports or a small `--top-ports` profile unless broader coverage is explicitly required.
+- In sandboxed runs, avoid exhaustive sweeps (`-p-`, very high `--top-ports`, or wide host ranges) unless explicitly required.
+- Do not spam traffic; start with the smallest port set that can answer the question.
+- Prefer `naabu` for broad port discovery; use `nmap` for scoped verification/enrichment.
+
+Usage rules:
+- Add `-n` by default in automation to avoid DNS delays.
+- Use `-oA` for reusable artifacts.
+- Prefer `-p 22,80,443,8080,8443` or `--top-ports 100` before considering larger sweeps.
+- Do not use `-h`/`--help` for routine usage unless absolutely necessary.
+
+Failure recovery:
+- If host appears down unexpectedly, rerun with `-Pn`.
+- If scan stalls, tighten scope (`-p` or smaller `--top-ports`) and lower retries.
+- If scripts run too long, add `--script-timeout`.
+
+If uncertain, query web_search with:
+`site:nmap.org/book nmap <flag>`

package/skills/tooling/nuclei.md

@@ -0,0 +1,67 @@
+---
+name: nuclei
+description: Exact Nuclei command structure, template selection, and bounded high-throughput execution controls.
+---
+
+# Nuclei CLI Playbook
+
+Official docs:
+- https://docs.projectdiscovery.io/opensource/nuclei/running
+- https://docs.projectdiscovery.io/opensource/nuclei/mass-scanning-cli
+- https://github.com/projectdiscovery/nuclei
+
+Canonical syntax:
+`nuclei [flags]`
+
+High-signal flags:
+- `-u, -target <url>` single target
+- `-l, -list <file>` targets file
+- `-im, -input-mode <mode>` list/burp/jsonl/yaml/openapi/swagger
+- `-t, -templates <path|tag>` explicit template path(s)
+- `-tags <tag1,tag2>` run by tag
+- `-s, -severity <critical,high,...>` severity filter
+- `-as, -automatic-scan` tech-mapped automatic scan
+- `-ni, -no-interactsh` disable OAST/interactsh requests
+- `-rl, -rate-limit <n>` global request rate cap
+- `-c, -concurrency <n>` template concurrency
+- `-bs, -bulk-size <n>` hosts in parallel per template
+- `-timeout <seconds>` request timeout
+- `-retries <n>` retries
+- `-stats` periodic scan stats output
+- `-silent` findings-only output
+- `-j, -jsonl` JSONL output
+- `-o <file>` output file
+
+Agent-safe baseline for automation:
+`nuclei -l targets.txt -as -s critical,high -rl 50 -c 20 -bs 20 -timeout 10 -retries 1 -silent -j -o nuclei.jsonl`
+
+Common patterns:
+- Focused severity scan:
+  `nuclei -u https://target.tld -s critical,high -silent -o nuclei_high.txt`
+- List-driven controlled scan:
+  `nuclei -l targets.txt -as -rl 50 -c 20 -bs 20 -timeout 10 -retries 1 -j -o nuclei.jsonl`
+- Tag-driven run:
+  `nuclei -l targets.txt -tags cve,misconfig -s critical,high,medium -silent`
+- Explicit templates:
+  `nuclei -l targets.txt -t http/cves/ -t dns/ -rl 30 -c 10 -bs 10 -j -o nuclei_templates.jsonl`
+- Deterministic non-OAST run:
+  `nuclei -l targets.txt -as -s critical,high -ni -stats -rl 30 -c 10 -bs 10 -timeout 10 -retries 1 -j -o nuclei_no_oast.jsonl`
+
+Critical correctness rules:
+- Provide a template selection method (`-as`, `-t`, or `-tags`); avoid unscoped broad runs.
+- Keep `-rl`, `-c`, and `-bs` explicit for predictable resource use.
+- Use `-ni` when outbound interactsh/OAST traffic is not expected or not allowed.
+- Use structured output (`-j -o <file>`) for automation.
+
+Usage rules:
+- Start with severity/tags/templates filters to keep runs explainable.
+- Keep retries conservative (`-retries 1`) unless transport instability is proven.
+- Do not use `-h`/`--help` for routine operation unless absolutely necessary.
+
+Failure recovery:
+- If performance degrades, lower `-c/-bs` before lowering `-rl`.
+- If findings are unexpectedly empty, verify template selection (`-as` vs explicit `-t/-tags`).
+- If scan duration grows, reduce target set and enforce stricter template/severity filters.
+
+If uncertain, query web_search with:
+`site:docs.projectdiscovery.io nuclei <flag> running`