Nota: Tu administrador de sitio debe habilitar el escaneo de código para tu instancia de GitHub Enterprise Server antes de que puedas utilizar esta característica. Para obtener más información, consulta "Configurar el escaneo de código en tu aplicativo."
Note: This article describes features present in the version of CodeQL CLI available at the time of the release of GitHub Enterprise Server. If your enterprise uses a more recent version of CodeQL CLI, see the Nube de GitHub Enterprise documentation instead.
About generating code scanning results with CodeQL CLI
Once you've made the CodeQL CLI available to servers in your CI system, and ensured that they can authenticate with GitHub Enterprise Server, you're ready to generate data.
You use three different commands to generate results and upload them to GitHub Enterprise Server:
database create
to create a CodeQL database to represent the hierarchical structure of a supported programming language in the repository.database analyze
to run queries to analyze the CodeQL database and summarize the results in a SARIF file.github upload-results
to upload the resulting SARIF file to GitHub Enterprise Server where the results are matched to a branch or pull request and displayed as escaneo de código alerts.
You can display the command-line help for any command using the --help
Nota: El cargar datos de SARIF para mostrarlos como resultados del escaneo de código eb GitHub Enterprise Server es compatible para los repositorios que pertenezcan a organizaciones con la GitHub Advanced Security habilitada. Para obtener más información, consulta la sección "Administrar la configuración de seguridad y análisis para tu repositorio".
Creating CodeQL databases to analyze
-
Check out the code that you want to analyze:
- For a branch, check out the head of the branch that you want to analyze.
- For a pull request, check out either the head commit of the pull request, or check out a GitHub-generated merge commit of the pull request.
-
Set up the environment for the codebase, making sure that any dependencies are available. For more information, see Creating databases for non-compiled languages and Creating databases for compiled languages in the documentation for the CodeQL CLI.
-
Find the build command, if any, for the codebase. Typically this is available in a configuration file in the CI system.
-
Run
codeql database create
from the checkout root of your repository and build the codebase.codeql database create <database> --command<build> --language=<language-identifier>
Note: If you use a containerized build, you need to run the CodeQL CLI inside the container where your build task takes place.
Option | Required | Usage |
---|---|---|
<database> | Specify the name and location of a directory to create for the CodeQL database. The command will fail if you try to overwrite an existing directory. If you also specify --db-cluster , this is the parent directory and a subdirectory is created for each language analyzed. | |
--language | Specify the identifier for the language to create a database for, one of: cpp`, `csharp`, `go`, `java`, `javascript`, y `python (use javascript to analyze TypeScript code). | |
--command | Recommended. Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from --source-root | |
--source-root | Optional. Use if you run the CLI outside the checkout root of the repository. By default, the database create command assumes that the current directory is the root directory for the source files, use this option to specify a different location. |
For more information, see Creating CodeQL databases in the documentation for the CodeQL CLI.
Basic example
This example creates a CodeQL database for the repository checked out at /checkouts/example-repo
. It uses the JavaScript extractor to create a hierarchical representation of the JavaScript and TypeScript code in the repository. The resulting database is stored in /codeql-dbs/example-repo
.
$ codeql database create /codeql-dbs/example-repo --language=javascript \
--source-root /checkouts/example-repo
> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.
Analyzing a CodeQL database
- Create a CodeQL database (see above).
- Run
codeql database analyze
on the database and specify which queries to use.codeql database analyze <database> --format=<format> \ --output=<output> <queries>
Option | Required | Usage |
---|---|---|
<database> | Specify the path for the directory that contains the CodeQL database to analyze. | |
<packs,queries> | Specify CodeQL packs or queries to run. To run the standard queries used for escaneo de código, omit this parameter. To see the other query suites included in the CodeQL CLI bundle, look in /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites . For information about creating your own query suite, see Creating CodeQL query suites in the documentation for the CodeQL CLI. | |
--format | Specify the format for the results file generated by the command. For upload to GitHub this should be: sarifv2.1.0 . For more information, see "SARIF support for escaneo de código." | |
--output | Specify where to save the SARIF results file. | |
--threads | Optional. Use if you want to use more than one thread to run queries. The default value is 1 . You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify 0 . | |
--verbose | Optional. Use to get more detailed information about the analysis process. |
For more information, see Analyzing databases with the CodeQL CLI in the documentation for the CodeQL CLI.
Basic example
This example analyzes a CodeQL database stored at /codeql-dbs/example-repo
and saves the results as a SARIF file: /temp/example-repo-js.sarif
.
$ codeql database analyze /codeql-dbs/example-repo \
javascript-code-scanning.qls
--format=sarifv2.1.0 --output=/temp/example-repo-js.sarif
> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.
Uploading results to GitHub Enterprise Server
Notas:
-
La carga de SARIF es compatible con un máximo de 1000 resultados por carga. Cualquier resultado que sobrepase este límite se ignorará. Si una herramienta genera demasiados resultados, debes actualizar la configuración para enfocarte en los resultados de las reglas o consultas más importantes.
-
Para cada carga, la carga de SARIF es compatible con un tamaño máximo de 10 MB para el archivo comprimido de
gzip
. Cualquier carga que esté sobre este límite, se rechazará. Si tu archivo SARIF es demasiado grande porque contiene demasiados resultados, debes actualizar la configuración para enfocarte en los resultados de las reglas o consultas más importantes.
Before you can upload results to GitHub Enterprise Server, you must determine the best way to pass the GitHub App or personal access token you created earlier to the CodeQL CLI (see Installing CodeQL CLI in your CI system). We recommend that you review your CI system's guidance on the secure use of a secret store. The CodeQL CLI supports:
- Passing the token to the CLI via standard input using the
--github-auth-stdin
option (recommended). - Saving the secret in the environment variable
GITHUB_TOKEN
and running the CLI without including the--github-auth-stdin
option.
When you have decided on the most secure and reliable method for your CI server, run codeql github upload-results
on each SARIF results file and include --github-auth-stdin
unless the token is available in the environment variable GITHUB_TOKEN
.
echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
--ref=<ref> --commit=<commit> --sarif=<file> \
--github-auth-stdin
Option | Required | Usage |
---|---|---|
--repository | Specify the OWNER/NAME of the repository to upload data to. The owner must be an organization within an enterprise that has a license for GitHub Advanced Security and GitHub Advanced Security must be enabled for the repository. For more information, see "Managing security and analysis settings for your repository." | |
--ref | Specify the name of the ref you checked out and analyzed so that the results can be matched to the correct code. For a branch use: refs/heads/BRANCH-NAME , for the head commit of a pull request use refs/pull/NUMBER/head , or for the GitHub-generated merge commit of a pull request use refs/pull/NUMBER/merge . | |
--commit | Specify the full SHA of the commit you analyzed. | |
--sarif | Specify the SARIF file to load. | |
--github-auth-stdin | Optional. Use to pass the CLI the GitHub App or personal access token created for authentication with GitHub's REST API via standard input. This is not needed if the command has access to a GITHUB_TOKEN environment variable set with this token. |
For more information, see github upload-results in the documentation for the CodeQL CLI.
Basic example
This example uploads results from the SARIF file temp/example-repo-js.sarif
to the repository my-org/example-repo
. It tells the escaneo de código API that the results are for the commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718
on the main
branch.
$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=/temp/example-repo-js.sarif --github-auth-stdin
There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the escaneo de código alerts in GitHub Enterprise Server shortly afterward. You can see alerts directly in the pull request or on the Security tab for branches, depending on the code you checked out. For more information, see "Triaging escaneo de código alerts in pull requests" and "Managing escaneo de código alerts for your repository."