hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-01-28 05:42:58 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Simplify getting started docs

Browse Source 
It is no longer necessary to check out a version of `github/codeql` as
a sibling directory to the distribution. Instead, users can download
the required packs as needed. using the `pack download` command or
the `--download` option for `codeql database analyze`.
This commit is contained in:
Andrew Eisenberg
2022-01-17 09:42:42 -08:00
parent 84097468cc
commit 7fcf567eda
1 changed files with 42 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
docs/codeql/codeql-cli/getting-started-with-the-codeql-cli.rst
View File

@@ -4,7 +4,7 @@ Getting started with the CodeQL CLI
===================================
To run CodeQL commands, you need to set up the CLI so that it can access
the tools, queries, and libraries required to create and analyze databases.
the tools, queries, and libraries required to create and analyze databases.
.. include:: ../reusables/license-note.rst
@@ -18,16 +18,16 @@ structures. To get started quickly, we recommend adopting a relatively simple
setup, as outlined in the steps below.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
and 4 are slightly different---for further details, see the sections labeled
follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
and 4 are slightly different---for further details, see the sections labeled
**Information for macOS "Catalina" (or newer) users**. If you are using macOS
on Apple Silicon (e.g. Apple M1), ensure that the `Xcode command-line developer
tools <https://developer.apple.com/downloads/index.action>`__ and `Rosetta 2
<https://support.apple.com/en-us/HT211861>`__ are installed.
For information about installing the CodeQL CLI in a CI system to create results
to display in GitHub as code scanning alerts, see
`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
to display in GitHub as code scanning alerts, see
`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
in the GitHub documentation.
1. Download the CodeQL CLI zip package
@@ -42,9 +42,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
There are several different versions of the CLI available to download, depending
on your use case:
- If you want to use the most up to date CodeQL tools and features, download the
version tagged ``latest``.
version tagged ``latest``.
- If you want to create CodeQL databases to upload to LGTM Enterprise, download
the version that is compatible with the relevant LGTM Enterprise version
@@ -53,9 +53,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
<https://github.com/github/codeql-cli-binaries/releases>`__ on GitHub. Using the
correct version of the CLI ensures that your CodeQL databases are
compatible with your version of LGTM Enterprise. For more information,
see `Preparing CodeQL databases to upload to LGTM
see `Preparing CodeQL databases to upload to LGTM
<https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
in the LGTM admin help.
in the LGTM admin help.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
`download the zip archive
@@ -72,97 +72,23 @@ Alternatively, you can download ``codeql.zip``, which contains the CLI for all s
**Information for macOS "Catalina" (or newer) users**
.. pull-quote:: macOS "Catalina" (or newer)
If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
version 12 ("Monterey"), you need to ensure that your web browser does not automatically
extract zip files. If you use Safari, complete the following steps before downloading
If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
version 12 ("Monterey"), you need to ensure that your web browser does not automatically
extract zip files. If you use Safari, complete the following steps before downloading
the CodeQL CLI zip archive:
i. Open Safari.
ii. From the Safari menu, select **Preferences...**.
iii. Click the **General** Tab.
iv. Ensure the check-box labeled **Open "safe" files after downloading**.
is unchecked.
2. Create a new CodeQL directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a new directory where you can place the CLI and any queries and libraries
you want to use. For example, ``$HOME/codeql-home``.
The CLI's built-in search operations automatically look in all of its sibling
directories for the files used in database creation and analysis. Keeping these
components in their own directory prevents the CLI searching unrelated sibling
directories while ensuring all files are available without specifying any
further options on the command line.
.. _local-copy-codeql-queries:
3. Obtain a local copy of the CodeQL queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `CodeQL repository <https://github.com/github/codeql>`__ contains
the queries and libraries required for CodeQL analysis of C/C++, C#, Java,
JavaScript/TypeScript, Python, and Ruby.
Clone a copy of this repository into ``codeql-home``.
By default, the root of the cloned repository will be called ``codeql``.
Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL
CLI that you will extract in step 4. If you use git on the command line, you can
clone and rename the repository in a single step by running
``git clone git@github.com:github/codeql.git codeql-repo`` in the ``codeql-home`` folder.
The CodeQL libraries and queries for Go analysis live in the `CodeQL for Go
repository <https://github.com/github/codeql-go/>`__. Clone a copy of this
repository into ``codeql-home``.
The cloned repositories should have a sibling relationship.
For example, if the root of the cloned CodeQL repository is
``$HOME/codeql-home/codeql-repo``, then the root of the cloned CodeQL for Go
repository should be ``$HOME/codeql-home/codeql-go``.
Within these repositories, the queries and libraries are organized into QL
packs. Along with the queries themselves, QL packs contain important metadata
that tells the CodeQL CLI how to process the query files. For more information,
see ":doc:`About QL packs <about-ql-packs>`."
.. pull-quote:: Important
There are different versions of the CodeQL queries available for different
users. Check out the correct version for your use case:
- For the queries used on `LGTM.com <https://lgtm.com>`__, check out the
``lgtm.com`` branch. You should use this branch for databases you've built
using the CodeQL CLI, fetched from code scanning on GitHub, or recently downloaded from LGTM.com.
The queries on the ``lgtm.com`` branch are more likely to be compatible
with the ``latest`` CLI, so you'll be less likely to have to upgrade
newly-created databases than if you use the ``main`` branch. Older databases
may need to be upgraded before you can analyze them.
- For the most up to date CodeQL queries, check out the ``main`` branch.
This branch represents the very latest version of CodeQL's analysis. Even
databases created using the most recent version of the CLI may have to be
upgraded before you can analyze them. For more information, see
":doc:`Upgrading CodeQL databases <upgrading-codeql-databases>`."
- For the queries used in a particular LGTM Enterprise release, check out the
branch tagged with the relevant release number. For example, the branch
tagged ``v1.27.0`` corresponds to LGTM Enterprise 1.27. You must use this
version if you want to upload data to LGTM Enterprise. For further
information, see `Preparing CodeQL databases to upload to LGTM
<https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
in the LGTM admin help.
4. Extract the zip archive
2. Extract the zip archive
~~~~~~~~~~~~~~~~~~~~~~~~~~
For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
simply
extract the zip archive into the directory you created in step 2.
For example, if the path to your copy of the CodeQL repository is
``$HOME/codeql-home/codeql-repo``, then extract the CLI into
``$HOME/codeql-home/``.
For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
simply extract the zip archive.
.. container:: toggle
@@ -171,17 +97,17 @@ For example, if the path to your copy of the CodeQL repository is
**Information for macOS "Catalina" (or newer) users**
.. pull-quote:: macOS "Catalina"
macOS "Catalina", "Big Sur", or "Monterey" users should run the following
commands in the Terminal, where ``${install_loc}`` is the path to the
directory you created in step 2:
i. ``mv ~/Downloads/codeql*.zip ${install_loc}``
ii. ``cd ${install_loc}``
macOS "Catalina", "Big Sur", or "Monterey" users should run the following
commands in the Terminal, where ``${extraction-root}`` is the path to the
directory where you will extract the CodeQL CLI zip archive:
i. ``mv ~/Downloads/codeql*.zip ${extraction-root}``
ii. ``cd ${extraction-root}``
iii. ``/usr/bin/xattr -c codeql*.zip``
iv. ``unzip codeql*.zip``
5. Launch ``codeql``
3. Launch ``codeql``
~~~~~~~~~~~~~~~~~~~~
Once extracted, you can run CodeQL processes by running the ``codeql``
@@ -191,7 +117,7 @@ executable in a couple of ways:
``<extraction-root>`` is the folder where you extracted the CodeQL CLI
package.
- By adding ``<extraction-root>/codeql`` to your ``PATH``, so that you
can run the executable as just ``codeql``.
can run the executable as just ``codeql``.
At this point, you can execute CodeQL commands. For a full list of the CodeQL
CLI commands, see the "`CodeQL CLI manual <../manual>`__."
@@ -204,7 +130,7 @@ CLI commands, see the "`CodeQL CLI manual <../manual>`__."
":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."
6. Verify your CodeQL CLI setup
4. Verify your CodeQL CLI setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CodeQL CLI has subcommands you can execute to verify that you are correctly set
@@ -212,17 +138,20 @@ up to create and analyze databases:
- Run ``codeql resolve languages`` to show which languages are
available for database creation. This will list the languages supported by
default in your CodeQL CLI package.
- Run ``codeql resolve qlpacks`` to show which QL packs the CLI can find. This
will display the names of the QL packs included in the CodeQL repositories:
``codeql-cpp``, ``codeql-csharp``, ``codeql-go``,
``codeql-java``, ``codeql-javascript``, and ``codeql-python``. The CodeQL
repositories also contain 'upgrade' packs and 'legacy' packs. Upgrade packs
are used by the CLI when you want to upgrade a database so that it can be
analyzed with a newer version of the CodeQL toolchain than was used to create
it. Legacy packs ensure that custom queries and libraries created using older
products are compatible with your version of CodeQL.
default in your CodeQL CLI package.
- (Optional) You can download some ":ref"`CodeQL packs <about-codeql-packs>` containing pre-compiled queries you would like to run.
To do this, run ``codeql pack download <pack-name> [...pack-name]``, where ``pack-name`` is the name of
the pack you want to download. The core query packs are a good place to start. They are:
- ``codeql/cpp-queries``
- ``codeql/csharp-queries``
- ``codeql/java-queries``
- ``codeql/javascript-queries``
- ``codeql/python-queries``
- ``codeql/ruby-queries``
Alternatively, you can download query packs during the analysis by using the `--download` flag of the `codeql database analyze`
command.
.. _using-two-versions-of-the-codeql-cli:
@@ -242,4 +171,4 @@ recommended directory setup depends on which versions you want to install:
directory. For example, if you unpack version 2.0.2 into
``$HOME/codeql-home/codeql-cli``, the older version should be
unpacked into ``$HOME/codeql-older-version/old-codeql-cli``. Here, the common
grandparent is the ``$HOME`` directory.
grandparent is the ``$HOME`` directory.