mirror of
https://github.com/github/awesome-copilot.git
synced 2026-03-18 15:15:15 +00:00
GHAS Pack - Agent Skills for GitHub Advanced Security - Includes Dependabot, CodeQL, and Secret Scanning (#1049)
* feat: add dependabot skill * feat: add codeql skill * feat: add secret-scanning skill * feat: run start and update docs * fix: replace deprecated @dependabot merge example with native auto-merge guidance The usage example still showed @dependabot merge despite the Jan 2026 deprecation. Replaced with gh pr merge --auto and GitHub UI auto-merge. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Ve Sharma
GitHub
@@ -58,6 +58,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
|
||||
| [cli-mastery](../skills/cli-mastery/SKILL.md) | Interactive training for the GitHub Copilot CLI. Guided lessons, quizzes, scenario challenges, and a full reference covering slash commands, shortcuts, modes, agents, skills, MCP, and configuration. Say "cliexpert" to start. | `references/final-exam.md`<br />`references/module-1-slash-commands.md`<br />`references/module-2-keyboard-shortcuts.md`<br />`references/module-3-modes.md`<br />`references/module-4-agents.md`<br />`references/module-5-skills.md`<br />`references/module-6-mcp.md`<br />`references/module-7-advanced.md`<br />`references/module-8-configuration.md`<br />`references/scenarios.md` |
|
||||
| [cloud-design-patterns](../skills/cloud-design-patterns/SKILL.md) | Cloud design patterns for distributed systems architecture covering 42 industry-standard patterns across reliability, performance, messaging, security, and deployment categories. Use when designing, reviewing, or implementing distributed system architectures. | `references/architecture-design.md`<br />`references/azure-service-mappings.md`<br />`references/best-practices.md`<br />`references/deployment-operational.md`<br />`references/event-driven.md`<br />`references/messaging-integration.md`<br />`references/performance.md`<br />`references/reliability-resilience.md`<br />`references/security.md` |
|
||||
| [code-exemplars-blueprint-generator](../skills/code-exemplars-blueprint-generator/SKILL.md) | Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams. | None |
|
||||
| [codeql](../skills/codeql/SKILL.md) | Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis. | `references/alert-management.md`<br />`references/cli-commands.md`<br />`references/compiled-languages.md`<br />`references/sarif-output.md`<br />`references/troubleshooting.md`<br />`references/workflow-configuration.md` |
|
||||
| [comment-code-generate-a-tutorial](../skills/comment-code-generate-a-tutorial/SKILL.md) | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | None |
|
||||
| [containerize-aspnet-framework](../skills/containerize-aspnet-framework/SKILL.md) | Containerize an ASP.NET .NET Framework project by creating Dockerfile and .dockerfile files customized for the project. | None |
|
||||
| [containerize-aspnetcore](../skills/containerize-aspnetcore/SKILL.md) | Containerize an ASP.NET Core project by creating Dockerfile and .dockerfile files customized for the project. | None |
|
||||
@@ -102,6 +103,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
|
||||
| [dataverse-python-usecase-builder](../skills/dataverse-python-usecase-builder/SKILL.md) | Generate complete solutions for specific Dataverse SDK use cases with architecture recommendations | None |
|
||||
| [debian-linux-triage](../skills/debian-linux-triage/SKILL.md) | Triage and resolve Debian Linux issues with apt, systemd, and AppArmor-aware guidance. | None |
|
||||
| [declarative-agents](../skills/declarative-agents/SKILL.md) | Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration | None |
|
||||
| [dependabot](../skills/dependabot/SKILL.md) | Comprehensive guide for configuring and managing GitHub Dependabot. Use this skill when users ask about creating or optimizing dependabot.yml files, managing Dependabot pull requests, configuring dependency update strategies, setting up grouped updates, monorepo patterns, multi-ecosystem groups, security update configuration, auto-triage rules, or any GitHub Advanced Security (GHAS) supply chain security topic related to Dependabot. | `references/dependabot-yml-reference.md`<br />`references/example-configs.md`<br />`references/pr-commands.md` |
|
||||
| [devops-rollout-plan](../skills/devops-rollout-plan/SKILL.md) | Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes | None |
|
||||
| [documentation-writer](../skills/documentation-writer/SKILL.md) | Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework. | None |
|
||||
| [dotnet-best-practices](../skills/dotnet-best-practices/SKILL.md) | Ensure .NET/C# code meets best practices for the solution/project. | None |
|
||||
@@ -215,6 +217,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
|
||||
| [sandbox-npm-install](../skills/sandbox-npm-install/SKILL.md) | Install npm packages in a Docker sandbox environment. Use this skill whenever you need to install, reinstall, or update node_modules inside a container where the workspace is mounted via virtiofs. Native binaries (esbuild, lightningcss, rollup) crash on virtiofs, so packages must be installed on the local ext4 filesystem and symlinked back. | `scripts/install.sh` |
|
||||
| [scaffolding-oracle-to-postgres-migration-test-project](../skills/scaffolding-oracle-to-postgres-migration-test-project/SKILL.md) | Scaffolds an xUnit integration test project for validating Oracle-to-PostgreSQL database migration behavior in .NET solutions. Creates the test project, transaction-rollback base class, and seed data manager. Use when setting up test infrastructure before writing migration integration tests, or when a test project is needed for Oracle-to-PostgreSQL validation. | None |
|
||||
| [scoutqa-test](../skills/scoutqa-test/SKILL.md) | This skill should be used when the user asks to "test this website", "run exploratory testing", "check for accessibility issues", "verify the login flow works", "find bugs on this page", or requests automated QA testing. Triggers on web application testing scenarios including smoke tests, accessibility audits, e-commerce flows, and user flow validation using ScoutQA CLI. Use this skill proactively after implementing web application features to verify they work correctly. | None |
|
||||
| [secret-scanning](../skills/secret-scanning/SKILL.md) | Guide for configuring and managing GitHub secret scanning, push protection, custom patterns, and secret alert remediation. This skill should be used when users need help enabling secret scanning, setting up push protection, defining custom secret patterns, triaging secret scanning alerts, or resolving blocked pushes. | `references/alerts-and-remediation.md`<br />`references/custom-patterns.md`<br />`references/push-protection.md` |
|
||||
| [semantic-kernel](../skills/semantic-kernel/SKILL.md) | Create, update, refactor, explain, or review Semantic Kernel solutions using shared guidance plus language-specific references for .NET and Python. | `references/dotnet.md`<br />`references/python.md` |
|
||||
| [shuffle-json-data](../skills/shuffle-json-data/SKILL.md) | Shuffle repetitive JSON objects safely by validating schema consistency before randomising entries. | None |
|
||||
| [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None |
|
||||
|
||||
405
skills/codeql/SKILL.md
Normal file
405
skills/codeql/SKILL.md
Normal file
@@ -0,0 +1,405 @@
|
||||
---
|
||||
name: codeql
|
||||
description: Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis.
|
||||
---
|
||||
|
||||
# CodeQL Code Scanning
|
||||
|
||||
This skill provides procedural guidance for configuring and running CodeQL code scanning — both through GitHub Actions workflows and the standalone CodeQL CLI.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when the request involves:
|
||||
|
||||
- Creating or customizing a `codeql.yml` GitHub Actions workflow
|
||||
- Choosing between default setup and advanced setup for code scanning
|
||||
- Configuring CodeQL language matrix, build modes, or query suites
|
||||
- Running CodeQL CLI locally (`codeql database create`, `database analyze`, `github upload-results`)
|
||||
- Understanding or interpreting SARIF output from CodeQL
|
||||
- Troubleshooting CodeQL analysis failures (build modes, compiled languages, runner requirements)
|
||||
- Setting up CodeQL for monorepos with per-component scanning
|
||||
- Configuring dependency caching, custom query packs, or model packs
|
||||
|
||||
## Supported Languages
|
||||
|
||||
CodeQL supports the following language identifiers:
|
||||
|
||||
| Language | Identifier | Alternatives |
|
||||
|---|---|---|
|
||||
| C/C++ | `c-cpp` | `c`, `cpp` |
|
||||
| C# | `csharp` | — |
|
||||
| Go | `go` | — |
|
||||
| Java/Kotlin | `java-kotlin` | `java`, `kotlin` |
|
||||
| JavaScript/TypeScript | `javascript-typescript` | `javascript`, `typescript` |
|
||||
| Python | `python` | — |
|
||||
| Ruby | `ruby` | — |
|
||||
| Rust | `rust` | — |
|
||||
| Swift | `swift` | — |
|
||||
| GitHub Actions | `actions` | — |
|
||||
|
||||
> Alternative identifiers are equivalent to the standard identifier (e.g., `javascript` does not exclude TypeScript analysis).
|
||||
|
||||
## Core Workflow — GitHub Actions
|
||||
|
||||
### Step 1: Choose Setup Type
|
||||
|
||||
- **Default setup** — Enable from repository Settings → Advanced Security → CodeQL analysis. Best for getting started quickly. Uses `none` build mode for most languages.
|
||||
- **Advanced setup** — Create a `.github/workflows/codeql.yml` file for full control over triggers, build modes, query suites, and matrix strategies.
|
||||
|
||||
To switch from default to advanced: disable default setup first, then commit the workflow file.
|
||||
|
||||
### Step 2: Configure Workflow Triggers
|
||||
|
||||
Define when scanning runs:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [main, protected]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
schedule:
|
||||
- cron: '30 6 * * 1' # Weekly Monday 6:30 UTC
|
||||
```
|
||||
|
||||
- `push` — scans on every push to specified branches; results appear in Security tab
|
||||
- `pull_request` — scans PR merge commits; results appear as PR check annotations
|
||||
- `schedule` — periodic scans of the default branch (cron must exist on default branch)
|
||||
- `merge_group` — add if repository uses merge queues
|
||||
|
||||
To skip scans for documentation-only PRs:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
pull_request:
|
||||
paths-ignore:
|
||||
- '**/*.md'
|
||||
- '**/*.txt'
|
||||
```
|
||||
|
||||
> `paths-ignore` controls whether the workflow runs, not which files are analyzed.
|
||||
|
||||
### Step 3: Configure Permissions
|
||||
|
||||
Set least-privilege permissions:
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
security-events: write # Required to upload SARIF results
|
||||
contents: read # Required to checkout code
|
||||
actions: read # Required for private repos using codeql-action
|
||||
```
|
||||
|
||||
### Step 4: Configure Language Matrix
|
||||
|
||||
Use a matrix strategy to analyze each language in parallel:
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
analyze:
|
||||
name: Analyze (${{ matrix.language }})
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: javascript-typescript
|
||||
build-mode: none
|
||||
- language: python
|
||||
build-mode: none
|
||||
```
|
||||
|
||||
For compiled languages, set the appropriate `build-mode`:
|
||||
- `none` — no build required (supported for C/C++, C#, Java, Rust)
|
||||
- `autobuild` — automatic build detection
|
||||
- `manual` — custom build commands (advanced setup only)
|
||||
|
||||
> For detailed per-language autobuild behavior and runner requirements, search `references/compiled-languages.md`.
|
||||
|
||||
### Step 5: Configure CodeQL Init and Analysis
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Initialize CodeQL
|
||||
uses: github/codeql-action/init@v4
|
||||
with:
|
||||
languages: ${{ matrix.language }}
|
||||
build-mode: ${{ matrix.build-mode }}
|
||||
queries: security-extended
|
||||
dependency-caching: true
|
||||
|
||||
- name: Perform CodeQL Analysis
|
||||
uses: github/codeql-action/analyze@v4
|
||||
with:
|
||||
category: "/language:${{ matrix.language }}"
|
||||
```
|
||||
|
||||
**Query suite options:**
|
||||
- `security-extended` — default security queries plus additional coverage
|
||||
- `security-and-quality` — security plus code quality queries
|
||||
- Custom query packs via `packs:` input (e.g., `codeql/javascript-queries:AlertSuppression.ql`)
|
||||
|
||||
**Dependency caching:** Set `dependency-caching: true` on the `init` action to cache restored dependencies across runs.
|
||||
|
||||
**Analysis category:** Use `category` to distinguish SARIF results in monorepos (e.g., per-language, per-component).
|
||||
|
||||
### Step 6: Monorepo Configuration
|
||||
|
||||
For monorepos with multiple components, use the `category` parameter to separate SARIF results:
|
||||
|
||||
```yaml
|
||||
category: "/language:${{ matrix.language }}/component:frontend"
|
||||
```
|
||||
|
||||
To restrict analysis to specific directories, use a CodeQL configuration file (`.github/codeql/codeql-config.yml`):
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
- apps/
|
||||
- services/
|
||||
paths-ignore:
|
||||
- node_modules/
|
||||
- '**/test/**'
|
||||
```
|
||||
|
||||
Reference it in the workflow:
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
config-file: .github/codeql/codeql-config.yml
|
||||
```
|
||||
|
||||
### Step 7: Manual Build Steps (Compiled Languages)
|
||||
|
||||
If `autobuild` fails or custom build commands are needed:
|
||||
|
||||
```yaml
|
||||
- language: c-cpp
|
||||
build-mode: manual
|
||||
```
|
||||
|
||||
Then add explicit build steps between `init` and `analyze`:
|
||||
|
||||
```yaml
|
||||
- if: matrix.build-mode == 'manual'
|
||||
name: Build
|
||||
run: |
|
||||
make bootstrap
|
||||
make release
|
||||
```
|
||||
|
||||
## Core Workflow — CodeQL CLI
|
||||
|
||||
### Step 1: Install the CodeQL CLI
|
||||
|
||||
Download the CodeQL bundle (includes CLI + precompiled queries):
|
||||
|
||||
```bash
|
||||
# Download from https://github.com/github/codeql-action/releases
|
||||
# Extract and add to PATH
|
||||
export PATH="$HOME/codeql:$PATH"
|
||||
|
||||
# Verify installation
|
||||
codeql resolve packs
|
||||
codeql resolve languages
|
||||
```
|
||||
|
||||
> Always use the CodeQL bundle, not a standalone CLI download. The bundle ensures query compatibility and provides precompiled queries for better performance.
|
||||
|
||||
### Step 2: Create a CodeQL Database
|
||||
|
||||
```bash
|
||||
# Single language
|
||||
codeql database create codeql-db \
|
||||
--language=javascript-typescript \
|
||||
--source-root=src
|
||||
|
||||
# Multiple languages (cluster mode)
|
||||
codeql database create codeql-dbs \
|
||||
--db-cluster \
|
||||
--language=java,python \
|
||||
--command=./build.sh \
|
||||
--source-root=src
|
||||
```
|
||||
|
||||
For compiled languages, provide the build command via `--command`.
|
||||
|
||||
### Step 3: Analyze the Database
|
||||
|
||||
```bash
|
||||
codeql database analyze codeql-db \
|
||||
javascript-code-scanning.qls \
|
||||
--format=sarif-latest \
|
||||
--sarif-category=javascript \
|
||||
--output=results.sarif
|
||||
```
|
||||
|
||||
Common query suites: `<language>-code-scanning.qls`, `<language>-security-extended.qls`, `<language>-security-and-quality.qls`.
|
||||
|
||||
### Step 4: Upload Results to GitHub
|
||||
|
||||
```bash
|
||||
codeql github upload-results \
|
||||
--repository=owner/repo \
|
||||
--ref=refs/heads/main \
|
||||
--commit=<commit-sha> \
|
||||
--sarif=results.sarif
|
||||
```
|
||||
|
||||
Requires `GITHUB_TOKEN` environment variable with `security-events: write` permission.
|
||||
|
||||
### CLI Server Mode
|
||||
|
||||
To avoid repeated JVM initialization when running multiple commands:
|
||||
|
||||
```bash
|
||||
codeql execute cli-server
|
||||
```
|
||||
|
||||
> For detailed CLI command reference, search `references/cli-commands.md`.
|
||||
|
||||
## Alert Management
|
||||
|
||||
### Severity Levels
|
||||
|
||||
Alerts have two severity dimensions:
|
||||
- **Standard severity:** `Error`, `Warning`, `Note`
|
||||
- **Security severity:** `Critical`, `High`, `Medium`, `Low` (derived from CVSS scores; takes display precedence)
|
||||
|
||||
### Copilot Autofix
|
||||
|
||||
GitHub Copilot Autofix generates fix suggestions for CodeQL alerts in pull requests automatically — no Copilot subscription required. Review suggestions carefully before committing.
|
||||
|
||||
### Alert Triage in PRs
|
||||
|
||||
- Alerts appear as check annotations on changed lines
|
||||
- Check fails by default for `error`/`critical`/`high` severity alerts
|
||||
- Configure merge protection rulesets to customize the threshold
|
||||
- Dismiss false positives with a documented reason for audit trail
|
||||
|
||||
> For detailed alert management guidance, search `references/alert-management.md`.
|
||||
|
||||
## Custom Queries and Packs
|
||||
|
||||
### Using Custom Query Packs
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
packs: |
|
||||
my-org/my-security-queries@1.0.0
|
||||
codeql/javascript-queries:AlertSuppression.ql
|
||||
```
|
||||
|
||||
### Creating Custom Query Packs
|
||||
|
||||
Use the CodeQL CLI to create and publish packs:
|
||||
|
||||
```bash
|
||||
# Initialize a new pack
|
||||
codeql pack init my-org/my-queries
|
||||
|
||||
# Install dependencies
|
||||
codeql pack install
|
||||
|
||||
# Publish to GitHub Container Registry
|
||||
codeql pack publish
|
||||
```
|
||||
|
||||
### CodeQL Configuration File
|
||||
|
||||
For advanced query and path configuration, create `.github/codeql/codeql-config.yml`:
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
- apps/
|
||||
- services/
|
||||
paths-ignore:
|
||||
- '**/test/**'
|
||||
- node_modules/
|
||||
queries:
|
||||
- uses: security-extended
|
||||
packs:
|
||||
javascript-typescript:
|
||||
- my-org/my-custom-queries
|
||||
```
|
||||
|
||||
## Code Scanning Logs
|
||||
|
||||
### Summary Metrics
|
||||
|
||||
Workflow logs include key metrics:
|
||||
- **Lines of code in codebase** — baseline before extraction
|
||||
- **Lines extracted** — including external libraries and auto-generated files
|
||||
- **Extraction errors/warnings** — files that failed or produced warnings during extraction
|
||||
|
||||
### Debug Logging
|
||||
|
||||
To enable detailed diagnostics:
|
||||
- **GitHub Actions:** re-run the workflow with "Enable debug logging" checked
|
||||
- **CodeQL CLI:** use `--verbosity=progress++` and `--logdir=codeql-logs`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| Workflow not triggering | Verify `on:` triggers match event; check `paths`/`branches` filters; ensure workflow exists on target branch |
|
||||
| `Resource not accessible` error | Add `security-events: write` and `contents: read` permissions |
|
||||
| Autobuild failure | Switch to `build-mode: manual` and add explicit build commands |
|
||||
| No source code seen | Verify `--source-root`, build command, and language identifier |
|
||||
| C# compiler failure | Check for `/p:EmitCompilerGeneratedFiles=true` conflicts with `.sqlproj` or legacy projects |
|
||||
| Fewer lines scanned than expected | Switch from `none` to `autobuild`/`manual`; verify build compiles all source |
|
||||
| Kotlin in no-build mode | Disable and re-enable default setup to switch to `autobuild` |
|
||||
| Cache miss every run | Verify `dependency-caching: true` on `init` action |
|
||||
| Out of disk/memory | Use larger runners; reduce analysis scope via `paths` config; use `build-mode: none` |
|
||||
| SARIF upload fails | Ensure token has `security-events: write`; check 10 MB file size limit |
|
||||
| SARIF results exceed limits | Split across multiple uploads with different `--sarif-category`; reduce query scope |
|
||||
| Two CodeQL workflows | Disable default setup if using advanced setup, or remove old workflow file |
|
||||
| Slow analysis | Enable dependency caching; use `--threads=0`; reduce query suite scope |
|
||||
|
||||
> For comprehensive troubleshooting with detailed solutions, search `references/troubleshooting.md`.
|
||||
|
||||
### Hardware Requirements (Self-Hosted Runners)
|
||||
|
||||
| Codebase Size | RAM | CPU |
|
||||
|---|---|---|
|
||||
| Small (<100K LOC) | 8 GB+ | 2 cores |
|
||||
| Medium (100K–1M LOC) | 16 GB+ | 4–8 cores |
|
||||
| Large (>1M LOC) | 64 GB+ | 8 cores |
|
||||
|
||||
All sizes: SSD with ≥14 GB free disk space.
|
||||
|
||||
### Action Versioning
|
||||
|
||||
Pin CodeQL actions to a specific major version:
|
||||
|
||||
```yaml
|
||||
uses: github/codeql-action/init@v4 # Recommended
|
||||
uses: github/codeql-action/autobuild@v4
|
||||
uses: github/codeql-action/analyze@v4
|
||||
```
|
||||
|
||||
For maximum security, pin to a full commit SHA instead of a version tag.
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed documentation, load the following reference files as needed:
|
||||
|
||||
- `references/workflow-configuration.md` — Full workflow trigger, runner, and configuration options
|
||||
- Search patterns: `trigger`, `schedule`, `paths-ignore`, `db-location`, `model packs`, `alert severity`, `merge protection`, `concurrency`, `config file`
|
||||
- `references/cli-commands.md` — Complete CodeQL CLI command reference
|
||||
- Search patterns: `database create`, `database analyze`, `upload-results`, `resolve packs`, `cli-server`, `installation`, `CI integration`
|
||||
- `references/sarif-output.md` — SARIF v2.1.0 object model, upload limits, and third-party support
|
||||
- Search patterns: `sarifLog`, `result`, `location`, `region`, `codeFlow`, `fingerprint`, `suppression`, `upload limits`, `third-party`, `precision`, `security-severity`
|
||||
- `references/compiled-languages.md` — Build modes and autobuild behavior per language
|
||||
- Search patterns: `C/C++`, `C#`, `Java`, `Go`, `Rust`, `Swift`, `autobuild`, `build-mode`, `hardware`, `dependency caching`
|
||||
- `references/troubleshooting.md` — Comprehensive error diagnosis and resolution
|
||||
- Search patterns: `no source code`, `out of disk`, `out of memory`, `403`, `C# compiler`, `analysis too long`, `fewer lines`, `Kotlin`, `extraction errors`, `debug logging`, `SARIF upload`, `SARIF limits`
|
||||
- `references/alert-management.md` — Alert severity, triage, Copilot Autofix, and dismissal
|
||||
- Search patterns: `severity`, `security severity`, `CVSS`, `Copilot Autofix`, `dismiss`, `triage`, `PR alerts`, `data flow`, `merge protection`, `REST API`
|
||||
170
skills/codeql/references/alert-management.md
Normal file
170
skills/codeql/references/alert-management.md
Normal file
@@ -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
|
||||
283
skills/codeql/references/cli-commands.md
Normal file
283
skills/codeql/references/cli-commands.md
Normal file
@@ -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 |
|
||||
284
skills/codeql/references/compiled-languages.md
Normal file
284
skills/codeql/references/compiled-languages.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# CodeQL Build Modes for Compiled Languages
|
||||
|
||||
Detailed reference for how CodeQL handles compiled language analysis, including build modes, autobuild behavior, runner requirements, and hardware specifications.
|
||||
|
||||
## Build Modes Overview
|
||||
|
||||
CodeQL offers three build modes for compiled languages:
|
||||
|
||||
| Mode | Description | When to Use |
|
||||
|---|---|---|
|
||||
| `none` | Analyze source without building. Dependencies inferred heuristically. | Default setup; quick scans; interpreted-like analysis |
|
||||
| `autobuild` | Automatically detect and run the build system. | When `none` produces inaccurate results; when Kotlin code is present |
|
||||
| `manual` | User provides explicit build commands. | Complex build systems; autobuild failures; custom build requirements |
|
||||
|
||||
## C/C++
|
||||
|
||||
### Supported Build Modes
|
||||
`none`, `autobuild`, `manual`
|
||||
|
||||
**Default setup mode:** `none`
|
||||
|
||||
### No Build (`none`)
|
||||
- Infers compilation units through source file extensions
|
||||
- Compilation flags and include paths inferred by inspecting the codebase
|
||||
- No working build command needed
|
||||
|
||||
**Accuracy considerations:**
|
||||
- May be less accurate if code depends heavily on custom macros/defines not in existing headers
|
||||
- May miss accuracy when codebase has many external dependencies
|
||||
|
||||
**Improving accuracy:**
|
||||
- Place custom macros/defines in header files included by source files
|
||||
- Ensure external dependencies (headers) are available in system include directories or workspace
|
||||
- Run extraction on the target platform (e.g., Windows runner for Windows projects)
|
||||
|
||||
### Autobuild
|
||||
|
||||
**Windows autodetection:**
|
||||
1. Invoke `MSBuild.exe` on `.sln` or `.vcxproj` closest to root
|
||||
2. If multiple files at same depth, attempts to build all
|
||||
3. Falls back to build scripts: `build.bat`, `build.cmd`, `build.exe`
|
||||
|
||||
**Linux/macOS autodetection:**
|
||||
1. Look for build system in root directory
|
||||
2. If not found, search subdirectories for unique build system
|
||||
3. Run appropriate configure/build command
|
||||
|
||||
**Supported build systems:** MSBuild, Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild, build scripts
|
||||
|
||||
### Runner Requirements (C/C++)
|
||||
- **Ubuntu:** `gcc` compiler; may need `clang` or `msvc`. Build tools: `msbuild`, `make`, `cmake`, `bazel`. Utilities: `python`, `perl`, `lex`, `yacc`.
|
||||
- **Auto-install dependencies:** Set `CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES=true` (enabled by default on GitHub-hosted; disabled on self-hosted). Requires Ubuntu with passwordless `sudo apt-get`.
|
||||
- **Windows:** `powershell.exe` in PATH
|
||||
|
||||
## C\#
|
||||
|
||||
### Supported Build Modes
|
||||
`none`, `autobuild`, `manual`
|
||||
|
||||
**Default setup mode:** `none`
|
||||
|
||||
### No Build (`none`)
|
||||
- Restores dependencies using heuristics from: `*.csproj`, `*.sln`, `nuget.config`, `packages.config`, `global.json`, `project.assets.json`
|
||||
- Uses private NuGet feeds if configured for the organization
|
||||
- Generates additional source files for accuracy:
|
||||
- Global `using` directives (implicit `using` feature)
|
||||
- ASP.NET Core `.cshtml` → `.cs` conversion
|
||||
|
||||
**Accuracy considerations:**
|
||||
- Requires internet access or private NuGet feed
|
||||
- Multiple versions of same NuGet dependency may cause issues (CodeQL picks newer version)
|
||||
- Multiple .NET framework versions may affect accuracy
|
||||
- Colliding class names cause missing method call targets
|
||||
|
||||
### Autobuild
|
||||
|
||||
**Windows autodetection:**
|
||||
1. `dotnet build` on `.sln` or `.csproj` closest to root
|
||||
2. `MSBuild.exe` on solution/project files
|
||||
3. Build scripts: `build.bat`, `build.cmd`, `build.exe`
|
||||
|
||||
**Linux/macOS autodetection:**
|
||||
1. `dotnet build` on `.sln` or `.csproj` closest to root
|
||||
2. `MSbuild` on solution/project files
|
||||
3. Build scripts: `build`, `build.sh`
|
||||
|
||||
### Injected Compiler Flags (Manual Builds)
|
||||
|
||||
The CodeQL tracer injects these flags into C# compiler invocations:
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `/p:MvcBuildViews=true` | Precompile ASP.NET MVC views for security analysis |
|
||||
| `/p:UseSharedCompilation=false` | Disable shared compilation server (required for tracer inspection) |
|
||||
| `/p:EmitCompilerGeneratedFiles=true` | Write generated source files to disk for extraction |
|
||||
|
||||
> `/p:EmitCompilerGeneratedFiles=true` may cause issues with legacy projects or `.sqlproj` files.
|
||||
|
||||
### Runner Requirements (C#)
|
||||
- **.NET Core:** .NET SDK (for `dotnet`)
|
||||
- **.NET Framework (Windows):** Microsoft Build Tools + NuGet CLI
|
||||
- **.NET Framework (Linux/macOS):** Mono Runtime (`mono`, `msbuild`, `nuget`)
|
||||
- **`build-mode: none`:** Requires internet access or private NuGet feed
|
||||
|
||||
## Go
|
||||
|
||||
### Supported Build Modes
|
||||
`autobuild`, `manual` (no `none` mode)
|
||||
|
||||
**Default setup mode:** `autobuild`
|
||||
|
||||
### Autobuild
|
||||
|
||||
Autodetection sequence:
|
||||
1. Invoke `make`, `ninja`, `./build`, or `./build.sh` until one succeeds and `go list ./...` works
|
||||
2. If none succeed, look for `go.mod` (`go get`), `Gopkg.toml` (`dep ensure -v`), or `glide.yaml` (`glide install`)
|
||||
3. If no dependency managers found, rearrange directory for `GOPATH` and use `go get`
|
||||
4. Extract all Go code (similar to `go build ./...`)
|
||||
|
||||
**Default setup** automatically detects `go.mod` and installs compatible Go version.
|
||||
|
||||
### Extractor Options
|
||||
|
||||
| Environment Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS` | `false` | Include `_test.go` files in analysis |
|
||||
| `CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS` | `false` | Include `vendor/` directories |
|
||||
|
||||
## Java/Kotlin
|
||||
|
||||
### Supported Build Modes
|
||||
- **Java:** `none`, `autobuild`, `manual`
|
||||
- **Kotlin:** `autobuild`, `manual` (no `none` mode)
|
||||
|
||||
**Default setup mode:**
|
||||
- Java only: `none`
|
||||
- Kotlin or Java+Kotlin: `autobuild`
|
||||
|
||||
> If Kotlin code is added to a repo using `none` mode, disable and re-enable default setup to switch to `autobuild`.
|
||||
|
||||
### No Build (`none`) — Java Only
|
||||
- Runs Gradle or Maven for dependency information (not actual build)
|
||||
- Queries each root build file; prefers newer dependency versions on clash
|
||||
- Uses private Maven registries if configured
|
||||
|
||||
**Accuracy considerations:**
|
||||
- Build scripts that can't be queried for dependencies may cause inaccurate guesses
|
||||
- Code generated during normal build process will be missed
|
||||
- Multiple versions of same dependency (CodeQL picks newer)
|
||||
- Multiple JDK versions — CodeQL uses highest found; lower-version files may be partially analyzed
|
||||
- Colliding class names cause missing method call targets
|
||||
|
||||
### Autobuild
|
||||
|
||||
**Autodetection sequence:**
|
||||
1. Search root directory for Gradle, Maven, Ant build files
|
||||
2. Run first found (Gradle preferred over Maven)
|
||||
3. Otherwise, search for build scripts
|
||||
|
||||
**Build systems:** Gradle, Maven, Ant
|
||||
|
||||
### Runner Requirements (Java)
|
||||
- JDK (appropriate version for the project)
|
||||
- Gradle and/or Maven
|
||||
- Internet access or private artifact repository (for `none` mode)
|
||||
|
||||
## Rust
|
||||
|
||||
### Supported Build Modes
|
||||
`none`, `autobuild`, `manual`
|
||||
|
||||
**Default setup mode:** `none`
|
||||
|
||||
## Swift
|
||||
|
||||
### Supported Build Modes
|
||||
`autobuild`, `manual` (no `none` mode)
|
||||
|
||||
**Default setup mode:** `autobuild`
|
||||
|
||||
**Runner requirement:** macOS runners only. Not supported on Actions Runner Controller (ARC) — Linux only.
|
||||
|
||||
> macOS runners are more expensive; consider scanning only the build step to optimize cost.
|
||||
|
||||
## Multi-Language Matrix Examples
|
||||
|
||||
### Mixed Build Modes
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: c-cpp
|
||||
build-mode: manual
|
||||
- language: csharp
|
||||
build-mode: autobuild
|
||||
- language: java-kotlin
|
||||
build-mode: none
|
||||
```
|
||||
|
||||
### Conditional Manual Build Steps
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Initialize CodeQL
|
||||
uses: github/codeql-action/init@v4
|
||||
with:
|
||||
languages: ${{ matrix.language }}
|
||||
build-mode: ${{ matrix.build-mode }}
|
||||
|
||||
- if: matrix.build-mode == 'manual'
|
||||
name: Build C/C++ code
|
||||
run: |
|
||||
make bootstrap
|
||||
make release
|
||||
|
||||
- name: Perform CodeQL Analysis
|
||||
uses: github/codeql-action/analyze@v4
|
||||
with:
|
||||
category: "/language:${{ matrix.language }}"
|
||||
```
|
||||
|
||||
### OS-Specific Runners
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: javascript-typescript
|
||||
build-mode: none
|
||||
runner: ubuntu-latest
|
||||
- language: swift
|
||||
build-mode: autobuild
|
||||
runner: macos-latest
|
||||
- language: csharp
|
||||
build-mode: autobuild
|
||||
runner: windows-latest
|
||||
|
||||
jobs:
|
||||
analyze:
|
||||
runs-on: ${{ matrix.runner }}
|
||||
```
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
### Recommended Specifications (Self-Hosted Runners)
|
||||
|
||||
| Codebase Size | Lines of Code | RAM | CPU Cores | Disk |
|
||||
|---|---|---|---|---|
|
||||
| Small | < 100K | 8 GB+ | 2 | SSD, ≥14 GB |
|
||||
| Medium | 100K – 1M | 16 GB+ | 4–8 | SSD, ≥14 GB |
|
||||
| Large | > 1M | 64 GB+ | 8 | SSD, ≥14 GB |
|
||||
|
||||
### Performance Tips
|
||||
- Use SSD storage for all codebase sizes
|
||||
- Ensure enough disk space for checkout + build + CodeQL data
|
||||
- Use `--threads=0` to use all available CPU cores
|
||||
- Enable dependency caching to reduce analysis time
|
||||
- Consider `none` build mode where accuracy is acceptable — significantly faster than `autobuild`
|
||||
|
||||
## Dependency Caching
|
||||
|
||||
### Advanced Setup Workflows
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
languages: java-kotlin
|
||||
dependency-caching: true
|
||||
```
|
||||
|
||||
| Value | Behavior |
|
||||
|---|---|
|
||||
| `false` / `none` / `off` | Disabled (default for advanced setup) |
|
||||
| `restore` | Restore existing caches only |
|
||||
| `store` | Store new caches only |
|
||||
| `true` / `full` / `on` | Restore and store caches |
|
||||
|
||||
Default setup on GitHub-hosted runners has caching enabled automatically.
|
||||
265
skills/codeql/references/sarif-output.md
Normal file
265
skills/codeql/references/sarif-output.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# CodeQL SARIF Output Reference
|
||||
|
||||
Detailed reference for the SARIF v2.1.0 output produced by CodeQL analysis. Use this when interpreting or processing CodeQL scan results.
|
||||
|
||||
## About SARIF
|
||||
|
||||
SARIF (Static Analysis Results Interchange Format) is a standardized JSON format for representing static analysis tool output. CodeQL produces SARIF v2.1.0 (specification: `sarifv2.1.0`).
|
||||
|
||||
- Specification: [OASIS SARIF v2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)
|
||||
- Schema: [sarif-schema-2.1.0.json](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json)
|
||||
- Format type: `sarifv2.1.0` (passed to `--format` flag)
|
||||
|
||||
## Top-Level Structure
|
||||
|
||||
### `sarifLog` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `$schema` | ✅ | Link to the SARIF schema |
|
||||
| `version` | ✅ | SARIF specification version (`"2.1.0"`) |
|
||||
| `runs` | ✅ | Array containing a single `run` object per language |
|
||||
|
||||
### `run` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `tool` | ✅ | Tool information (`toolComponent`) |
|
||||
| `artifacts` | ✅ | Array of artifact objects for every file referenced in a result |
|
||||
| `results` | ✅ | Array of `result` objects |
|
||||
| `newLineSequences` | ✅ | Newline character sequences |
|
||||
| `columnKind` | ✅ | Column counting method |
|
||||
| `properties` | ✅ | Contains `semmle.formatSpecifier` identifying the format |
|
||||
|
||||
## Tool Information
|
||||
|
||||
### `tool` Object
|
||||
|
||||
Contains a single `driver` property.
|
||||
|
||||
### `toolComponent` Object (Driver)
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `name` | ✅ | `"CodeQL command-line toolchain"` |
|
||||
| `organization` | ✅ | `"GitHub"` |
|
||||
| `version` | ✅ | CodeQL release version (e.g., `"2.19.0"`) |
|
||||
| `rules` | ✅ | Array of `reportingDescriptor` objects for available/run rules |
|
||||
|
||||
## Rules
|
||||
|
||||
### `reportingDescriptor` Object (Rule)
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `id` | ✅ | Rule identifier from `@id` query property (e.g., `cpp/unsafe-format-string`). Uses `@opaqueid` if defined. |
|
||||
| `name` | ✅ | Same as `@id` property from the query |
|
||||
| `shortDescription` | ✅ | From `@name` query property |
|
||||
| `fullDescription` | ✅ | From `@description` query property |
|
||||
| `defaultConfiguration` | ❌ | `reportingConfiguration` with `enabled` (true/false) and `level` based on `@severity`. Omitted if no `@severity` specified. |
|
||||
|
||||
### Severity Mapping
|
||||
|
||||
| CodeQL `@severity` | SARIF `level` |
|
||||
|---|---|
|
||||
| `error` | `error` |
|
||||
| `warning` | `warning` |
|
||||
| `recommendation` | `note` |
|
||||
|
||||
## Results
|
||||
|
||||
### `result` Object
|
||||
|
||||
By default, results are grouped by unique message format string and primary location. Two results at the same location with the same message appear as a single result. Disable grouping with `--ungroup-results`.
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `ruleId` | ✅ | Rule identifier (matches `reportingDescriptor.id`) |
|
||||
| `ruleIndex` | ✅ | Index into the `rules` array |
|
||||
| `message` | ✅ | Problem description. May contain SARIF "Message with placeholder" linking to `relatedLocations`. |
|
||||
| `locations` | ✅ | Array containing a single `location` object |
|
||||
| `partialFingerprints` | ✅ | Dictionary with at least `primaryLocationLineHash` for deduplication |
|
||||
| `codeFlows` | ❌ | Populated for `@kind path-problem` queries with one or more `codeFlow` objects |
|
||||
| `relatedLocations` | ❌ | Populated when message has placeholder options; each unique location included once |
|
||||
| `suppressions` | ❌ | If suppressed: single `suppression` object with `@kind: IN_SOURCE`. If not suppressed but other results are: empty array. Otherwise: not set. |
|
||||
|
||||
### Fingerprints
|
||||
|
||||
`partialFingerprints` contains:
|
||||
- `primaryLocationLineHash` — fingerprint based on the context of the primary location
|
||||
|
||||
Used by GitHub to track alerts across commits and avoid duplicate notifications.
|
||||
|
||||
## Locations
|
||||
|
||||
### `location` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `physicalLocation` | ✅ | Physical file location |
|
||||
| `id` | ❌ | Present in `relatedLocations` array |
|
||||
| `message` | ❌ | Present in `relatedLocations` and `threadFlowLocation.location` |
|
||||
|
||||
### `physicalLocation` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `artifactLocation` | ✅ | File reference |
|
||||
| `region` | ❌ | Present for text file locations |
|
||||
| `contextRegion` | ❌ | Present when location has an associated snippet |
|
||||
|
||||
### `region` Object
|
||||
|
||||
Two types of regions may be produced:
|
||||
|
||||
**Line/Column Offset Regions:**
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `startLine` | ✅ | Starting line number |
|
||||
| `startColumn` | ❌ | Omitted if equal to default value of 1 |
|
||||
| `endLine` | ❌ | Omitted if identical to `startLine` |
|
||||
| `endColumn` | ✅ | Ending column number |
|
||||
| `snippet` | ❌ | Source code snippet |
|
||||
|
||||
**Character Offset Regions:**
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `charOffset` | ✅ | Character offset from start of file |
|
||||
| `charLength` | ✅ | Length in characters |
|
||||
| `snippet` | ❌ | Source code snippet |
|
||||
|
||||
> Consumers should handle both region types robustly.
|
||||
|
||||
## Artifacts
|
||||
|
||||
### `artifact` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `location` | ✅ | `artifactLocation` object |
|
||||
| `index` | ✅ | Index of the artifact |
|
||||
| `contents` | ❌ | Populated with `artifactContent` when using `--sarif-add-file-contents` |
|
||||
|
||||
### `artifactLocation` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `uri` | ✅ | File path (relative or absolute) |
|
||||
| `index` | ✅ | Index reference |
|
||||
| `uriBaseId` | ❌ | Set when file is relative to a known abstract location (e.g., source root) |
|
||||
|
||||
## Code Flows (Path Problems)
|
||||
|
||||
For queries of `@kind path-problem`, results include code flow information showing the data flow path.
|
||||
|
||||
### `codeFlow` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `threadFlows` | ✅ | Array of `threadFlow` objects |
|
||||
|
||||
### `threadFlow` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `locations` | ✅ | Array of `threadFlowLocation` objects |
|
||||
|
||||
### `threadFlowLocation` Object
|
||||
|
||||
| Property | Always Generated | Description |
|
||||
|---|:---:|---|
|
||||
| `location` | ✅ | A `location` object for this step in the flow |
|
||||
|
||||
## Automation Details
|
||||
|
||||
The `category` value from `github/codeql-action/analyze` appears as `<run>.automationDetails.id` in the SARIF output.
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"automationDetails": {
|
||||
"id": "/language:javascript-typescript"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key CLI Flags for SARIF
|
||||
|
||||
| Flag | Effect |
|
||||
|---|---|
|
||||
| `--format=sarif-latest` | Produce SARIF v2.1.0 output |
|
||||
| `--sarif-category=<cat>` | Set `automationDetails.id` for result categorization |
|
||||
| `--sarif-add-file-contents` | Include source file content in `artifact.contents` |
|
||||
| `--ungroup-results` | Report every occurrence separately (no deduplication by location + message) |
|
||||
| `--output=<file>` | Write SARIF to specified file |
|
||||
|
||||
## Third-Party SARIF Support
|
||||
|
||||
When uploading SARIF from non-CodeQL tools, ensure these properties are populated for best results on GitHub.
|
||||
|
||||
### Recommended `reportingDescriptor` Properties
|
||||
|
||||
| Property | Required | Description |
|
||||
|---|:---:|---|
|
||||
| `id` | ✅ | Unique rule identifier |
|
||||
| `name` | ❌ | Rule name (max 255 chars) |
|
||||
| `shortDescription.text` | ✅ | Concise description (max 1024 chars) |
|
||||
| `fullDescription.text` | ✅ | Full description (max 1024 chars) |
|
||||
| `defaultConfiguration.level` | ❌ | Default severity: `note`, `warning`, `error` |
|
||||
| `help.text` | ✅ | Documentation in text format |
|
||||
| `help.markdown` | ❌ | Documentation in Markdown (displayed if available) |
|
||||
| `properties.tags[]` | ❌ | Tags for filtering (e.g., `security`) |
|
||||
| `properties.precision` | ❌ | `very-high`, `high`, `medium`, `low` — affects display ordering |
|
||||
| `properties.problem.severity` | ❌ | Non-security severity: `error`, `warning`, `recommendation` |
|
||||
| `properties.security-severity` | ❌ | Score 0.0–10.0 for security queries. Maps to: >9.0=critical, 7.0–8.9=high, 4.0–6.9=medium, 0.1–3.9=low |
|
||||
|
||||
### Source File Location Requirements
|
||||
|
||||
- Use relative paths (relative to repository root) when possible
|
||||
- Absolute URIs are converted to relative using the source root
|
||||
- Source root can be set via:
|
||||
- `checkout_path` input to `github/codeql-action/analyze`
|
||||
- `checkout_uri` parameter to SARIF upload API
|
||||
- `invocations[0].workingDirectory.uri` in the SARIF file
|
||||
- Consistent file paths are required across runs for fingerprint stability
|
||||
- Symlinked files must use resolved (non-symlink) URIs
|
||||
|
||||
### Fingerprint Requirements
|
||||
|
||||
- `partialFingerprints` with `primaryLocationLineHash` prevents duplicate alerts across commits
|
||||
- CodeQL SARIF automatically includes fingerprints
|
||||
- Third-party SARIF: the `upload-sarif` action computes fingerprints if missing
|
||||
- API uploads without fingerprints may produce duplicate alerts
|
||||
|
||||
## Upload Limits
|
||||
|
||||
### File Size
|
||||
- Maximum: **10 MB** (gzip-compressed)
|
||||
- If too large: reduce query scope, remove `--sarif-add-file-contents`, or split into multiple uploads
|
||||
|
||||
### Object Count Limits
|
||||
|
||||
| Object | Maximum |
|
||||
|---|---|
|
||||
| Runs per file | 20 |
|
||||
| Results per run | 25,000 |
|
||||
| Rules per run | 25,000 |
|
||||
| Tool extensions per run | 100 |
|
||||
| Thread flow locations per result | 10,000 |
|
||||
| Locations per result | 1,000 |
|
||||
| Tags per rule | 20 |
|
||||
|
||||
Files exceeding these limits are rejected. Split analysis across multiple SARIF uploads with different `--sarif-category` values.
|
||||
|
||||
### Validation
|
||||
|
||||
Validate SARIF files before upload using the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/).
|
||||
|
||||
## Backwards Compatibility
|
||||
|
||||
- Fields marked "always generated" will never be removed in future versions
|
||||
- Fields not always generated may change circumstances under which they appear
|
||||
- New fields may be added without breaking changes
|
||||
- Consumers should be robust to both presence and absence of optional fields
|
||||
259
skills/codeql/references/troubleshooting.md
Normal file
259
skills/codeql/references/troubleshooting.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# CodeQL Troubleshooting Reference
|
||||
|
||||
Comprehensive guide for diagnosing and resolving CodeQL analysis errors, SARIF upload issues, and common configuration problems.
|
||||
|
||||
## Build and Analysis Errors
|
||||
|
||||
### "No source code was seen during the build"
|
||||
|
||||
**Cause:** CodeQL extractor did not find any source files during database creation.
|
||||
|
||||
**Solutions:**
|
||||
- Verify the `--source-root` points to the correct directory
|
||||
- For compiled languages, ensure the build command actually compiles source files
|
||||
- Check that `autobuild` is detecting the correct build system
|
||||
- Switch from `autobuild` to `manual` build mode with explicit build commands
|
||||
- Verify the language specified matches the actual source code language
|
||||
|
||||
### Automatic Build Failed
|
||||
|
||||
**Cause:** `autobuild` could not detect or run the project's build system.
|
||||
|
||||
**Solutions:**
|
||||
- Switch to `build-mode: manual` and provide explicit build commands
|
||||
- Ensure all build dependencies are installed on the runner
|
||||
- For C/C++: verify `gcc`, `make`, `cmake`, or `msbuild` are available
|
||||
- For C#: verify `.NET SDK` or `MSBuild` is installed
|
||||
- For Java: verify `gradle` or `maven` is installed
|
||||
- Check the autobuild logs for the specific detection step that failed
|
||||
|
||||
### C# Compiler Unexpectedly Failing
|
||||
|
||||
**Cause:** The CodeQL tracer injects compiler flags that may conflict with project configuration.
|
||||
|
||||
**Details:** CodeQL injects `/p:EmitCompilerGeneratedFiles=true` which can cause issues with:
|
||||
- Legacy .NET Framework projects
|
||||
- Projects using `.sqlproj` files
|
||||
|
||||
**Solutions:**
|
||||
- Add `<EmitCompilerGeneratedFiles>false</EmitCompilerGeneratedFiles>` to problematic project files
|
||||
- Use `build-mode: none` for C# if build accuracy is acceptable
|
||||
- Exclude problematic projects from the CodeQL analysis
|
||||
|
||||
### Analysis Takes Too Long
|
||||
|
||||
**Cause:** Large codebase, complex queries, or insufficient resources.
|
||||
|
||||
**Solutions:**
|
||||
- Use `build-mode: none` where accuracy is acceptable (significantly faster)
|
||||
- Enable dependency caching: `dependency-caching: true`
|
||||
- Set `timeout-minutes` on the job to prevent hung workflows
|
||||
- Use `--threads=0` (CLI) to use all available CPU cores
|
||||
- Reduce query scope: use `default` suite instead of `security-and-quality`
|
||||
- For self-hosted runners, ensure hardware meets recommendations:
|
||||
- Small (<100K LOC): 8 GB RAM, 2 cores
|
||||
- Medium (100K–1M LOC): 16 GB RAM, 4–8 cores
|
||||
- Large (>1M LOC): 64 GB RAM, 8 cores
|
||||
- Configure larger GitHub-hosted runners if available
|
||||
- Use `paths` in config file to limit analyzed directories
|
||||
|
||||
### CodeQL Scanned Fewer Lines Than Expected
|
||||
|
||||
**Cause:** Build command didn't compile all source files, or `build-mode: none` missed generated code.
|
||||
|
||||
**Solutions:**
|
||||
- Switch from `none` to `autobuild` or `manual` build mode
|
||||
- Ensure the build command compiles the full codebase (not just a subset)
|
||||
- Check the code scanning logs for extraction metrics:
|
||||
- Lines of code in codebase (baseline)
|
||||
- Lines of code extracted
|
||||
- Lines excluding auto-generated files
|
||||
- Verify language detection includes all expected languages
|
||||
|
||||
### Kotlin Detected in No-Build Mode
|
||||
|
||||
**Cause:** Repository uses `build-mode: none` (Java only) but also contains Kotlin code.
|
||||
|
||||
**Solutions:**
|
||||
- Disable default setup and re-enable it (switches to `autobuild`)
|
||||
- Or switch to advanced setup with `build-mode: autobuild` for `java-kotlin`
|
||||
- Kotlin requires a build to be analyzed; `none` mode only works for Java
|
||||
|
||||
## Permission and Access Errors
|
||||
|
||||
### Error: 403 "Resource not accessible by integration"
|
||||
|
||||
**Cause:** `GITHUB_TOKEN` lacks required permissions.
|
||||
|
||||
**Solutions:**
|
||||
- Add explicit permissions to the workflow:
|
||||
```yaml
|
||||
permissions:
|
||||
security-events: write
|
||||
contents: read
|
||||
actions: read
|
||||
```
|
||||
- For Dependabot PRs, use `pull_request_target` instead of `pull_request`
|
||||
- Verify the repository has GitHub Code Security enabled (for private repos)
|
||||
|
||||
### Cannot Enable CodeQL in a Private Repository
|
||||
|
||||
**Cause:** GitHub Code Security is not enabled.
|
||||
|
||||
**Solution:** Enable GitHub Code Security in repository Settings → Advanced Security.
|
||||
|
||||
### Error: "GitHub Code Security or Advanced Security must be enabled"
|
||||
|
||||
**Cause:** Attempting to use code scanning on a private repo without the required license.
|
||||
|
||||
**Solutions:**
|
||||
- Enable GitHub Code Security for the repository
|
||||
- Contact organization admin to enable Advanced Security
|
||||
|
||||
## Configuration Errors
|
||||
|
||||
### Two CodeQL Workflows Running
|
||||
|
||||
**Cause:** Both default setup and a pre-existing `codeql.yml` workflow are active.
|
||||
|
||||
**Solutions:**
|
||||
- Disable default setup if using advanced setup, or
|
||||
- Delete the old workflow file if using default setup
|
||||
- Check repository Settings → Advanced Security for active configurations
|
||||
|
||||
### Some Languages Not Analyzed
|
||||
|
||||
**Cause:** Matrix configuration doesn't include all languages.
|
||||
|
||||
**Solutions:**
|
||||
- Add missing languages to the `matrix.include` array
|
||||
- Verify language identifiers are correct (e.g., `javascript-typescript` not just `javascript`)
|
||||
- Check that each language has an appropriate `build-mode`
|
||||
|
||||
### Unclear What Triggered a Workflow Run
|
||||
|
||||
**Solutions:**
|
||||
- Check the tool status page in repository Settings → Advanced Security
|
||||
- Review workflow run logs for trigger event details
|
||||
- Look at the `on:` triggers in the workflow file
|
||||
|
||||
### Error: "is not a .ql file, .qls file, a directory, or a query pack specification"
|
||||
|
||||
**Cause:** Invalid query or pack reference in the workflow.
|
||||
|
||||
**Solutions:**
|
||||
- Verify query pack names and versions exist
|
||||
- Use correct format: `owner/pack-name@version` or `owner/pack-name:path/to/query.ql`
|
||||
- Run `codeql resolve packs` to verify available packs
|
||||
|
||||
## Resource Errors
|
||||
|
||||
### "Out of disk" or "Out of memory"
|
||||
|
||||
**Cause:** Runner lacks sufficient resources for the analysis.
|
||||
|
||||
**Solutions:**
|
||||
- Use larger GitHub-hosted runners (if available)
|
||||
- For self-hosted runners, increase RAM and disk (SSD with ≥14 GB)
|
||||
- Reduce analysis scope with `paths` configuration
|
||||
- Analyze fewer languages per job
|
||||
- Use `build-mode: none` to reduce resource usage
|
||||
|
||||
### Extraction Errors in Database
|
||||
|
||||
**Cause:** Some source files couldn't be processed by the CodeQL extractor.
|
||||
|
||||
**Solutions:**
|
||||
- Check extraction metrics in workflow logs for error counts
|
||||
- Enable debug logging for detailed extraction diagnostics
|
||||
- Verify source files are syntactically valid
|
||||
- Ensure all build dependencies are available
|
||||
|
||||
## Logging and Debugging
|
||||
|
||||
### Enable Debug Logging
|
||||
|
||||
To get more detailed diagnostic information:
|
||||
|
||||
**GitHub Actions:**
|
||||
1. Re-run the workflow with debug logging enabled
|
||||
2. In the workflow run, click "Re-run jobs" → "Enable debug logging"
|
||||
|
||||
**CodeQL CLI:**
|
||||
```bash
|
||||
codeql database create my-db \
|
||||
--language=javascript-typescript \
|
||||
--verbosity=progress++ \
|
||||
--logdir=codeql-logs
|
||||
```
|
||||
|
||||
**Verbosity levels:** `errors`, `warnings`, `progress`, `progress+`, `progress++`, `progress+++`
|
||||
|
||||
### Code Scanning Log Metrics
|
||||
|
||||
Workflow logs include summary metrics:
|
||||
- **Lines of code in codebase** — baseline before extraction
|
||||
- **Lines of code in CodeQL database** — extracted including external libraries
|
||||
- **Lines excluding auto-generated files** — net analyzed code
|
||||
- **Extraction success/error/warning counts** — per-file extraction results
|
||||
|
||||
### Private Registry Diagnostics
|
||||
|
||||
For `build-mode: none` with private package registries:
|
||||
- Check the "Setup proxy for registries" step in workflow logs
|
||||
- Look for `Credentials loaded for the following registries:` message
|
||||
- Verify organization-level private registry configuration
|
||||
- Ensure internet access is available for dependency resolution
|
||||
|
||||
## SARIF Upload Errors
|
||||
|
||||
### SARIF File Too Large
|
||||
|
||||
**Limit:** 10 MB maximum (gzip-compressed).
|
||||
|
||||
**Solutions:**
|
||||
- Focus on the most important query suites (use `default` instead of `security-and-quality`)
|
||||
- Reduce the number of queries via configuration
|
||||
- Split analysis into multiple jobs with separate SARIF uploads
|
||||
- Remove `--sarif-add-file-contents` flag
|
||||
|
||||
### SARIF Results Exceed Limits
|
||||
|
||||
GitHub enforces limits on SARIF data objects:
|
||||
|
||||
| Object | Maximum |
|
||||
|---|---|
|
||||
| Runs per file | 20 |
|
||||
| Results per run | 25,000 |
|
||||
| Rules per run | 25,000 |
|
||||
| Tool extensions per run | 100 |
|
||||
| Thread flow locations per result | 10,000 |
|
||||
| Location per result | 1,000 |
|
||||
| Tags per rule | 20 |
|
||||
|
||||
**Solutions:**
|
||||
- Reduce query scope to focus on high-impact rules
|
||||
- Split analysis across multiple SARIF uploads with different `--sarif-category`
|
||||
- Disable noisy queries that produce many results
|
||||
|
||||
### SARIF File Invalid
|
||||
|
||||
**Solutions:**
|
||||
- Validate against the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/)
|
||||
- Ensure `version` is `"2.1.0"` and `$schema` points to the correct schema
|
||||
- Verify required properties (`runs`, `tool.driver`, `results`) are present
|
||||
|
||||
### Upload Rejected: Default Setup Enabled
|
||||
|
||||
**Cause:** Cannot upload CodeQL-generated SARIF when default setup is active.
|
||||
|
||||
**Solutions:**
|
||||
- Disable default setup before uploading via CLI/API
|
||||
- Or switch to using default setup exclusively (no manual uploads)
|
||||
|
||||
### Missing Authentication Token
|
||||
|
||||
**Solutions:**
|
||||
- Set `GITHUB_TOKEN` environment variable with `security-events: write` scope
|
||||
- Or use `--github-auth-stdin` to pipe the token
|
||||
- For GitHub Actions: the token is automatically available via `${{ secrets.GITHUB_TOKEN }}`
|
||||
398
skills/codeql/references/workflow-configuration.md
Normal file
398
skills/codeql/references/workflow-configuration.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# CodeQL Workflow Configuration Reference
|
||||
|
||||
Detailed reference for configuring CodeQL analysis via GitHub Actions workflows. This supplements the procedural guidance in SKILL.md.
|
||||
|
||||
## Trigger Configuration
|
||||
|
||||
### Push Trigger
|
||||
|
||||
Scan on every push to specified branches:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [main, protected]
|
||||
```
|
||||
|
||||
- Code scanning is triggered on every push to the listed branches
|
||||
- The workflow must exist on the target branch for scanning to activate
|
||||
- Results appear in the repository Security tab
|
||||
- When push results map to an open PR, alerts also appear as PR annotations
|
||||
|
||||
### Pull Request Trigger
|
||||
|
||||
Scan merge commits of pull requests:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
```
|
||||
|
||||
- Scans the PR's merge commit (not the head commit) for more accurate results
|
||||
- For private fork PRs, enable "Run workflows from fork pull requests" in repository settings
|
||||
- Results appear as PR check annotations
|
||||
|
||||
### Schedule Trigger
|
||||
|
||||
Periodic scans on the default branch:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
schedule:
|
||||
- cron: '20 14 * * 1' # Monday 14:20 UTC
|
||||
```
|
||||
|
||||
- Only triggers if the workflow file exists on the default branch
|
||||
- Catches newly discovered vulnerabilities even without active development
|
||||
|
||||
### Merge Group Trigger
|
||||
|
||||
Required when using merge queues:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
merge_group:
|
||||
```
|
||||
|
||||
### Path Filtering
|
||||
|
||||
Control when the workflow runs based on changed files:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
pull_request:
|
||||
paths-ignore:
|
||||
- '**/*.md'
|
||||
- '**/*.txt'
|
||||
- 'docs/**'
|
||||
```
|
||||
|
||||
Or use `paths` to only trigger on specific directories:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'src/**'
|
||||
- 'apps/**'
|
||||
```
|
||||
|
||||
> **Important:** `paths-ignore` and `paths` control whether the workflow runs. When the workflow does run, it analyzes ALL changed files in the PR (including those matched by `paths-ignore`), unless files are excluded via the CodeQL configuration file's `paths-ignore`.
|
||||
|
||||
### Workflow Dispatch (Manual Trigger)
|
||||
|
||||
```yaml
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
language:
|
||||
description: 'Language to analyze'
|
||||
required: true
|
||||
default: 'javascript-typescript'
|
||||
```
|
||||
|
||||
## Runner and OS Configuration
|
||||
|
||||
### GitHub-Hosted Runners
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
analyze:
|
||||
runs-on: ubuntu-latest # Also: windows-latest, macos-latest
|
||||
```
|
||||
|
||||
- `ubuntu-latest` — most common, recommended for most languages
|
||||
- `macos-latest` — required for Swift analysis
|
||||
- `windows-latest` — required for some C/C++ and C# projects using MSBuild
|
||||
|
||||
### Self-Hosted Runners
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
analyze:
|
||||
runs-on: [self-hosted, ubuntu-latest]
|
||||
```
|
||||
|
||||
Requirements for self-hosted runners:
|
||||
- Git must be in the PATH
|
||||
- SSD with ≥14 GB disk space recommended
|
||||
- See hardware requirements table in SKILL.md
|
||||
|
||||
### Timeout Configuration
|
||||
|
||||
Prevent hung workflows:
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
analyze:
|
||||
timeout-minutes: 120
|
||||
```
|
||||
|
||||
## Language and Build Mode Matrix
|
||||
|
||||
### Standard Matrix Pattern
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: javascript-typescript
|
||||
build-mode: none
|
||||
- language: python
|
||||
build-mode: none
|
||||
- language: java-kotlin
|
||||
build-mode: none
|
||||
- language: c-cpp
|
||||
build-mode: autobuild
|
||||
```
|
||||
|
||||
### Multi-Language Repository with Mixed Build Modes
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: c-cpp
|
||||
build-mode: manual
|
||||
- language: csharp
|
||||
build-mode: autobuild
|
||||
- language: java-kotlin
|
||||
build-mode: none
|
||||
```
|
||||
|
||||
### Build Mode Summary
|
||||
|
||||
| Language | `none` | `autobuild` | `manual` | Default Setup Mode |
|
||||
|---|:---:|:---:|:---:|---|
|
||||
| C/C++ | ✅ | ✅ | ✅ | `none` |
|
||||
| C# | ✅ | ✅ | ✅ | `none` |
|
||||
| Go | ❌ | ✅ | ✅ | `autobuild` |
|
||||
| Java | ✅ | ✅ | ✅ | `none` |
|
||||
| Kotlin | ❌ | ✅ | ✅ | `autobuild` |
|
||||
| Python | ✅ | ❌ | ❌ | `none` |
|
||||
| Ruby | ✅ | ❌ | ❌ | `none` |
|
||||
| Rust | ✅ | ✅ | ✅ | `none` |
|
||||
| Swift | ❌ | ✅ | ✅ | `autobuild` |
|
||||
| JavaScript/TypeScript | ✅ | ❌ | ❌ | `none` |
|
||||
| GitHub Actions | ✅ | ❌ | ❌ | `none` |
|
||||
|
||||
## CodeQL Database Location
|
||||
|
||||
Override the default database location:
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
db-location: '${{ github.runner_temp }}/my_location'
|
||||
```
|
||||
|
||||
- Default: `${{ github.runner_temp }}/codeql_databases`
|
||||
- Path must be writable and either not exist or be an empty directory
|
||||
- On self-hosted runners, ensure cleanup between runs
|
||||
|
||||
## Query Suites and Packs
|
||||
|
||||
### Built-In Query Suites
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
queries: security-extended
|
||||
```
|
||||
|
||||
Options:
|
||||
- (default) — standard security queries
|
||||
- `security-extended` — additional security queries with slightly higher false-positive rate
|
||||
- `security-and-quality` — security plus code quality queries
|
||||
|
||||
### Custom Query Packs
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
packs: |
|
||||
codeql/javascript-queries:AlertSuppression.ql
|
||||
codeql/javascript-queries:~1.0.0
|
||||
my-org/my-custom-pack@1.2.3
|
||||
```
|
||||
|
||||
### Model Packs
|
||||
|
||||
Extend CodeQL coverage for custom libraries/frameworks:
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
packs: my-org/my-model-pack
|
||||
```
|
||||
|
||||
## Analysis Category
|
||||
|
||||
Distinguish between multiple analyses for the same commit:
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/analyze@v4
|
||||
with:
|
||||
category: "/language:${{ matrix.language }}"
|
||||
```
|
||||
|
||||
### Monorepo Category Patterns
|
||||
|
||||
```yaml
|
||||
# Per language (default auto-generated pattern)
|
||||
category: "/language:${{ matrix.language }}"
|
||||
|
||||
# Per component
|
||||
category: "/language:${{ matrix.language }}/component:frontend"
|
||||
|
||||
# Per app in monorepo
|
||||
category: "/language:javascript-typescript/app:blog"
|
||||
```
|
||||
|
||||
The `category` value appears as `<run>.automationDetails.id` in the SARIF output.
|
||||
|
||||
## CodeQL Configuration File
|
||||
|
||||
Create `.github/codeql/codeql-config.yml` for advanced path and query configuration:
|
||||
|
||||
```yaml
|
||||
name: "CodeQL Configuration"
|
||||
|
||||
# Directories to scan
|
||||
paths:
|
||||
- apps/
|
||||
- services/
|
||||
- packages/
|
||||
|
||||
# Directories to exclude
|
||||
paths-ignore:
|
||||
- node_modules/
|
||||
- '**/test/**'
|
||||
- '**/fixtures/**'
|
||||
- '**/*.test.ts'
|
||||
|
||||
# Additional queries
|
||||
queries:
|
||||
- uses: security-extended
|
||||
- uses: security-and-quality
|
||||
|
||||
# Custom query packs
|
||||
packs:
|
||||
javascript-typescript:
|
||||
- codeql/javascript-queries
|
||||
python:
|
||||
- codeql/python-queries
|
||||
```
|
||||
|
||||
Reference in the workflow:
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
config-file: .github/codeql/codeql-config.yml
|
||||
```
|
||||
|
||||
## Dependency Caching
|
||||
|
||||
Enable caching to speed up dependency resolution:
|
||||
|
||||
```yaml
|
||||
- uses: github/codeql-action/init@v4
|
||||
with:
|
||||
dependency-caching: true
|
||||
```
|
||||
|
||||
Values:
|
||||
- `false` / `none` / `off` — disabled (default for advanced setup)
|
||||
- `restore` — only restore existing caches
|
||||
- `store` — only store new caches
|
||||
- `true` / `full` / `on` — restore and store caches
|
||||
|
||||
> Default setup on GitHub-hosted runners has caching enabled automatically.
|
||||
|
||||
## Alert Severity and Merge Protection
|
||||
|
||||
Use repository rulesets to block PRs based on code scanning alerts:
|
||||
|
||||
- A required tool finds an alert matching the defined severity threshold
|
||||
- A required tool's analysis is still in progress
|
||||
- A required tool is not configured for the repository
|
||||
|
||||
Configure via repository Settings → Rules → Rulesets → Code scanning.
|
||||
|
||||
## Concurrency Control
|
||||
|
||||
Prevent duplicate workflow runs:
|
||||
|
||||
```yaml
|
||||
concurrency:
|
||||
group: codeql-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
```
|
||||
|
||||
## Complete Workflow Example
|
||||
|
||||
```yaml
|
||||
name: "CodeQL Analysis"
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
schedule:
|
||||
- cron: '30 6 * * 1'
|
||||
|
||||
permissions:
|
||||
security-events: write
|
||||
contents: read
|
||||
actions: read
|
||||
|
||||
concurrency:
|
||||
group: codeql-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
analyze:
|
||||
name: Analyze (${{ matrix.language }})
|
||||
runs-on: ${{ matrix.language == 'swift' && 'macos-latest' || 'ubuntu-latest' }}
|
||||
timeout-minutes: 120
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: javascript-typescript
|
||||
build-mode: none
|
||||
- language: python
|
||||
build-mode: none
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Initialize CodeQL
|
||||
uses: github/codeql-action/init@v4
|
||||
with:
|
||||
languages: ${{ matrix.language }}
|
||||
build-mode: ${{ matrix.build-mode }}
|
||||
queries: security-extended
|
||||
dependency-caching: true
|
||||
|
||||
- if: matrix.build-mode == 'manual'
|
||||
name: Manual Build
|
||||
run: |
|
||||
echo 'Replace with actual build commands'
|
||||
exit 1
|
||||
|
||||
- name: Perform CodeQL Analysis
|
||||
uses: github/codeql-action/analyze@v4
|
||||
with:
|
||||
category: "/language:${{ matrix.language }}"
|
||||
```
|
||||
422
skills/dependabot/SKILL.md
Normal file
422
skills/dependabot/SKILL.md
Normal file
@@ -0,0 +1,422 @@
|
||||
---
|
||||
name: dependabot
|
||||
description: >-
|
||||
Comprehensive guide for configuring and managing GitHub Dependabot. Use this skill when
|
||||
users ask about creating or optimizing dependabot.yml files, managing Dependabot pull requests,
|
||||
configuring dependency update strategies, setting up grouped updates, monorepo patterns,
|
||||
multi-ecosystem groups, security update configuration, auto-triage rules, or any GitHub
|
||||
Advanced Security (GHAS) supply chain security topic related to Dependabot.
|
||||
---
|
||||
|
||||
# Dependabot Configuration & Management
|
||||
|
||||
## Overview
|
||||
|
||||
Dependabot is GitHub's built-in dependency management tool with three core capabilities:
|
||||
|
||||
1. **Dependabot Alerts** — Notify when dependencies have known vulnerabilities (CVEs)
|
||||
2. **Dependabot Security Updates** — Auto-create PRs to fix vulnerable dependencies
|
||||
3. **Dependabot Version Updates** — Auto-create PRs to keep dependencies current
|
||||
|
||||
All configuration lives in a **single file**: `.github/dependabot.yml` on the default branch. GitHub does **not** support multiple `dependabot.yml` files per repository.
|
||||
|
||||
## Configuration Workflow
|
||||
|
||||
Follow this process when creating or optimizing a `dependabot.yml`:
|
||||
|
||||
### Step 1: Detect All Ecosystems
|
||||
|
||||
Scan the repository for dependency manifests. Look for:
|
||||
|
||||
| Ecosystem | YAML Value | Manifest Files |
|
||||
|---|---|---|
|
||||
| npm/pnpm/yarn | `npm` | `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` |
|
||||
| pip/pipenv/poetry/uv | `pip` | `requirements.txt`, `Pipfile`, `pyproject.toml`, `setup.py` |
|
||||
| Docker | `docker` | `Dockerfile` |
|
||||
| Docker Compose | `docker-compose` | `docker-compose.yml` |
|
||||
| GitHub Actions | `github-actions` | `.github/workflows/*.yml` |
|
||||
| Go modules | `gomod` | `go.mod` |
|
||||
| Bundler (Ruby) | `bundler` | `Gemfile` |
|
||||
| Cargo (Rust) | `cargo` | `Cargo.toml` |
|
||||
| Composer (PHP) | `composer` | `composer.json` |
|
||||
| NuGet (.NET) | `nuget` | `*.csproj`, `packages.config` |
|
||||
| .NET SDK | `dotnet-sdk` | `global.json` |
|
||||
| Maven (Java) | `maven` | `pom.xml` |
|
||||
| Gradle (Java) | `gradle` | `build.gradle` |
|
||||
| Terraform | `terraform` | `*.tf` |
|
||||
| OpenTofu | `opentofu` | `*.tf` |
|
||||
| Helm | `helm` | `Chart.yaml` |
|
||||
| Hex (Elixir) | `mix` | `mix.exs` |
|
||||
| Swift | `swift` | `Package.swift` |
|
||||
| Pub (Dart) | `pub` | `pubspec.yaml` |
|
||||
| Bun | `bun` | `bun.lockb` |
|
||||
| Dev Containers | `devcontainers` | `devcontainer.json` |
|
||||
| Git Submodules | `gitsubmodule` | `.gitmodules` |
|
||||
| Pre-commit | `pre-commit` | `.pre-commit-config.yaml` |
|
||||
|
||||
Note: pnpm and yarn both use the `npm` ecosystem value.
|
||||
|
||||
### Step 2: Map Directory Locations
|
||||
|
||||
For each ecosystem, identify where manifests live. Use `directories` (plural) with glob patterns for monorepos:
|
||||
|
||||
```yaml
|
||||
directories:
|
||||
- "/" # root
|
||||
- "/apps/*" # all app subdirs
|
||||
- "/packages/*" # all package subdirs
|
||||
- "/lib-*" # dirs starting with lib-
|
||||
- "**/*" # recursive (all subdirs)
|
||||
```
|
||||
|
||||
Important: `directory` (singular) does NOT support globs. Use `directories` (plural) for wildcards.
|
||||
|
||||
### Step 3: Configure Each Ecosystem Entry
|
||||
|
||||
Every entry needs at minimum:
|
||||
|
||||
```yaml
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
```
|
||||
|
||||
### Step 4: Optimize with Grouping, Labels, and Scheduling
|
||||
|
||||
See sections below for each optimization technique.
|
||||
|
||||
## Monorepo Strategies
|
||||
|
||||
### Glob Patterns for Workspace Coverage
|
||||
|
||||
For monorepos with many packages, use glob patterns to avoid listing each directory:
|
||||
|
||||
```yaml
|
||||
- package-ecosystem: "npm"
|
||||
directories:
|
||||
- "/"
|
||||
- "/apps/*"
|
||||
- "/packages/*"
|
||||
- "/services/*"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
```
|
||||
|
||||
### Cross-Directory Grouping
|
||||
|
||||
Use `group-by: dependency-name` to create a single PR when the same dependency updates across multiple directories:
|
||||
|
||||
```yaml
|
||||
groups:
|
||||
monorepo-deps:
|
||||
group-by: dependency-name
|
||||
```
|
||||
|
||||
This creates one PR per dependency across all specified directories, reducing CI costs and review burden.
|
||||
|
||||
Limitations:
|
||||
- All directories must use the same package ecosystem
|
||||
- Applies to version updates only
|
||||
- Incompatible version constraints create separate PRs
|
||||
|
||||
### Standalone Packages Outside Workspaces
|
||||
|
||||
If a directory has its own lockfile and is NOT part of the workspace (e.g., scripts in `.github/`), create a separate ecosystem entry for it.
|
||||
|
||||
## Dependency Grouping
|
||||
|
||||
Reduce PR noise by grouping related dependencies into single PRs.
|
||||
|
||||
### By Dependency Type
|
||||
|
||||
```yaml
|
||||
groups:
|
||||
dev-dependencies:
|
||||
dependency-type: "development"
|
||||
update-types: ["minor", "patch"]
|
||||
production-dependencies:
|
||||
dependency-type: "production"
|
||||
update-types: ["minor", "patch"]
|
||||
```
|
||||
|
||||
### By Name Pattern
|
||||
|
||||
```yaml
|
||||
groups:
|
||||
angular:
|
||||
patterns: ["@angular*"]
|
||||
update-types: ["minor", "patch"]
|
||||
testing:
|
||||
patterns: ["jest*", "@testing-library*", "ts-jest"]
|
||||
```
|
||||
|
||||
### For Security Updates
|
||||
|
||||
```yaml
|
||||
groups:
|
||||
security-patches:
|
||||
applies-to: security-updates
|
||||
patterns: ["*"]
|
||||
update-types: ["patch", "minor"]
|
||||
```
|
||||
|
||||
Key behaviors:
|
||||
- Dependencies matching multiple groups go to the **first** match
|
||||
- `applies-to` defaults to `version-updates` when absent
|
||||
- Ungrouped dependencies get individual PRs
|
||||
|
||||
## Multi-Ecosystem Groups
|
||||
|
||||
Combine updates across different package ecosystems into a single PR:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
|
||||
multi-ecosystem-groups:
|
||||
infrastructure:
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
labels: ["infrastructure", "dependencies"]
|
||||
|
||||
updates:
|
||||
- package-ecosystem: "docker"
|
||||
directory: "/"
|
||||
patterns: ["nginx", "redis"]
|
||||
multi-ecosystem-group: "infrastructure"
|
||||
|
||||
- package-ecosystem: "terraform"
|
||||
directory: "/"
|
||||
patterns: ["aws*"]
|
||||
multi-ecosystem-group: "infrastructure"
|
||||
```
|
||||
|
||||
The `patterns` key is required when using `multi-ecosystem-group`.
|
||||
|
||||
## PR Customization
|
||||
|
||||
### Labels
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "npm"
|
||||
```
|
||||
|
||||
Set `labels: []` to disable all labels including defaults. SemVer labels (`major`, `minor`, `patch`) are always applied if present in the repo.
|
||||
|
||||
### Commit Messages
|
||||
|
||||
```yaml
|
||||
commit-message:
|
||||
prefix: "deps"
|
||||
prefix-development: "deps-dev"
|
||||
include: "scope" # adds deps/deps-dev scope after prefix
|
||||
```
|
||||
|
||||
### Assignees and Milestones
|
||||
|
||||
```yaml
|
||||
assignees: ["security-team-lead"]
|
||||
milestone: 4 # numeric ID from milestone URL
|
||||
```
|
||||
|
||||
### Branch Name Separator
|
||||
|
||||
```yaml
|
||||
pull-request-branch-name:
|
||||
separator: "-" # default is /
|
||||
```
|
||||
|
||||
### Target Branch
|
||||
|
||||
```yaml
|
||||
target-branch: "develop" # PRs target this instead of default branch
|
||||
```
|
||||
|
||||
Note: When `target-branch` is set, security updates still target the default branch; all ecosystem config only applies to version updates.
|
||||
|
||||
## Schedule Optimization
|
||||
|
||||
### Intervals
|
||||
|
||||
Supported: `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `yearly`, `cron`
|
||||
|
||||
```yaml
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday" # for weekly only
|
||||
time: "09:00" # HH:MM format
|
||||
timezone: "America/New_York"
|
||||
```
|
||||
|
||||
### Cron Expressions
|
||||
|
||||
```yaml
|
||||
schedule:
|
||||
interval: "cron"
|
||||
cronjob: "0 9 * * 1" # Every Monday at 9 AM
|
||||
```
|
||||
|
||||
### Cooldown Periods
|
||||
|
||||
Delay updates for newly released versions to avoid early-adopter issues:
|
||||
|
||||
```yaml
|
||||
cooldown:
|
||||
default-days: 5
|
||||
semver-major-days: 30
|
||||
semver-minor-days: 7
|
||||
semver-patch-days: 3
|
||||
include: ["*"]
|
||||
exclude: ["critical-lib"]
|
||||
```
|
||||
|
||||
Cooldown applies to version updates only, not security updates.
|
||||
|
||||
## Security Updates Configuration
|
||||
|
||||
### Enable via Repository Settings
|
||||
|
||||
Settings → Advanced Security → Enable Dependabot alerts, security updates, and grouped security updates.
|
||||
|
||||
### Group Security Updates in YAML
|
||||
|
||||
```yaml
|
||||
groups:
|
||||
security-patches:
|
||||
applies-to: security-updates
|
||||
patterns: ["*"]
|
||||
update-types: ["patch", "minor"]
|
||||
```
|
||||
|
||||
### Disable Version Updates (Security Only)
|
||||
|
||||
```yaml
|
||||
open-pull-requests-limit: 0 # disables version update PRs
|
||||
```
|
||||
|
||||
### Auto-Triage Rules
|
||||
|
||||
GitHub presets auto-dismiss low-impact alerts for development dependencies. Custom rules can filter by severity, package name, CWE, and more. Configure in repository Settings → Advanced Security.
|
||||
|
||||
## PR Comment Commands
|
||||
|
||||
Interact with Dependabot PRs using `@dependabot` comments.
|
||||
|
||||
> **Note:** As of January 2026, merge/close/reopen commands have been deprecated.
|
||||
> Use GitHub's native UI, CLI (`gh pr merge`), or auto-merge instead.
|
||||
|
||||
| Command | Effect |
|
||||
|---|---|
|
||||
| `@dependabot rebase` | Rebase the PR |
|
||||
| `@dependabot recreate` | Recreate the PR from scratch |
|
||||
| `@dependabot ignore this dependency` | Close and never update this dependency |
|
||||
| `@dependabot ignore this major version` | Ignore this major version |
|
||||
| `@dependabot ignore this minor version` | Ignore this minor version |
|
||||
| `@dependabot ignore this patch version` | Ignore this patch version |
|
||||
|
||||
For grouped PRs, additional commands:
|
||||
- `@dependabot ignore DEPENDENCY_NAME` — ignore specific dependency in group
|
||||
- `@dependabot unignore DEPENDENCY_NAME` — clear ignores, reopen with updates
|
||||
- `@dependabot unignore *` — clear all ignores for all dependencies in group
|
||||
- `@dependabot show DEPENDENCY_NAME ignore conditions` — display current ignores
|
||||
|
||||
For the complete command reference, see `references/pr-commands.md`.
|
||||
|
||||
## Ignore and Allow Rules
|
||||
|
||||
### Ignore Specific Dependencies
|
||||
|
||||
```yaml
|
||||
ignore:
|
||||
- dependency-name: "lodash"
|
||||
- dependency-name: "@types/node"
|
||||
update-types: ["version-update:semver-patch"]
|
||||
- dependency-name: "express"
|
||||
versions: ["5.x"]
|
||||
```
|
||||
|
||||
### Allow Only Specific Types
|
||||
|
||||
```yaml
|
||||
allow:
|
||||
- dependency-type: "production"
|
||||
- dependency-name: "express"
|
||||
```
|
||||
|
||||
Rule: If a dependency matches both `allow` and `ignore`, it is **ignored**.
|
||||
|
||||
### Exclude Paths
|
||||
|
||||
```yaml
|
||||
exclude-paths:
|
||||
- "vendor/**"
|
||||
- "test/fixtures/**"
|
||||
```
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### Versioning Strategy
|
||||
|
||||
Controls how Dependabot edits version constraints:
|
||||
|
||||
| Value | Behavior |
|
||||
|---|---|
|
||||
| `auto` | Default — increase for apps, widen for libraries |
|
||||
| `increase` | Always increase minimum version |
|
||||
| `increase-if-necessary` | Only change if current range excludes new version |
|
||||
| `lockfile-only` | Only update lockfiles, ignore manifests |
|
||||
| `widen` | Widen range to include both old and new versions |
|
||||
|
||||
### Rebase Strategy
|
||||
|
||||
```yaml
|
||||
rebase-strategy: "disabled" # stop auto-rebasing
|
||||
```
|
||||
|
||||
Allow rebase over extra commits by including `[dependabot skip]` in commit messages.
|
||||
|
||||
### Open PR Limit
|
||||
|
||||
```yaml
|
||||
open-pull-requests-limit: 10 # default is 5 for version, 10 for security
|
||||
```
|
||||
|
||||
Set to `0` to disable version updates entirely.
|
||||
|
||||
### Private Registries
|
||||
|
||||
```yaml
|
||||
registries:
|
||||
npm-private:
|
||||
type: npm-registry
|
||||
url: https://npm.example.com
|
||||
token: ${{secrets.NPM_TOKEN}}
|
||||
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
registries:
|
||||
- npm-private
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
**Can I have multiple `dependabot.yml` files?**
|
||||
No. GitHub supports exactly one file at `.github/dependabot.yml`. Use multiple `updates` entries within that file for different ecosystems and directories.
|
||||
|
||||
**Does Dependabot support pnpm?**
|
||||
Yes. Use `package-ecosystem: "npm"` — Dependabot detects `pnpm-lock.yaml` automatically.
|
||||
|
||||
**How do I reduce PR noise in a monorepo?**
|
||||
Use `groups` to batch updates, `directories` with globs for coverage, and `group-by: dependency-name` for cross-directory grouping. Consider `monthly` or `quarterly` intervals for low-priority ecosystems.
|
||||
|
||||
**How do I handle dependencies outside the workspace?**
|
||||
Create a separate ecosystem entry with its own `directory` pointing to that location.
|
||||
|
||||
## Resources
|
||||
|
||||
- `references/dependabot-yml-reference.md` — Complete YAML options reference
|
||||
- `references/pr-commands.md` — Full PR comment commands reference
|
||||
- `references/example-configs.md` — Real-world configuration examples
|
||||
374
skills/dependabot/references/dependabot-yml-reference.md
Normal file
374
skills/dependabot/references/dependabot-yml-reference.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# Dependabot YAML Options Reference
|
||||
|
||||
Complete reference for all configuration options in `.github/dependabot.yml`.
|
||||
|
||||
## File Structure
|
||||
|
||||
```yaml
|
||||
version: 2 # Required, always 2
|
||||
|
||||
registries: # Optional: private registry access
|
||||
REGISTRY_NAME:
|
||||
type: "..."
|
||||
url: "..."
|
||||
|
||||
multi-ecosystem-groups: # Optional: cross-ecosystem grouping
|
||||
GROUP_NAME:
|
||||
schedule:
|
||||
interval: "..."
|
||||
|
||||
updates: # Required: list of ecosystem configurations
|
||||
- package-ecosystem: "..." # Required
|
||||
directory: "/" # Required (or directories)
|
||||
schedule: # Required
|
||||
interval: "..."
|
||||
```
|
||||
|
||||
## Required Keys
|
||||
|
||||
### `version`
|
||||
|
||||
Always `2`. Must be at the top level.
|
||||
|
||||
### `package-ecosystem`
|
||||
|
||||
Defines which package manager to monitor. One entry per ecosystem (can have multiple entries for the same ecosystem with different directories).
|
||||
|
||||
| Package Manager | YAML Value | Manifest Files |
|
||||
|---|---|---|
|
||||
| Bazel | `bazel` | `MODULE.bazel`, `WORKSPACE` |
|
||||
| Bun | `bun` | `bun.lockb` |
|
||||
| Bundler (Ruby) | `bundler` | `Gemfile`, `Gemfile.lock` |
|
||||
| Cargo (Rust) | `cargo` | `Cargo.toml`, `Cargo.lock` |
|
||||
| Composer (PHP) | `composer` | `composer.json`, `composer.lock` |
|
||||
| Conda | `conda` | `environment.yml` |
|
||||
| Dev Containers | `devcontainers` | `devcontainer.json` |
|
||||
| Docker | `docker` | `Dockerfile` |
|
||||
| Docker Compose | `docker-compose` | `docker-compose.yml` |
|
||||
| .NET SDK | `dotnet-sdk` | `global.json` |
|
||||
| Elm | `elm` | `elm.json` |
|
||||
| Git Submodules | `gitsubmodule` | `.gitmodules` |
|
||||
| GitHub Actions | `github-actions` | `.github/workflows/*.yml` |
|
||||
| Go Modules | `gomod` | `go.mod`, `go.sum` |
|
||||
| Gradle | `gradle` | `build.gradle`, `build.gradle.kts` |
|
||||
| Helm | `helm` | `Chart.yaml` |
|
||||
| Hex (Elixir) | `mix` | `mix.exs`, `mix.lock` |
|
||||
| Julia | `julia` | `Project.toml`, `Manifest.toml` |
|
||||
| Maven | `maven` | `pom.xml` |
|
||||
| npm/pnpm/yarn | `npm` | `package.json`, lockfiles |
|
||||
| NuGet | `nuget` | `*.csproj`, `packages.config` |
|
||||
| OpenTofu | `opentofu` | `*.tf` |
|
||||
| pip/pipenv/poetry/uv | `pip` | `requirements.txt`, `Pipfile`, `pyproject.toml` |
|
||||
| Pre-commit | `pre-commit` | `.pre-commit-config.yaml` |
|
||||
| Pub (Dart/Flutter) | `pub` | `pubspec.yaml` |
|
||||
| Rust Toolchain | `rust-toolchain` | `rust-toolchain.toml` |
|
||||
| Swift | `swift` | `Package.swift` |
|
||||
| Terraform | `terraform` | `*.tf` |
|
||||
| uv | `uv` | `uv.lock`, `pyproject.toml` |
|
||||
| vcpkg | `vcpkg` | `vcpkg.json` |
|
||||
|
||||
### `directory` / `directories`
|
||||
|
||||
Location of package manifests relative to repo root.
|
||||
|
||||
- `directory` — single path (no glob support)
|
||||
- `directories` — list of paths (supports `*` and `**` globs)
|
||||
|
||||
```yaml
|
||||
# Single directory
|
||||
directory: "/"
|
||||
|
||||
# Multiple directories with globs
|
||||
directories:
|
||||
- "/"
|
||||
- "/apps/*"
|
||||
- "/packages/*"
|
||||
```
|
||||
|
||||
For GitHub Actions, use `/` — Dependabot automatically searches `.github/workflows/`.
|
||||
|
||||
### `schedule`
|
||||
|
||||
How often to check for updates.
|
||||
|
||||
| Parameter | Values | Notes |
|
||||
|---|---|---|
|
||||
| `interval` | `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `yearly`, `cron` | Required |
|
||||
| `day` | `monday`–`sunday` | Weekly only |
|
||||
| `time` | `HH:MM` | UTC by default |
|
||||
| `timezone` | IANA timezone string | e.g., `America/New_York` |
|
||||
| `cronjob` | Cron expression | Required when interval is `cron` |
|
||||
|
||||
```yaml
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "tuesday"
|
||||
time: "09:00"
|
||||
timezone: "Europe/London"
|
||||
```
|
||||
|
||||
## Grouping Options
|
||||
|
||||
### `groups`
|
||||
|
||||
Group dependencies into fewer PRs.
|
||||
|
||||
| Parameter | Purpose | Values |
|
||||
|---|---|---|
|
||||
| `IDENTIFIER` | Group name (used in branch/PR title) | Letters, pipes, underscores, hyphens |
|
||||
| `applies-to` | Update type | `version-updates` (default), `security-updates` |
|
||||
| `dependency-type` | Filter by type | `development`, `production` |
|
||||
| `patterns` | Include matching names | List of strings with `*` wildcard |
|
||||
| `exclude-patterns` | Exclude matching names | List of strings with `*` wildcard |
|
||||
| `update-types` | SemVer filter | `major`, `minor`, `patch` |
|
||||
| `group-by` | Cross-directory grouping | `dependency-name` |
|
||||
|
||||
```yaml
|
||||
groups:
|
||||
dev-deps:
|
||||
dependency-type: "development"
|
||||
update-types: ["minor", "patch"]
|
||||
angular:
|
||||
patterns: ["@angular*"]
|
||||
exclude-patterns: ["@angular/cdk"]
|
||||
monorepo:
|
||||
group-by: dependency-name
|
||||
```
|
||||
|
||||
### `multi-ecosystem-groups` (top-level)
|
||||
|
||||
Group updates across different ecosystems into one PR.
|
||||
|
||||
```yaml
|
||||
multi-ecosystem-groups:
|
||||
GROUP_NAME:
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
labels: ["infrastructure"]
|
||||
assignees: ["@platform-team"]
|
||||
```
|
||||
|
||||
Assign ecosystems with `multi-ecosystem-group: "GROUP_NAME"` in each `updates` entry. The `patterns` key is required in each ecosystem entry when using this feature.
|
||||
|
||||
## Filtering Options
|
||||
|
||||
### `allow`
|
||||
|
||||
Explicitly define which dependencies to maintain.
|
||||
|
||||
| Parameter | Purpose |
|
||||
|---|---|
|
||||
| `dependency-name` | Match by name (supports `*` wildcard) |
|
||||
| `dependency-type` | `direct`, `indirect`, `all`, `production`, `development` |
|
||||
|
||||
```yaml
|
||||
allow:
|
||||
- dependency-type: "production"
|
||||
- dependency-name: "express"
|
||||
```
|
||||
|
||||
### `ignore`
|
||||
|
||||
Exclude dependencies or versions from updates.
|
||||
|
||||
| Parameter | Purpose |
|
||||
|---|---|
|
||||
| `dependency-name` | Match by name (supports `*` wildcard) |
|
||||
| `versions` | Specific versions or ranges (e.g., `["5.x"]`, `[">=2.0.0"]`) |
|
||||
| `update-types` | SemVer levels: `version-update:semver-major`, `version-update:semver-minor`, `version-update:semver-patch` |
|
||||
|
||||
```yaml
|
||||
ignore:
|
||||
- dependency-name: "lodash"
|
||||
- dependency-name: "@types/node"
|
||||
update-types: ["version-update:semver-patch"]
|
||||
- dependency-name: "express"
|
||||
versions: ["5.x"]
|
||||
```
|
||||
|
||||
Rule: if a dependency matches both `allow` and `ignore`, it is **ignored**.
|
||||
|
||||
### `exclude-paths`
|
||||
|
||||
Ignore specific directories or files during manifest scanning.
|
||||
|
||||
```yaml
|
||||
exclude-paths:
|
||||
- "vendor/**"
|
||||
- "test/fixtures/**"
|
||||
- "*.lock"
|
||||
```
|
||||
|
||||
Supports glob patterns: `*` (single segment), `**` (recursive), specific file paths.
|
||||
|
||||
## PR Customization Options
|
||||
|
||||
### `labels`
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "npm"
|
||||
```
|
||||
|
||||
Set `labels: []` to disable all labels. SemVer labels are always applied if they exist in the repo.
|
||||
|
||||
### `assignees`
|
||||
|
||||
```yaml
|
||||
assignees:
|
||||
- "user1"
|
||||
- "user2"
|
||||
```
|
||||
|
||||
Assignees must have write access (or read access for org repos).
|
||||
|
||||
### `milestone`
|
||||
|
||||
```yaml
|
||||
milestone: 4 # numeric ID from milestone URL
|
||||
```
|
||||
|
||||
### `commit-message`
|
||||
|
||||
```yaml
|
||||
commit-message:
|
||||
prefix: "deps" # up to 50 chars; colon auto-added if ends with letter/number
|
||||
prefix-development: "deps-dev" # separate prefix for dev dependencies
|
||||
include: "scope" # adds deps/deps-dev after prefix
|
||||
```
|
||||
|
||||
### `pull-request-branch-name`
|
||||
|
||||
```yaml
|
||||
pull-request-branch-name:
|
||||
separator: "-" # options: "-", "_", "/"
|
||||
```
|
||||
|
||||
### `target-branch`
|
||||
|
||||
```yaml
|
||||
target-branch: "develop"
|
||||
```
|
||||
|
||||
When set, version update config only applies to version updates. Security updates always target the default branch.
|
||||
|
||||
## Scheduling & Rate Limiting
|
||||
|
||||
### `cooldown`
|
||||
|
||||
Delay version updates for newly released versions:
|
||||
|
||||
| Parameter | Purpose |
|
||||
|---|---|
|
||||
| `default-days` | Default cooldown (1–90 days) |
|
||||
| `semver-major-days` | Cooldown for major updates |
|
||||
| `semver-minor-days` | Cooldown for minor updates |
|
||||
| `semver-patch-days` | Cooldown for patch updates |
|
||||
| `include` | Dependencies to apply cooldown (up to 150, supports `*`) |
|
||||
| `exclude` | Dependencies exempt from cooldown (up to 150, takes precedence) |
|
||||
|
||||
```yaml
|
||||
cooldown:
|
||||
default-days: 5
|
||||
semver-major-days: 30
|
||||
semver-minor-days: 7
|
||||
semver-patch-days: 3
|
||||
include: ["*"]
|
||||
exclude: ["critical-security-lib"]
|
||||
```
|
||||
|
||||
### `open-pull-requests-limit`
|
||||
|
||||
```yaml
|
||||
open-pull-requests-limit: 10 # default: 5 for version updates
|
||||
```
|
||||
|
||||
Set to `0` to disable version updates entirely. Security updates have a separate internal limit of 10.
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### `versioning-strategy`
|
||||
|
||||
Supported by: `bundler`, `cargo`, `composer`, `mix`, `npm`, `pip`, `pub`, `uv`.
|
||||
|
||||
| Value | Behavior |
|
||||
|---|---|
|
||||
| `auto` | Default: increase for apps, widen for libraries |
|
||||
| `increase` | Always increase minimum version |
|
||||
| `increase-if-necessary` | Only change if current range excludes new version |
|
||||
| `lockfile-only` | Only update lockfiles |
|
||||
| `widen` | Widen range to include old and new versions |
|
||||
|
||||
### `rebase-strategy`
|
||||
|
||||
```yaml
|
||||
rebase-strategy: "disabled"
|
||||
```
|
||||
|
||||
Default behavior: Dependabot auto-rebases PRs on conflicts. Rebasing stops 30 days after PR opens.
|
||||
|
||||
Allow Dependabot to force push over extra commits by including `[dependabot skip]` in commit messages.
|
||||
|
||||
### `vendor`
|
||||
|
||||
Supported by: `bundler`, `gomod`.
|
||||
|
||||
```yaml
|
||||
vendor: true # maintain vendored dependencies
|
||||
```
|
||||
|
||||
Go modules auto-detect vendored dependencies.
|
||||
|
||||
### `insecure-external-code-execution`
|
||||
|
||||
Supported by: `bundler`, `mix`, `pip`.
|
||||
|
||||
```yaml
|
||||
insecure-external-code-execution: "allow"
|
||||
```
|
||||
|
||||
Allows Dependabot to execute code in manifests during updates. Required for some ecosystems that run code during resolution.
|
||||
|
||||
## Private Registries
|
||||
|
||||
### Top-Level Registry Definition
|
||||
|
||||
```yaml
|
||||
registries:
|
||||
npm-private:
|
||||
type: npm-registry
|
||||
url: https://npm.example.com
|
||||
token: ${{secrets.NPM_TOKEN}}
|
||||
|
||||
maven-central:
|
||||
type: maven-repository
|
||||
url: https://repo.maven.apache.org/maven2
|
||||
username: ""
|
||||
password: ""
|
||||
|
||||
docker-ghcr:
|
||||
type: docker-registry
|
||||
url: https://ghcr.io
|
||||
username: ${{secrets.GHCR_USER}}
|
||||
password: ${{secrets.GHCR_TOKEN}}
|
||||
|
||||
python-private:
|
||||
type: python-index
|
||||
url: https://pypi.example.com/simple
|
||||
token: ${{secrets.PYPI_TOKEN}}
|
||||
```
|
||||
|
||||
### Associating Registries with Ecosystems
|
||||
|
||||
```yaml
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
registries:
|
||||
- npm-private
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
```
|
||||
|
||||
Use `registries: "*"` to allow access to all defined registries.
|
||||
409
skills/dependabot/references/example-configs.md
Normal file
409
skills/dependabot/references/example-configs.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# Dependabot Configuration Examples
|
||||
|
||||
Real-world `dependabot.yml` configurations for common scenarios.
|
||||
|
||||
---
|
||||
|
||||
## 1. Basic Single Ecosystem
|
||||
|
||||
Minimal configuration for a single npm project:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Monorepo with Glob Patterns
|
||||
|
||||
Turborepo/pnpm monorepo with multiple workspace packages:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directories:
|
||||
- "/"
|
||||
- "/apps/*"
|
||||
- "/packages/*"
|
||||
- "/services/*"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
groups:
|
||||
dev-dependencies:
|
||||
dependency-type: "development"
|
||||
update-types: ["minor", "patch"]
|
||||
production-dependencies:
|
||||
dependency-type: "production"
|
||||
update-types: ["minor", "patch"]
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "npm"
|
||||
commit-message:
|
||||
prefix: "deps"
|
||||
include: "scope"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Grouped Dev vs Production Dependencies
|
||||
|
||||
Separate dev and production updates to prioritize review of production changes:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
groups:
|
||||
production-deps:
|
||||
dependency-type: "production"
|
||||
dev-deps:
|
||||
dependency-type: "development"
|
||||
exclude-patterns:
|
||||
- "eslint*"
|
||||
linting:
|
||||
patterns:
|
||||
- "eslint*"
|
||||
- "prettier*"
|
||||
- "@typescript-eslint*"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Cross-Directory Grouping (Monorepo)
|
||||
|
||||
Create one PR per shared dependency across directories:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directories:
|
||||
- "/frontend"
|
||||
- "/admin-panel"
|
||||
- "/mobile-app"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
groups:
|
||||
monorepo-dependencies:
|
||||
group-by: dependency-name
|
||||
```
|
||||
|
||||
When `lodash` updates in all three directories, Dependabot creates a single PR.
|
||||
|
||||
---
|
||||
|
||||
## 5. Multi-Ecosystem Group (Docker + Terraform)
|
||||
|
||||
Consolidate infrastructure dependency updates into a single PR:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
|
||||
multi-ecosystem-groups:
|
||||
infrastructure:
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
labels: ["infrastructure", "dependencies"]
|
||||
assignees: ["@platform-team"]
|
||||
|
||||
updates:
|
||||
- package-ecosystem: "docker"
|
||||
directory: "/"
|
||||
patterns: ["nginx", "redis", "postgres"]
|
||||
multi-ecosystem-group: "infrastructure"
|
||||
|
||||
- package-ecosystem: "terraform"
|
||||
directory: "/"
|
||||
patterns: ["aws*", "terraform-*"]
|
||||
multi-ecosystem-group: "infrastructure"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Security Updates Only (Version Updates Disabled)
|
||||
|
||||
Monitor for security vulnerabilities without version update PRs:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "daily"
|
||||
open-pull-requests-limit: 0 # disables version update PRs
|
||||
groups:
|
||||
security-all:
|
||||
applies-to: security-updates
|
||||
patterns: ["*"]
|
||||
update-types: ["patch", "minor"]
|
||||
|
||||
- package-ecosystem: "pip"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "daily"
|
||||
open-pull-requests-limit: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Private Registries
|
||||
|
||||
Access private npm and Docker registries:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
|
||||
registries:
|
||||
npm-private:
|
||||
type: npm-registry
|
||||
url: https://npm.internal.example.com
|
||||
token: ${{secrets.NPM_PRIVATE_TOKEN}}
|
||||
|
||||
docker-ghcr:
|
||||
type: docker-registry
|
||||
url: https://ghcr.io
|
||||
username: ${{secrets.GHCR_USER}}
|
||||
password: ${{secrets.GHCR_TOKEN}}
|
||||
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
registries:
|
||||
- npm-private
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
|
||||
- package-ecosystem: "docker"
|
||||
directory: "/"
|
||||
registries:
|
||||
- docker-ghcr
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Cooldown Periods
|
||||
|
||||
Delay updates for newly released versions to avoid early-adopter bugs:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
cooldown:
|
||||
default-days: 5
|
||||
semver-major-days: 30
|
||||
semver-minor-days: 14
|
||||
semver-patch-days: 3
|
||||
include: ["*"]
|
||||
exclude:
|
||||
- "security-critical-lib"
|
||||
- "@company/internal-*"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Cron Scheduling
|
||||
|
||||
Run updates at a specific time using cron expressions:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "cron"
|
||||
cronjob: "0 9 * * 1" # Every Monday at 9:00 AM
|
||||
timezone: "America/New_York"
|
||||
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "cron"
|
||||
cronjob: "0 6 1 * *" # First day of each month at 6:00 AM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Full-Featured Configuration
|
||||
|
||||
A comprehensive example combining multiple optimizations:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
|
||||
registries:
|
||||
npm-private:
|
||||
type: npm-registry
|
||||
url: https://npm.example.com
|
||||
token: ${{secrets.NPM_TOKEN}}
|
||||
|
||||
updates:
|
||||
# npm — monorepo workspaces
|
||||
- package-ecosystem: "npm"
|
||||
directories:
|
||||
- "/"
|
||||
- "/apps/*"
|
||||
- "/packages/*"
|
||||
- "/services/*"
|
||||
registries:
|
||||
- npm-private
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
time: "09:00"
|
||||
timezone: "America/New_York"
|
||||
groups:
|
||||
dev-dependencies:
|
||||
dependency-type: "development"
|
||||
update-types: ["minor", "patch"]
|
||||
production-dependencies:
|
||||
dependency-type: "production"
|
||||
update-types: ["minor", "patch"]
|
||||
angular:
|
||||
patterns: ["@angular*"]
|
||||
update-types: ["minor", "patch"]
|
||||
security-patches:
|
||||
applies-to: security-updates
|
||||
patterns: ["*"]
|
||||
update-types: ["patch", "minor"]
|
||||
ignore:
|
||||
- dependency-name: "aws-sdk"
|
||||
update-types: ["version-update:semver-major"]
|
||||
cooldown:
|
||||
default-days: 3
|
||||
semver-major-days: 14
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "npm"
|
||||
commit-message:
|
||||
prefix: "deps"
|
||||
prefix-development: "deps-dev"
|
||||
include: "scope"
|
||||
assignees:
|
||||
- "security-lead"
|
||||
open-pull-requests-limit: 15
|
||||
|
||||
# GitHub Actions
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
groups:
|
||||
actions:
|
||||
patterns: ["*"]
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "ci"
|
||||
commit-message:
|
||||
prefix: "ci"
|
||||
|
||||
# Docker
|
||||
- package-ecosystem: "docker"
|
||||
directories:
|
||||
- "/services/*"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "docker"
|
||||
commit-message:
|
||||
prefix: "deps"
|
||||
|
||||
# pip
|
||||
- package-ecosystem: "pip"
|
||||
directory: "/scripts"
|
||||
schedule:
|
||||
interval: "monthly"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "python"
|
||||
versioning-strategy: "increase-if-necessary"
|
||||
commit-message:
|
||||
prefix: "deps"
|
||||
|
||||
# Terraform
|
||||
- package-ecosystem: "terraform"
|
||||
directory: "/infra"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "terraform"
|
||||
commit-message:
|
||||
prefix: "infra"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Ignore Patterns and Versioning Strategy
|
||||
|
||||
Control exactly what gets updated and how:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "daily"
|
||||
versioning-strategy: "increase"
|
||||
ignore:
|
||||
# Never auto-update to Express 5.x (breaking changes)
|
||||
- dependency-name: "express"
|
||||
versions: ["5.x"]
|
||||
# Skip patch updates for type definitions
|
||||
- dependency-name: "@types/*"
|
||||
update-types: ["version-update:semver-patch"]
|
||||
# Ignore all updates for a vendored package
|
||||
- dependency-name: "legacy-internal-lib"
|
||||
allow:
|
||||
- dependency-type: "all"
|
||||
exclude-paths:
|
||||
- "vendor/**"
|
||||
- "test/fixtures/**"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Target Non-Default Branch
|
||||
|
||||
Test updates on a development branch before production:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
target-branch: "develop"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "staging"
|
||||
|
||||
- package-ecosystem: "pip"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
target-branch: "develop"
|
||||
```
|
||||
|
||||
Note: Security updates always target the default branch regardless of `target-branch`.
|
||||
91
skills/dependabot/references/pr-commands.md
Normal file
91
skills/dependabot/references/pr-commands.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Dependabot PR Comment Commands
|
||||
|
||||
Interact with Dependabot pull requests by commenting `@dependabot <command>`. Dependabot acknowledges commands with a thumbs-up reaction.
|
||||
|
||||
> **Deprecation Notice (January 27, 2026):** The following commands have been removed:
|
||||
> `@dependabot merge`, `@dependabot squash and merge`, `@dependabot cancel merge`,
|
||||
> `@dependabot close`, and `@dependabot reopen`.
|
||||
> Use GitHub's native UI, CLI (`gh pr merge`), API, or auto-merge feature instead.
|
||||
|
||||
## Commands for Individual PRs
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `@dependabot rebase` | Rebase the PR against the target branch |
|
||||
| `@dependabot recreate` | Recreate the PR from scratch, overwriting any manual edits |
|
||||
| `@dependabot ignore this dependency` | Close the PR and stop all future updates for this dependency |
|
||||
| `@dependabot ignore this major version` | Close and stop updates for this major version |
|
||||
| `@dependabot ignore this minor version` | Close and stop updates for this minor version |
|
||||
| `@dependabot ignore this patch version` | Close and stop updates for this patch version |
|
||||
| `@dependabot show DEPENDENCY_NAME ignore conditions` | Display a table of all current ignore conditions for the dependency |
|
||||
|
||||
## Commands for Grouped Updates
|
||||
|
||||
These commands work on Dependabot PRs created by grouped version or security updates.
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `@dependabot ignore DEPENDENCY_NAME` | Close the PR and stop updating this dependency in the group |
|
||||
| `@dependabot ignore DEPENDENCY_NAME major version` | Stop updating this dependency's major version |
|
||||
| `@dependabot ignore DEPENDENCY_NAME minor version` | Stop updating this dependency's minor version |
|
||||
| `@dependabot ignore DEPENDENCY_NAME patch version` | Stop updating this dependency's patch version |
|
||||
| `@dependabot unignore *` | Close current PR, clear ALL ignore conditions for ALL dependencies in the group, open a new PR |
|
||||
| `@dependabot unignore DEPENDENCY_NAME` | Close current PR, clear all ignores for a specific dependency, open a new PR with its updates |
|
||||
| `@dependabot unignore DEPENDENCY_NAME IGNORE_CONDITION` | Close current PR, clear a specific ignore condition, open a new PR |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Merge After CI (Use Native GitHub Features)
|
||||
|
||||
Auto-merge is the recommended replacement for the deprecated `@dependabot merge` command:
|
||||
|
||||
```bash
|
||||
# Enable auto-merge via GitHub CLI
|
||||
gh pr merge <PR_NUMBER> --auto --squash
|
||||
|
||||
# Or enable auto-merge via the GitHub UI:
|
||||
# PR → "Enable auto-merge" → select merge method → confirm
|
||||
```
|
||||
|
||||
GitHub will automatically merge the PR once all required CI checks pass.
|
||||
|
||||
### Ignore a Major Version Bump
|
||||
|
||||
```
|
||||
@dependabot ignore this major version
|
||||
```
|
||||
|
||||
Useful when a major version has breaking changes and migration is not yet planned.
|
||||
|
||||
### Check Active Ignore Conditions
|
||||
|
||||
```
|
||||
@dependabot show express ignore conditions
|
||||
```
|
||||
|
||||
Displays a table showing all ignore conditions currently stored for the `express` dependency.
|
||||
|
||||
### Unignore a Dependency in a Group
|
||||
|
||||
```
|
||||
@dependabot unignore lodash
|
||||
```
|
||||
|
||||
Closes the current grouped PR, clears all ignore conditions for `lodash`, and opens a new PR that includes available `lodash` updates.
|
||||
|
||||
### Unignore a Specific Condition
|
||||
|
||||
```
|
||||
@dependabot unignore express [< 1.9, > 1.8.0]
|
||||
```
|
||||
|
||||
Clears only the specified version range ignore for `express`.
|
||||
|
||||
## Tips
|
||||
|
||||
- **Rebase vs Recreate**: Use `rebase` to resolve conflicts while keeping your review state. Use `recreate` to start fresh if the PR has diverged significantly.
|
||||
- **Force push over extra commits**: If you've pushed commits to a Dependabot branch and want Dependabot to rebase over them, include `[dependabot skip]` in your commit message.
|
||||
- **Persistent ignores**: Ignore commands via PR comments are stored centrally. For transparency in team repos, prefer using `ignore` in `dependabot.yml` instead.
|
||||
- **Merging Dependabot PRs**: Use GitHub's native auto-merge feature, the CLI (`gh pr merge`), or the web UI. The old `@dependabot merge` commands were deprecated in January 2026.
|
||||
- **Closing/Reopening**: Use the GitHub UI or CLI. The old `@dependabot close` and `@dependabot reopen` commands were deprecated in January 2026.
|
||||
- **Grouped commands**: When using `@dependabot unignore`, Dependabot closes the current PR and opens a fresh one with the updated dependency set.
|
||||
224
skills/secret-scanning/SKILL.md
Normal file
224
skills/secret-scanning/SKILL.md
Normal file
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: secret-scanning
|
||||
description: Guide for configuring and managing GitHub secret scanning, push protection, custom patterns, and secret alert remediation. This skill should be used when users need help enabling secret scanning, setting up push protection, defining custom secret patterns, triaging secret scanning alerts, or resolving blocked pushes.
|
||||
---
|
||||
|
||||
# Secret Scanning
|
||||
|
||||
This skill provides procedural guidance for configuring GitHub secret scanning — detecting leaked credentials, preventing secret pushes, defining custom patterns, and managing alerts.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when the request involves:
|
||||
|
||||
- Enabling or configuring secret scanning for a repository or organization
|
||||
- Setting up push protection to block secrets before they reach the repository
|
||||
- Defining custom secret patterns with regular expressions
|
||||
- Resolving a blocked push from the command line
|
||||
- Triaging, dismissing, or remediating secret scanning alerts
|
||||
- Configuring delegated bypass for push protection
|
||||
- Excluding directories from secret scanning via `secret_scanning.yml`
|
||||
- Understanding alert types (user, partner, push protection)
|
||||
- Enabling validity checks or extended metadata checks
|
||||
|
||||
## How Secret Scanning Works
|
||||
|
||||
Secret scanning automatically detects exposed credentials across:
|
||||
|
||||
- Entire Git history on all branches
|
||||
- Issue descriptions, comments, and titles (open and closed)
|
||||
- Pull request titles, descriptions, and comments
|
||||
- GitHub Discussions titles, descriptions, and comments
|
||||
- Wikis and secret gists
|
||||
|
||||
### Availability
|
||||
|
||||
| Repository Type | Availability |
|
||||
|---|---|
|
||||
| Public repos | Automatic, free |
|
||||
| Private/internal (org-owned) | Requires GitHub Secret Protection on Team/Enterprise Cloud |
|
||||
| User-owned | Enterprise Cloud with Enterprise Managed Users |
|
||||
|
||||
## Core Workflow — Enable Secret Scanning
|
||||
|
||||
### Step 1: Enable Secret Protection
|
||||
|
||||
1. Navigate to repository **Settings** → **Advanced Security**
|
||||
2. Click **Enable** next to "Secret Protection"
|
||||
3. Confirm by clicking **Enable Secret Protection**
|
||||
|
||||
For organizations, use security configurations to enable at scale:
|
||||
- Settings → Advanced Security → Global settings → Security configurations
|
||||
|
||||
### Step 2: Enable Push Protection
|
||||
|
||||
Push protection blocks secrets during the push process — before they reach the repository.
|
||||
|
||||
1. Navigate to repository **Settings** → **Advanced Security**
|
||||
2. Enable "Push protection" under Secret Protection
|
||||
|
||||
Push protection blocks secrets in:
|
||||
- Command line pushes
|
||||
- GitHub UI commits
|
||||
- File uploads
|
||||
- REST API requests
|
||||
- REST API content creation endpoints
|
||||
|
||||
### Step 3: Configure Exclusions (Optional)
|
||||
|
||||
Create `.github/secret_scanning.yml` to auto-close alerts for specific directories:
|
||||
|
||||
```yaml
|
||||
paths-ignore:
|
||||
- "docs/**"
|
||||
- "test/fixtures/**"
|
||||
- "**/*.example"
|
||||
```
|
||||
|
||||
**Limits:**
|
||||
- Maximum 1,000 entries in `paths-ignore`
|
||||
- File must be under 1 MB
|
||||
- Excluded paths also skip push protection checks
|
||||
|
||||
**Best practices:**
|
||||
- Be as specific as possible with exclusion paths
|
||||
- Add comments explaining why each path is excluded
|
||||
- Review exclusions periodically — remove stale entries
|
||||
- Inform the security team about exclusions
|
||||
|
||||
### Step 4: Enable Additional Features (Optional)
|
||||
|
||||
**Non-provider patterns** — detect private keys, connection strings, generic API keys:
|
||||
- Settings → Advanced Security → enable "Scan for non-provider patterns"
|
||||
|
||||
**AI-powered generic secret detection** — uses Copilot to detect unstructured secrets like passwords:
|
||||
- Settings → Advanced Security → enable "Use AI detection"
|
||||
|
||||
**Validity checks** — verify if detected secrets are still active:
|
||||
- Settings → Advanced Security → enable "Validity checks"
|
||||
- GitHub periodically tests detected credentials against provider APIs
|
||||
- Status shown in alert: `active`, `inactive`, or `unknown`
|
||||
|
||||
**Extended metadata checks** — additional context about who owns a secret:
|
||||
- Requires validity checks to be enabled first
|
||||
- Helps prioritize remediation and identify responsible teams
|
||||
|
||||
## Core Workflow — Resolve Blocked Pushes
|
||||
|
||||
When push protection blocks a push from the command line:
|
||||
|
||||
### Option A: Remove the Secret
|
||||
|
||||
**If the secret is in the latest commit:**
|
||||
```bash
|
||||
# Remove the secret from the file
|
||||
# Then amend the commit
|
||||
git commit --amend --all
|
||||
git push
|
||||
```
|
||||
|
||||
**If the secret is in an earlier commit:**
|
||||
```bash
|
||||
# Find the earliest commit containing the secret
|
||||
git log
|
||||
|
||||
# Start interactive rebase before that commit
|
||||
git rebase -i <COMMIT-ID>~1
|
||||
|
||||
# Change 'pick' to 'edit' for the offending commit
|
||||
# Remove the secret, then:
|
||||
git add .
|
||||
git commit --amend
|
||||
git rebase --continue
|
||||
git push
|
||||
```
|
||||
|
||||
### Option B: Bypass Push Protection
|
||||
|
||||
1. Visit the URL returned in the push error message (as the same user)
|
||||
2. Select a bypass reason:
|
||||
- **It's used in tests** — alert created and auto-closed
|
||||
- **It's a false positive** — alert created and auto-closed
|
||||
- **I'll fix it later** — open alert created
|
||||
3. Click **Allow me to push this secret**
|
||||
4. Re-push within 3 hours
|
||||
|
||||
### Option C: Request Bypass Privileges
|
||||
|
||||
If delegated bypass is enabled and you lack bypass privileges:
|
||||
1. Visit the URL from the push error
|
||||
2. Add a comment explaining why the secret is safe
|
||||
3. Click **Submit request**
|
||||
4. Wait for email notification of approval/denial
|
||||
5. If approved, push the commit; if denied, remove the secret
|
||||
|
||||
> For detailed bypass and delegated bypass workflows, search `references/push-protection.md`.
|
||||
|
||||
## Custom Patterns
|
||||
|
||||
Define organization-specific secret patterns using regular expressions.
|
||||
|
||||
### Quick Setup
|
||||
|
||||
1. Settings → Advanced Security → Custom patterns → **New pattern**
|
||||
2. Enter pattern name and regex for secret format
|
||||
3. Add a sample test string
|
||||
4. Click **Save and dry run** to test (up to 1,000 results)
|
||||
5. Review results for false positives
|
||||
6. Click **Publish pattern**
|
||||
7. Optionally enable push protection for the pattern
|
||||
|
||||
### Scopes
|
||||
|
||||
Custom patterns can be defined at:
|
||||
- **Repository level** — applies to that repo only
|
||||
- **Organization level** — applies to all repos with secret scanning enabled
|
||||
- **Enterprise level** — applies across all organizations
|
||||
|
||||
### Copilot-Assisted Pattern Generation
|
||||
|
||||
Use Copilot secret scanning to generate regex from a text description of the secret type, including optional example strings.
|
||||
|
||||
> For detailed custom pattern configuration, search `references/custom-patterns.md`.
|
||||
|
||||
## Alert Management
|
||||
|
||||
### Alert Types
|
||||
|
||||
| Type | Description | Visibility |
|
||||
|---|---|---|
|
||||
| **User alerts** | Secrets found in repository | Security tab |
|
||||
| **Push protection alerts** | Secrets pushed via bypass | Security tab (filter: `bypassed: true`) |
|
||||
| **Partner alerts** | Secrets reported to provider | Not shown in repo (provider-only) |
|
||||
|
||||
### Alert Lists
|
||||
|
||||
- **Default alerts** — supported provider patterns and custom patterns
|
||||
- **Generic alerts** — non-provider patterns and AI-detected secrets (limited to 5,000 per repo)
|
||||
|
||||
### Remediation Priority
|
||||
|
||||
1. **Rotate the credential immediately** — this is the critical action
|
||||
2. Review the alert for context (location, commit, author)
|
||||
3. Check validity status: `active` (urgent), `inactive` (lower priority), `unknown`
|
||||
4. Remove from Git history if needed (time-intensive, often unnecessary after rotation)
|
||||
|
||||
### Dismissing Alerts
|
||||
|
||||
Dismiss with a documented reason:
|
||||
- **False positive** — detected string is not a real secret
|
||||
- **Revoked** — credential has already been revoked
|
||||
- **Used in tests** — secret is only in test code
|
||||
|
||||
> For detailed alert types, validity checks, and REST API, search `references/alerts-and-remediation.md`.
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed documentation, load the following reference files as needed:
|
||||
|
||||
- `references/push-protection.md` — Push protection mechanics, bypass workflow, delegated bypass, user push protection
|
||||
- Search patterns: `bypass`, `delegated`, `bypass request`, `command line`, `REST API`, `user push protection`
|
||||
- `references/custom-patterns.md` — Custom pattern creation, regex syntax, dry runs, Copilot regex generation, scopes
|
||||
- Search patterns: `custom pattern`, `regex`, `dry run`, `publish`, `organization`, `enterprise`, `Copilot`
|
||||
- `references/alerts-and-remediation.md` — Alert types, validity checks, extended metadata, generic alerts, secret removal, REST API
|
||||
- Search patterns: `user alert`, `partner alert`, `validity`, `metadata`, `generic`, `remediation`, `git history`, `REST API`
|
||||
245
skills/secret-scanning/references/alerts-and-remediation.md
Normal file
245
skills/secret-scanning/references/alerts-and-remediation.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# Alerts and Remediation Reference
|
||||
|
||||
Detailed reference for secret scanning alert types, validity checks, remediation workflows, and API access.
|
||||
|
||||
## Alert Types
|
||||
|
||||
### User Alerts
|
||||
|
||||
Generated when secret scanning detects a supported secret in the repository.
|
||||
|
||||
- Displayed in the repository **Security** tab
|
||||
- Created for provider patterns, non-provider patterns, custom patterns, and AI-detected secrets
|
||||
- Scanning covers entire Git history on all branches
|
||||
|
||||
### Push Protection Alerts
|
||||
|
||||
Generated when a contributor bypasses push protection to push a secret.
|
||||
|
||||
- Displayed in the Security tab (filter: `bypassed: true`)
|
||||
- Record the bypass reason chosen by the contributor
|
||||
- Include the commit and file where the secret was pushed
|
||||
|
||||
**Bypass reasons and their alert behavior:**
|
||||
|
||||
| Bypass Reason | Alert Status |
|
||||
|---|---|
|
||||
| It's used in tests | Closed (resolved as "used in tests") |
|
||||
| It's a false positive | Closed (resolved as "false positive") |
|
||||
| I'll fix it later | Open |
|
||||
|
||||
### Partner Alerts
|
||||
|
||||
Generated when GitHub detects a leaked secret matching a partner's pattern.
|
||||
|
||||
- Sent directly to the service provider (e.g., AWS, Stripe, GitHub)
|
||||
- **Not** displayed in the repository Security tab
|
||||
- Provider may automatically revoke the credential
|
||||
- No action required by the repository owner
|
||||
|
||||
## Alert Lists
|
||||
|
||||
### Default Alerts List
|
||||
|
||||
The primary view showing alerts for:
|
||||
- Supported provider patterns (e.g., GitHub PATs, AWS keys, Stripe keys)
|
||||
- Custom patterns defined at repo/org/enterprise level
|
||||
|
||||
### Generic Alerts List
|
||||
|
||||
Separate view (toggle from default list) showing:
|
||||
- Non-provider patterns (private keys, connection strings)
|
||||
- AI-detected generic secrets (passwords)
|
||||
|
||||
**Limitations:**
|
||||
- Maximum 5,000 alerts per repository (open + closed)
|
||||
- Only first 5 detected locations shown for non-provider patterns
|
||||
- Only first detected location shown for AI-detected secrets
|
||||
- Not shown in security overview summary views
|
||||
|
||||
## Paired Credentials
|
||||
|
||||
When a resource requires paired credentials (e.g., access key + secret key):
|
||||
- Alert is only created when BOTH parts are detected in the same file
|
||||
- Prevents noise from partial leaks
|
||||
- Reduces false positives
|
||||
|
||||
## Validity Checks
|
||||
|
||||
Validity checks verify whether a detected secret is still active.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Enable validity checks in repository/organization settings
|
||||
2. GitHub periodically sends the secret to the issuer's API
|
||||
3. Validation result is displayed on the alert
|
||||
|
||||
### Validation Statuses
|
||||
|
||||
| Status | Meaning | Priority |
|
||||
|---|---|---|
|
||||
| `Active` | Secret is confirmed to be valid and exploitable | 🔴 Immediate |
|
||||
| `Inactive` | Secret has been revoked or expired | 🟡 Lower priority |
|
||||
| `Unknown` | GitHub cannot determine validity | 🟠 Investigate |
|
||||
|
||||
### On-Demand Validation
|
||||
|
||||
Click the validation button on an individual alert to trigger an immediate check.
|
||||
|
||||
### Privacy
|
||||
|
||||
GitHub makes minimal API calls (typically GET requests) to the least intrusive endpoints, selecting endpoints that don't return personal information.
|
||||
|
||||
## Extended Metadata Checks
|
||||
|
||||
Provides additional context about detected secrets when validity checks are enabled.
|
||||
|
||||
### Available Metadata
|
||||
|
||||
Depends on what the service provider shares:
|
||||
- Secret owner information
|
||||
- Scope and permissions of the secret
|
||||
- Creation date and expiration
|
||||
- Associated account or project
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Deeper insight** — know who owns a secret
|
||||
- **Prioritize remediation** — understand scope and impact
|
||||
- **Improve incident response** — quickly identify responsible teams
|
||||
- **Enhance compliance** — ensure secrets align with governance policies
|
||||
- **Reduce false positives** — additional context helps determine if action is needed
|
||||
|
||||
### Enabling
|
||||
|
||||
- Requires validity checks to be enabled first
|
||||
- Can be enabled at repository, organization, or enterprise level
|
||||
- Available via security configurations for bulk enablement
|
||||
|
||||
## Remediation Workflow
|
||||
|
||||
### Priority: Rotate the Credential
|
||||
|
||||
**Always rotate (revoke and reissue) the exposed credential first.** This is more important than removing the secret from Git history.
|
||||
|
||||
### Step-by-Step Remediation
|
||||
|
||||
1. **Receive alert** — via Security tab, email notification, or webhook
|
||||
2. **Assess severity** — check validity status (active = urgent)
|
||||
3. **Rotate the credential** — revoke the old credential and generate a new one
|
||||
4. **Update references** — update all code/config that used the old credential
|
||||
5. **Investigate impact** — check logs for unauthorized use during the exposure window
|
||||
6. **Close the alert** — mark as resolved with appropriate reason
|
||||
7. **Optionally clean Git history** — remove from commit history (time-intensive)
|
||||
|
||||
### Removing Secrets from Git History
|
||||
|
||||
If needed, use `git filter-repo` (recommended) or `BFG Repo-Cleaner`:
|
||||
|
||||
```bash
|
||||
# Install git-filter-repo
|
||||
pip install git-filter-repo
|
||||
|
||||
# Remove a specific file from all history
|
||||
git filter-repo --path secrets.env --invert-paths
|
||||
|
||||
# Force push the cleaned history
|
||||
git push --force --all
|
||||
```
|
||||
|
||||
> **Note:** Rewriting history is disruptive — it invalidates existing clones and PRs. Only do this when absolutely necessary and after rotating the credential.
|
||||
|
||||
### Dismissing Alerts
|
||||
|
||||
Choose the appropriate reason:
|
||||
|
||||
| Reason | When to Use |
|
||||
|---|---|
|
||||
| **False positive** | Detected string is not a real secret |
|
||||
| **Revoked** | Credential has already been revoked/rotated |
|
||||
| **Used in tests** | Secret is only in test code with acceptable risk |
|
||||
|
||||
Add a dismissal comment for audit trail.
|
||||
|
||||
## Alert Notifications
|
||||
|
||||
Alerts generate notifications via:
|
||||
- **Email** — to repository admins, organization owners, security managers
|
||||
- **Webhooks** — `secret_scanning_alert` event
|
||||
- **GitHub Actions** — `secret_scanning_alert` event trigger
|
||||
- **Security overview** — aggregated view at organization level
|
||||
|
||||
## REST API
|
||||
|
||||
### List Alerts
|
||||
|
||||
```
|
||||
GET /repos/{owner}/{repo}/secret-scanning/alerts
|
||||
```
|
||||
|
||||
Query parameters: `state` (open/resolved), `secret_type`, `resolution`, `sort`, `direction`
|
||||
|
||||
### Get Alert Details
|
||||
|
||||
```
|
||||
GET /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}
|
||||
```
|
||||
|
||||
Returns: secret type, secret value (if permitted), locations, validity, resolution status, `dismissed_comment`
|
||||
|
||||
### Update Alert
|
||||
|
||||
```
|
||||
PATCH /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}
|
||||
```
|
||||
|
||||
Body: `state` (open/resolved), `resolution` (false_positive/revoked/used_in_tests/wont_fix), `resolution_comment`
|
||||
|
||||
### List Alert Locations
|
||||
|
||||
```
|
||||
GET /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}/locations
|
||||
```
|
||||
|
||||
Returns: file path, line numbers, commit SHA, blob SHA
|
||||
|
||||
### Organization-Level Endpoints
|
||||
|
||||
```
|
||||
GET /orgs/{org}/secret-scanning/alerts
|
||||
```
|
||||
|
||||
Lists alerts across all repositories in the organization.
|
||||
|
||||
## Webhook Events
|
||||
|
||||
### `secret_scanning_alert`
|
||||
|
||||
Triggered when a secret scanning alert is:
|
||||
- Created
|
||||
- Resolved
|
||||
- Reopened
|
||||
- Validated (validity status changes)
|
||||
|
||||
Payload includes: alert number, secret type, resolution, commit SHA, and location details.
|
||||
|
||||
## Exclusion Configuration
|
||||
|
||||
### `secret_scanning.yml`
|
||||
|
||||
Place at `.github/secret_scanning.yml` to auto-close alerts for specific paths:
|
||||
|
||||
```yaml
|
||||
paths-ignore:
|
||||
- "docs/**" # Documentation with example secrets
|
||||
- "test/fixtures/**" # Test fixture data
|
||||
- "**/*.example" # Example configuration files
|
||||
- "samples/credentials" # Sample credential files
|
||||
```
|
||||
|
||||
**Limits:**
|
||||
- Maximum 1,000 entries
|
||||
- File must be under 1 MB
|
||||
- Excluded paths are also excluded from push protection
|
||||
|
||||
**Alerts for excluded paths are closed as "ignored by configuration."**
|
||||
158
skills/secret-scanning/references/custom-patterns.md
Normal file
158
skills/secret-scanning/references/custom-patterns.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Custom Patterns Reference
|
||||
|
||||
Detailed reference for defining custom secret scanning patterns using regular expressions at the repository, organization, and enterprise level.
|
||||
|
||||
## Overview
|
||||
|
||||
Custom patterns extend secret scanning to detect organization-specific secrets not covered by default patterns. They are defined as regular expressions and can optionally enforce push protection.
|
||||
|
||||
## Pattern Definition
|
||||
|
||||
### Required Fields
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| **Pattern name** | Human-readable name for the pattern |
|
||||
| **Secret format** | Regular expression matching the secret |
|
||||
|
||||
### Optional Fields (via "More options")
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| **Before secret** | Regex for content that must appear before the secret |
|
||||
| **After secret** | Regex for content that must appear after the secret |
|
||||
| **Additional match requirements** | Extra constraints on the match |
|
||||
| **Sample test string** | Example string to validate the regex |
|
||||
|
||||
### Regex Syntax
|
||||
|
||||
Custom patterns use standard regular expressions. Common patterns:
|
||||
|
||||
```
|
||||
# API key with prefix
|
||||
MYAPP_[A-Za-z0-9]{32}
|
||||
|
||||
# Connection string
|
||||
Server=[\w.]+;Database=\w+;User Id=\w+;Password=[^;]+
|
||||
|
||||
# Internal token format
|
||||
myorg-token-[a-f0-9]{64}
|
||||
|
||||
# JWT-like pattern
|
||||
eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+
|
||||
```
|
||||
|
||||
Use filter patterns similar to GitHub Actions workflow syntax for glob-style matching in before/after fields.
|
||||
|
||||
## Defining Patterns by Scope
|
||||
|
||||
### Repository Level
|
||||
|
||||
1. Repository Settings → Advanced Security
|
||||
2. Under "Secret Protection" → Custom patterns → **New pattern**
|
||||
3. Enter pattern name, regex, and optional fields
|
||||
4. **Save and dry run** to test
|
||||
5. Review results (up to 1,000 matches)
|
||||
6. **Publish pattern** when satisfied
|
||||
7. Optionally enable push protection
|
||||
|
||||
**Prerequisite:** Secret Protection must be enabled on the repository.
|
||||
|
||||
### Organization Level
|
||||
|
||||
1. Organization Settings → Advanced Security → Global settings
|
||||
2. Under "Custom patterns" → **New pattern**
|
||||
3. Enter pattern details
|
||||
4. **Save and dry run** — select repositories for testing:
|
||||
- All repositories in the organization, or
|
||||
- Up to 10 selected repositories
|
||||
5. **Publish pattern** when satisfied
|
||||
6. Optionally enable push protection
|
||||
|
||||
**Notes:**
|
||||
- Push protection for org-level custom patterns only applies to repos with push protection enabled
|
||||
- Organization owners and repo admins receive alerts
|
||||
|
||||
### Enterprise Level
|
||||
|
||||
1. Enterprise settings → Policies → Advanced Security → Security features
|
||||
2. Under "Secret scanning custom patterns" → **New pattern**
|
||||
3. Enter pattern details
|
||||
4. **Save and dry run** — select up to 10 repositories
|
||||
5. **Publish pattern** when satisfied
|
||||
6. Optionally enable push protection
|
||||
|
||||
**Notes:**
|
||||
- Only the pattern creator can edit or dry-run enterprise-level patterns
|
||||
- Dry runs require admin access to the selected repositories
|
||||
- Push protection requires enterprise-level secret scanning push protection to be enabled
|
||||
|
||||
## Dry Run Process
|
||||
|
||||
Dry runs test patterns against repository content without creating alerts.
|
||||
|
||||
1. Click **Save and dry run** after defining the pattern
|
||||
2. Select target repositories (org/enterprise level)
|
||||
3. Click **Run**
|
||||
4. Review up to 1,000 sample results
|
||||
5. Identify false positives
|
||||
6. Edit pattern and re-run if needed
|
||||
7. **Publish pattern** only when false positive rate is acceptable
|
||||
|
||||
> Dry runs are essential — always test before publishing to avoid alert noise.
|
||||
|
||||
## Managing Published Patterns
|
||||
|
||||
### Editing Patterns
|
||||
|
||||
After publishing, patterns can be edited:
|
||||
1. Navigate to the custom pattern
|
||||
2. Modify the regex or optional fields
|
||||
3. Save and dry run to validate changes
|
||||
4. Publish the updated pattern
|
||||
|
||||
### Enabling Push Protection
|
||||
|
||||
Push protection can only be enabled after a pattern is published:
|
||||
1. Navigate to the published pattern
|
||||
2. Click **Enable** next to push protection
|
||||
|
||||
**Caution:** Enabling push protection for commonly found patterns can disrupt contributor workflows.
|
||||
|
||||
### Disabling or Deleting Patterns
|
||||
|
||||
- Disable: stops new alert generation but retains existing alerts
|
||||
- Delete: removes the pattern and stops all scanning for it
|
||||
|
||||
## Copilot-Assisted Pattern Generation
|
||||
|
||||
Use Copilot secret scanning to generate regex automatically:
|
||||
|
||||
1. Navigate to custom pattern creation
|
||||
2. Select "Generate with Copilot" (if available)
|
||||
3. Provide a text description of the secret type (e.g., "internal API key starting with MYORG_ followed by 40 hex characters")
|
||||
4. Optionally provide example strings that should match
|
||||
5. Copilot generates a regex pattern
|
||||
6. Review and refine the generated regex
|
||||
7. Test with dry run before publishing
|
||||
|
||||
## Pattern Inheritance
|
||||
|
||||
| Scope | Applies To |
|
||||
|---|---|
|
||||
| Repository | That repository only |
|
||||
| Organization | All repos in the org with secret scanning enabled |
|
||||
| Enterprise | All repos across all orgs with secret scanning enabled |
|
||||
|
||||
Organization and enterprise patterns automatically apply to new repositories when secret scanning is enabled.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always dry run** before publishing — review for false positives
|
||||
2. **Start specific** — narrow regexes reduce false positives
|
||||
3. **Use before/after context** — adds precision without overly complex regex
|
||||
4. **Test with real examples** — include sample strings that should and shouldn't match
|
||||
5. **Document patterns** — name patterns clearly so teams understand what they detect
|
||||
6. **Review periodically** — remove or update patterns that no longer apply
|
||||
7. **Be cautious with push protection** — enable only for patterns with low false positive rates
|
||||
8. **Consider Copilot** — let AI generate the initial regex, then refine manually
|
||||
164
skills/secret-scanning/references/push-protection.md
Normal file
164
skills/secret-scanning/references/push-protection.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Push Protection Reference
|
||||
|
||||
Detailed reference for GitHub push protection — preventing secrets from reaching repositories, bypass workflows, and delegated bypass configuration.
|
||||
|
||||
## How Push Protection Works
|
||||
|
||||
Push protection scans for secrets during the push process and blocks pushes containing detected secrets. It operates as a preventative control, unlike standard secret scanning which detects secrets after commit.
|
||||
|
||||
### What Gets Scanned
|
||||
|
||||
| Surface | Scanned |
|
||||
|---|---|
|
||||
| Command line pushes | ✅ |
|
||||
| GitHub UI commits | ✅ |
|
||||
| File uploads to repo | ✅ |
|
||||
| REST API content creation requests | ✅ |
|
||||
|
||||
### Types of Push Protection
|
||||
|
||||
**Repository push protection:**
|
||||
- Requires GitHub Secret Protection enabled
|
||||
- Disabled by default; enabled by repo admin, org owner, or security manager
|
||||
- Generates alerts for bypasses in the Security tab
|
||||
- Can be enabled at repository, organization, or enterprise level
|
||||
|
||||
**User push protection:**
|
||||
- Enabled by default for all GitHub.com accounts
|
||||
- Blocks pushes to public repositories containing supported secrets
|
||||
- Does NOT generate alerts when bypassed (unless repo also has push protection enabled)
|
||||
- Managed via personal account settings
|
||||
|
||||
## Resolving Blocked Pushes — Command Line
|
||||
|
||||
When push protection blocks a push, the error message includes:
|
||||
- The secret type detected
|
||||
- Commit SHAs containing the secret
|
||||
- File paths and line numbers
|
||||
- A URL to bypass (if permitted)
|
||||
|
||||
### Remove Secret from Latest Commit
|
||||
|
||||
```bash
|
||||
# Edit the file to remove the secret
|
||||
# Amend the commit
|
||||
git commit --amend --all
|
||||
|
||||
# Push again
|
||||
git push
|
||||
```
|
||||
|
||||
### Remove Secret from Earlier Commits
|
||||
|
||||
```bash
|
||||
# 1. Review the push error for all commits containing the secret
|
||||
# 2. Find the earliest commit with the secret
|
||||
git log
|
||||
|
||||
# 3. Interactive rebase before that commit
|
||||
git rebase -i <EARLIEST-COMMIT>~1
|
||||
|
||||
# 4. Change 'pick' to 'edit' for the offending commit(s)
|
||||
# 5. Remove the secret from the file
|
||||
# 6. Stage and amend
|
||||
git add .
|
||||
git commit --amend
|
||||
|
||||
# 7. Continue rebase
|
||||
git rebase --continue
|
||||
|
||||
# 8. Push
|
||||
git push
|
||||
```
|
||||
|
||||
### Bypass Push Protection
|
||||
|
||||
1. Visit the URL from the error message (must be the same user who pushed)
|
||||
2. Select a reason:
|
||||
- **It's used in tests** → creates a closed alert (resolved as "used in tests")
|
||||
- **It's a false positive** → creates a closed alert (resolved as "false positive")
|
||||
- **I'll fix it later** → creates an open alert
|
||||
3. Click **Allow me to push this secret**
|
||||
4. Re-push within **3 hours** (after that, repeat the bypass process)
|
||||
|
||||
> A bypass reason is required when the repo has secret scanning enabled. For public repos with only user push protection (no repo push protection), no reason is needed and no alert is generated.
|
||||
|
||||
## Resolving Blocked Pushes — GitHub UI
|
||||
|
||||
When creating or editing a file in the GitHub UI:
|
||||
1. A banner appears warning about the detected secret
|
||||
2. Options to remove the secret or bypass are presented inline
|
||||
3. Same bypass reasons apply as command line
|
||||
|
||||
## Resolving Blocked Pushes — REST API
|
||||
|
||||
Push protection also applies to REST API content creation endpoints. When blocked:
|
||||
- The API returns an error response with details about the detected secret
|
||||
- Include the bypass reason in the request to proceed
|
||||
|
||||
## Delegated Bypass
|
||||
|
||||
Delegated bypass gives organizations fine-grained control over who can bypass push protection.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Organization owners/repo admins create a **bypass list** of users, roles, or teams
|
||||
2. Users on the bypass list can bypass push protection directly (with a reason)
|
||||
3. All other contributors must **submit a bypass request** for review
|
||||
4. Bypass requests appear in the Security tab → "Push protection bypass" page
|
||||
5. Requests expire after **7 days** if not reviewed
|
||||
|
||||
### Who Can Always Bypass (Without Request)
|
||||
|
||||
- Organization owners
|
||||
- Security managers
|
||||
- Users in teams/roles added to the bypass list
|
||||
- Users with custom role having "review and manage secret scanning bypass requests" permission
|
||||
|
||||
### Enabling Delegated Bypass
|
||||
|
||||
**Repository level:**
|
||||
1. Settings → Advanced Security → Push protection
|
||||
2. Enable "Restrict who can bypass push protection"
|
||||
3. Add users, teams, or roles to the bypass list
|
||||
|
||||
**Organization level:**
|
||||
1. Organization Settings → Advanced Security → Global settings
|
||||
2. Configure delegated bypass in security configuration
|
||||
|
||||
### Managing Bypass Requests
|
||||
|
||||
Designated reviewers:
|
||||
1. Navigate to repository Security tab → "Push protection bypass"
|
||||
2. Review pending requests (includes the secret, commit, and contributor's comment)
|
||||
3. **Approve** — contributor can push the secret and any future commits with the same secret
|
||||
4. **Deny** — contributor must remove the secret before pushing
|
||||
|
||||
### Bypass Request Flow (Contributor Perspective)
|
||||
|
||||
1. Push is blocked; visit the URL from the error message
|
||||
2. Add a comment explaining why the secret is safe to push
|
||||
3. Click **Submit request**
|
||||
4. Wait for email notification of approval/denial
|
||||
5. If approved: push the commit
|
||||
6. If denied: remove the secret and push again
|
||||
|
||||
## Push Protection Patterns
|
||||
|
||||
Push protection supports a subset of secret scanning patterns. Not all detected secret types trigger push protection blocks.
|
||||
|
||||
Key considerations:
|
||||
- Older/legacy token formats may not be supported by push protection
|
||||
- Some patterns have higher false positive rates and are excluded from push protection
|
||||
- Custom patterns can have push protection enabled after publishing
|
||||
|
||||
For the full list of patterns supported by push protection, see [Supported secret scanning patterns](https://docs.github.com/en/code-security/secret-scanning/introduction/supported-secret-scanning-patterns).
|
||||
|
||||
## Configuring Push Protection for Custom Patterns
|
||||
|
||||
After publishing a custom pattern:
|
||||
1. Navigate to the custom pattern in Settings → Advanced Security
|
||||
2. Click **Enable** next to push protection
|
||||
3. The pattern will now block pushes containing matching secrets
|
||||
|
||||
> Push protection for custom patterns only applies to repos that have push protection enabled. Enabling push protection for commonly found patterns can be disruptive to contributors.
|
||||
Reference in New Issue
Block a user