You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
+24-25Lines changed: 24 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -56,6 +56,12 @@ You must specify:
56
56
57
57
You can also specify:
58
58
59
+
- ``--sarif-category``: an identifying category for the results. Used when
60
+
you want to upload more than one set of results for a commit.
61
+
For example, when you use ``github upload-results`` to send results for more than one
62
+
language to the GitHub code scanning API. For more information about this use case,
63
+
see `Configuring CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system>`__ in the GitHub documentation.
The analysis generates a file in the v2.1.0 SARIF format that is supported by all versions of GitHub.
120
+
This file can be uploaded to GitHub using ``github upload-results`` or the code scanning API.
121
+
For more information, see `Analyzing a CodeQL database <https://docs.github.com/en/code-security/secure-coding/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__
122
+
or `Code scanning API <https://docs.github.com/en/rest/reference/code-scanning>`__ in the GitHub documentation.
112
123
113
-
The CodeQL repository includes query suites that are used by the CodeQL action on
114
-
`GitHub.com <https://github.com>`__. The query suites are located at the following paths in
124
+
CodeQL query suites are ``.qls`` files that use directives to select queries to run
125
+
based on certain metadata properties. The standard QL packs have metadata that specify
126
+
the location of the code scanning suites, so the CodeQL CLI knows where to find these
127
+
suite files automatically, and you don't have to specify the full path on the command line.
128
+
For more information, see ":ref:`About QL packs <standard-ql-packs>`."
129
+
130
+
The standard query suites are stored at the following paths in
@@ -120,23 +136,6 @@ and at the following path in the CodeQL for Go repository::
120
136
121
137
ql/src/codeql-suites/go-code-scanning.qls
122
138
123
-
These locations are specified in the metadata included in the standard QL packs.
124
-
This means that the CodeQL CLI knows where to find the suite files automatically, and
125
-
you don't have to specify the full path on the command line when running an
126
-
analysis. For more information, see ":ref:`About QL packs <standard-ql-packs>`."
127
-
128
-
.. pull-quote::
129
-
130
-
Important
131
-
132
-
If you plan to upload the results to GitHub, you must generate SARIF results.
133
-
For more information, see `Analyzing a CodeQL database <https://docs.github.com/en/code-security/secure-coding/running-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__ in the GitHub documentation.
134
-
135
-
For example, to run the code scanning query suite on a C++ codebase and generate
136
-
results in the v2.1 SARIF format supported by all versions of GitHub, you would run::
Copy file name to clipboardExpand all lines: docs/codeql/codeql-cli/creating-codeql-databases.rst
+49-29Lines changed: 49 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,6 +17,12 @@ Before you generate a CodeQL database, you need to:
17
17
- Check out the version of your codebase you want to analyze. The directory
18
18
should be ready to build, with all dependencies already installed.
19
19
20
+
For information about using the CodeQL CLI in a third-party CI system to create results
21
+
to display in GitHub as code scanning alerts, see `Configuring CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system>`__
22
+
in the GitHub documentation. For information about enabling CodeQL code scanning using GitHub Actions,
23
+
see `Setting up code scanning for a repository <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository>`__
24
+
in the GitHub documentation.
25
+
20
26
Running ``codeql database create``
21
27
----------------------------------
22
28
@@ -33,21 +39,30 @@ You must specify:
33
39
be created when you execute the command---you cannot specify an existing
34
40
directory.
35
41
- ``--language``: the identifier for the language to create a database for.
42
+
When used with ``--db-cluster``, the option accepts a comma-separated list,
43
+
or can be specified more than once.
36
44
CodeQL supports creating databases for the following languages:
37
45
38
46
.. include:: ../reusables/extractors.rst
39
47
40
-
Other options may be specified depending on the location of your source file and
41
-
the language you want to analyze:
48
+
You can specify additional options depending on the location of your source file,
49
+
if the code needs to be compiled, and if you want to create CodeQL databases for
50
+
more than one language:
42
51
43
52
- ``--source-root``: the root folder for the primary source files used in
44
53
database creation. By default, the command assumes that the current
45
54
directory is the source root---use this option to specify a different location.
46
-
- ``--command``: for compiled languages only, the build commands that invoke the
47
-
compiler. Do not specify ``--command`` options for Python and
48
-
JavaScript. Commands will be run from the current folder, or ``--source-root``
55
+
- ``--db-cluster``: use for multi-language codebases when you want to create
56
+
databases for more than one language.
57
+
- ``--command``: used when you create a database for one or more compiled languages,
58
+
omit if the only languages requested are Python and JavaScript.
59
+
This specifies the build commands needed to invoke the compiler.
60
+
Commands are run from the current folder, or ``--source-root``
49
61
if specified. If you don't include a ``--command``, CodeQL will attempt to
50
62
detect the build system automatically, using a built-in autobuilder.
63
+
- ``--no-run-unnecessary-builds``: used with ``--db-cluster`` to suppress the build
64
+
command for languages where the CodeQL CLI does not need to monitor the build
65
+
(for example, Python and JavaScript/TypeScript).
51
66
52
67
For full details of all the options you can use when creating databases,
53
68
see the `database create reference documentation <../manual/database-create>`__.
@@ -62,31 +77,13 @@ it failed. For compiled languages, the console will display the output of the
62
77
build system.
63
78
64
79
When the database is successfully created, you'll find a new directory at the
65
-
path specified in the command. This directory contains a number of
80
+
path specified in the command. If you used the ``--db-cluster`` option to create
81
+
more than one database, a subdirectory is created for each language.
82
+
Each CodeQL database directory contains a number of
66
83
subdirectories, including the relational data (required for analysis) and a
67
84
source archive---a copy of the source files made at the time the database was
68
85
created---which is used for displaying analysis results.
69
86
70
-
Obtaining databases from LGTM.com
71
-
---------------------------------
72
-
73
-
`LGTM.com <https://lgtm.com>`__ analyzes thousands of open-source projects using
74
-
CodeQL. For each project on LGTM.com, you can download an archived CodeQL
75
-
database corresponding to the most recently analyzed revision of the code. These
76
-
databases can also be analyzed using the CodeQL CLI.
Copy file name to clipboardExpand all lines: docs/codeql/codeql-cli/getting-started-with-the-codeql-cli.rst
+5Lines changed: 5 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,6 +22,11 @@ follow the steps below. For macOS version 10.15 ("Catalina"), steps 1 and 4 are
22
22
slightly different---for further details, see the sections labeled **Information
23
23
for macOS "Catalina" users**.
24
24
25
+
For information about installing the CodeQL CLI in a CI system to create results
26
+
to display in GitHub as code scanning alerts, see
27
+
`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>`__
Copy file name to clipboardExpand all lines: docs/codeql/writing-codeql-queries/about-codeql-queries.rst
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ CodeQL includes queries to find the most relevant and interesting problems for e
13
13
- **Alert queries**: queries that highlight issues in specific locations in your code.
14
14
- **Path queries**: queries that describe the flow of information between a source and a sink in your code.
15
15
16
-
You can add custom queries to :doc:`QL packs <../codeql-cli/about-ql-packs>` to analyze your projects with "`Code scanning <https://docs.github.com/github/finding-security-vulnerabilities-and-errors-in-your-code>`__", use them to analyze a database with the ":ref:`CodeQL CLI <codeql-cli>`," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__.
16
+
You can add custom queries to :doc:`QL packs <../codeql-cli/about-ql-packs>` to analyze your projects with "`Code scanning <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning>`__", use them to analyze a database with the ":ref:`CodeQL CLI <codeql-cli>`," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__.
17
17
18
18
This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages in the ":ref:`CodeQL language guides <codeql-language-guides>`," and detailed technical information about QL in the ":ref:`QL language reference <ql-language-reference>`."
19
19
For more information on how to format your code when contributing queries to the GitHub repository, see the `CodeQL style guide <https://github.com/github/codeql/blob/main/docs/ql-style-guide.md>`__.
0 commit comments