@vigolium/piolium 0.0.1

package/skills/codeql/references/diagnostic-query-templates.md

@@ -0,0 +1,339 @@
+# Diagnostic Query Templates
+
+Language-specific QL queries for enumerating sources and sinks recognized by CodeQL. Used during the data extensions creation process.
+
+## Source Enumeration Query
+
+All languages use the class `RemoteFlowSource`. The import differs per language.
+
+### Import Reference
+
+| Language | Imports | Class |
+|----------|---------|-------|
+| Python | `import python` + `import semmle.python.dataflow.new.RemoteFlowSources` | `RemoteFlowSource` |
+| JavaScript | `import javascript` | `RemoteFlowSource` |
+| Java | `import java` + `import semmle.code.java.dataflow.FlowSources` | `RemoteFlowSource` |
+| Go | `import go` | `RemoteFlowSource` |
+| C/C++ | `import cpp` + `import semmle.code.cpp.security.FlowSources` | `RemoteFlowSource` |
+| C# | `import csharp` + `import semmle.code.csharp.security.dataflow.flowsources.Remote` | `RemoteFlowSource` |
+| Ruby | `import ruby` + `import codeql.ruby.dataflow.RemoteFlowSources` | `RemoteFlowSource` |
+
+### Template (Python — swap imports per table above)
+
+```ql
+/**
+ * @name List recognized dataflow sources
+ * @description Enumerates all locations CodeQL recognizes as dataflow sources
+ * @kind problem
+ * @id custom/list-sources
+ */
+import python
+import semmle.python.dataflow.new.RemoteFlowSources
+
+from RemoteFlowSource src
+select src,
+  src.getSourceType()
+    + " | " + src.getLocation().getFile().getRelativePath()
+    + ":" + src.getLocation().getStartLine().toString()
+```
+
+**Note:** `getSourceType()` is available on Python, Java, and C#. For Go, JavaScript, Ruby, and C++ replace the select with:
+```ql
+select src,
+  src.getLocation().getFile().getRelativePath()
+    + ":" + src.getLocation().getStartLine().toString()
+```
+
+---
+
+## Sink Enumeration Queries
+
+The Concepts API differs significantly across languages. Use the correct template.
+
+### Concept Class Reference
+
+| Concept | Python | JavaScript | Go | Ruby |
+|---------|--------|------------|-----|------|
+| SQL | `SqlExecution.getSql()` | `DatabaseAccess.getAQueryArgument()` | `SQL::QueryString` (is-a Node) | `SqlExecution.getSql()` |
+| Command exec | `SystemCommandExecution.getCommand()` | `SystemCommandExecution.getACommandArgument()` | `SystemCommandExecution.getCommandName()` | `SystemCommandExecution.getAnArgument()` |
+| File access | `FileSystemAccess.getAPathArgument()` | `FileSystemAccess.getAPathArgument()` | `FileSystemAccess.getAPathArgument()` | `FileSystemAccess.getAPathArgument()` |
+| HTTP client | `Http::Client::Request.getAUrlPart()` | — | — | — |
+| Decoding | `Decoding.getAnInput()` | — | — | — |
+| XML parsing | — | — | — | `XmlParserCall.getAnInput()` |
+
+### Python
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks
+ */
+import python
+import semmle.python.Concepts
+
+from DataFlow::Node sink, string kind
+where
+  exists(SqlExecution e | sink = e.getSql() and kind = "sql-execution")
+  or
+  exists(SystemCommandExecution e |
+    sink = e.getCommand() and kind = "command-execution"
+  )
+  or
+  exists(FileSystemAccess e |
+    sink = e.getAPathArgument() and kind = "file-access"
+  )
+  or
+  exists(Http::Client::Request r |
+    sink = r.getAUrlPart() and kind = "http-request"
+  )
+  or
+  exists(Decoding d | sink = d.getAnInput() and kind = "decoding")
+  or
+  exists(CodeExecution e | sink = e.getCode() and kind = "code-execution")
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```
+
+### JavaScript / TypeScript
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks-js
+ */
+import javascript
+
+from DataFlow::Node sink, string kind
+where
+  exists(DatabaseAccess e |
+    sink = e.getAQueryArgument() and kind = "database-access"
+  )
+  or
+  exists(SystemCommandExecution e |
+    sink = e.getACommandArgument() and kind = "command-execution"
+  )
+  or
+  exists(FileSystemAccess e |
+    sink = e.getAPathArgument() and kind = "file-access"
+  )
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```
+
+### Go
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks-go
+ */
+import go
+import semmle.go.frameworks.SQL
+
+from DataFlow::Node sink, string kind
+where
+  sink instanceof SQL::QueryString and kind = "sql-query"
+  or
+  exists(SystemCommandExecution e |
+    sink = e.getCommandName() and kind = "command-execution"
+  )
+  or
+  exists(FileSystemAccess e |
+    sink = e.getAPathArgument() and kind = "file-access"
+  )
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```
+
+### Ruby
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks-ruby
+ */
+import ruby
+import codeql.ruby.Concepts
+
+from DataFlow::Node sink, string kind
+where
+  exists(SqlExecution e | sink = e.getSql() and kind = "sql-execution")
+  or
+  exists(SystemCommandExecution e |
+    sink = e.getAnArgument() and kind = "command-execution"
+  )
+  or
+  exists(FileSystemAccess e |
+    sink = e.getAPathArgument() and kind = "file-access"
+  )
+  or
+  exists(CodeExecution e | sink = e.getCode() and kind = "code-execution")
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```
+
+### Java
+
+Java lacks a unified Concepts module. Use language-specific sink classes. The diagnostics query needs its own `qlpack.yml` with a `codeql/java-all` dependency — create it alongside the `.ql` files:
+
+```yaml
+# $DIAG_DIR/qlpack.yml
+name: custom/diagnostics
+version: 0.0.1
+dependencies:
+  codeql/java-all: "*"
+```
+
+Then run `codeql pack install` in the diagnostics directory before executing queries.
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks
+ */
+import java
+import semmle.code.java.dataflow.DataFlow
+import semmle.code.java.security.QueryInjection
+import semmle.code.java.security.CommandLineQuery
+import semmle.code.java.security.TaintedPathQuery
+import semmle.code.java.security.XSS
+import semmle.code.java.security.RequestForgery
+import semmle.code.java.security.Xxe
+
+from DataFlow::Node sink, string kind
+where
+  sink instanceof QueryInjectionSink and kind = "sql-injection"
+  or
+  sink instanceof CommandInjectionSink and kind = "command-injection"
+  or
+  sink instanceof TaintedPathSink and kind = "path-injection"
+  or
+  sink instanceof XssSink and kind = "xss"
+  or
+  sink instanceof RequestForgerySink and kind = "ssrf"
+  or
+  sink instanceof XxeSink and kind = "xxe"
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```
+
+### C / C++
+
+C++ uses a similar per-vulnerability-class pattern. Requires a `qlpack.yml` with `codeql/cpp-all` dependency (same approach as Java):
+
+```yaml
+# $DIAG_DIR/qlpack.yml
+name: custom/diagnostics
+version: 0.0.1
+dependencies:
+  codeql/cpp-all: "*"
+```
+
+Then run `codeql pack install` in the diagnostics directory before executing queries.
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks-cpp
+ */
+import cpp
+import semmle.code.cpp.dataflow.DataFlow
+import semmle.code.cpp.security.CommandExecution
+import semmle.code.cpp.security.FileAccess
+import semmle.code.cpp.security.BufferWrite
+
+from DataFlow::Node sink, string kind
+where
+  exists(FunctionCall call |
+    sink.asExpr() = call.getAnArgument() and
+    call.getTarget().hasGlobalOrStdName("system") and
+    kind = "command-injection"
+  )
+  or
+  exists(FunctionCall call |
+    sink.asExpr() = call.getAnArgument() and
+    call.getTarget().hasGlobalOrStdName(["fopen", "open", "freopen"]) and
+    kind = "file-access"
+  )
+  or
+  exists(FunctionCall call |
+    sink.asExpr() = call.getAnArgument() and
+    call.getTarget().hasGlobalOrStdName(["sprintf", "strcpy", "strcat", "gets"]) and
+    kind = "buffer-write"
+  )
+  or
+  exists(FunctionCall call |
+    sink.asExpr() = call.getAnArgument() and
+    call.getTarget().hasGlobalOrStdName(["execl", "execle", "execlp", "execv", "execvp", "execvpe", "popen"]) and
+    kind = "command-execution"
+  )
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```
+
+### C\#
+
+C# uses per-vulnerability sink classes. Requires a `qlpack.yml` with `codeql/csharp-all` dependency:
+
+```yaml
+# $DIAG_DIR/qlpack.yml
+name: custom/diagnostics
+version: 0.0.1
+dependencies:
+  codeql/csharp-all: "*"
+```
+
+Then run `codeql pack install` in the diagnostics directory before executing queries.
+
+```ql
+/**
+ * @name List recognized dataflow sinks
+ * @description Enumerates security-relevant sinks CodeQL recognizes
+ * @kind problem
+ * @id custom/list-sinks-csharp
+ */
+import csharp
+import semmle.code.csharp.dataflow.DataFlow
+import semmle.code.csharp.security.dataflow.SqlInjectionQuery
+import semmle.code.csharp.security.dataflow.CommandInjectionQuery
+import semmle.code.csharp.security.dataflow.TaintedPathQuery
+import semmle.code.csharp.security.dataflow.XSSQuery
+
+from DataFlow::Node sink, string kind
+where
+  sink instanceof SqlInjection::Sink and kind = "sql-injection"
+  or
+  sink instanceof CommandInjection::Sink and kind = "command-injection"
+  or
+  sink instanceof TaintedPath::Sink and kind = "path-injection"
+  or
+  sink instanceof XSS::Sink and kind = "xss"
+select sink,
+  kind
+    + " | " + sink.getLocation().getFile().getRelativePath()
+    + ":" + sink.getLocation().getStartLine().toString()
+```

package/skills/codeql/references/extension-yaml-format.md

@@ -0,0 +1,209 @@
+# Data Extension YAML Format
+
+YAML format for CodeQL data extension files. Used by the create-data-extensions workflow to model project-specific sources, sinks, and flow summaries.
+
+## Structure
+
+All extension files follow this structure:
+
+```yaml
+extensions:
+  - addsTo:
+      pack: codeql/<language>-all  # Target library pack
+      extensible: <model-type>      # sourceModel, sinkModel, summaryModel, neutralModel
+    data:
+      - [<columns>]
+```
+
+## Source Models
+
+Columns: `[package, type, subtypes, name, signature, ext, output, kind, provenance]`
+
+| Column | Description | Example |
+|--------|-------------|---------|
+| package | Module/package path | `myapp.auth` |
+| type | Class or module name | `AuthManager` |
+| subtypes | Include subclasses | `True` (Java: capitalized) / `true` (Python/JS/Go) |
+| name | Method name | `get_token` |
+| signature | Method signature (optional) | `""` (Python/JS), `"(String,int)"` (Java) |
+| ext | Extension (optional) | `""` |
+| output | What is tainted | `ReturnValue`, `Parameter[0]` (Java) / `Argument[0]` (Python/JS/Go) |
+| kind | Source category | `remote`, `local`, `file`, `environment`, `database` |
+| provenance | How model was created | `manual` |
+
+**Java-specific format differences:**
+- **subtypes**: Use `True` / `False` (capitalized, Python-style), not `true` / `false`
+- **output for parameters**: Use `Parameter[N]` (not `Argument[N]`) to mark method parameters as sources
+- **signature**: Required for disambiguation — use Java type syntax: `"(String)"`, `"(String,int)"`
+- **Parameter ranges**: Use `Parameter[0..2]` to mark multiple consecutive parameters
+
+Example (Python):
+
+```yaml
+# $OUTPUT_DIR/extensions/sources.yml
+extensions:
+  - addsTo:
+      pack: codeql/python-all
+      extensible: sourceModel
+    data:
+      - ["myapp.http", "Request", true, "get_param", "", "", "ReturnValue", "remote", "manual"]
+      - ["myapp.http", "Request", true, "get_header", "", "", "ReturnValue", "remote", "manual"]
+```
+
+Example (Java — note `True`, `Parameter[N]`, and signature):
+
+```yaml
+# $OUTPUT_DIR/extensions/sources.yml
+extensions:
+  - addsTo:
+      pack: codeql/java-all
+      extensible: sourceModel
+    data:
+      - ["com.myapp.controller", "ApiController", True, "search", "(String)", "", "Parameter[0]", "remote", "manual"]
+      - ["com.myapp.service", "FileService", True, "upload", "(String,String)", "", "Parameter[0..1]", "remote", "manual"]
+```
+
+## Sink Models
+
+Columns: `[package, type, subtypes, name, signature, ext, input, kind, provenance]`
+
+Note: column 7 is `input` (which argument receives tainted data), not `output`.
+
+| Kind | Vulnerability |
+|------|---------------|
+| `sql-injection` | SQL injection |
+| `command-injection` | Command injection |
+| `path-injection` | Path traversal |
+| `xss` | Cross-site scripting |
+| `code-injection` | Code injection |
+| `ssrf` | Server-side request forgery |
+| `unsafe-deserialization` | Insecure deserialization |
+
+Example (Python):
+
+```yaml
+# $OUTPUT_DIR/extensions/sinks.yml
+extensions:
+  - addsTo:
+      pack: codeql/python-all
+      extensible: sinkModel
+    data:
+      - ["myapp.db", "Connection", true, "raw_query", "", "", "Argument[0]", "sql-injection", "manual"]
+      - ["myapp.shell", "Runner", false, "execute", "", "", "Argument[0]", "command-injection", "manual"]
+```
+
+Example (Java — note `True` and `Argument[N]` for sink input):
+
+```yaml
+extensions:
+  - addsTo:
+      pack: codeql/java-all
+      extensible: sinkModel
+    data:
+      - ["com.myapp.db", "QueryRunner", True, "execute", "(String)", "", "Argument[0]", "sql-injection", "manual"]
+```
+
+## Summary Models
+
+Columns: `[package, type, subtypes, name, signature, ext, input, output, kind, provenance]`
+
+| Kind | Description |
+|------|-------------|
+| `taint` | Data flows through, still tainted |
+| `value` | Data flows through, exact value preserved |
+
+Example:
+
+```yaml
+# $OUTPUT_DIR/extensions/summaries.yml
+extensions:
+  # Pass-through: taint propagates
+  - addsTo:
+      pack: codeql/python-all
+      extensible: summaryModel
+    data:
+      - ["myapp.cache", "Cache", true, "get", "", "", "Argument[0]", "ReturnValue", "taint", "manual"]
+      - ["myapp.utils", "JSON", false, "parse", "", "", "Argument[0]", "ReturnValue", "taint", "manual"]
+
+```
+
+## Neutral Models
+
+Columns: `[package, type, name, signature, kind, provenance]` (6 columns, NOT the 10-column `summaryModel` format).
+
+Use `neutralModel` to explicitly block taint propagation through known-safe functions.
+
+Example:
+
+```yaml
+  - addsTo:
+      pack: codeql/python-all
+      extensible: neutralModel
+    data:
+      - ["myapp.security", "Sanitizer", "escape_html", "", "summary", "manual"]
+```
+
+**`neutralModel` vs no model:** If a function has no model at all, CodeQL may still infer flow through it. Use `neutralModel` to explicitly block taint propagation through known-safe functions.
+
+## Language-Specific Notes
+
+**Python:** Use dotted module paths for `package` (e.g., `myapp.db`).
+
+**JavaScript:** `package` is often `""` for project-local code. Use the import path for npm packages.
+
+**Go:** Use full import paths (e.g., `myapp/internal/db`). `type` is often `""` for package-level functions.
+
+**Java:** Use fully qualified package names (e.g., `com.myapp.db`).
+
+**C/C++:** Use `""` for package, put the namespace in `type`.
+
+## Deploying Extensions
+
+**Known limitation:** `--additional-packs` and `--model-packs` flags do not work with pre-compiled query packs (bundled CodeQL distributions that cache `java-all` inside `.codeql/libraries/`). Extensions placed in a standalone model pack directory will be resolved by `codeql resolve qlpacks` but silently ignored during `codeql database analyze`.
+
+**Workaround — copy extensions into the library pack's `ext/` directory:**
+
+> **Warning:** Files copied into the `ext/` directory live inside CodeQL's managed pack cache. They will be **lost** when packs are updated via `codeql pack download` or version upgrades. After any pack update, re-run this deployment step to restore the extensions.
+
+```bash
+# Find the java-all ext directory used by the query pack
+JAVA_ALL_EXT=$(find "$(codeql resolve qlpacks 2>/dev/null | grep 'java-queries' | awk '{print $NF}' | tr -d '()')" \
+  -path '*/.codeql/libraries/codeql/java-all/*/ext' -type d 2>/dev/null | head -1)
+
+if [ -n "$JAVA_ALL_EXT" ]; then
+  PROJECT_NAME=$(basename "$(pwd)")
+  cp "$OUTPUT_DIR/extensions/sources.yml" "$JAVA_ALL_EXT/${PROJECT_NAME}.sources.model.yml"
+  [ -f "$OUTPUT_DIR/extensions/sinks.yml" ] && cp "$OUTPUT_DIR/extensions/sinks.yml" "$JAVA_ALL_EXT/${PROJECT_NAME}.sinks.model.yml"
+  [ -f "$OUTPUT_DIR/extensions/summaries.yml" ] && cp "$OUTPUT_DIR/extensions/summaries.yml" "$JAVA_ALL_EXT/${PROJECT_NAME}.summaries.model.yml"
+
+  # Verify deployment — confirm files landed correctly
+  DEPLOYED=$(ls "$JAVA_ALL_EXT/${PROJECT_NAME}".*.model.yml 2>/dev/null | wc -l)
+  if [ "$DEPLOYED" -gt 0 ]; then
+    echo "Extensions deployed to $JAVA_ALL_EXT ($DEPLOYED files):"
+    ls -la "$JAVA_ALL_EXT/${PROJECT_NAME}".*.model.yml
+  else
+    echo "ERROR: Files were copied but verification failed. Check path: $JAVA_ALL_EXT"
+  fi
+else
+  echo "WARNING: Could not find java-all ext directory. Extensions may not load."
+  echo "Attempted path lookup from: codeql resolve qlpacks | grep java-queries"
+  echo "Run 'codeql resolve qlpacks' manually to debug."
+fi
+```
+
+**For Python/JS/Go:** The same limitation may apply. Locate the `<lang>-all` pack's `ext/` directory and copy extensions there.
+
+**Alternative (if query packs are NOT pre-compiled):** Use `--additional-packs=./codeql-extensions` with a proper model pack `qlpack.yml`:
+
+```yaml
+# $OUTPUT_DIR/extensions/qlpack.yml
+name: custom/<project>-extensions
+version: 0.0.1
+library: true
+extensionTargets:
+  codeql/<lang>-all: "*"
+dataExtensions:
+  - sources.yml
+  - sinks.yml
+  - summaries.yml
+```

package/skills/codeql/references/important-only-suite.md

@@ -0,0 +1,153 @@
+# Important-Only Query Suite
+
+In important-only mode, generate a custom `.qls` query suite file at runtime. This applies the same precision/severity filtering to **all** packs (official + third-party).
+
+## Why a Custom Suite
+
+The built-in `security-extended` suite only applies to the official `codeql/<lang>-queries` pack. Third-party packs (Trail of Bits, Community Packs) run unfiltered when passed directly to `codeql database analyze`. A custom `.qls` suite loads queries from all packs and applies a single set of `include`/`exclude` filters uniformly.
+
+## Metadata Criteria
+
+Two-phase filtering: the **suite** selects candidate queries (broad), then a **post-analysis jq filter** removes low-severity medium-precision results from the SARIF output.
+
+### Phase 1: Suite selection (which queries run)
+
+Queries are included if they match **any** of these blocks (OR logic across blocks, AND logic within):
+
+| Block | kind | precision | problem.severity | tags |
+|-------|------|-----------|-----------------|------|
+| 1 | `problem`, `path-problem` | `high`, `very-high` | *(any)* | must contain `security` |
+| 2 | `problem`, `path-problem` | `medium` | *(any)* | must contain `security` |
+
+### Phase 2: Post-analysis filter (which results are reported)
+
+After `codeql database analyze` completes, filter the SARIF output:
+
+| precision | security-severity | Action |
+|-----------|-------------------|--------|
+| high / very-high | *(any)* | **Keep** |
+| medium | >= 6.0 | **Keep** |
+| medium | < 6.0 or missing | **Drop** |
+
+This ensures medium-precision queries with meaningful security impact (e.g., `cpp/path-injection` at 7.5, `cpp/world-writable-file-creation` at 7.8) are included, while noisy low-severity medium-precision findings are filtered out.
+
+Excluded: deprecated queries, model editor/generator queries. Experimental queries are **included**.
+
+**Key difference from `security-extended`:** The `security-extended` suite includes medium-precision queries at any severity. Important-only mode adds a security-severity threshold to reduce noise from medium-precision queries that flag low-impact issues.
+
+## Suite Template
+
+Generate this file as `important-only.qls` in the results directory before running analysis:
+
+```yaml
+- description: Important-only — security vulnerabilities, medium-high confidence
+# Official queries
+- queries: .
+  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>
+# Filtering: security only, high/very-high precision (any severity),
+# medium precision (any severity — low-severity filtered post-analysis by security-severity score).
+# Experimental queries included.
+- include:
+    kind:
+      - problem
+      - path-problem
+    precision:
+      - high
+      - very-high
+    tags contain:
+      - security
+- include:
+    kind:
+      - problem
+      - path-problem
+    precision:
+      - medium
+    tags contain:
+      - security
+- exclude:
+    deprecated: //
+- exclude:
+    tags contain:
+      - modeleditor
+      - modelgenerator
+```
+
+> **Post-analysis step required:** After running the analysis, apply the post-analysis jq filter (defined in the run-analysis workflow Step 5) to remove medium-precision results with `security-severity` < 6.0.
+
+## Generation Script
+
+The agent should generate the suite file dynamically based on installed packs:
+
+```bash
+RAW_DIR="$OUTPUT_DIR/raw"
+SUITE_FILE="$RAW_DIR/important-only.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
+
+# Use a heredoc WITHOUT quotes so ${CODEQL_LANG} expands
+cat > "$SUITE_FILE" << HEADER
+- description: Important-only — security vulnerabilities, medium-high confidence
+- queries: .
+  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 the filtering rules (quoted heredoc — no variable expansion needed)
+cat >> "$SUITE_FILE" << 'FILTERS'
+- include:
+    kind:
+      - problem
+      - path-problem
+    precision:
+      - high
+      - very-high
+    tags contain:
+      - security
+- include:
+    kind:
+      - problem
+      - path-problem
+    precision:
+      - medium
+    tags contain:
+      - security
+- 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" | head -20; then
+  echo "ERROR: Suite file failed to resolve. Check CODEQL_LANG=$CODEQL_LANG and installed packs."
+fi
+echo "Suite generated: $SUITE_FILE"
+```
+
+## How Filtering Works on Third-Party Queries
+
+CodeQL query suite filters match on query metadata (`@precision`, `@problem.severity`, `@tags`). Third-party queries that:
+
+- **Have proper metadata**: Filtered normally (kept if they match the include criteria)
+- **Lack `@precision`**: Excluded by `include` blocks (they require precision to match). This is correct — if a query doesn't declare its precision, we cannot assess its confidence.
+- **Lack `@tags security`**: Excluded. Non-security queries are not relevant to important-only mode.
+
+This is a stricter-than-necessary filter for third-party packs, but it ensures only well-annotated security queries run in important-only mode. The post-analysis jq filter then further narrows medium-precision results to those with `security-severity` >= 6.0.