@vigolium/piolium 0.0.1

package/skills/codeql/references/ruleset-catalog.md

@@ -0,0 +1,63 @@
+# Ruleset Catalog
+
+## Official CodeQL Suites
+
+| Suite | False Positives | Use Case |
+|-------|-----------------|----------|
+| `security-extended` | Low | **Default** - Security audits |
+| `security-and-quality` | Medium | Comprehensive review |
+| `security-experimental` | Higher | Research, vulnerability hunting |
+
+**Usage:** `codeql/<lang>-queries:codeql-suites/<lang>-security-extended.qls`
+
+**Languages:** `cpp`, `csharp`, `go`, `java`, `javascript`, `python`, `ruby`, `swift`
+
+---
+
+## Trail of Bits Packs
+
+| Pack | Language | Focus |
+|------|----------|-------|
+| `trailofbits/cpp-queries` | C/C++ | Memory safety, integer overflows |
+| `trailofbits/go-queries` | Go | Concurrency, error handling |
+| `trailofbits/java-queries` | Java | Security, code quality |
+
+**Install:**
+```bash
+codeql pack download trailofbits/cpp-queries
+codeql pack download trailofbits/go-queries
+codeql pack download trailofbits/java-queries
+```
+
+---
+
+## CodeQL Community Packs
+
+| Pack | Language |
+|------|----------|
+| `GitHubSecurityLab/CodeQL-Community-Packs-JavaScript` | JavaScript/TypeScript |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Python` | Python |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Go` | Go |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Java` | Java |
+| `GitHubSecurityLab/CodeQL-Community-Packs-CPP` | C/C++ |
+| `GitHubSecurityLab/CodeQL-Community-Packs-CSharp` | C# |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Ruby` | Ruby |
+
+**Install:**
+```bash
+codeql pack download GitHubSecurityLab/CodeQL-Community-Packs-<Lang>
+```
+
+**Source:** [github.com/GitHubSecurityLab/CodeQL-Community-Packs](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs)
+
+---
+
+## Verify Installation
+
+```bash
+# List all installed packs
+codeql resolve qlpacks
+
+# Check specific packs
+codeql resolve qlpacks | grep -E "(trailofbits|GitHubSecurityLab)"
+```

package/skills/codeql/references/run-all-suite.md

@@ -0,0 +1,92 @@
+# Run-All Query Suite
+
+In run-all mode, generate a custom `.qls` query suite file at runtime. This ensures all queries from all installed packs actually execute, avoiding the silent filtering caused by each pack's `defaultSuiteFile`.
+
+## Why a Custom Suite
+
+When you pass a pack name directly to `codeql database analyze` (e.g., `-- codeql/cpp-queries`), CodeQL uses the pack's `defaultSuiteFile` field from `qlpack.yml`. For official packs, this is typically `codeql-suites/<lang>-code-scanning.qls`, which applies strict precision and severity filters. This silently drops many queries and can produce zero results for small codebases.
+
+The run-all suite explicitly references the broadest built-in suite (`security-and-quality`) for official packs and loads third-party packs with minimal filtering.
+
+## Suite Template
+
+Generate this file as `run-all.qls` in the results directory before running analysis:
+
+```yaml
+- description: Run-all — all security and quality queries from all installed packs
+# Official queries: use security-and-quality suite (broadest built-in suite)
+- import: codeql-suites/<CODEQL_LANG>-security-and-quality.qls
+  from: codeql/<CODEQL_LANG>-queries
+# Third-party packs (include only if installed, one entry per pack)
+# - queries: .
+#   from: trailofbits/<CODEQL_LANG>-queries
+# - queries: .
+#   from: GitHubSecurityLab/CodeQL-Community-Packs-<CODEQL_LANG>
+# Minimal filtering — only select alert-type queries
+- include:
+    kind:
+      - problem
+      - path-problem
+- exclude:
+    deprecated: //
+- exclude:
+    tags contain:
+      - modeleditor
+      - modelgenerator
+```
+
+## Generation Script
+
+```bash
+RAW_DIR="$OUTPUT_DIR/raw"
+SUITE_FILE="$RAW_DIR/run-all.qls"
+
+# NOTE: CODEQL_LANG must be set before running this script (e.g., CODEQL_LANG=cpp)
+# NOTE: INSTALLED_THIRD_PARTY_PACKS must be a space-separated list of pack names
+
+cat > "$SUITE_FILE" << HEADER
+- description: Run-all — all security and quality queries from all installed packs
+- import: codeql-suites/${CODEQL_LANG}-security-and-quality.qls
+  from: codeql/${CODEQL_LANG}-queries
+HEADER
+
+# Add each installed third-party pack
+for PACK in $INSTALLED_THIRD_PARTY_PACKS; do
+  cat >> "$SUITE_FILE" << PACK_ENTRY
+- queries: .
+  from: ${PACK}
+PACK_ENTRY
+done
+
+# Append minimal filtering rules (quoted heredoc — no expansion needed)
+cat >> "$SUITE_FILE" << 'FILTERS'
+- include:
+    kind:
+      - problem
+      - path-problem
+- exclude:
+    deprecated: //
+- exclude:
+    tags contain:
+      - modeleditor
+      - modelgenerator
+FILTERS
+
+# Verify the suite resolves correctly
+: "${CODEQL_LANG:?ERROR: CODEQL_LANG must be set before generating suite}"
+: "${SUITE_FILE:?ERROR: SUITE_FILE must be set}"
+
+if ! codeql resolve queries "$SUITE_FILE" | wc -l; then
+  echo "ERROR: Suite file failed to resolve. Check CODEQL_LANG=$CODEQL_LANG and installed packs."
+fi
+echo "Suite generated: $SUITE_FILE"
+```
+
+## How This Differs From Important-Only
+
+| Aspect | Run all | Important only |
+|--------|---------|----------------|
+| Official pack suite | `security-and-quality` (all security + code quality) | All queries loaded, filtered by precision |
+| Third-party packs | All `problem`/`path-problem` queries | Only `security`-tagged queries with precision metadata |
+| Precision filter | None | high/very-high always; medium only if security-severity >= 6.0 |
+| Post-analysis filter | None | Drops medium-precision results with security-severity < 6.0 |

package/skills/codeql/references/sarif-processing.md

@@ -0,0 +1,79 @@
+# SARIF Processing
+
+jq commands for processing CodeQL SARIF output. Used in the run-analysis workflow Step 5.
+
+> **SARIF structure note:** `security-severity` and `level` are stored on rule definitions (`.runs[].tool.driver.rules[]`), NOT on individual result objects. Results reference rules by `ruleIndex`. The jq commands below join results with their rule metadata.
+>
+> **Portability note:** These jq patterns assume CodeQL SARIF output where `ruleIndex` is populated. For SARIF from other tools (e.g., Semgrep), use `ruleId`-based lookups instead.
+
+> **Directory convention:** Unfiltered output lives in `$RAW_DIR` (`$OUTPUT_DIR/raw`). Final results live in `$RESULTS_DIR` (`$OUTPUT_DIR/results`). The summary commands below operate on `$RESULTS_DIR/results.sarif` (the final output).
+
+## Count Findings
+
+```bash
+jq '.runs[].results | length' "$RESULTS_DIR/results.sarif"
+```
+
+## Summary by SARIF Level
+
+```bash
+jq -r '
+  .runs[] |
+  . as $run |
+  .results[] |
+  ($run.tool.driver.rules[.ruleIndex].defaultConfiguration.level // "unknown")
+' "$RESULTS_DIR/results.sarif" \
+  | sort | uniq -c | sort -rn
+```
+
+## Summary by Security Severity (most useful for triage)
+
+```bash
+jq -r '
+  .runs[] |
+  . as $run |
+  .results[] |
+  ($run.tool.driver.rules[.ruleIndex].properties["security-severity"] // "none") + " | " +
+  .ruleId + " | " +
+  (.locations[0].physicalLocation.artifactLocation.uri // "?") + ":" +
+  ((.locations[0].physicalLocation.region.startLine // 0) | tostring) + " | " +
+  (.message.text // "no message" | .[0:80])
+' "$RESULTS_DIR/results.sarif" | sort -rn | head -20
+```
+
+## Summary by Rule
+
+```bash
+jq -r '.runs[].results[] | .ruleId' "$RESULTS_DIR/results.sarif" \
+  | sort | uniq -c | sort -rn
+```
+
+## Important-Only Post-Filter
+
+If scan mode is "important only", filter out medium-precision results with `security-severity` < 6.0 from the report. The suite includes all medium-precision security queries to let CodeQL evaluate them, but low-severity medium-precision findings are noise.
+
+The filter reads from `$RAW_DIR/results.sarif` (unfiltered) and writes to `$RESULTS_DIR/results.sarif` (final). The raw file is preserved unmodified.
+
+```bash
+# Filter important-only results: drop medium-precision findings with security-severity < 6.0
+# Medium-precision queries without a security-severity score default to 0.0 (excluded).
+# Non-medium queries are always kept regardless of security-severity.
+# Reads from raw/, writes to results/ — preserving the unfiltered original.
+RAW_DIR="$OUTPUT_DIR/raw"
+RESULTS_DIR="$OUTPUT_DIR/results"
+jq '
+  .runs[] |= (
+    . as $run |
+    .results = [
+      .results[] |
+      ($run.tool.driver.rules[.ruleIndex].properties.precision // "unknown") as $prec |
+      ($run.tool.driver.rules[.ruleIndex].properties["security-severity"] // null) as $raw_sev |
+      (if $prec == "medium" then ($raw_sev // "0" | tonumber) else 10 end) as $sev |
+      select(
+        ($prec == "high") or ($prec == "very-high") or ($prec == "unknown") or
+        ($prec == "medium" and $sev >= 6.0)
+      )
+    ]
+  )
+' "$RAW_DIR/results.sarif" > "$RESULTS_DIR/results.sarif"
+```

package/skills/codeql/references/threat-models.md

@@ -0,0 +1,51 @@
+# Threat Models Reference
+
+Control which source categories are active during CodeQL analysis. By default, only `remote` sources are tracked.
+
+## Available Models
+
+| Model | Sources Included | When to Enable | False Positive Impact |
+|-------|------------------|----------------|----------------------|
+| `remote` | HTTP requests, network input | Always (default). Covers web services, APIs, network-facing code. | Low — these are the most common attack vectors. |
+| `local` | Command line args, local files | CLI tools, batch processors, desktop apps where local users are untrusted. | Medium — generates noise for web-only services where CLI args are developer-controlled. |
+| `environment` | Environment variables | Apps that read config from env vars at runtime (12-factor apps, containers). Skip for apps that only read env at startup into validated config objects. | Medium — many env reads are startup-only config, not runtime-tainted data. |
+| `database` | Database query results | Second-order injection scenarios: stored XSS, data from shared databases where other writers are untrusted. | High — most apps trust their own database. Only enable when auditing for stored/second-order attacks. |
+| `file` | File contents | File upload processors, log parsers, config file readers that accept user-provided files. | Medium — triggers on all file reads including trusted config files. |
+
+## Default Behavior
+
+With no `--threat-model` flag, CodeQL uses `remote` only (the `default` group). This is correct for most web applications and APIs. Expanding beyond `remote` is useful when the application's trust boundary extends to local inputs.
+
+## Usage
+
+Enable additional threat models with the `--threat-model` flag (singular, NOT `--threat-models`):
+
+```bash
+# Web service (default — remote only, no flag needed)
+codeql database analyze codeql.db \
+  -- results/suite.qls
+
+# CLI tool — local users can provide malicious input
+codeql database analyze codeql.db \
+  --threat-model local \
+  -- results/suite.qls
+
+# Container app reading env vars from untrusted orchestrator
+codeql database analyze codeql.db \
+  --threat-model local --threat-model environment \
+  -- results/suite.qls
+
+# Full coverage — audit mode for all input vectors
+codeql database analyze codeql.db \
+  --threat-model all \
+  -- results/suite.qls
+
+# Enable all except database (to reduce noise)
+codeql database analyze codeql.db \
+  --threat-model all --threat-model '!database' \
+  -- results/suite.qls
+```
+
+The `--threat-model` flag can be repeated. Each invocation adds (or removes with `!` prefix) a threat model group. The `remote` group is always enabled by default — use `--threat-model '!default'` to disable it (rare). The `all` group enables everything, and `!<name>` disables a specific model.
+
+Multiple models can be combined. Each additional model expands the set of sources CodeQL considers tainted, increasing coverage but potentially increasing false positives. Start with the narrowest set that matches the application's actual threat model, then expand if needed.

package/skills/codeql/workflows/build-database.md

@@ -0,0 +1,280 @@
+# Build Database Workflow
+
+Create high-quality CodeQL databases by trying build methods in sequence until one produces good results.
+
+## Task System
+
+Create these tasks on workflow start:
+
+```
+TaskCreate: "Detect language and configure" (Step 1)
+TaskCreate: "Build database" (Step 2) - blockedBy: Step 1
+TaskCreate: "Apply fixes if needed" (Step 3) - blockedBy: Step 2
+TaskCreate: "Assess quality" (Step 4) - blockedBy: Step 3
+TaskCreate: "Improve quality if needed" (Step 5) - blockedBy: Step 4
+TaskCreate: "Generate final report" (Step 6) - blockedBy: Step 5
+```
+
+---
+
+## Overview
+
+Database creation differs by language type:
+
+### Interpreted Languages (Python, JavaScript, Go, Ruby)
+- **No build required** — CodeQL extracts source directly
+- **Exclusion config supported** — Use `--codescanning-config` to skip irrelevant files
+
+### Compiled Languages (C/C++, Java, C#, Rust, Swift)
+- **Build required** — CodeQL must trace the compilation
+- **Exclusion config NOT supported** — All compiled code must be traced
+- Try build methods in order until one succeeds:
+  1. **Autobuild** — CodeQL auto-detects and runs the build
+  2. **Custom Command** — Explicit build command for the detected build system
+  2m. **macOS arm64 Toolchain** — Homebrew compiler + multi-step tracing (Apple Silicon workaround)
+  3. **Multi-step** — Fine-grained control with init → trace-command → finalize
+  4. **No-build fallback** — `--build-mode=none` (partial analysis, last resort)
+
+> **macOS Apple Silicon:** On arm64 Macs, system tools (`/usr/bin/make`, `/usr/bin/clang`, `/usr/bin/ar`) are `arm64e` but CodeQL's `libtrace.dylib` only has `arm64`. macOS kills `arm64e` processes with a non-`arm64e` injected dylib (SIGKILL, exit 137). Step 2a detects this and routes to Method 2m.
+
+---
+
+## Output Directory
+
+This workflow receives `$OUTPUT_DIR` from the parent skill (resolved once at invocation). All files go inside it.
+
+```bash
+DB_NAME="$OUTPUT_DIR/codeql.db"
+```
+
+---
+
+## Build Log
+
+Maintain a log file throughout. Initialize at start:
+
+```bash
+LOG_FILE="$OUTPUT_DIR/build.log"
+echo "=== CodeQL Database Build Log ===" > "$LOG_FILE"
+echo "Started: $(date -Iseconds)" >> "$LOG_FILE"
+echo "Output dir: $OUTPUT_DIR" >> "$LOG_FILE"
+echo "Database: $DB_NAME" >> "$LOG_FILE"
+```
+
+Log helper:
+```bash
+log_step()   { echo "[$(date -Iseconds)] $1" >> "$LOG_FILE"; }
+log_cmd()    { echo "[$(date -Iseconds)] COMMAND: $1" >> "$LOG_FILE"; }
+log_result() { echo "[$(date -Iseconds)] RESULT: $1" >> "$LOG_FILE"; echo "" >> "$LOG_FILE"; }
+```
+
+**What to log:** Detected language/build system, each build attempt with exact command, fix attempts and outcomes, quality assessment results, final successful command.
+
+---
+
+## Step 1: Detect Language and Configure
+
+**Entry:** CodeQL CLI installed and on PATH (`codeql --version` succeeds)
+**Exit:** `CODEQL_LANG` variable set to a valid CodeQL language identifier; exclusion config created (interpreted) or skipped (compiled)
+
+### 1a. Detect Language
+
+```bash
+fd -t f -e py -e js -e ts -e go -e rb -e java -e c -e cpp -e h -e hpp -e rs -e cs | \
+  sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5
+ls -la Makefile CMakeLists.txt build.gradle pom.xml Cargo.toml *.sln 2>/dev/null || true
+```
+
+| Language | `--language=` | Type |
+|----------|---------------|------|
+| Python | `python` | Interpreted |
+| JavaScript/TypeScript | `javascript` | Interpreted |
+| Go | `go` | Interpreted |
+| Ruby | `ruby` | Interpreted |
+| Java/Kotlin | `java` | Compiled |
+| C/C++ | `cpp` | Compiled |
+| C# | `csharp` | Compiled |
+| Rust | `rust` | Compiled |
+| Swift | `swift` | Compiled (macOS) |
+
+### 1b. Create Exclusion Config (Interpreted Languages Only)
+
+> **Skip for compiled languages** — exclusion config is not supported when build tracing is required.
+
+Scan for irrelevant directories and create `$OUTPUT_DIR/codeql-config.yml` with `paths-ignore` entries for `node_modules`, `vendor`, `venv`, third-party code, and generated/minified files.
+
+---
+
+## Step 2: Build Database
+
+**Entry:** Step 1 complete (`CODEQL_LANG` set, `DB_NAME` assigned, log file initialized)
+**Exit:** `codeql resolve database -- "$DB_NAME"` succeeds (database exists and is valid)
+
+### For Interpreted Languages
+
+```bash
+log_step "Building database for interpreted language: <LANG>"
+CMD="codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. --codescanning-config=$OUTPUT_DIR/codeql-config.yml --overwrite"
+log_cmd "$CMD"
+$CMD 2>&1 | tee -a "$LOG_FILE"
+```
+
+**Skip to Step 4 after success.**
+
+---
+
+### For Compiled Languages
+
+#### Step 2a: macOS arm64e Detection (C/C++ primarily)
+
+```bash
+IS_MACOS_ARM64E=false
+if [[ "$(uname -s)" == "Darwin" ]] && [[ "$(uname -m)" == "arm64" ]]; then
+  LIBTRACE=$(find "$(dirname "$(command -v codeql)")" -name libtrace.dylib 2>/dev/null | head -1)
+  if [ -n "$LIBTRACE" ]; then
+    LIBTRACE_ARCHS=$(lipo -archs "$LIBTRACE" 2>/dev/null)
+    if [[ "$LIBTRACE_ARCHS" != *"arm64e"* ]]; then
+      MAKE_ARCHS=$(lipo -archs /usr/bin/make 2>/dev/null)
+      [[ "$MAKE_ARCHS" == *"arm64e"* ]] && IS_MACOS_ARM64E=true
+    fi
+  fi
+fi
+```
+
+**If `IS_MACOS_ARM64E=true`:** Skip Methods 1 and 2 — go directly to Method 2m.
+
+---
+
+Try build methods in sequence until one succeeds:
+
+#### Method 1: Autobuild
+
+> **Skip if `IS_MACOS_ARM64E=true`.**
+
+```bash
+log_step "METHOD 1: Autobuild"
+CMD="codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. --overwrite"
+log_cmd "$CMD"
+$CMD 2>&1 | tee -a "$LOG_FILE"
+```
+
+#### Method 2: Custom Command
+
+> **Skip if `IS_MACOS_ARM64E=true`.**
+
+Detect build system and use explicit command:
+
+| Build System | Detection | Command |
+|--------------|-----------|---------|
+| Make | `Makefile` | `make clean && make -j$(nproc)` |
+| CMake | `CMakeLists.txt` | `cmake -B build && cmake --build build` |
+| Gradle | `build.gradle` | `./gradlew clean build -x test` |
+| Maven | `pom.xml` | `mvn clean compile -DskipTests` |
+| Cargo | `Cargo.toml` | `cargo clean && cargo build` |
+| .NET | `*.sln` | `dotnet clean && dotnet build` |
+
+Also check for project-specific build scripts (`build.sh`, `compile.sh`) and README instructions.
+
+```bash
+log_step "METHOD 2: Custom command"
+CMD="codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. --command='$BUILD_CMD' --overwrite"
+log_cmd "$CMD"
+$CMD 2>&1 | tee -a "$LOG_FILE"
+```
+
+#### Method 2m: macOS arm64 Toolchain (Apple Silicon workaround)
+
+> **Use when `IS_MACOS_ARM64E=true`.** Replaces Methods 1 and 2 on affected systems.
+
+See [macos-arm64e-workaround.md](../references/macos-arm64e-workaround.md) for the full sub-method sequence (2m-a through 2m-d): Homebrew compiler with multi-step tracing → Rosetta x86_64 → system compiler verification → ask user.
+
+#### Method 3: Multi-step Build
+
+For complex builds needing fine-grained control:
+
+> **On macOS with `IS_MACOS_ARM64E=true`:** Only trace arm64 Homebrew binaries. Do NOT trace system tools.
+
+```bash
+log_step "METHOD 3: Multi-step build"
+codeql database init $DB_NAME --language=$CODEQL_LANG --source-root=. --overwrite
+codeql database trace-command $DB_NAME -- <build step 1>
+codeql database trace-command $DB_NAME -- <build step 2>
+codeql database finalize $DB_NAME
+```
+
+#### Method 4: No-Build Fallback (Last Resort)
+
+> **WARNING:** Creates a database without build tracing. Only source-level patterns detected.
+
+```bash
+log_step "METHOD 4: No-build fallback (partial analysis)"
+CMD="codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. --build-mode=none --overwrite"
+log_cmd "$CMD"
+$CMD 2>&1 | tee -a "$LOG_FILE"
+```
+
+---
+
+## Step 3: Apply Fixes (if build failed)
+
+**Entry:** Step 2 build method failed (non-zero exit or `codeql resolve database` fails)
+**Exit:** Fix applied and current build method retried; either succeeds (go to Step 4) or all fixes exhausted (try next build method in Step 2)
+
+Try fixes in order, then retry current build method. See [build-fixes.md](../references/build-fixes.md) for the full fix catalog: clean state, clean build cache, install dependencies, handle private registries.
+
+---
+
+## Steps 4-5: Assess and Improve Quality
+
+**Entry:** Database exists and `codeql resolve database` succeeds
+**Exit (Step 4):** Quality metrics collected (baseline LoC, file counts, extractor errors, finalization status)
+**Exit (Step 5):** Quality is GOOD (baseline LoC > 0, errors < 5%, project files present) OR user accepts current state
+
+Run quality checks and compare against expected source files. See [quality-assessment.md](../references/quality-assessment.md) for metric collection, quality criteria table, and improvement steps.
+
+---
+
+## Exit Conditions
+
+**Success:** Quality assessment shows GOOD or user accepts current state.
+
+**Failure (all methods exhausted):**
+```
+AskUserQuestion: "All build methods failed. Options:"
+  1. "Accept current state" (if any database exists)
+  2. "I'll fix the build manually and retry"
+  3. "Abort"
+```
+
+---
+
+## Final Report
+
+```bash
+echo "=== Build Complete ===" >> "$LOG_FILE"
+echo "Finished: $(date -Iseconds)" >> "$LOG_FILE"
+echo "Final database: $DB_NAME" >> "$LOG_FILE"
+echo "Successful method: <METHOD>" >> "$LOG_FILE"
+codeql resolve database -- "$DB_NAME" >> "$LOG_FILE" 2>&1
+```
+
+Report to user:
+```
+## Database Build Complete
+
+**Output directory:** $OUTPUT_DIR
+**Database:** $DB_NAME
+**Language:** <LANG>
+**Build method:** autobuild | custom | multi-step
+**Files extracted:** <COUNT>
+
+### Quality:
+- Errors: <N>
+- Coverage: <good/partial/poor>
+
+### Build Log:
+See `$OUTPUT_DIR/build.log` for complete details.
+
+**Final command used:** <EXACT_COMMAND>
+**Ready for analysis.**
+```