Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 499fa76

Browse filesBrowse files
lcarteylcartey
committed
Update user manual with CodeQL packs
1 parent eee6399 commit 499fa76
Copy full SHA for 499fa76

File tree

Expand file treeCollapse file tree

2 files changed

+86
-16
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+86
-16
lines changed

‎docs/user_manual.md

Copy file name to clipboardExpand all lines: docs/user_manual.md
+85-16Lines changed: 85 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,15 @@
2929
| 0.21.0 | 2024-05-01 | Luke Cartey | Add MISRA C++ 2023 as under development, and clarify MISRA C 2012 coverage. |
3030
| 0.22.0 | 2024-10-02 | Luke Cartey | Add MISRA C 2023 as under development, and clarify MISRA C 2012 coverage. |
3131
| 0.23.0 | 2024-10-21 | Luke Cartey | Add assembly as a hazard. |
32+
| 0.24.0 | 2024-10-22 | Luke Cartey | Add CodeQL packs as a usable output, update release artifacts list. |
3233

3334
## Release information
3435

3536
This user manual documents release `2.37.0-dev` of the coding standards located at [https://github.com/github/codeql-coding-standards](https://github.com/github/codeql-coding-standards).
3637
The release page documents the release notes and contains the following artifacts part of the release:
3738

38-
- `code-scanning-cpp-query-pack-2.37.0-dev.zip`: coding standard queries and scripts to be used with GitHub Code Scanning or the CodeQL CLI as documented in the section _Operating manual_.
39+
- `coding-standards-codeql-packs-2.37.0-dev.zip`: CodeQL packs that can be used with GitHub Code Scanning or the CodeQL CLI as documented in the section _Operating manual_.
40+
- `code-scanning-cpp-query-pack-2.37.0-dev.zip`: Legacy packaging for the queries and scripts to be used with GitHub Code Scanning or the CodeQL CLI as documented in the section _Operating manual_.
3941
- `supported_rules_list_2.37.0-dev.csv`: A Comma Separated File (CSV) containing the supported rules per standard and the queries that implement the rule.
4042
- `supported_rules_list_2.37.0-dev.md`: A Markdown formatted file with a table containing the supported rules per standard and the queries that implement the rule.
4143
- `user_manual_2.37.0-dev.md`: This user manual.
@@ -158,22 +160,52 @@ This section describes how to operate the "CodeQL Coding Standards".
158160

159161
#### Pre-requisite: downloading the CodeQL CLI
160162

161-
You must download a compatible version of the CodeQL CLI and CodeQL Standard Library for C++.
163+
You must download a compatible version of the CodeQL CLI, as specified in the release notes for the release you are using.
162164

163-
**Option 1:** Use the CodeQL CLI bundle, which includes both required components:
165+
**Option 1:** Use the CodeQL CLI bundle, which includes both the CodeQL CLI and GitHub's default security queries:
164166

165167
1. Download the CodeQL CLI bundle from the [`github/codeql-action` releases page](https://github.com/github/codeql-action/releases).
166168
2. Expand the compressed archive to a specified location on your machine.
167169
3. [Optional] Add the CodeQL CLI to your user or system path.
168170

169-
**Option 2:** Fetch the components separately:
171+
This approach is suitable if you wish to use the default queries provided by GitHub in addition to the Coding Standards queries.
172+
173+
**Option 2:** Use the CodeQL CLI binary:
170174

171175
1. Download the CodeQL CLI from the [`github/codeql-cli-binaries` releases page](https://github.com/github/codeql-cli-binaries/releases)
172176
2. Expand the compressed archive to a specified location on your machine.
173-
3. Using `git`, clone the [`github/codeql`](https://github.com/github/codeql) repository to a sibling directory of the CodeQL CLI. The `github/codeql` repository contains the CodeQL Standard Library for C++.
174-
4. [Optional] Add the CodeQL CLI to your user or system path.
177+
3. [Optional] Add the CodeQL CLI to your user or system path.
178+
179+
#### Pre-requisite: downloading the Coding Standards queries
180+
181+
The Coding Standards packs can be downloaded into the local CodeQL package cache using the following command:
182+
183+
```bash
184+
codeql pack download codeql/<standard>-<language>-coding-standards@<version>
185+
```
186+
187+
The supported standards and languages are:
188+
* `codeql/misra-c-coding-standards` - a CodeQL query pack for reporting violations of MISRA C.
189+
* `codeql/cert-c-coding-standards` - a CodeQL query pack for reporting violations of CERT C.
190+
* `codeql/misra-cpp-coding-standards` - a CodeQL query pack for reporting violations of MISRA C++.
191+
* `codeql/cert-cpp-coding-standards` - a CodeQL query pack for reporting violations of CERT C++.
192+
* `codeql/autosar-cpp-coding-standards` - - a CodeQL query pack for reporting violations of AUTOSAR for C++.
193+
194+
Ensure that the `@<version>` string matches the desired Coding Standards version.
195+
196+
Alternatively, the packs can be downloaded directly from a release on the `github/codeql-coding-standards` repository by choosing the `coding-standards-codeql-packs.zip`, which contains the following files:
197+
198+
* `misra-c-coding-standards.tgz` - a CodeQL query pack for reporting violations of MISRA C.
199+
* `cert-c-coding-standards.tgz` - a CodeQL query pack for reporting violations of CERT C.
200+
* `cert-cpp-coding-standards.tgz` - a CodeQL query pack for reporting violations of CERT C++.
201+
* `autosar-cpp-coding-standards.tgz` - a CodeQL query pack for reporting violations of AUTOSAR for C++.
202+
* `common-cpp-coding-standards.tgz` - a CodeQL library pack, used if you are writing your own C++ queries against Coding Standards.
203+
* `common-c-coding-standards.tgz` - a CodeQL library pack, used if you are writing your own C queries against Coding Standards.
204+
* `report-coding-standards.tgz` - a CodeQL query pack for running diagnostics on databases.
175205

176-
The release notes for the "CodeQL Coding Standards" pack you are using will specify the appropriate versions to use.
206+
Each pack will need to be decompressed using the `tar` program, and placed in a known location.
207+
208+
Finally, we provide a legacy single zip containing all the artifacts from a release, named `code-scanning-cpp-query-pack.zip`. This also contains the CodeQL packs listed above.
177209

178210
#### Creating a CodeQL database
179211

@@ -194,26 +226,65 @@ Reference: [CodeQL CLI: Creating a CodeQL database](https://codeql.github.com/do
194226

195227
#### Running the default analysis for one or more Coding Standards
196228

197-
Once you have a CodeQL database for your project, you can run the "default" query suite. This will run all the "automated" queries for each implemented rule in the specified Coding Standards.
229+
Once you have a CodeQL database for your project you can run the default analysis for a specified Coding Standard using the `codeql database analyze` command by specifying the names of the QL packs which you want to run as arguments, along with a version specifier:
230+
231+
```bash
232+
codeql database analyze --format=sarifv2.1.0 --output=<name-of-results-file>.sarif path/to/<output_database_name> codeql/<standard>-<language>-coding-standard@version
233+
```
234+
235+
For example, this command would run MISRA C and CERT C with the default query sets:
236+
237+
```bash
238+
codeql database analyze --format=sarifv2.1.0 --output=results.sarif path/to/<output_database_name> codeql/misra-c-coding-standard@version codeql/cert-c-coding-standard@version
239+
```
240+
The output of this command will be a [SARIF file](https://sarifweb.azurewebsites.net/) called `<name-of-results-file>.sarif`.
241+
242+
##### Locating the Coding Standards CodeQL packs
243+
244+
If you have downloaded a release artifact containing the packs, you will need to provide the `--search-path` parameter, pointing to each of the uncompressed query packs.
245+
```
246+
--search-path path/to/pack1:path/to/pack2
247+
```
248+
249+
Alternatively, the packs can be made available to CodeQL without specification on the comamnd line by placing them inside the distribution under the `qlpacks/codeql/` directory, or placed inside a directory adjacent to the folder containing the distribution.
250+
251+
##### Alternative query sets
252+
253+
Each supported standard includes a variety of query suites, which enable the running of different sets of queries based on specified properties. In addition, a custom query suite can be defined as specified by the CodeQL CLI documentation, in order to select any arbitrary sets of queries in this repository. To run
254+
255+
```bash
256+
codeql database analyze --format=sarifv2.1.0 --output=<name-of-results-file>.sarif path/to/<output_database_name> codeql/<standard>-<language>-coding-standard@version:codeql-suites/<alternative-suite>.qls
257+
```
198258

199-
The query suites can be run by using the `codeql database analyze` command:
259+
If modifying the query suite, ensure that all Rules you expect to be covered by CodeQL in your Guideline Enforcement Plan (or similar) are included in the query suite, by running:
200260

201261
```bash
202-
codeql database analyze --format=sarifv2.1.0 --output=<name-of-results-file>.sarif path/to/<output_database_name> path/to/codeql-coding-standards/cpp/<coding-standard>/src/codeql-suites/<coding-standard>-default.qls...
262+
codeql resolve queries codeql/<standard>-<language>-coding-standard@version:codeql-suites/<alternative-suite>.qls
203263
```
204264

205-
For each Coding Standard you want to run, add a trailing entry in the following format: `path/to/codeql-coding-standards/cpp/<coding-standard>/src/codeql-suites/<coding-standard>-default.qls`.
265+
##### Supported SARIF versions
206266

207267
The only supported SARIF version for use in a functional safety environment is version 2.1.0.
208268
To select this SARIF version you **must** specify the flag `--format=sarifv2.1.0` when invoking the database analyze command `codeql database analyze ...` as shown in the above example.
209269

210-
Running the default analysis for one or more Coding Standards may require further performance customizations for larger codebases.
211-
The following flags may be passed to the `database analyze` command to adjust the performance:
270+
##### Performance optimizations
271+
272+
Running the default analysis for one or more Coding Standards may require further performance customizations for larger codebases. The following flags may be passed to the `database analyze` command to adjust the performance:
212273

213274
- `--ram` - to specify the maximum amount of RAM to use during the analysis as [documented](https://codeql.github.com/docs/codeql-cli/manual/database-analyze/#options-to-control-ram-usage) in the CodeQL CLI manual.
214275
- `--thread` - to specify number of threads to use while evaluating as [documented](https://codeql.github.com/docs/codeql-cli/manual/database-analyze/#cmdoption-codeql-database-analyze-j) in the CodeQL CLI manual.
215276

216-
The output of this command will be a [SARIF file](https://sarifweb.azurewebsites.net/) called `<name-of-results-file>.sarif`.
277+
##### Legacy approach
278+
279+
If you have downloaded the legacy release artifact `code-scanning-query-pack.zip`, you can run the default query suite using the `codeql database analyze` command as follows:
280+
281+
```bash
282+
codeql database analyze --format=sarifv2.1.0 --output=<name-of-results-file>.sarif path/to/<output_database_name> path/to/codeql-coding-standards/<language>/<coding-standard>/src/codeql-suites/<coding-standard>-default.qls...
283+
```
284+
285+
For each Coding Standard you want to run, add a trailing entry in the following format: `path/to/codeql-coding-standards/<language>/<coding-standard>/src/codeql-suites/<coding-standard>-default.qls`. Custom query suites can be run by specifying the appropriate paths.
286+
287+
All other options discussed above are valid.
217288

218289
#### Running the analysis for audit level queries
219290

@@ -223,8 +294,6 @@ Optionally, you may want to run the "audit" level queries. These queries produce
223294
codeql database analyze --format=sarifv2.1.0 --output=<name-of-results-file>.sarif path/to/<output_database_name> path/to/codeql-coding-standards/cpp/<coding-standard>/src/codeql-suites/<coding-standard>-audit.qls...
224295
```
225296

226-
For each Coding Standard you want to run, add a trailing entry in the following format: `path/to/codeql-coding-standards/cpp/<coding-standard>/src/codeql-suites/<coding-standard>-default.qls`.
227-
228297
#### Producing an analysis report
229298

230299
In addition to producing a results file, an analysis report can be produced that summarizes:

‎scripts/release/bump-version.sh

Copy file name to clipboardExpand all lines: scripts/release/bump-version.sh
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ find . -name 'qlpack.yml' | grep -v './codeql_modules' | grep -v './scripts' | x
1515
# update the documentation.
1616

1717
find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/code-scanning-cpp-query-pack-.*\.zip\`/code-scanning-cpp-query-pack-${1}.zip\`/"
18+
find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/coding-standard-codeql-pack-.*\.zip\`/coding-standard-codeql-pack-${1}.zip\`/"
1819
find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/supported_rules_list_.*\.csv\`/supported_rules_list_${1}.csv\`/"
1920
find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/supported_rules_list_.*\.md\`/supported_rules_list_${1}.md\`/"
2021
find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/user_manual_.*\.md\`/user_manual_${1}.md\`/"

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.