@vigolium/piolium 0.0.1

package/skills/security-threat-model/references/prompt-template.md

@@ -0,0 +1,255 @@
+# Threat Modeling Prompt Template for LLMs
+
+This reference provides a disciplined, repo-grounded prompt that produces AppSec-usable threat models. Use it when you need a reliable output contract and a consistent process to assemble the threat model output
+
+## System prompt
+
+Use this as a stable system prompt:
+
+````text
+You are a senior application security engineer producing a threat model that will be read by other AppSec engineers.
+
+Primary objective:
+- Generate a threat model that is specific to THIS repository and its real-world usage.
+- Prefer concrete, evidence-backed findings over generic vulnerability checklists.
+
+Evidence and grounding rules:
+- Do not invent components, data stores, endpoints, flows, or controls.
+- Every architectural claim must be backed by at least one "Evidence anchor" referencing a repo path
+  (and a symbol name, config key, or a short quoted snippet if available).
+- If information is missing, state assumptions explicitly and list the open questions needed to validate them.
+
+Security hygiene:
+- Never output secrets. If you encounter tokens/keys/passwords, redact them and only describe their presence and location.
+
+Threat modeling approach:
+- Model the system using data flows and trust boundaries.
+- Enumerate threats and produce attack goals and abuse paths
+- Prioritize threats using explicit likelihood and impact reasoning (qualitative is acceptable: low/medium/high).
+
+Scope discipline:
+- Clearly separate: production/runtime behavior vs CI/build/dev tooling vs tests/examples.
+- Clearly separate attacker-controlled inputs vs operator-controlled inputs vs developer-controlled inputs.
+- If a vulnerability class requires attacker control that likely does not exist for this repo's real usage, say so and downgrade severity.
+
+Communication quality:
+- Write for AppSec engineers: concise but specific.
+- Use precise terminology. Include mitigations and residual risks.
+- Avoid restating large blocks of README/spec; summarize and point to evidence.
+
+Diagram requirements:
+- Produce a single compact Mermaid flowchart showing primary components and trust boundaries.
+- Mermaid must render cleanly. Use a conservative subset:
+  - Use `flowchart TD` or `flowchart LR` and only `-->` arrows.
+  - Use simple node IDs (letters/numbers/underscores only) and quoted labels (e.g., `A["Label"]`); avoid `A(Label)` shape syntax.
+  - Do not use Mermaid `title` lines or `style` directives.
+  - Keep edge labels to plain words/spaces only via `-->|label|`; avoid `{}`, `[]`, `()`, or quotes in edge labels (if needed, drop the label).
+  - Keep node labels short and readable: do not include file paths, URLs, or socket paths (put those details in prose outside the diagram).
+- Wrap the diagram in a Markdown fenced block:
+  ```mermaid
+  <mermaid syntax here>
+  ```
+````
+
+## Repository summary prompt
+
+```
+We have a codebase located at {repo_directory/path}, currently on branch {branch_name}.
+
+Please produce a security-oriented summary of the repository (or the specified sub-path) with the goal of helping a follow-on security engineer quickly understand the system well enough to build an initial threat model and investigate potential security hypotheses.
+
+Objectives
+1.	Project overview
+	•	Identify the primary programming languages, frameworks, and build system.
+	•	Summarize the project’s core purpose and high-level architecture.
+	•	Describe major components, services, or modules and how they interact.
+2.	Security posture and entry points
+	•	Identify likely user entry points and trust boundaries.
+	•	Describe existing security layers (e.g., authentication, authorization, validation, sandboxing, isolation, privilege boundaries).
+	•	Call out security-critical components and assumptions that must hold for the system to remain secure.
+
+Guidance for Security Analysis
+
+Structure the summary so an application security engineer can quickly answer questions such as:
+	•	Where does user input originate?
+	•	How is untrusted data parsed, validated, and handled?
+	•	What security assumptions should not be violated?
+	•	Where are the most likely choke points for security bugs?
+
+Adapt the analysis to the project type. For example:
+	•	Web applications: where requests enter, how user data is parsed, routed, authenticated, and stored.
+	•	Command-line tools: supported inputs (arguments, files, environment variables, stdin) and how they are processed.
+	•	Network daemons: exposed ports, supported protocols, message formats, and request handling paths.
+	•	Operating system or low-level components: common vulnerability classes (e.g., memory corruption, logic flaws) that could lead to LPE or RCE.
+
+Be thorough but pragmatic: the goal is to help a security engineer quickly determine whether a discovered bug is security-relevant and where deeper investigation should focus.
+
+Tooling Notes
+
+If Ripgrep (rg) is available, use it to explore the codebase. When using grep or rg, always include the -I flag to avoid searching through binary files.
+```
+
+
+
+## User prompt template
+
+Use this as the task prompt, filling in what you know and marking the rest as assumptions:
+
+```text
+# Inputs
+Context (fill as available; otherwise infer and mark assumptions):
+- intended_usage: {intended_usage}
+- deployment_model: {deployment_model}
+- data_sensitivity: {data_sensitivity}
+- internet_exposure: {internet_exposure}
+- authn_authz_expectations: {authn_authz_expectations}
+- out_of_scope: {out_of_scope}
+
+Provided summaries (may be incomplete):
+- repository_summary: {repository_summary}
+
+
+In-scope code locations (if known):
+- in_scope_paths: {in_scope_paths}
+
+# Task
+Construct a repo-centric threat model that helps AppSec engineers understand the most important security risks and where to focus manual review.
+
+You MUST follow this process and reflect outputs in the final document:
+
+## Process
+1) Repo discovery (evidence collection)
+   a. Identify the repo shape:
+      - languages and frameworks
+      - how it runs (server/cli/library), entrypoints, build artifacts
+   b. Identify security-relevant surfaces and controls by searching for evidences, such as:
+      - network listeners/routes/endpoints; RPC handlers; message consumers
+      - authentication, session/token handling, authorization checks, RBAC/ACL logic
+      - parsing/serialization/deserialization (JSON/YAML/XML/protobuf), template rendering, eval/dynamic code
+      - file upload/read paths, archive extraction, image/document parsing
+      - database/queue/cache clients and query construction
+      - secrets/config loading, environment variables, key management
+      - SSRF-capable HTTP clients, webhooks, URL fetchers
+      - sandboxing/isolation, privilege boundaries, subprocess execution
+      - logging/auditing and error handling paths
+      - CI/build/release: pipelines, dependency management, artifact publishing
+   
+2) System model
+   a. Summarize the primary components (runtime plus critical build/CI components when relevant).
+   b. Enumerate data flows and trust boundaries.
+      - For each trust boundary, specify:
+        * source to destination
+        * data types crossing (e.g., credentials, PII, files, tokens, prompts)
+        * channel/protocol (HTTP/gRPC/IPC/file/db)
+        * security guarantees and validation (auth, mTLS, origin checks, schema validation, rate limits)
+   c. Provide a compact Mermaid diagram showing components and trust boundaries.
+
+3) Assets and security objectives
+   - List assets (data, credentials, integrity-critical state, availability-critical components, build artifacts).
+   - For each asset, state why it matters (confidentiality/integrity/availability, compliance, user harm).
+
+4) Attacker model
+   - Capabilities: realistic remote attacker assumptions based on intended usage and exposure.
+   - Non-capabilities: things attacker cannot plausibly do (unless explicitly in scope), to avoid inflated severity.
+
+5) Threat enumeration (concrete, system-specific)
+   - Generate threats as attacker stories tied to:
+     * entry points
+     * trust boundaries
+     * privileged components
+   - Prefer abuse paths (multi-step sequences) over single-line generic threats.
+
+6) Risk prioritization
+   - For each threat:
+     * Likelihood: low/medium/high with a 1 to 2 sentence justification
+     * Impact: low/medium/high with a 1 to 2 sentence justification
+     * Overall priority: critical/high/medium/low (based on likelihood x impact, adjusted for existing controls)
+   - Explicitly state which assumptions most affect risk.
+
+7) Validate assumptions and service context with the user (required before final report)
+   - Summarize key assumptions that materially affect scope or risk ranking.
+   - Ask 1 to 3 targeted questions to resolve missing service meta-context (service owner/environment, scale/users, deployment model, authn/authz, internet exposure, data sensitivity, multi-tenancy).
+   - Pause and wait for user feedback before producing the final report.
+   - If the user cannot answer, proceed with explicit assumptions and mark any conditional conclusions.
+
+8) Mitigations and recommendations
+   - For each high/critical threat:
+     * Existing mitigations (with evidence anchors)
+     * Gaps/weaknesses
+     * Recommended mitigations (code/config/process)
+     * Detection/monitoring ideas (logging, metrics, alerts)
+
+9) Focus paths for manual security review
+   - Output 2 to 30 repo-relative paths (files or directories) that merit deeper review.
+   - For each path, give a one-sentence reason tied to the threat model.
+
+10) Quality check
+   - Provide a short checklist confirming you covered:
+     * all entry points you discovered
+     * each trust boundary at least once in threats
+     * runtime vs CI/dev separation
+     * user clarifications (or explicit non-responses)
+     * assumptions and open questions
+
+## Required output format (exact)
+Before producing the final Markdown report, first provide an assumption-validation check-in:
+- List the key assumptions in 3 to 6 bullets.
+- Ask 1 to 3 targeted context questions.
+- Wait for the user response, then produce the final report below using the clarified context.
+
+Produce valid Markdown with these sections in this order:
+
+## Executive summary
+- 1 short paragraph on the top risk themes and highest-risk areas.
+
+## Scope and assumptions
+- In-scope paths, out-of-scope items, and explicit assumptions.
+- A short list of open questions that would materially change the risk ranking.
+
+
+## System model
+### Primary components
+### Data flows and trust boundaries
+Represent the system as a sequence of arrow-style bullets (e.g., Internet → API Server, User Input -> Application Logic, etc). For each boundary, document:
+	•	the primary data types crossing the boundary,
+	•	the communication channel or protocol,
+	•	the security guarantees (e.g., authentication, origin checks, encryption, rate limiting), and
+	•	any input validation, normalization, or schema enforcement performed.
+
+#### Diagram
+- Include a single, compact Mermaid diagram (`flowchart TD` or `flowchart LR`) showing primary components and trust boundaries (e.g., separate trust zones via subgraphs). Keep it compact, use only `-->`, avoid `title`/`style`, keep node labels short (no paths/URLs), and keep edge labels to plain words only (avoid `{}`, `[]`, `()`, or quotes).
+
+
+## Assets and security objectives
+- A table: Asset | Why it matters | Security objective (C/I/A)
+
+## Attacker model
+### Capabilities
+### Non-capabilities
+
+## Entry points and attack surfaces
+- A table: Surface | How reached | Trust boundary | Notes | Evidence (repo path / symbol)
+
+## Top abuse paths
+- 5 to 10 short abuse paths, each as a numbered sequence of steps (attacker goal -> steps -> impact).
+
+## Threat model table
+- A Markdown table with columns:
+  Threat ID | Threat source | Prerequisites | Threat action | Impact | Impacted assets | Existing controls (evidence) | Gaps | Recommended mitigations | Detection ideas | Likelihood | Impact severity | Priority
+
+Rules:
+- Threat IDs must be stable and formatted: TM-001, TM-002, ...
+- Priority must be one of: critical, high, medium, low.
+- Keep prerequisites to 1 to 2 sentences. Keep recommended mitigations concrete.
+
+## Criticality calibration
+- Define what counts as critical/high/medium/low for THIS repo and context.
+- Include 2 to 3 examples per level (tailored to the repo's assets and exposure).
+
+## Focus paths for security review
+- A table: Path | Why it matters | Related Threat IDs
+
+## Notes on use
+
+- Fill in known context, but allow the model to infer and mark assumptions.
+- Include 1–2 repo-path anchors per major claim; do not dump every match.

package/skills/security-threat-model/references/security-controls-and-assets.md

@@ -0,0 +1,32 @@
+# Security Controls and Asset Categories
+
+Use this as a lightweight checklist to keep outputs consistent across teams. Prefer concrete, system-specific items over generic text.
+
+## Asset categories (pick only what applies)
+- User data (PII, content, uploads)
+- Authentication artifacts (passwords, tokens, sessions, cookies)
+- Authorization state (roles, policies, ACLs)
+- Secrets and keys (API keys, signing keys, encryption keys)
+- Configuration and feature flags
+- Models and weights (if ML systems)
+- Source code and build artifacts
+- Audit logs and telemetry
+- Availability-critical resources (queues, caches, rate limits, compute budgets)
+- Tenant isolation boundaries and metadata
+
+## Security control categories
+- Identity and access: authN, authZ, session handling, mTLS, key rotation
+- Input protection: schema validation, parsing hardening, upload scanning, sandboxing
+- Network safeguards: TLS, network policies, WAF, rate limiting, DoS controls
+- Data protection: encryption at rest/in transit, tokenization, redaction
+- Isolation: process sandboxing, container boundaries, tenant isolation, seccomp
+- Observability: audit logs, alerting, anomaly detection, tamper resistance
+- Supply chain: dependency pinning, SBOMs, provenance, signing
+- Change control: CI checks, deployment approvals, config guardrails
+
+## Mitigation phrasing patterns
+- "Enforce schema at <boundary> for <payload> before <component>."
+- "Require authZ check for <action> on <resource> in <service>."
+- "Isolate <parser/component> in a sandbox with <resource limits>."
+- "Rate limit <endpoint> by <key> and apply burst caps."
+- "Encrypt <data> at rest using <key management> and rotate <keys>."

package/skills/semgrep/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: semgrep
+description: >-
+  Run Semgrep static analysis scan on a codebase using parallel subagents.
+  Supports two scan modes — "run all" (full ruleset coverage) and "important
+  only" (high-confidence security vulnerabilities). Automatically detects and
+  uses Semgrep Pro for cross-file taint analysis when available. Use when asked
+  to scan code for vulnerabilities, run a security audit with Semgrep, find
+  bugs, or perform static analysis. Spawns parallel workers for multi-language
+  codebases.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Task
+  - AskUserQuestion
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+---
+
+# Semgrep Security Scan
+
+Run a Semgrep scan with automatic language detection, parallel execution via Task subagents, and merged SARIF output.
+
+## Essential Principles
+
+1. **Always use `--metrics=off`** — Semgrep sends telemetry by default; `--config auto` also phones home. Every `semgrep` command must include `--metrics=off` to prevent data leakage during security audits.
+2. **User must approve the scan plan (Step 3 is a hard gate)** — The original "scan this codebase" request is NOT approval. Present exact rulesets, target, engine, and mode; wait for explicit "yes"/"proceed" before spawning scanners.
+3. **Third-party rulesets are required, not optional** — Trail of Bits, 0xdea, and Decurity rules catch vulnerabilities absent from the official registry. Include them whenever the detected language matches.
+4. **Spawn all scan Tasks in a single message** — Parallel execution is the core performance advantage. Never spawn Tasks sequentially; always emit all Task tool calls in one response.
+5. **Always check for Semgrep Pro before scanning** — Pro enables cross-file taint tracking and catches ~250% more true positives. Skipping the check means silently missing critical inter-file vulnerabilities.
+
+## When to Use
+
+- Security audit of a codebase
+- Finding vulnerabilities before code review
+- Scanning for known bug patterns
+- First-pass static analysis
+
+## When NOT to Use
+
+- Binary analysis → Use binary analysis tools
+- Already have Semgrep CI configured → Use existing pipeline
+- Need cross-file analysis but no Pro license → Consider CodeQL as alternative
+- Creating custom Semgrep rules → Use `semgrep-rule-creator` skill
+- Porting existing rules to other languages → Use `semgrep-rule-variant-creator` skill
+
+## Output Directory
+
+All scan results, SARIF files, and temporary data are stored in a single output directory.
+
+- **If the user specifies an output directory** in their prompt, use it as `OUTPUT_DIR`.
+- **If not specified**, default to `./static_analysis_semgrep_1`. If that already exists, increment to `_2`, `_3`, etc.
+
+In both cases, **always create the directory** with `mkdir -p` before writing any files.
+
+```bash
+# Resolve output directory
+if [ -n "$USER_SPECIFIED_DIR" ]; then
+  OUTPUT_DIR="$USER_SPECIFIED_DIR"
+else
+  BASE="static_analysis_semgrep"
+  N=1
+  while [ -e "${BASE}_${N}" ]; do
+    N=$((N + 1))
+  done
+  OUTPUT_DIR="${BASE}_${N}"
+fi
+mkdir -p "$OUTPUT_DIR/raw" "$OUTPUT_DIR/results"
+```
+
+The output directory is resolved **once** at the start of Step 1 and used throughout all subsequent steps.
+
+```
+$OUTPUT_DIR/
+├── rulesets.txt                 # Approved rulesets (logged after Step 3)
+├── raw/                         # Per-scan raw output (unfiltered)
+│   ├── python-python.json
+│   ├── python-python.sarif
+│   ├── python-django.json
+│   ├── python-django.sarif
+│   └── ...
+└── results/                     # Final merged output
+    └── results.sarif
+```
+
+## Prerequisites
+
+**Required:** Semgrep CLI (`semgrep --version`). If not installed, see [Semgrep installation docs](https://semgrep.dev/docs/getting-started/).
+
+**Optional:** Semgrep Pro — enables cross-file taint tracking, inter-procedural analysis, and additional languages (Apex, C#, Elixir). Check with:
+
+```bash
+semgrep --pro --validate --config p/default 2>/dev/null && echo "Pro available" || echo "OSS only"
+```
+
+**Limitations:** OSS mode cannot track data flow across files. Pro mode uses `-j 1` for cross-file analysis (slower per ruleset, but parallel rulesets compensate).
+
+## Scan Modes
+
+Select mode in Step 2 of the workflow. Mode affects both scanner flags and post-processing.
+
+| Mode | Coverage | Findings Reported |
+|------|----------|-------------------|
+| **Run all** | All rulesets, all severity levels | Everything |
+| **Important only** | All rulesets, pre- and post-filtered | Security vulns only, medium-high confidence/impact |
+
+**Important only** applies two filter layers:
+1. **Pre-filter**: `--severity MEDIUM --severity HIGH --severity CRITICAL` (CLI flag)
+2. **Post-filter**: JSON metadata — keeps only `category=security`, `confidence∈{MEDIUM,HIGH}`, `impact∈{MEDIUM,HIGH}`
+
+See [scan-modes.md](references/scan-modes.md) for metadata criteria and jq filter commands.
+
+## Orchestration Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ MAIN AGENT (this skill)                                          │
+│ Step 1: Detect languages + check Pro availability                │
+│ Step 2: Select scan mode + rulesets (ref: rulesets.md)           │
+│ Step 3: Present plan + rulesets, get approval [⛔ HARD GATE]     │
+│ Step 4: Spawn parallel scan Tasks (approved rulesets + mode)     │
+│ Step 5: Merge results and report                                 │
+└──────────────────────────────────────────────────────────────────┘
+         │ Step 4
+         ▼
+┌─────────────────┐
+│ Scan Tasks      │
+│ (parallel)      │
+├─────────────────┤
+│ Python scanner  │
+│ JS/TS scanner   │
+│ Go scanner      │
+│ Docker scanner  │
+└─────────────────┘
+```
+
+## Workflow
+
+**Follow the detailed workflow in [scan-workflow.md](workflows/scan-workflow.md).** Summary:
+
+| Step | Action | Gate | Key Reference |
+|------|--------|------|---------------|
+| 1 | Resolve output dir, detect languages + Pro availability | — | Use Glob, not Bash |
+| 2 | Select scan mode + rulesets | — | [rulesets.md](references/rulesets.md) |
+| 3 | Present plan, get explicit approval | ⛔ HARD | AskUserQuestion |
+| 4 | Spawn parallel scan Tasks | — | [scanner-task-prompt.md](references/scanner-task-prompt.md) |
+| 5 | Merge results and report | — | Merge script (below) |
+
+**Task enforcement:** On invocation, create 5 tasks with blockedBy dependencies (each step blocks the previous). Step 3 is a HARD GATE — mark complete ONLY after user explicitly approves.
+
+**Merge command (Step 5):**
+
+```bash
+uv run {baseDir}/scripts/merge_sarif.py $OUTPUT_DIR/raw $OUTPUT_DIR/results/results.sarif
+```
+
+## Agents
+
+| Agent | Tools | Purpose |
+|-------|-------|---------|
+| `static-analysis:semgrep-scanner` | Bash | Executes parallel semgrep scans for a language category |
+
+Use `subagent_type: static-analysis:semgrep-scanner` in Step 4 when spawning Task subagents.
+
+## Rationalizations to Reject
+
+| Shortcut | Why It's Wrong |
+|----------|----------------|
+| "User asked for scan, that's approval" | Original request ≠ plan approval. Present plan, use AskUserQuestion, await explicit "yes" |
+| "Step 3 task is blocking, just mark complete" | Lying about task status defeats enforcement. Only mark complete after real approval |
+| "I already know what they want" | Assumptions cause scanning wrong directories/rulesets. Present plan for verification |
+| "Just use default rulesets" | User must see and approve exact rulesets before scan |
+| "Add extra rulesets without asking" | Modifying approved list without consent breaks trust |
+| "Third-party rulesets are optional" | Trail of Bits, 0xdea, Decurity catch vulnerabilities not in official registry — REQUIRED |
+| "Use --config auto" | Sends metrics; less control over rulesets |
+| "One Task at a time" | Defeats parallelism; spawn all Tasks together |
+| "Pro is too slow, skip --pro" | Cross-file analysis catches 250% more true positives; worth the time |
+| "Semgrep handles GitHub URLs natively" | URL handling fails on repos with non-standard YAML; always clone first |
+| "Cleanup is optional" | Cloned repos pollute the user's workspace and accumulate across runs |
+| "Use `.` or relative path as target" | Subagents need absolute paths to avoid ambiguity |
+| "Let the user pick an output dir later" | Output directory must be resolved at Step 1, before any files are created |
+
+## Reference Index
+
+| File | Content |
+|------|---------|
+| [rulesets.md](references/rulesets.md) | Complete ruleset catalog and selection algorithm |
+| [scan-modes.md](references/scan-modes.md) | Pre/post-filter criteria and jq commands |
+| [scanner-task-prompt.md](references/scanner-task-prompt.md) | Template for spawning scanner subagents |
+
+| Workflow | Purpose |
+|----------|---------|
+| [scan-workflow.md](workflows/scan-workflow.md) | Complete 5-step scan execution process |
+
+## Success Criteria
+
+- [ ] Output directory resolved (user-specified or auto-incremented default)
+- [ ] All generated files stored inside `$OUTPUT_DIR`
+- [ ] Languages detected with file counts; Pro status checked
+- [ ] Scan mode selected by user (run all / important only)
+- [ ] Rulesets include third-party rules for all detected languages
+- [ ] User explicitly approved the scan plan (Step 3 gate passed)
+- [ ] All scan Tasks spawned in a single message and completed
+- [ ] Every `semgrep` command used `--metrics=off`
+- [ ] Approved rulesets logged to `$OUTPUT_DIR/rulesets.txt`
+- [ ] Raw per-scan outputs stored in `$OUTPUT_DIR/raw/`
+- [ ] `results.sarif` exists in `$OUTPUT_DIR/results/` and is valid JSON
+- [ ] Important-only mode: post-filter applied before merge; unfiltered results preserved in `raw/`
+- [ ] Results summary reported with severity and category breakdown
+- [ ] Cloned repos (if any) cleaned up from `$OUTPUT_DIR/repos/`

package/skills/semgrep/references/rulesets.md

@@ -0,0 +1,162 @@
+# Semgrep Rulesets Reference
+
+## Complete Ruleset Catalog
+
+### Security-Focused Rulesets
+
+| Ruleset | Description | Use Case |
+|---------|-------------|----------|
+| `p/security-audit` | Comprehensive vulnerability detection, higher false positives | Manual audits, security reviews |
+| `p/secrets` | Hardcoded credentials, API keys, tokens | Always include |
+| `p/owasp-top-ten` | OWASP Top 10 web application vulnerabilities | Web app security |
+| `p/cwe-top-25` | CWE Top 25 most dangerous software weaknesses | General security |
+| `p/sql-injection` | SQL injection patterns and tainted data flows | Database security |
+| `p/insecure-transport` | Ensures code uses encrypted channels | Network security |
+| `p/gitleaks` | Hard-coded credentials detection (gitleaks port) | Secrets scanning |
+| `p/findsecbugs` | FindSecBugs rule pack for Java | Java security |
+| `p/phpcs-security-audit` | PHP security audit rules | PHP security |
+
+### CI/CD Rulesets
+
+| Ruleset | Description | Use Case |
+|---------|-------------|----------|
+| `p/default` | Default ruleset, balanced coverage | First-time users |
+| `p/ci` | High-confidence security + logic bugs, low FP | CI pipelines |
+| `p/r2c-ci` | Low false positives, CI-safe | CI/CD blocking |
+| `p/r2c` | Community favorite, curated by Semgrep (618k+ downloads) | General scanning |
+| `p/auto` | Auto-selects rules based on detected languages/frameworks | Quick scans |
+| `p/comment` | Comment-related rules | Code review |
+
+### Third-Party Rulesets
+
+| Ruleset | Description | Maintainer |
+|---------|-------------|------------|
+| `p/gitlab` | GitLab-maintained security rules | GitLab |
+
+---
+
+## Ruleset Selection Algorithm
+
+Follow this algorithm to select rulesets based on detected languages and frameworks.
+
+### Step 1: Always Include Security Baseline
+
+```json
+{
+  "baseline": ["p/security-audit", "p/secrets"]
+}
+```
+
+- `p/security-audit` - Comprehensive vulnerability detection (always include)
+- `p/secrets` - Hardcoded credentials, API keys, tokens (always include)
+
+### Step 2: Add Language-Specific Rulesets
+
+For each detected language, add the primary ruleset. If a framework is detected, add its ruleset too.
+
+**GA Languages (production-ready):**
+
+| Detection | Primary Ruleset | Framework Rulesets | Pro Rule Count |
+|-----------|-----------------|-------------------|----------------|
+| `.py` | `p/python` | `p/django`, `p/flask`, `p/fastapi` | 710+ |
+| `.js`, `.jsx` | `p/javascript` | `p/react`, `p/nodejs`, `p/express`, `p/nextjs`, `p/angular` | 250+ (JS), 70+ (JSX) |
+| `.ts`, `.tsx` | `p/typescript` | `p/react`, `p/nodejs`, `p/express`, `p/nextjs`, `p/angular` | 230+ |
+| `.go` | `p/golang` | `p/go` (alias) | 80+ |
+| `.java` | `p/java` | `p/spring`, `p/findsecbugs` | 190+ |
+| `.kt` | `p/kotlin` | `p/spring` | 60+ |
+| `.rb` | `p/ruby` | `p/rails` | 40+ |
+| `.php` | `p/php` | `p/symfony`, `p/laravel`, `p/phpcs-security-audit` | 50+ |
+| `.c`, `.cpp`, `.h` | `p/c` | - | 150+ |
+| `.rs` | `p/rust` | - | 40+ |
+| `.cs` | `p/csharp` | - | 170+ |
+| `.scala` | `p/scala` | - | Community |
+| `.swift` | `p/swift` | - | 60+ |
+
+**Beta Languages (Pro recommended):**
+
+| Detection | Primary Ruleset | Notes |
+|-----------|-----------------|-------|
+| `.ex`, `.exs` | `p/elixir` | Requires Pro for best coverage |
+| `.cls`, `.trigger` | `p/apex` | Salesforce; requires Pro |
+
+**Experimental Languages:**
+
+| Detection | Primary Ruleset | Notes |
+|-----------|-----------------|-------|
+| `.sol` | No official ruleset | Use Decurity third-party rules |
+| `Dockerfile` | `p/dockerfile` | Limited rules |
+| `.yaml`, `.yml` | `p/yaml` | K8s, GitHub Actions, docker-compose patterns |
+| `.json` | `r/json.aws` | AWS IAM policies; use `r/json.*` for specific rules |
+| Bash scripts | - | Community support |
+| Cairo, Circom | - | Experimental, smart contracts |
+
+**Framework detection hints:**
+
+| Framework | Detection Signals | Ruleset |
+|-----------|------------------|---------|
+| Django | `settings.py`, `urls.py`, `django` in requirements | `p/django` |
+| Flask | `flask` in requirements, `@app.route` | `p/flask` |
+| FastAPI | `fastapi` in requirements, `@app.get/post` | `p/fastapi` |
+| React | `package.json` with react dependency, `.jsx`/`.tsx` files | `p/react` |
+| Next.js | `next.config.js`, `pages/` or `app/` directory | `p/nextjs` |
+| Angular | `angular.json`, `@angular/` dependencies | `p/angular` |
+| Express | `express` in package.json, `app.use()` patterns | `p/express` |
+| NestJS | `@nestjs/` dependencies, `@Controller` decorators | `p/nodejs` |
+| Spring | `pom.xml` with spring, `@SpringBootApplication` | `p/spring` |
+| Rails | `Gemfile` with rails, `config/routes.rb` | `p/rails` |
+| Laravel | `composer.json` with laravel, `artisan` | `p/laravel` |
+| Symfony | `composer.json` with symfony, `config/packages/` | `p/symfony` |
+
+### Step 3: Add Infrastructure Rulesets
+
+| Detection | Ruleset | Description |
+|-----------|---------|-------------|
+| `Dockerfile` | `p/dockerfile` | Container security, best practices |
+| `.tf`, `.hcl` | `p/terraform` | IaC misconfigurations, CIS benchmarks, AWS/Azure/GCP |
+| k8s manifests | `p/kubernetes` | K8s security, RBAC issues |
+| CloudFormation | `p/cloudformation` | AWS infrastructure security |
+| GitHub Actions | `p/github-actions` | CI/CD security, secrets exposure |
+| `.yaml`, `.yml` | `p/yaml` | Generic YAML patterns (K8s, docker-compose) |
+| AWS IAM JSON | `r/json.aws` | IAM policy misconfigurations (use `--config r/json.aws`) |
+
+### Step 4: Add Third-Party Rulesets
+
+These are **NOT optional**. Include automatically when language matches:
+
+| Languages | Source | Why Required |
+|-----------|--------|--------------|
+| Python, Go, Ruby, JS/TS, Terraform, HCL | [Trail of Bits](https://github.com/trailofbits/semgrep-rules) | Security audit patterns from real engagements (AGPLv3) |
+| C, C++ | [0xdea](https://github.com/0xdea/semgrep-rules) | Memory safety, low-level vulnerabilities |
+| Solidity, Cairo, Rust | [Decurity](https://github.com/Decurity/semgrep-smart-contracts) | Smart contract vulnerabilities, DeFi exploits |
+| Go | [dgryski](https://github.com/dgryski/semgrep-go) | Additional Go-specific patterns |
+| Android (Java/Kotlin) | [MindedSecurity](https://github.com/mindedsecurity/semgrep-rules-android-security) | OWASP MASTG-derived mobile security rules |
+| Java, Go, JS/TS, C#, Python, PHP | [elttam](https://github.com/elttam/semgrep-rules) | Security consulting patterns |
+| Dockerfile, PHP, Go, Java | [kondukto](https://github.com/kondukto-io/semgrep-rules) | Container and web app security |
+| PHP, Kotlin, Java | [dotta](https://github.com/federicodotta/semgrep-rules) | Pentest-derived web/mobile app rules |
+| Terraform, HCL | [HashiCorp](https://github.com/hashicorp-forge/semgrep-rules) | HashiCorp infrastructure patterns |
+| Swift, Java, Cobol | [akabe1](https://github.com/akabe1/akabe1-semgrep-rules) | iOS and legacy system patterns |
+| Java | [Atlassian Labs](https://github.com/atlassian-labs/atlassian-sast-ruleset) | Atlassian-maintained Java rules |
+| Python, JS/TS, Java, Ruby, Go, PHP | [Apiiro](https://github.com/apiiro/malicious-code-ruleset) | Malicious code detection, supply chain |
+
+### Step 5: Verify Rulesets
+
+Before finalizing, verify official rulesets load:
+
+```bash
+# Quick validation (exits 0 if valid)
+semgrep --config p/python --validate --metrics=off 2>&1 | head -3
+```
+
+Or browse the [Semgrep Registry](https://semgrep.dev/explore).
+
+### Output Format
+
+```json
+{
+  "baseline": ["p/security-audit", "p/secrets"],
+  "python": ["p/python", "p/django"],
+  "javascript": ["p/javascript", "p/react", "p/nodejs"],
+  "docker": ["p/dockerfile"],
+  "third_party": ["https://github.com/trailofbits/semgrep-rules"]
+}
+```