Sobre os pacotes do CodeQL
Observação: este artigo descreve os recursos disponíveis com o pacote CodeQL CLI 2.17.6 incluído na versão inicial de GitHub Enterprise Server 3.14.
Se o administrador do site atualizou a versão do CodeQL CLI para uma mais recente, confira a versão GitHub Enterprise Cloud deste artigo para obter informações sobre os recursos mais recentes.
Os pacotes do CodeQL são usados para criar, compartilhar, gerar dependência e executar consultas e bibliotecas do CodeQL. Os pacotes do CodeQL contêm consultas, arquivos de biblioteca, conjuntos de consultas e metadados. Você pode personalizar suas análises do CodeQL baixando pacotes criados por outras pessoas e executando-os em sua base de código.
Existem três tipos de pacotes do CodeQL: pacotes de consultas, pacotes de bibliotecas e pacotes de modelos.
-
Os pacotes de consulta contêm um conjunto de consultas pré-compiladas que podem ser avaliadas em um banco de dados do CodeQL. Os pacotes de consultas foram projetados para serem executados. Quando um pacote de consultas é publicado, o pacote inclui todas as dependências transitivas e representações pré-compiladas de cada consulta, além das fontes de consulta. Isso garante a execução consistente e eficiente das consultas no pacote.
-
Os pacotes de biblioteca são projetados para serem usados por pacotes de consultas (ou outros pacotes de biblioteca) e não contêm consultas. As bibliotecas não são compiladas separadamente.
-
Pacotes de modelos podem ser usados para expandir análises do code scanning para reconhecer bibliotecas e estruturas para as quais não há suporte por padrão. Pacotes de modelos estão atualmente em beta e sujeitos a alterações. Durante o beta, os pacotes de modelo estão disponíveis para análise do C#, Java/Kotlin, e Ruby. Para obter mais informações sobre como criar seus próprios pacotes de modelo, confira "Como criar e trabalhar com pacotes do CodeQL".
Os pacotes padrão do CodeQL para todas as linguagens com suporte estão publicados no Container registry. Se você instalou a CodeQL CLI da maneira padrão, usando o pacote da CodeQL CLI, os pacotes de consulta principais já foram baixados e já estão disponíveis. Eles são:
codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
codeql/swift-queries
Você também pode usar a CodeQL CLI para criar seus próprios pacotes do CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Para obter mais informações, confira "Como criar e trabalhar com pacotes do CodeQL".
Você pode publicar os pacotes do CodeQL que criou, usando a CodeQL CLI. Para obter mais informações sobre a publicação e o download de pacotes do CodeQL, consulte "Publicar e usar pacotes do CodeQL".
Fazendo o download e usando pacotes de consulta de CodeQL
O pacote de CodeQL CLI inclui consultas mantidas por especialistas de GitHub, pesquisadores de segurança e contribuidores da comunidade. Se você quiser executar consultas desenvolvidas por outras organizações, os pacotes de consulta do CodeQL fornecem uma maneira eficiente e confiável de baixar e executar consultas, enquanto os pacotes de modelo (beta) podem ser usados para expandir análises do code scanning para reconhecer bibliotecas e estruturas que não tiverem suporte por padrão. Para obter mais informações sobre pacotes de consulta, confira "Sobre a varredura de código com CodeQL". Para informações sobre como escrever seus próprios pacotes de modelos, consulte "Como criar e trabalhar com pacotes do CodeQL".
Antes de usar um pacote de consultas do CodeQL para analisar um banco de dados, você deve baixar os pacotes necessários do GitHub Container registry. Isso pode ser feito usando o sinalizador --download
como parte do comando codeql database analyze
ou executando codeql pack download
. Se um pacote não estiver disponível publicamente, você precisará usar um GitHub App ou um personal access token para fazer a autenticação. Para obter mais informações e um exemplo, confira "Como carregar os resultados da análise do CodeQL no GitHub".
Opção | Obrigatório | Uso |
---|---|---|
<scope/name@version:path> | Especifique o escopo e o nome de um ou mais pacotes de consulta CodeQL para fazer o download usando uma lista separada por vírgulas. Opcionalmente, inclua a versão para fazer o download e descompactar. Por padrão, a versão mais recente deste pacote foi baixada. Opcionalmente, inclua um caminho para um conjunto de consultas, diretórios ou consultas a serem executadas. Se nenhum caminho for incluído, execute as consultas padrão deste pacote. | |
--github-auth-stdin | Passe a CLI pelo GitHub App ou o personal access token já criado para autenticação com a API REST de GitHub do repositório de segredo por meio da entrada padrão. Isso não será necessário se o comando tiver acesso a uma variável de ambiente GITHUB_TOKEN definida com esse token. |
Observação: se você especificar uma versão específica de um pacote de consultas a ser usada, lembre-se de que a versão especificada pode acabar ficando muito antiga em relação à versão mais recente do CodeQL para garantir um uso eficiente. Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, reavalie quais versões fixar sempre que atualizar a CodeQL CLI que você está usando.
Para obter mais informações sobre a compatibilidade de pacotes, confira "Publicar e usar pacotes do CodeQL".
Exemplo básico do download e uso de pacotes de consulta
Este exemplo executa o comando codeql database analyze
com a opção --download
para:
- Baixar a versão mais recente do pacote
octo-org/security-queries
. - Baixar uma versão do pacote
octo-org/optional-security-queries
que seja compativel com a versão 1.0.1 (nesse caso, é a versão 1.0.2). Para obter mais informações sobre compatibilidade semver, confira a documentação do intervalo de versão semântica do npm. - Execute todas as consultas padrão em
octo-org/security-queries
. - Executar somente a consulta
queries/csrf.ql
deocto-org/optional-security-queries
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
octo-org/security-queries \
octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
--format=sarif-latest --output=/temp/example-repo-js.sarif
> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.
Download direto de pacotes CodeQL
Se você quiser baixar um pacote CodeQL sem executá-lo imediatamente, poderá usar o comando codeql pack download
. Isso será útil se você quiser evitar acessar a Internet ao executar consultas CodeQL. Ao executar a análise CodeQL, você pode especificar pacotes, versões e caminhos da mesma forma que no exemplo anterior:
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
Baixar pacotes do CodeQL de vários registros de contêiner do GitHub
Se os pacotes do CodeQL residirem em vários registros de contêiner, você precisará instruir a CodeQL CLI onde localizar cada pacote. Para obter mais informações, confira "Personalizando a configuração avançada para varredura de código".
Como especificar quais consultas devem ser executadas em um pacote do CodeQL
Os especificadores de consulta são usados por codeql database analyze
e outros comandos que operam em um conjunto de consultas.
A forma completa de um especificador de consulta é scope/name@range:path
, em que:
scope/name
é o nome qualificado de um pacote do CodeQL.range
é um intervalo semver.path
é um caminho do sistema de arquivos para uma só consulta, um diretório que contém consultas ou um arquivo de conjunto de consultas.
Quando você especifica scope/name
, range
e path
são opcionais. Se você omitir um range
, a versão mais recente do pacote especificado será usada. Se você omitir um path
, o conjunto de consultas padrão do pacote especificado será usado.
O pode path
ser um dos seguintes: um arquivo de consulta .ql
, um diretório que contém uma ou mais consultas ou um arquivo de conjunto de consultas .qls
. Se você omitir um nome de pacote, precisará fornecer um path
, que será interpretado em relação ao diretório de trabalho do processo atual. Não há suporte para padrões glob.
Se você especificar scope/name
e path
, o path
não poderá ser absoluto. Ele é considerado relativo à raiz do pacote do CodeQL.
Especificadores de consulta de exemplo
-
codeql/python-queries
– Todas as consultas no pacote de consultas padrão da versão mais recente do pacotecodeql/python-queries
. -
codeql/python-queries@1.2.3
– Todas as consultas no pacote de consultas padrão da versão1.2.3
do pacotecodeql/python-queries
. -
codeql/python-queries@~1.2.3
– Todas as consultas no conjunto de consultas padrão da versão mais recente do pacotecodeql/python-queries
que são >=1.2.3
e <1.3.0
. -
codeql/python-queries:Functions
– Todas as consultas no diretórioFunctions
na versão mais recente do pacotecodeql/python-queries
. -
codeql/python-queries@1.2.3:Functions
– Todas as consultas no diretórioFunctions
da versão 1.2.3 do pacotecodeql/python-queries
. -
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls
– Todas as consultas no diretóriocodeql-suites/python-code-scanning.qls
da versão 1.2.3 do pacotecodeql/python-queries
. -
suites/my-suite.qls
– Todas as consultas no arquivosuites/my-suite.qls
relativas ao diretório de trabalho atual.
Dica
O conjunto de consultas padrão dos pacotes de consultas padrão do CodeQL são codeql-suites/<lang>-code-scanning.qls
. Vários outros pacotes de consultas úteis também podem ser encontrados no diretório codeql-suites
de cada pacote. Por exemplo, o pacote codeql/cpp-queries
contém os seguintes conjuntos de consultas:
-
cpp-code-scanning.qls
– Consultas de verificação de código padrão para C++. O conjunto de consultas padrão desse pacote. -
cpp-security-extended.qls
– Consultas do conjunto padrãocpp-code-scanning.qls
para C++, além de consultas de gravidade e precisão inferiores. -
cpp-security-and-quality.qls
– Consultas decpp-security-extended.qls
, além de consultas de capacidade de manutenção e confiabilidade.
Você pode ver as fontes desses conjuntos de consultas no repositório do CodeQL. Os pacotes de consultas para outras linguagens são semelhantes.
Usando pacotes de modelo para analisar chamadas a dependências personalizadas
Você pode incluir pacotes de modelos publicados em uma análise do code scanning com a opção --model-packs
. Por exemplo:
$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
--model-packs my-repo/my-java-model-pack \
--output=/temp/my-company.sarif codeql/java-queries
Neste exemplo, as consultas relevantes no pacote de consultas padrão codeql/java-queries
usarão as informações de dependência do pacote de modelos, my-repo/my-java-model-pack
, para verificar vulnerabilidades no código que chama essas dependências.
Você pode especificar vários pacotes de modelos publicados em uma análise.
Para obter mais informações sobre como gravar seus próprios pacotes de modelos, consulte "Como criar e trabalhar com pacotes do CodeQL".
Sobre pacotes publicados
Quando um pacote é publicado para uso em análises, o comando codeql pack create
ou codeql pack publish
verifica se o conteúdo está completo e também adiciona mais conteúdo a ele:
-
Para pacotes de consulta, uma cópia de cada um dos pacotes de biblioteca dos quais eles dependem, nas versões precisas com as quais eles foram desenvolvidos. Os usuários do pacote de consultas não precisarão baixar esses pacotes de biblioteca separadamente.
-
Para pacotes de consulta, representações pré-compiladas de cada uma das consultas. É mais rápido executá-las do que compilar a origem do QL para a consulta em cada análise.
A maioria desses dados está localizada em um diretório chamado .codeql
no pacote publicado, mas as consultas pré-compiladas estão em arquivos com um sufixo .qlx
ao lado da origem .ql
de cada consulta. Ao analisar um banco de dados com uma consulta de um pacote publicado, o CodeQL carregará esses arquivos em vez da origem do .ql
. Se você precisar modificar o conteúdo de um pacote publicado, remova todos os arquivos .qlx
, pois eles podem impedir que as modificações nos arquivos .ql
entrem em vigor.