From b715dba7f675b687025e81a90d7788efab0630bf Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Wed, 9 Oct 2024 23:55:49 +0100 Subject: [PATCH 01/17] Generate qlpack bundles when generating artifacts --- .github/workflows/code-scanning-pack-gen.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 7b187b2980..02d57bd18b 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -102,11 +102,21 @@ jobs: codeql query compile --precompile --threads 0 cpp codeql query compile --precompile --threads 0 c + codeql pack bundle --output=misra-c-coding-standards.tgz c/misra/src + codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src + codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src + codeql pack bundle --output=autosar-cpp-coding-standards.tgz cpp/autosar/src + cd .. zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/configuration codeql-coding-standards/scripts/reports codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/guideline_recategorization codeql-coding-standards/schemas - name: Upload GHAS Query Pack - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: code-scanning-cpp-query-pack.zip path: code-scanning-cpp-query-pack.zip + + - uses: actions/upload-artifact@v4 + with: + name: coding-standards-qlpacks + path: *-cp?p?-coding-standards.tgz \ No newline at end of file From f41d71de0cc57ea62e7952e1d421327dc5c1856a Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Thu, 10 Oct 2024 09:29:31 +0100 Subject: [PATCH 02/17] Remove spurious line break --- .github/workflows/code-scanning-pack-gen.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 02d57bd18b..97b24f917a 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -8,7 +8,6 @@ on: - main - next - "rc/**" - push: branches: - main From 29881baf5f4637fd0c554a7fcb2b3bd04df984a3 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Thu, 10 Oct 2024 09:29:45 +0100 Subject: [PATCH 03/17] Run codeql pack bundle after zipping up the existing pack --- .github/workflows/code-scanning-pack-gen.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 97b24f917a..12350e4855 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -101,14 +101,14 @@ jobs: codeql query compile --precompile --threads 0 cpp codeql query compile --precompile --threads 0 c - codeql pack bundle --output=misra-c-coding-standards.tgz c/misra/src - codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src - codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src - codeql pack bundle --output=autosar-cpp-coding-standards.tgz cpp/autosar/src - cd .. zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/configuration codeql-coding-standards/scripts/reports codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/guideline_recategorization codeql-coding-standards/schemas + codeql pack bundle --output=misra-c-coding-standards.tgz codeql-coding-standards/c/misra/src + codeql pack bundle --output=cert-c-coding-standards.tgz codeql-coding-standards/c/cert/src + codeql pack bundle --output=cert-cpp-coding-standards.tgz codeql-coding-standards/cpp/cert/src + codeql pack bundle --output=autosar-cpp-coding-standards.tgz codeql-coding-standards/cpp/autosar/src + - name: Upload GHAS Query Pack uses: actions/upload-artifact@v4 with: From c669f45c40d2dcdc7b3bd74e4a7f35ea2d95d16e Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Thu, 10 Oct 2024 09:30:12 +0100 Subject: [PATCH 04/17] Correctly quote the path pattern for upload-artifact --- .github/workflows/code-scanning-pack-gen.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 12350e4855..dab56addae 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -115,7 +115,8 @@ jobs: name: code-scanning-cpp-query-pack.zip path: code-scanning-cpp-query-pack.zip - - uses: actions/upload-artifact@v4 + - name: Upload qlpacks + uses: actions/upload-artifact@v4 with: name: coding-standards-qlpacks - path: *-cp?p?-coding-standards.tgz \ No newline at end of file + path: '*-cp?p?-coding-standards.tgz' \ No newline at end of file From 147725dc1dff3df864d7c22033f1a8d1ffa5d16a Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Thu, 10 Oct 2024 23:30:24 +0100 Subject: [PATCH 05/17] Expand set of packs created, separate step --- .github/workflows/code-scanning-pack-gen.yml | 21 ++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index dab56addae..3166f0dc64 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -104,18 +104,27 @@ jobs: cd .. zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/configuration codeql-coding-standards/scripts/reports codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/guideline_recategorization codeql-coding-standards/schemas - codeql pack bundle --output=misra-c-coding-standards.tgz codeql-coding-standards/c/misra/src - codeql pack bundle --output=cert-c-coding-standards.tgz codeql-coding-standards/c/cert/src - codeql pack bundle --output=cert-cpp-coding-standards.tgz codeql-coding-standards/cpp/cert/src - codeql pack bundle --output=autosar-cpp-coding-standards.tgz codeql-coding-standards/cpp/autosar/src - - name: Upload GHAS Query Pack uses: actions/upload-artifact@v4 with: name: code-scanning-cpp-query-pack.zip path: code-scanning-cpp-query-pack.zip - - name: Upload qlpacks + - name: Create qlpack bundles + env: + CODEQL_HOME: ${{ github.workspace }}/codeql_home + run: | + PATH=$PATH:$CODEQL_HOME/codeql + + codeql pack bundle --output=common-cpp-coding-standards.tgz cpp/common/src + codeql pack bundle --output=common-c-coding-standards.tgz c/common/src + codeql pack bundle --output=misra-c-coding-standards.tgz c/misra/src + codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src + codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src + codeql pack bundle --output=autosar-cpp-coding-standards.tgz -vvv cpp/autosar/src + codeql pack bundle --output=report-cpp-coding-standards.tgz cpp/report/src + + - name: Upload qlpack bundles uses: actions/upload-artifact@v4 with: name: coding-standards-qlpacks From 9ddbe53a50bddbdd0c4ede338b8833180a5e4693 Mon Sep 17 00:00:00 2001 From: Luke Cartey <5377966+lcartey@users.noreply.github.com> Date: Fri, 11 Oct 2024 09:13:04 +0100 Subject: [PATCH 06/17] Address workflow issues - Update pattern to capture .tgz qlpack files. - Add extra verbosity to the cert-cpp call to see what discrepancies occur with the autosar-cpp (as we see the autosar pack bundling retrigger compilation) - Combine the query compile calls in the earlier step to try to promote retaining all the cache. --- .github/workflows/code-scanning-pack-gen.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 3166f0dc64..3965e7d26d 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -98,8 +98,7 @@ jobs: run: | PATH=$PATH:$CODEQL_HOME/codeql - codeql query compile --precompile --threads 0 cpp - codeql query compile --precompile --threads 0 c + codeql query compile --precompile --threads 0 cpp c cd .. zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/configuration codeql-coding-standards/scripts/reports codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/guideline_recategorization codeql-coding-standards/schemas @@ -120,7 +119,7 @@ jobs: codeql pack bundle --output=common-c-coding-standards.tgz c/common/src codeql pack bundle --output=misra-c-coding-standards.tgz c/misra/src codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src - codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src + codeql pack bundle --output=cert-cpp-coding-standards.tgz -vvv cpp/cert/src codeql pack bundle --output=autosar-cpp-coding-standards.tgz -vvv cpp/autosar/src codeql pack bundle --output=report-cpp-coding-standards.tgz cpp/report/src @@ -128,4 +127,4 @@ jobs: uses: actions/upload-artifact@v4 with: name: coding-standards-qlpacks - path: '*-cp?p?-coding-standards.tgz' \ No newline at end of file + path: '*-coding-standards.tgz' \ No newline at end of file From 9e5aa28e080b6205095fd5e5320b2fbc8ae11f58 Mon Sep 17 00:00:00 2001 From: Luke Cartey <5377966+lcartey@users.noreply.github.com> Date: Mon, 21 Oct 2024 23:45:34 +0100 Subject: [PATCH 07/17] Increase CodeQL compilation cache size --- .github/workflows/code-scanning-pack-gen.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 3965e7d26d..5a37353f19 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -97,8 +97,9 @@ jobs: CODEQL_HOME: ${{ github.workspace }}/codeql_home run: | PATH=$PATH:$CODEQL_HOME/codeql - - codeql query compile --precompile --threads 0 cpp c + # Precompile all queries, and use a compilation cache larger than default + # to ensure we cache all the queries for later steps + codeql query compile --precompile --threads 0 --compilation-cache-size=1024 cpp c cd .. zip -r codeql-coding-standards/code-scanning-cpp-query-pack.zip codeql-coding-standards/c/ codeql-coding-standards/cpp/ codeql-coding-standards/.codeqlmanifest.json codeql-coding-standards/supported_codeql_configs.json codeql-coding-standards/scripts/configuration codeql-coding-standards/scripts/reports codeql-coding-standards/scripts/shared codeql-coding-standards/scripts/guideline_recategorization codeql-coding-standards/schemas From c7f04f531f08de27ab4f1f49543654bd2d408709 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 10:24:04 +0100 Subject: [PATCH 08/17] Add coding-standards-qlpacks as a release artifact --- scripts/release/release-layout.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/release/release-layout.yml b/scripts/release/release-layout.yml index 5e496120f2..32ba2b63d9 100644 --- a/scripts/release/release-layout.yml +++ b/scripts/release/release-layout.yml @@ -10,6 +10,10 @@ layout: - workflow-artifact: name: "Code Scanning Query Pack Generation" artifact: code-scanning-cpp-query-pack.zip + coding-standards-qlpacks.zip: + - workflow-artifact: + name: "Code Scanning Query Pack Generation" + artifact: coding-standards-qlpacks.zip supported_rules_list.csv: - shell: | python ${{ coding-standards.root }}/scripts/release/create_supported_rules_list.py --csv > supported_rules_list.csv From d238d2e0753a34b9297e772231c25b2bb2d9518c Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 11:05:56 +0100 Subject: [PATCH 09/17] Fix name --- scripts/release/release-layout.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/release/release-layout.yml b/scripts/release/release-layout.yml index 32ba2b63d9..357b7a56fc 100644 --- a/scripts/release/release-layout.yml +++ b/scripts/release/release-layout.yml @@ -13,7 +13,7 @@ layout: coding-standards-qlpacks.zip: - workflow-artifact: name: "Code Scanning Query Pack Generation" - artifact: coding-standards-qlpacks.zip + artifact: coding-standards-qlpacks supported_rules_list.csv: - shell: | python ${{ coding-standards.root }}/scripts/release/create_supported_rules_list.py --csv > supported_rules_list.csv From 80988039fccdeef7b5f375ff26f269d3db513391 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 14:11:09 +0100 Subject: [PATCH 10/17] Removed leftover debugging --- .github/workflows/code-scanning-pack-gen.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 5a37353f19..306a33e735 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -120,8 +120,8 @@ jobs: codeql pack bundle --output=common-c-coding-standards.tgz c/common/src codeql pack bundle --output=misra-c-coding-standards.tgz c/misra/src codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src - codeql pack bundle --output=cert-cpp-coding-standards.tgz -vvv cpp/cert/src - codeql pack bundle --output=autosar-cpp-coding-standards.tgz -vvv cpp/autosar/src + codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src + codeql pack bundle --output=autosar-cpp-coding-standards.tgz cpp/autosar/src codeql pack bundle --output=report-cpp-coding-standards.tgz cpp/report/src - name: Upload qlpack bundles From 772d593ef3279626b062abade169dd7c9c2ed72e Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 14:11:23 +0100 Subject: [PATCH 11/17] Pack generation: update report pack name for clarity --- .github/workflows/code-scanning-pack-gen.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 306a33e735..68961b3202 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -122,7 +122,7 @@ jobs: codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src codeql pack bundle --output=autosar-cpp-coding-standards.tgz cpp/autosar/src - codeql pack bundle --output=report-cpp-coding-standards.tgz cpp/report/src + codeql pack bundle --output=report-coding-standards.tgz cpp/report/src - name: Upload qlpack bundles uses: actions/upload-artifact@v4 From f146f74ebf5d39509bcd94529660bff334728894 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 17:23:09 +0100 Subject: [PATCH 12/17] Rename to coding-standards-codeql-packs --- .github/workflows/code-scanning-pack-gen.yml | 2 +- scripts/release/release-layout.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index 68961b3202..e03b377424 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -127,5 +127,5 @@ jobs: - name: Upload qlpack bundles uses: actions/upload-artifact@v4 with: - name: coding-standards-qlpacks + name: coding-standards-codeql-packs path: '*-coding-standards.tgz' \ No newline at end of file diff --git a/scripts/release/release-layout.yml b/scripts/release/release-layout.yml index 357b7a56fc..4ced0b4d30 100644 --- a/scripts/release/release-layout.yml +++ b/scripts/release/release-layout.yml @@ -10,10 +10,10 @@ layout: - workflow-artifact: name: "Code Scanning Query Pack Generation" artifact: code-scanning-cpp-query-pack.zip - coding-standards-qlpacks.zip: + coding-standards-codeql-packs.zip: - workflow-artifact: name: "Code Scanning Query Pack Generation" - artifact: coding-standards-qlpacks + artifact: coding-standards-codeql-packs supported_rules_list.csv: - shell: | python ${{ coding-standards.root }}/scripts/release/create_supported_rules_list.py --csv > supported_rules_list.csv From eee63999c5bb6714c07d4b20cc68f40a9b02ed62 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 18:13:34 +0100 Subject: [PATCH 13/17] Add MISRA C++ 2023 CodeQL pack --- .github/workflows/code-scanning-pack-gen.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/code-scanning-pack-gen.yml b/.github/workflows/code-scanning-pack-gen.yml index e03b377424..ea13a4e76c 100644 --- a/.github/workflows/code-scanning-pack-gen.yml +++ b/.github/workflows/code-scanning-pack-gen.yml @@ -122,6 +122,7 @@ jobs: codeql pack bundle --output=cert-c-coding-standards.tgz c/cert/src codeql pack bundle --output=cert-cpp-coding-standards.tgz cpp/cert/src codeql pack bundle --output=autosar-cpp-coding-standards.tgz cpp/autosar/src + codeql pack bundle --output=misra-cpp-coding-standards.tgz cpp/misra/src codeql pack bundle --output=report-coding-standards.tgz cpp/report/src - name: Upload qlpack bundles From 499fa76800e24e7e28879d6f87e2858bc037ea1d Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 18:14:10 +0100 Subject: [PATCH 14/17] Update user manual with CodeQL packs --- docs/user_manual.md | 101 +++++++++++++++++++++++++++----- scripts/release/bump-version.sh | 1 + 2 files changed, 86 insertions(+), 16 deletions(-) diff --git a/docs/user_manual.md b/docs/user_manual.md index 17c08237ef..b74c962d0e 100644 --- a/docs/user_manual.md +++ b/docs/user_manual.md @@ -29,13 +29,15 @@ | 0.21.0 | 2024-05-01 | Luke Cartey | Add MISRA C++ 2023 as under development, and clarify MISRA C 2012 coverage. | | 0.22.0 | 2024-10-02 | Luke Cartey | Add MISRA C 2023 as under development, and clarify MISRA C 2012 coverage. | | 0.23.0 | 2024-10-21 | Luke Cartey | Add assembly as a hazard. | +| 0.24.0 | 2024-10-22 | Luke Cartey | Add CodeQL packs as a usable output, update release artifacts list. | ## Release information 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). The release page documents the release notes and contains the following artifacts part of the release: -- `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_. +- `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_. +- `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_. - `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. - `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. - `user_manual_2.37.0-dev.md`: This user manual. @@ -158,22 +160,52 @@ This section describes how to operate the "CodeQL Coding Standards". #### Pre-requisite: downloading the CodeQL CLI -You must download a compatible version of the CodeQL CLI and CodeQL Standard Library for C++. +You must download a compatible version of the CodeQL CLI, as specified in the release notes for the release you are using. -**Option 1:** Use the CodeQL CLI bundle, which includes both required components: +**Option 1:** Use the CodeQL CLI bundle, which includes both the CodeQL CLI and GitHub's default security queries: 1. Download the CodeQL CLI bundle from the [`github/codeql-action` releases page](https://github.com/github/codeql-action/releases). 2. Expand the compressed archive to a specified location on your machine. 3. [Optional] Add the CodeQL CLI to your user or system path. -**Option 2:** Fetch the components separately: +This approach is suitable if you wish to use the default queries provided by GitHub in addition to the Coding Standards queries. + +**Option 2:** Use the CodeQL CLI binary: 1. Download the CodeQL CLI from the [`github/codeql-cli-binaries` releases page](https://github.com/github/codeql-cli-binaries/releases) 2. Expand the compressed archive to a specified location on your machine. - 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++. - 4. [Optional] Add the CodeQL CLI to your user or system path. +3. [Optional] Add the CodeQL CLI to your user or system path. + +#### Pre-requisite: downloading the Coding Standards queries + +The Coding Standards packs can be downloaded into the local CodeQL package cache using the following command: + +```bash +codeql pack download codeql/--coding-standards@ +``` + +The supported standards and languages are: + * `codeql/misra-c-coding-standards` - a CodeQL query pack for reporting violations of MISRA C. + * `codeql/cert-c-coding-standards` - a CodeQL query pack for reporting violations of CERT C. + * `codeql/misra-cpp-coding-standards` - a CodeQL query pack for reporting violations of MISRA C++. + * `codeql/cert-cpp-coding-standards` - a CodeQL query pack for reporting violations of CERT C++. + * `codeql/autosar-cpp-coding-standards` - - a CodeQL query pack for reporting violations of AUTOSAR for C++. + +Ensure that the `@` string matches the desired Coding Standards version. + +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: + + * `misra-c-coding-standards.tgz` - a CodeQL query pack for reporting violations of MISRA C. + * `cert-c-coding-standards.tgz` - a CodeQL query pack for reporting violations of CERT C. + * `cert-cpp-coding-standards.tgz` - a CodeQL query pack for reporting violations of CERT C++. + * `autosar-cpp-coding-standards.tgz` - a CodeQL query pack for reporting violations of AUTOSAR for C++. + * `common-cpp-coding-standards.tgz` - a CodeQL library pack, used if you are writing your own C++ queries against Coding Standards. + * `common-c-coding-standards.tgz` - a CodeQL library pack, used if you are writing your own C queries against Coding Standards. + * `report-coding-standards.tgz` - a CodeQL query pack for running diagnostics on databases. -The release notes for the "CodeQL Coding Standards" pack you are using will specify the appropriate versions to use. +Each pack will need to be decompressed using the `tar` program, and placed in a known location. + +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. #### Creating a CodeQL database @@ -194,26 +226,65 @@ Reference: [CodeQL CLI: Creating a CodeQL database](https://codeql.github.com/do #### Running the default analysis for one or more Coding Standards -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. +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: + +```bash +codeql database analyze --format=sarifv2.1.0 --output=.sarif path/to/ codeql/--coding-standard@version +``` + +For example, this command would run MISRA C and CERT C with the default query sets: + +```bash +codeql database analyze --format=sarifv2.1.0 --output=results.sarif path/to/ codeql/misra-c-coding-standard@version codeql/cert-c-coding-standard@version +``` +The output of this command will be a [SARIF file](https://sarifweb.azurewebsites.net/) called `.sarif`. + +##### Locating the Coding Standards CodeQL packs + +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. +``` +--search-path path/to/pack1:path/to/pack2 +``` + +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. + +##### Alternative query sets + +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 + +```bash +codeql database analyze --format=sarifv2.1.0 --output=.sarif path/to/ codeql/--coding-standard@version:codeql-suites/.qls +``` -The query suites can be run by using the `codeql database analyze` command: +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: ```bash -codeql database analyze --format=sarifv2.1.0 --output=.sarif path/to/ path/to/codeql-coding-standards/cpp//src/codeql-suites/-default.qls... +codeql resolve queries codeql/--coding-standard@version:codeql-suites/.qls ``` -For each Coding Standard you want to run, add a trailing entry in the following format: `path/to/codeql-coding-standards/cpp//src/codeql-suites/-default.qls`. +##### Supported SARIF versions The only supported SARIF version for use in a functional safety environment is version 2.1.0. 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. -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: +##### Performance optimizations + +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: - `--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. - `--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. -The output of this command will be a [SARIF file](https://sarifweb.azurewebsites.net/) called `.sarif`. +##### Legacy approach + +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: + +```bash +codeql database analyze --format=sarifv2.1.0 --output=.sarif path/to/ path/to/codeql-coding-standards///src/codeql-suites/-default.qls... +``` + +For each Coding Standard you want to run, add a trailing entry in the following format: `path/to/codeql-coding-standards///src/codeql-suites/-default.qls`. Custom query suites can be run by specifying the appropriate paths. + +All other options discussed above are valid. #### Running the analysis for audit level queries @@ -223,8 +294,6 @@ Optionally, you may want to run the "audit" level queries. These queries produce codeql database analyze --format=sarifv2.1.0 --output=.sarif path/to/ path/to/codeql-coding-standards/cpp//src/codeql-suites/-audit.qls... ``` -For each Coding Standard you want to run, add a trailing entry in the following format: `path/to/codeql-coding-standards/cpp//src/codeql-suites/-default.qls`. - #### Producing an analysis report In addition to producing a results file, an analysis report can be produced that summarizes: diff --git a/scripts/release/bump-version.sh b/scripts/release/bump-version.sh index fd5ab5ea0d..5bbd0eeae0 100755 --- a/scripts/release/bump-version.sh +++ b/scripts/release/bump-version.sh @@ -15,6 +15,7 @@ find . -name 'qlpack.yml' | grep -v './codeql_modules' | grep -v './scripts' | x # update the documentation. 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\`/" +find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/coding-standard-codeql-pack-.*\.zip\`/coding-standard-codeql-pack-${1}.zip\`/" find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/supported_rules_list_.*\.csv\`/supported_rules_list_${1}.csv\`/" find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/supported_rules_list_.*\.md\`/supported_rules_list_${1}.md\`/" find docs -name 'user_manual.md' -print0 | xargs -0 sed -i "s/user_manual_.*\.md\`/user_manual_${1}.md\`/" From 1c6fce51adf7e2bc0441603f487de61d5322d9d0 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 19:11:02 +0100 Subject: [PATCH 15/17] Update wording of recommendation to use the bundle --- docs/user_manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual.md b/docs/user_manual.md index b74c962d0e..c9fbacdd4b 100644 --- a/docs/user_manual.md +++ b/docs/user_manual.md @@ -168,7 +168,7 @@ You must download a compatible version of the CodeQL CLI, as specified in the re 2. Expand the compressed archive to a specified location on your machine. 3. [Optional] Add the CodeQL CLI to your user or system path. -This approach is suitable if you wish to use the default queries provided by GitHub in addition to the Coding Standards queries. +This approach is recommended if you wish to use the default queries provided by GitHub in addition to the Coding Standards queries. **Option 2:** Use the CodeQL CLI binary: From 47804a7b52f4606d123bb4ca0f45e1e0acd558ca Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 22 Oct 2024 19:11:19 +0100 Subject: [PATCH 16/17] Add release notes --- change_notes/2024-10-22-update-release-artifacts.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 change_notes/2024-10-22-update-release-artifacts.md diff --git a/change_notes/2024-10-22-update-release-artifacts.md b/change_notes/2024-10-22-update-release-artifacts.md new file mode 100644 index 0000000000..46d0ed0c30 --- /dev/null +++ b/change_notes/2024-10-22-update-release-artifacts.md @@ -0,0 +1,4 @@ + - Modifications to the release artifacts: + - New CodeQL pack release artifacts have been created. These release artifacts can be downloaded from the release, and will be published to the GitHub registry under the `codeql` org for ease of deployment. + - The user manual has been updated to describe how to use the CodeQL packs. + - We no longer require a separate download of the CodeQL Standard Library for C++ - all queries have been pre-compiled and linked with the appropriate standard library. \ No newline at end of file From 96366ae6cb1c006e1176d55cf285fd606bed1fdb Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Wed, 23 Oct 2024 09:33:16 +0100 Subject: [PATCH 17/17] Update links --- docs/user_manual.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_manual.md b/docs/user_manual.md index c9fbacdd4b..926d1b13f4 100644 --- a/docs/user_manual.md +++ b/docs/user_manual.md @@ -271,8 +271,8 @@ To select this SARIF version you **must** specify the flag `--format=sarifv2.1.0 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: -- `--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. -- `--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. +- `--ram` - to specify the maximum amount of RAM to use during the analysis as [documented](https://docs.github.com/en/code-security/codeql-cli/codeql-cli-manual/database-analyze#options-to-control-ram-usage) in the CodeQL CLI manual. +- `--thread` - to specify number of threads to use while evaluating as [documented](https://docs.github.com/en/code-security/codeql-cli/codeql-cli-manual/database-analyze#-j---threadsnum) in the CodeQL CLI manual. ##### Legacy approach