devskill 2.0.7 → 2.0.8

package/skills/codeql/references/alert-management.md

@@ -0,0 +1,170 @@
+# CodeQL Alert Management Reference
+
+Guide for understanding, triaging, dismissing, and resolving code scanning alerts generated by CodeQL.
+
+## Alert Severity Levels
+
+### Standard Severity
+
+All code scanning alerts have one of these severity levels:
+
+| Level | Description |
+|---|---|
+| `Error` | High-confidence, high-impact issues that should be fixed |
+| `Warning` | Moderate-confidence or moderate-impact issues |
+| `Note` | Low-confidence or informational findings |
+
+### Security Severity
+
+Security alerts additionally have a security severity derived from CVSS scores:
+
+| Level | CVSS Score Range | Description |
+|---|---|---|
+| `Critical` | > 9.0 | Severe vulnerabilities requiring immediate attention |
+| `High` | 7.0 – 8.9 | Significant vulnerabilities that should be prioritized |
+| `Medium` | 4.0 – 6.9 | Moderate vulnerabilities to address in normal workflow |
+| `Low` | 0.1 – 3.9 | Minor issues with limited security impact |
+
+When a security severity is present, it takes precedence over the standard severity for display and sorting.
+
+### How Security Severity Is Calculated
+
+For each CodeQL security query added to the Default or Extended suite:
+1. All CVEs matching the query's CWE tags are identified
+2. The 75th percentile of CVSS scores for those CVEs is calculated
+3. That score becomes the query's security severity
+4. The numerical score maps to Critical/High/Medium/Low per CVSS definitions
+
+## Alert Labels
+
+Alerts in non-application code receive category labels:
+
+| Label | Description |
+|---|---|
+| **Generated** | Code generated by the build process |
+| **Test** | Test code (detected by file path) |
+| **Library** | Library or third-party code |
+| **Documentation** | Documentation files |
+
+These labels are assigned automatically based on file paths. They cannot be manually overridden.
+
+## Alert Triage in Pull Requests
+
+### How PR Alerts Work
+
+- Alerts appear as annotations in the **Conversation** tab and **Files changed** tab
+- The **Code scanning results** check summarizes all findings
+- Alerts only appear in a PR if ALL identified lines exist in the PR diff
+- New alerts on changed lines are shown; pre-existing alerts are not
+
+### PR Check Failure Behavior
+
+By default, the check fails if alerts have severity of `error`, `critical`, or `high`. Override this threshold via repository Settings → Rules → Rulesets → Code scanning.
+
+### Merge Protection
+
+Configure rulesets to block PR merging when:
+- A required tool finds alerts matching the severity threshold
+- A required tool's analysis is still in progress
+- A required tool is not configured for the repository
+
+## Copilot Autofix
+
+GitHub Copilot Autofix automatically generates fix suggestions for CodeQL alerts in pull requests.
+
+### Availability
+- Free for all public repositories
+- Available for private repos with GitHub Code Security license
+- No Copilot subscription required
+- Supports a subset of CodeQL queries (not all)
+
+### How It Works
+1. Code scanning detects an alert in a PR
+2. Alert information is sent to the LLM for analysis
+3. Fix suggestions are posted as PR comments with inline code changes
+4. Developers review, edit, and commit the suggested fix
+
+### Using Autofix Suggestions
+- Click **Edit** to apply the fix directly on GitHub or via GitHub CLI
+- Use **View autofix patch** to apply locally
+- Always review and test the fix before committing
+- The fix may include changes to files not in the original PR diff (e.g., adding a dependency to `package.json`)
+
+### Dismissing Autofix
+Click **Dismiss suggestion** on the comment to reject a suggestion.
+
+## Dismissing Alerts
+
+### When to Dismiss
+
+Dismiss alerts when:
+- The finding is a false positive (code uses a pattern CodeQL doesn't recognize as safe)
+- The code is used only for testing and risk is acceptable
+- The effort to fix is greater than the benefit
+
+### Dismissal Reasons
+
+Choose the appropriate reason — it affects whether the query continues running:
+
+| Reason | When to Use |
+|---|---|
+| **False positive** | The alert is incorrect; the code is actually safe |
+| **Won't fix** | The risk is accepted or the code is being deprecated |
+| **Used in tests** | The vulnerable pattern is only in test code |
+
+### Dismissal Comments
+- Add a comment explaining the dismissal rationale
+- Comments are stored in the alert timeline for audit/compliance
+- Accessible via REST API at `alerts/{alert_number}` → `dismissed_comment`
+
+### Contributing Improvements
+For false positives from unsupported sanitization libraries, consider contributing to the CodeQL repository to improve analysis accuracy.
+
+## Resolving Alerts
+
+### Fix and Re-scan
+1. Fix the vulnerability in the source code
+2. Commit and push the changes
+3. The next code scanning run will verify the fix
+4. Alert is automatically closed when the fix is confirmed
+
+### Removing Stale Configurations
+If alerts persist from old/disabled configurations:
+1. Navigate to the alert's **Affected branches** section
+2. Identify stale configurations
+3. Delete the stale configuration to remove outdated alerts
+
+## Alert Data Flow
+
+For `path-problem` queries, alerts include data flow information:
+
+- **Source** — where untrusted data enters (e.g., user input)
+- **Sink** — where the data is used unsafely (e.g., SQL query, HTML output)
+- **Path** — the intermediate steps data takes from source to sink
+
+Click **Show paths** on alert annotations to visualize the full data flow.
+
+## Multi-Configuration Alerts
+
+When multiple code scanning configurations analyze the same file:
+- The same problem detected by the same query appears as a single alert
+- The **Affected branches** section shows which configurations found the alert
+- Different configurations may show different statuses
+- Re-run out-of-date configurations to synchronize alert statuses
+
+## Viewing Alerts
+
+### Repository Security Tab
+- Navigate to **Security** → **Code scanning alerts**
+- Filter by: tool, severity, rule, branch, state
+- Click an alert to see full details, affected branches, and data flow
+
+### Pull Request Checks
+- View **Code scanning results** check in the PR
+- Click **View all branch alerts** for the full alert list
+- Annotations appear inline in **Files changed**
+
+### REST API
+- `GET /repos/{owner}/{repo}/code-scanning/alerts` — list alerts
+- `GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}` — get alert details
+- `PATCH /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}` — update alert status

package/skills/codeql/references/cli-commands.md

@@ -0,0 +1,283 @@
+# CodeQL CLI Command Reference
+
+Detailed reference for the CodeQL CLI — installation, database creation, analysis, SARIF upload, and CI integration.
+
+## Installation
+
+### Download the CodeQL Bundle
+
+Always download the CodeQL bundle (CLI + precompiled queries) from:
+**https://github.com/github/codeql-action/releases**
+
+The bundle includes:
+- CodeQL CLI product
+- Compatible queries and libraries from `github/codeql`
+- Precompiled query plans for faster analysis
+
+### Platform-Specific Bundles
+
+| Platform | File |
+|---|---|
+| All platforms | `codeql-bundle.tar.zst` |
+| Linux | `codeql-bundle-linux64.tar.zst` |
+| macOS | `codeql-bundle-osx64.tar.zst` |
+| Windows | `codeql-bundle-win64.tar.zst` |
+
+> `.tar.gz` variants are also available for systems without Zstandard support.
+
+### Setup
+
+```bash
+# Extract the bundle
+tar xf codeql-bundle-linux64.tar.zst
+
+# Add to PATH
+export PATH="$HOME/codeql:$PATH"
+
+# Verify installation
+codeql resolve packs
+codeql resolve languages
+```
+
+`codeql resolve packs` should list available query packs for all supported languages. If packs are missing, verify you downloaded the bundle (not standalone CLI).
+
+### CI System Setup
+
+Ensure the full CodeQL bundle contents are available on every CI server:
+- Copy from a central location and extract on each server, or
+- Use the GitHub REST API to download the bundle dynamically per run
+
+## Core Commands
+
+### `codeql database create`
+
+Create a CodeQL database from source code.
+
+```bash
+# Basic usage (interpreted language)
+codeql database create <output-dir> \
+  --language=<language> \
+  --source-root=<source-dir>
+
+# Compiled language with build command
+codeql database create <output-dir> \
+  --language=java-kotlin \
+  --command='./gradlew build' \
+  --source-root=.
+
+# Multiple languages (cluster mode)
+codeql database create <output-dir> \
+  --db-cluster \
+  --language=java,python,javascript-typescript \
+  --command='./build.sh' \
+  --source-root=.
+```
+
+**Key flags:**
+
+| Flag | Description |
+|---|---|
+| `--language=<lang>` | Language to extract (required). Use CodeQL language identifiers. |
+| `--source-root=<dir>` | Root directory of source code (default: current directory) |
+| `--command=<cmd>` | Build command for compiled languages |
+| `--db-cluster` | Create databases for multiple languages in one pass |
+| `--overwrite` | Overwrite existing database directory |
+| `--threads=<n>` | Number of threads for extraction (default: 1; use 0 for all available cores) |
+| `--ram=<mb>` | RAM limit in MB for extraction |
+
+### `codeql database analyze`
+
+Run queries against a CodeQL database and produce SARIF output.
+
+```bash
+codeql database analyze <database-dir> \
+  <query-suite-or-pack> \
+  --format=sarif-latest \
+  --sarif-category=<category> \
+  --output=<output-file>
+```
+
+**Key flags:**
+
+| Flag | Description |
+|---|---|
+| `--format=sarif-latest` | Output format (use `sarif-latest` for current SARIF v2.1.0) |
+| `--sarif-category=<cat>` | Category tag for the SARIF results (important for multi-language repos) |
+| `--output=<file>` | Output file path for SARIF results |
+| `--threads=<n>` | Number of threads for analysis |
+| `--ram=<mb>` | RAM limit in MB |
+| `--sarif-add-file-contents` | Include source file contents in SARIF output |
+| `--ungroup-results` | Disable result grouping (each occurrence reported separately) |
+| `--no-download` | Skip downloading query packs (use only locally available packs) |
+
+**Common query suites:**
+
+| Suite | Description |
+|---|---|
+| `<lang>-code-scanning.qls` | Standard code scanning queries |
+| `<lang>-security-extended.qls` | Extended security queries |
+| `<lang>-security-and-quality.qls` | Security + code quality queries |
+
+**Examples:**
+
+```bash
+# JavaScript analysis with extended security
+codeql database analyze codeql-db/javascript-typescript \
+  javascript-typescript-security-extended.qls \
+  --format=sarif-latest \
+  --sarif-category=javascript \
+  --output=js-results.sarif
+
+# Java analysis with all available threads
+codeql database analyze codeql-db/java-kotlin \
+  java-kotlin-code-scanning.qls \
+  --format=sarif-latest \
+  --sarif-category=java \
+  --output=java-results.sarif \
+  --threads=0
+
+# Include file contents in SARIF
+codeql database analyze codeql-db \
+  javascript-typescript-code-scanning.qls \
+  --format=sarif-latest \
+  --output=results.sarif \
+  --sarif-add-file-contents
+```
+
+### `codeql github upload-results`
+
+Upload SARIF results to GitHub code scanning.
+
+```bash
+codeql github upload-results \
+  --repository=<owner/repo> \
+  --ref=<git-ref> \
+  --commit=<commit-sha> \
+  --sarif=<sarif-file>
+```
+
+**Key flags:**
+
+| Flag | Description |
+|---|---|
+| `--repository=<owner/repo>` | Target GitHub repository |
+| `--ref=<ref>` | Git ref (e.g., `refs/heads/main`, `refs/pull/42/head`) |
+| `--commit=<sha>` | Full commit SHA |
+| `--sarif=<file>` | Path to SARIF file |
+| `--github-url=<url>` | GitHub instance URL (for GHES; defaults to github.com) |
+| `--github-auth-stdin` | Read auth token from stdin instead of `GITHUB_TOKEN` env var |
+
+**Authentication:** Set `GITHUB_TOKEN` environment variable with a token that has `security-events: write` scope, or use `--github-auth-stdin`.
+
+### `codeql resolve packs`
+
+List available query packs:
+
+```bash
+codeql resolve packs
+```
+
+Use to verify installation and diagnose missing packs. Available since CLI v2.19.0 (earlier versions: use `codeql resolve qlpacks`).
+
+### `codeql resolve languages`
+
+List supported languages:
+
+```bash
+codeql resolve languages
+```
+
+Shows which language extractors are available in the current installation.
+
+### `codeql database bundle`
+
+Create a relocatable archive of a CodeQL database for sharing or troubleshooting:
+
+```bash
+codeql database bundle <database-dir> \
+  --output=<archive-file>
+```
+
+Useful for sharing databases with team members or GitHub Support.
+
+## CLI Server Mode
+
+### `codeql execute cli-server`
+
+Run a persistent server to avoid repeated JVM initialization when executing multiple commands:
+
+```bash
+codeql execute cli-server [options]
+```
+
+**Key flags:**
+
+| Flag | Description |
+|---|---|
+| `-v, --verbose` | Increase progress messages |
+| `-q, --quiet` | Decrease progress messages |
+| `--verbosity=<level>` | Set verbosity: `errors`, `warnings`, `progress`, `progress+`, `progress++`, `progress+++` |
+| `--logdir=<dir>` | Write detailed logs to directory |
+| `--common-caches=<dir>` | Location for persistent cached data (default: `~/.codeql`) |
+| `-J=<opt>` | Pass option to the JVM |
+
+The server accepts commands via stdin and returns results, keeping the JVM warm between commands. Primarily useful in CI environments running multiple sequential CodeQL commands.
+
+## CI Integration Pattern
+
+### Complete CI Script Example
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+REPO="my-org/my-repo"
+REF="refs/heads/main"
+COMMIT=$(git rev-parse HEAD)
+LANGUAGES=("javascript-typescript" "python")
+
+# Create databases for all languages
+codeql database create codeql-dbs \
+  --db-cluster \
+  --source-root=. \
+  --language=$(IFS=,; echo "${LANGUAGES[*]}")
+
+# Analyze each language and upload results
+for lang in "${LANGUAGES[@]}"; do
+  echo "Analyzing $lang..."
+
+  codeql database analyze "codeql-dbs/$lang" \
+    "${lang}-security-extended.qls" \
+    --format=sarif-latest \
+    --sarif-category="$lang" \
+    --output="${lang}-results.sarif" \
+    --threads=0
+
+  codeql github upload-results \
+    --repository="$REPO" \
+    --ref="$REF" \
+    --commit="$COMMIT" \
+    --sarif="${lang}-results.sarif"
+
+  echo "$lang analysis uploaded."
+done
+```
+
+### External CI Systems
+
+For CI systems other than GitHub Actions:
+1. Install the CodeQL bundle on CI runners
+2. Run `codeql database create` with appropriate build commands
+3. Run `codeql database analyze` to generate SARIF
+4. Run `codeql github upload-results` to push results to GitHub
+5. Set `GITHUB_TOKEN` with `security-events: write` permission
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `GITHUB_TOKEN` | Authentication for `github upload-results` |
+| `CODEQL_EXTRACTOR_<LANG>_OPTION_<KEY>` | Extractor configuration (e.g., `CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS=true`) |
+| `CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES` | Auto-install C/C++ build dependencies on Ubuntu |
+| `CODEQL_RAM` | Override default RAM allocation for analysis |
+| `CODEQL_THREADS` | Override default thread count |