CodeQL Code Scanning

Esta habilidade fornece orientação procedural para configurar e executar o CodeQL code scanning — tanto através de fluxos de trabalho do GitHub Actions quanto da CLI standalone do CodeQL.

Quando Usar Esta Habilidade

Use esta habilidade quando a solicitação envolver:

• Criar ou personalizar um codeql.yml fluxo de trabalho do GitHub Actions
• Escolher entre configuração padrão e configuração avançada para code scanning
• Configurar a matriz de linguagens do CodeQL, modos de compilação ou suítes de consultas
• Executar a CLI do CodeQL localmente (codeql database create, database analyze, github upload-results)
• Entender ou interpretar a saída SARIF do CodeQL
• Solucionar falhas de análise do CodeQL (modos de compilação, linguagens compiladas, requisitos do runner)
• Configurar o CodeQL para monorepos com escaneamento por componente
• Configurar cache de dependências, pacotes de consultas personalizados ou pacotes de modelos

Linguagens Suportadas

O CodeQL suporta os seguintes identificadores de linguagem:

Identificadores alternativos são equivalentes ao identificador padrão (por exemplo, javascript não exclui a análise de TypeScript).

Fluxo de Trabalho Principal — GitHub Actions

Etapa 1: Escolher o Tipo de Configuração

• Configuração padrão — Habilite em Configurações do repositório → Segurança Avançada → Análise CodeQL. Melhor para começar rapidamente. Usa o modo de compilação none para a maioria das linguagens.
• Configuração avançada — Crie um arquivo .github/workflows/codeql.yml para controle total sobre gatilhos, modos de compilação, suítes de consultas e estratégias de matriz.

Para alternar de padrão para avançado: desabilite a configuração padrão primeiro e, em seguida, confirme o arquivo de fluxo de trabalho.

Etapa 2: Configurar Gatilhos do Fluxo de Trabalho

Defina quando o escaneamento é executado:

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'  # Weekly Monday 6:30 UTC

• push — escaneia a cada push para branches especificados; os resultados aparecem na aba Segurança
• pull_request — escaneia commits de merge de PRs; os resultados aparecem como anotações de verificação de PR
• schedule — escaneamentos periódicos do branch padrão (cron deve existir no branch padrão)
• merge_group — adicione se o repositório usa filas de merge

Para pular escaneamentos para PRs apenas de documentação:

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

paths-ignore controla se o fluxo de trabalho é executado, não quais arquivos são analisados.

Etapa 3: Configurar Permissões

Defina permissões de menor privilégio:

permissions:
  security-events: write   # Required to upload SARIF results
  contents: read            # Required to checkout code
  actions: read             # Required for private repos using codeql-action

Etapa 4: Configurar Matriz de Linguagens

Use uma estratégia de matriz para analisar cada linguagem em paralelo:

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

Para linguagens compiladas, defina o build-mode apropriado:

• none — nenhuma compilação necessária (suportado para C/C++, C#, Java, Rust)
• autobuild — detecção automática de compilação
• manual — comandos de compilação personalizados (apenas configuração avançada)

Para comportamento detalhado de autobuild por linguagem e requisitos do runner, pesquise references/compiled-languages.md.

Etapa 5: Configurar Inicialização e Análise do CodeQL

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 }}"

Opções de suíte de consultas:

• security-extended — consultas de segurança padrão mais cobertura adicional
• security-and-quality — consultas de segurança mais qualidade de código
• Pacotes de consultas personalizados via entrada packs: (por exemplo, codeql/javascript-queries:AlertSuppression.ql)

…