@vigolium/piolium 0.0.1

package/skills/codeql/workflows/create-data-extensions.md

@@ -0,0 +1,261 @@
+# Create Data Extensions Workflow
+
+Generate data extension YAML files to improve CodeQL's data flow coverage for project-specific APIs. Runs after database build and before analysis.
+
+## Task System
+
+Create these tasks on workflow start:
+
+```
+TaskCreate: "Check for existing data extensions" (Step 1)
+TaskCreate: "Query known sources and sinks" (Step 2) - blockedBy: Step 1
+TaskCreate: "Identify missing sources and sinks" (Step 3) - blockedBy: Step 2
+TaskCreate: "Create data extension files" (Step 4) - blockedBy: Step 3
+TaskCreate: "Validate with re-analysis" (Step 5) - blockedBy: Step 4
+```
+
+### Early Exit Points
+
+| After Step | Condition | Action |
+|------------|-----------|--------|
+| Step 1 | Extensions already exist | Return found packs/files to run-analysis workflow, finish |
+| Step 3 | No missing models identified | Report coverage is adequate, finish |
+
+---
+
+## Steps
+
+### Step 1: Check for Existing Data Extensions
+
+**Entry:** CodeQL database exists (`codeql resolve database` succeeds)
+**Exit:** Either existing extensions found (report and finish) OR no extensions found (proceed to Step 2)
+
+Search the project for existing data extensions and model packs.
+
+```bash
+# 1. In-repo model packs (exclude output dirs and legacy database dirs)
+fd '(qlpack|codeql-pack)\.yml$' . --exclude 'static_analysis_codeql_*' --exclude 'codeql_*.db' | while read -r f; do
+  if grep -q 'dataExtensions' "$f"; then
+    echo "MODEL PACK: $(dirname "$f") - $(grep '^name:' "$f")"
+  fi
+done
+
+# 2. Standalone data extension files
+rg -l '^extensions:' --glob '*.yml' --glob '!static_analysis_codeql_*/**' --glob '!codeql_*.db/**' | head -20
+
+# 3. Installed model packs
+codeql resolve qlpacks 2>/dev/null | grep -iE 'model|extension'
+```
+
+**If any found:** Report to user and finish. These will be picked up by the run-analysis workflow.
+
+**If none found:** Proceed to Step 2.
+
+---
+
+### Step 2: Query Known Sources and Sinks
+
+**Entry:** Step 1 found no existing extensions; database and language identified
+**Exit:** `sources.csv` and `sinks.csv` exist in `$DIAG_DIR` with enumerated source/sink locations
+
+Run custom QL queries against the database to enumerate all sources and sinks CodeQL currently recognizes.
+
+#### 2a: Select Database and Language
+
+A CodeQL database is a directory containing a `codeql-database.yml` marker file. `$DB_NAME` may already be set by the parent skill. If not, discover inside `$OUTPUT_DIR`.
+
+```bash
+if [ -z "$DB_NAME" ]; then
+  FOUND_DBS=()
+  while IFS= read -r yml; do
+    FOUND_DBS+=("$(dirname "$yml")")
+  done < <(find "$OUTPUT_DIR" -maxdepth 2 -name "codeql-database.yml" 2>/dev/null)
+
+  if [ ${#FOUND_DBS[@]} -eq 0 ]; then
+    echo "ERROR: No CodeQL database found in $OUTPUT_DIR"; exit 1
+  elif [ ${#FOUND_DBS[@]} -eq 1 ]; then
+    DB_NAME="${FOUND_DBS[0]}"
+  else
+    # Multiple databases — use AskUserQuestion to select
+    # SKIP if user already specified which database in their prompt
+  fi
+fi
+
+CODEQL_LANG=$(codeql resolve database --format=json -- "$DB_NAME" | jq -r '.languages[0]')
+DIAG_DIR="$OUTPUT_DIR/diagnostics"
+mkdir -p "$DIAG_DIR"
+```
+
+#### 2b: Write Source Enumeration Query
+
+Use the `Write` tool to create `$DIAG_DIR/list-sources.ql` using the source template from [diagnostic-query-templates.md](../references/diagnostic-query-templates.md#source-enumeration-query). Pick the correct import block for `$CODEQL_LANG`.
+
+#### 2c: Write Sink Enumeration Query
+
+Use the `Write` tool to create `$DIAG_DIR/list-sinks.ql` using the language-specific sink template from [diagnostic-query-templates.md](../references/diagnostic-query-templates.md#sink-enumeration-queries).
+
+**For Java:** Also create `$DIAG_DIR/qlpack.yml` with a `codeql/java-all` dependency and run `codeql pack install` before executing queries.
+
+#### 2d: Run Queries
+
+```bash
+codeql query run --database="$DB_NAME" --output="$DIAG_DIR/sources.bqrs" -- "$DIAG_DIR/list-sources.ql"
+codeql bqrs decode --format=csv --output="$DIAG_DIR/sources.csv" -- "$DIAG_DIR/sources.bqrs"
+
+codeql query run --database="$DB_NAME" --output="$DIAG_DIR/sinks.bqrs" -- "$DIAG_DIR/list-sinks.ql"
+codeql bqrs decode --format=csv --output="$DIAG_DIR/sinks.csv" -- "$DIAG_DIR/sinks.bqrs"
+```
+
+#### 2e: Summarize Results
+
+Read both CSV files and present a summary showing source types and sink kinds with counts.
+
+---
+
+### Step 3: Identify Missing Sources and Sinks
+
+**Entry:** Step 2 complete (`sources.csv` and `sinks.csv` available)
+**Exit:** Either no gaps found (report adequate coverage and finish) OR user confirms which gaps to model (proceed to Step 4)
+
+Cross-reference the project's API surface against CodeQL's known models.
+
+#### 3a: Map the Project's API Surface
+
+Read source code to identify security-relevant patterns:
+
+| Pattern | What To Find | Likely Model Type |
+|---------|-------------|-------------------|
+| HTTP/request handlers | Custom request parsing | `sourceModel` (kind: `remote`) |
+| Database layers | Custom ORM, raw query wrappers | `sinkModel` (kind: `sql-injection`) |
+| Command execution | Shell wrappers, process spawners | `sinkModel` (kind: `command-injection`) |
+| File operations | Custom file read/write | `sinkModel` (kind: `path-injection`) |
+| Template rendering | HTML output, response builders | `sinkModel` (kind: `xss`) |
+| Deserialization | Custom deserializers | `sinkModel` (kind: `unsafe-deserialization`) |
+| HTTP clients | URL construction | `sinkModel` (kind: `ssrf`) |
+| Sanitizers | Input validation, escaping | `neutralModel` |
+| Pass-through wrappers | Logging, caching, encoding | `summaryModel` (kind: `taint`) |
+
+Use `Grep` to search for these patterns in source code (adapt per language).
+
+#### 3b: Cross-Reference Against Known Sources and Sinks
+
+For each API pattern found, check if it appears in `sources.csv` or `sinks.csv` from Step 2.
+
+**An API is "missing" if:**
+- It handles user input but does not appear in `sources.csv`
+- It performs a dangerous operation but does not appear in `sinks.csv`
+- It wraps tainted data but has no summary model
+
+#### 3c: Report Gaps
+
+Present findings and use `AskUserQuestion`:
+
+```
+header: "Extensions"
+question: "Create data extension files for the identified gaps?"
+options:
+  - label: "Create all (Recommended)"
+    description: "Generate extensions for all identified gaps"
+  - label: "Select individually"
+    description: "Choose which gaps to model"
+  - label: "Skip"
+    description: "No extensions needed, proceed to analysis"
+```
+
+---
+
+### Step 4: Create Data Extension Files
+
+**Entry:** Step 3 identified gaps and user confirmed which to model
+**Exit:** YAML extension files created in `$OUTPUT_DIR/extensions/` and deployed to `<lang>-all` ext/ directory
+
+Generate YAML data extension files for the gaps confirmed by the user.
+
+#### File Structure
+
+Create files in `$OUTPUT_DIR/extensions/`:
+
+```
+$OUTPUT_DIR/extensions/
+  sources.yml       # sourceModel entries
+  sinks.yml         # sinkModel entries
+  summaries.yml     # summaryModel and neutralModel entries
+```
+
+#### YAML Format and Deployment
+
+See [extension-yaml-format.md](../references/extension-yaml-format.md) for column definitions, per-language examples (Python, Java, JS, Go, C/C++), and the deployment workaround for pre-compiled query packs.
+
+Use the `Write` tool to create each file. Only create files that have entries — skip empty categories.
+
+---
+
+### Step 5: Validate with Re-Analysis
+
+**Entry:** Step 4 complete (extension files deployed)
+**Exit:** Finding delta measured (with-extensions count >= baseline count); extensions validated as loading correctly
+
+Run a full security analysis with and without extensions to measure the finding delta.
+
+#### 5a: Run Baseline Analysis (without extensions)
+
+Validation artifacts go in `$DIAG_DIR` (not `results/`) since these are intermediate comparisons, not the final analysis output.
+
+```bash
+codeql database analyze "$DB_NAME" \
+  --format=sarif-latest --output="$DIAG_DIR/baseline.sarif" --threads=0 \
+  -- codeql/<lang>-queries:codeql-suites/<lang>-security-extended.qls
+```
+
+#### 5b: Run Analysis with Extensions
+
+```bash
+codeql database cleanup "$DB_NAME"
+codeql database analyze "$DB_NAME" \
+  --format=sarif-latest --output="$DIAG_DIR/with-extensions.sarif" --threads=0 --rerun \
+  -- codeql/<lang>-queries:codeql-suites/<lang>-security-extended.qls
+```
+
+Use `-vvv` flag to verify extensions are being loaded.
+
+#### 5c: Compare Findings
+
+```bash
+BASELINE=$(python3 -c "import json; print(sum(len(r.get('results',[])) for r in json.load(open('$DIAG_DIR/baseline.sarif')).get('runs',[])))")
+WITH_EXT=$(python3 -c "import json; print(sum(len(r.get('results',[])) for r in json.load(open('$DIAG_DIR/with-extensions.sarif')).get('runs',[])))")
+echo "Findings: $BASELINE → $WITH_EXT (+$((WITH_EXT - BASELINE)))"
+```
+
+**If counts did not increase:** Check extension loading (`-vvv`), pre-compiled pack workaround, Java `True`/`False` capitalization, column value accuracy.
+
+---
+
+## Final Output
+
+```
+## Data Extensions Created
+
+**Output directory:** $OUTPUT_DIR
+**Database:** $DB_NAME
+**Language:** <LANG>
+
+### Files Created:
+- $OUTPUT_DIR/extensions/sources.yml — <N> source models
+- $OUTPUT_DIR/extensions/sinks.yml — <N> sink models
+- $OUTPUT_DIR/extensions/summaries.yml — <N> summary/neutral models
+
+### Model Coverage:
+- Sources: <BEFORE> → <AFTER> (+<DELTA>)
+- Sinks: <BEFORE> → <AFTER> (+<DELTA>)
+
+### Usage:
+Extensions deployed to `<lang>-all` ext/ directory (auto-loaded).
+Source files in `$OUTPUT_DIR/extensions/` for version control.
+Run the run-analysis workflow to use them.
+```
+
+## References
+
+- [Threat models reference](../references/threat-models.md) — control which source categories are active during analysis
+- [CodeQL data extensions](https://codeql.github.com/docs/codeql-cli/using-custom-queries-with-the-codeql-cli/#using-extension-packs)
+- [Customizing library models](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-python/)

package/skills/codeql/workflows/run-analysis.md

@@ -0,0 +1,301 @@
+# Run Analysis Workflow
+
+Execute CodeQL security queries on an existing database with ruleset selection and result formatting.
+
+## Scan Modes
+
+Two modes control analysis scope. Both use all installed packs — the difference is filtering.
+
+| Mode | Description | Suite Reference |
+|------|-------------|-----------------|
+| **Run all** | All queries from all installed packs via `security-and-quality` suite | [run-all-suite.md](../references/run-all-suite.md) |
+| **Important only** | Security queries filtered by precision and security-severity threshold | [important-only-suite.md](../references/important-only-suite.md) |
+
+> **WARNING:** Do NOT pass pack names directly to `codeql database analyze` (e.g., `-- codeql/cpp-queries`). Each pack's `defaultSuiteFile` silently applies strict filters and can produce zero results. Always use an explicit suite reference.
+
+---
+
+## Task System
+
+Create these tasks on workflow start:
+
+```
+TaskCreate: "Select database and detect language" (Step 1)
+TaskCreate: "Select scan mode, check additional packs" (Step 2) - blockedBy: Step 1
+TaskCreate: "Select query packs, model packs, and threat models" (Step 3) - blockedBy: Step 2
+TaskCreate: "Execute analysis" (Step 4) - blockedBy: Step 3
+TaskCreate: "Process and report results" (Step 5) - blockedBy: Step 4
+```
+
+### Gates
+
+| Task | Gate Type | Cannot Proceed Until |
+|------|-----------|---------------------|
+| Step 2 | **SOFT GATE** | User selects mode; confirms installed/ignored for each missing pack |
+| Step 3 | **SOFT GATE** | User approves query packs, model packs, and threat model selection |
+
+**Auto-skip rule:** If the user already specified a choice in the invocation, skip the corresponding `AskUserQuestion` and use the provided value directly.
+
+---
+
+## Steps
+
+### Step 1: Select Database and Detect Language
+
+**Entry:** `$OUTPUT_DIR` is set (from parent skill). `$DB_NAME` may already be set if the parent skill resolved database selection.
+**Exit:** `DB_NAME` and `CODEQL_LANG` variables set; database resolves successfully.
+
+**If `$DB_NAME` is already set** (parent skill handled database selection): validate it and proceed.
+
+**If `$DB_NAME` is not set:** discover databases by looking for `codeql-database.yml` marker files. Search inside `$OUTPUT_DIR` first, then fall back to the project root (top-level and one subdirectory deep).
+
+```bash
+# Skip discovery if DB_NAME was already resolved by parent skill
+if [ -z "$DB_NAME" ]; then
+  # Discover databases inside OUTPUT_DIR
+  FOUND_DBS=()
+  while IFS= read -r yml; do
+    FOUND_DBS+=("$(dirname "$yml")")
+  done < <(find "$OUTPUT_DIR" -maxdepth 2 -name "codeql-database.yml" 2>/dev/null)
+
+  # Fallback: search project root (top-level and one subdir deep)
+  if [ ${#FOUND_DBS[@]} -eq 0 ]; then
+    while IFS= read -r yml; do
+      FOUND_DBS+=("$(dirname "$yml")")
+    done < <(find . -maxdepth 3 -name "codeql-database.yml" -not -path "*/\.*" 2>/dev/null)
+  fi
+
+  if [ ${#FOUND_DBS[@]} -eq 0 ]; then
+    echo "ERROR: No CodeQL database found in $OUTPUT_DIR or project root"
+    exit 1
+  elif [ ${#FOUND_DBS[@]} -eq 1 ]; then
+    DB_NAME="${FOUND_DBS[0]}"
+  else
+    # Multiple databases found — present to user
+    # Use AskUserQuestion with each DB's path and language
+    # SKIP if user already specified which database in their prompt
+  fi
+fi
+
+CODEQL_LANG=$(codeql resolve database --format=json -- "$DB_NAME" | jq -r '.languages[0]')
+echo "Using: $DB_NAME (language: $CODEQL_LANG)"
+```
+
+**When multiple databases are found**, use `AskUserQuestion` to let user select — list each database with its path and language. **Skip `AskUserQuestion` if the user already specified which database to use in their prompt.**
+
+If multi-language database, ask which language to analyze.
+
+---
+
+### Step 2: Select Scan Mode, Check Additional Packs
+
+**Entry:** Step 1 complete (`DB_NAME` and `CODEQL_LANG` set)
+**Exit:** Scan mode selected; all available packs (official, ToB, community) checked for installation status; model packs detected
+
+#### 2a: Select Scan Mode
+
+**Skip if user already specified.** Otherwise use `AskUserQuestion`:
+
+```
+header: "Scan Mode"
+question: "Which scan mode should be used?"
+options:
+  - label: "Run all (Recommended)"
+    description: "Maximum coverage — all queries from all installed packs"
+  - label: "Important only"
+    description: "Security vulnerabilities only — medium-high precision, security-severity threshold"
+```
+
+#### 2b: Query Packs
+
+For each pack available for the detected language (see [ruleset-catalog.md](../references/ruleset-catalog.md)):
+
+| Language | Trail of Bits | Community Pack |
+|----------|---------------|----------------|
+| C/C++ | `trailofbits/cpp-queries` | `GitHubSecurityLab/CodeQL-Community-Packs-CPP` |
+| Go | `trailofbits/go-queries` | `GitHubSecurityLab/CodeQL-Community-Packs-Go` |
+| Java | `trailofbits/java-queries` | `GitHubSecurityLab/CodeQL-Community-Packs-Java` |
+| JavaScript | — | `GitHubSecurityLab/CodeQL-Community-Packs-JavaScript` |
+| Python | — | `GitHubSecurityLab/CodeQL-Community-Packs-Python` |
+| C# | — | `GitHubSecurityLab/CodeQL-Community-Packs-CSharp` |
+| Ruby | — | `GitHubSecurityLab/CodeQL-Community-Packs-Ruby` |
+
+Check if installed (`codeql resolve qlpacks | grep -i "<PACK_NAME>"`). If not, ask user to install or ignore.
+
+#### 2c: Detect Model Packs
+
+Search three locations for data extension model packs:
+1. **In-repo model packs** — `qlpack.yml`/`codeql-pack.yml` with `dataExtensions`
+2. **In-repo standalone data extensions** — `.yml` files with `extensions:` key
+3. **Installed model packs** — resolved by CodeQL
+
+Record all detected packs for Step 3.
+
+---
+
+### Step 3: Select Query Packs and Model Packs
+
+**Entry:** Step 2 complete (scan mode, pack availability, and model packs all determined)
+**Exit:** User confirmed query packs, model packs, and threat model selection; all flags built (`THREAT_MODEL_FLAG`, `MODEL_PACK_FLAGS`, `ADDITIONAL_PACK_FLAGS`)
+
+> **CHECKPOINT** — Present available packs to user for confirmation.
+> **Skip if user already specified pack preferences.**
+
+#### 3a: Confirm Query Packs
+
+**Important-only mode:** Inform user all installed packs included with filtering. Proceed to 3b.
+
+**Run-all mode:** Use `AskUserQuestion` to confirm "Use all" or "Select individually".
+
+#### 3b: Select Model Packs (if any detected)
+
+**Skip if no model packs detected in Step 2c.**
+
+Use `AskUserQuestion`: "Use all (Recommended)" / "Select individually" / "Skip".
+
+**Notes:**
+- In-repo standalone extensions (`.yml`) are auto-discovered — pass source directory via `--additional-packs`
+- In-repo model packs (with `qlpack.yml`) need parent directory via `--additional-packs`
+- Installed model packs use `--model-packs`
+
+#### 3c: Select Threat Models
+
+Threat models control which input sources CodeQL treats as tainted. See [threat-models.md](../references/threat-models.md).
+
+Use `AskUserQuestion`:
+
+```
+header: "Threat Models"
+question: "Which input sources should CodeQL treat as tainted?"
+options:
+  - label: "Remote only (Recommended)"
+    description: "Default — HTTP requests, network input"
+  - label: "Remote + Local"
+    description: "Add CLI args, local files"
+  - label: "All sources"
+    description: "Remote, local, environment, database, file"
+  - label: "Custom"
+    description: "Select specific threat models individually"
+```
+
+Build the flag: `THREAT_MODEL_FLAG=""` (remote only needs no flag), `--threat-model local`, etc.
+
+---
+
+### Step 4: Execute Analysis
+
+**Entry:** Step 3 complete (all flags and pack selections finalized)
+**Exit:** `$RAW_DIR/results.sarif` exists and contains valid SARIF output
+
+#### Log selected query packs
+
+Write the selected query packs, model packs, and threat models to `$OUTPUT_DIR/rulesets.txt`:
+
+```bash
+cat > "$OUTPUT_DIR/rulesets.txt" << RULESETS
+# CodeQL Analysis — Selected Query Packs
+# Generated: $(date -Iseconds)
+# Scan mode: <run-all|important-only>
+# Database: $DB_NAME
+# Language: $CODEQL_LANG
+
+## Query packs:
+<one pack per line>
+
+## Model packs:
+<one pack per line, or "None">
+
+## Threat models:
+<threat model selection, or "default (remote)">
+RULESETS
+```
+
+#### Generate custom suite
+
+**Important-only mode:** Generate the custom `.qls` suite using the template and script in [important-only-suite.md](../references/important-only-suite.md).
+
+**Run-all mode:** Generate the custom `.qls` suite using the template in [run-all-suite.md](../references/run-all-suite.md).
+
+```bash
+RAW_DIR="$OUTPUT_DIR/raw"
+RESULTS_DIR="$OUTPUT_DIR/results"
+mkdir -p "$RAW_DIR" "$RESULTS_DIR"
+SUITE_FILE="$RAW_DIR/<mode>.qls"
+
+# Verify suite resolves correctly before running
+codeql resolve queries "$SUITE_FILE" | wc -l
+```
+
+#### Run analysis
+
+Output goes to `$RAW_DIR/results.sarif` (unfiltered). The final results are produced in Step 5.
+
+```bash
+codeql database analyze $DB_NAME \
+  --format=sarif-latest \
+  --output="$RAW_DIR/results.sarif" \
+  --threads=0 \
+  $THREAT_MODEL_FLAG \
+  $MODEL_PACK_FLAGS \
+  $ADDITIONAL_PACK_FLAGS \
+  -- "$SUITE_FILE"
+```
+
+**Flag reference for model packs:**
+
+| Source | Flag | Example |
+|--------|------|---------|
+| Installed model packs | `--model-packs` | `--model-packs=myorg/java-models` |
+| In-repo model packs | `--additional-packs` | `--additional-packs=./lib/codeql-models` |
+| In-repo standalone extensions | `--additional-packs` | `--additional-packs=.` |
+
+### Performance
+
+If codebase is large, read [performance-tuning.md](../references/performance-tuning.md) and apply relevant optimizations.
+
+---
+
+### Step 5: Process and Report Results
+
+**Entry:** Step 4 complete (`$RAW_DIR/results.sarif` exists)
+**Exit:** `$RESULTS_DIR/results.sarif` contains final results; findings summarized by severity, rule, and location; zero-finding results investigated; final report presented to user
+
+#### Produce final results
+
+- **Run-all mode:** Copy unfiltered results to the final location:
+  ```bash
+  cp "$RAW_DIR/results.sarif" "$RESULTS_DIR/results.sarif"
+  ```
+
+- **Important-only mode:** Apply the post-analysis filter from [sarif-processing.md](../references/sarif-processing.md#important-only-post-filter) to remove medium-precision results with `security-severity` < 6.0. The filter reads from `$RAW_DIR/results.sarif` and writes to `$RESULTS_DIR/results.sarif`, preserving the unfiltered original.
+
+Process the final SARIF output (`$RESULTS_DIR/results.sarif`) using the jq commands in [sarif-processing.md](../references/sarif-processing.md): count findings, summarize by level, summarize by security severity, summarize by rule.
+
+---
+
+## Final Output
+
+Report to user:
+
+```
+## CodeQL Analysis Complete
+
+**Output directory:** $OUTPUT_DIR
+**Database:** $DB_NAME
+**Language:** <LANG>
+**Scan mode:** Run all | Important only
+**Query packs:** <list of query packs used>
+**Model packs:** <list of model packs used, or "None">
+**Threat models:** <list of threat models, or "default (remote)">
+
+### Results Summary:
+- Total findings: <N>
+- Error: <N>
+- Warning: <N>
+- Note: <N>
+
+### Output Files:
+- SARIF (final): $OUTPUT_DIR/results/results.sarif
+- SARIF (unfiltered): $OUTPUT_DIR/raw/results.sarif
+- Rulesets: $OUTPUT_DIR/rulesets.txt
+```