From 835b8878390230681f09ba45c821832cc4ae1eda Mon Sep 17 00:00:00 2001 From: Remco Vermeulen Date: Tue, 21 Jun 2022 15:43:23 +0200 Subject: [PATCH] Update the README - Add a description - Add how it can be used section - Add a troubleshoot section --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 30d0e9d..fb6035b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,85 @@ -# codeql-coding-standards-bundle-releases -CodeQL bundles containing the CodeQL Coding Standards queries +# CodeQL Coding Standards Bundle + +The CodeQL Coding Standards Bundle is a CodeQL bundle that includes the queries from the matching [CodeQL Coding Standards](https://github.com/github/codeql-coding-standards) project that is be open sourced in July 2022. More information on the CodeQL Coding Standards project can be found in [this](https://github.blog/2022-06-20-adding-support-for-coding-standards-autosar-c-and-cert-c/) blog post. + +The queries implement the guidelines specified in the following standards targeting the projects using the C++14: +- [AUTOSAR - Guidelines for the use of C++14 language in critical and safety-related systems Release 18-10](https://www.autosar.org/fileadmin/user_upload/standards/adaptive/18-10/AUTOSAR_RS_CPP14Guidelines.pdf) +- [MISRA C++:2008](https://www.misra.org.uk) +- [SEI CERT C++ Coding Standard: Rules for Developing Safe, Reliable, and Secure Systems (2016 Edition)](https://resources.sei.cmu.edu/library/asset-view.cfm?assetID=494932) + +## How to use the bundle + +The bundle can be use with the [Github CodeQL Action](https://github.com/github/codeql-action) by preceding the `github/codeql-action/init@v2` step with the following step: + +```yaml +- name: Download CodeQL Coding Standards Bundle + run: | + gh release download -R advanced-security/codeql-coding-standards-bundle-releases v1.10.0 --pattern 'codeql-coding-standards.tar.gz' +``` + +The step initializing the Github CodeQL Action using `github/codeql-action/init@v2` can be instructed to use the bundle through the `tools` key and the queries can be specified through the `queries` key as follows: + +```yaml +- name: CodeQL Initialize + uses: github/codeql-action/init@v2 + with: + tools: codeql-coding-standards.tar.gz + queries: autosar-default,cert-default +``` + +The CodeQL Coding Standards Bundle supports the following CodeQL query suites: + +- `autosar-default`: All the AUTOSAR queries that are not audit queries. +- `autosar-required`: The AUTOSAR ueries with obligation *required*, and that are not audit queries. +- `autosar-advisory`: The AUTOSAR queries with obligation *advisory*, and that are not audit queries. +- `autosar-audit`: The AUTOSAR queries that are audit queries. An audit query provides information that can aid in a manual review of a guideline with enforcement *non-automated*. +- `cert-default`: All the CERT queries. + +## Troubleshooting + +An elaborate user manual will be provided when the CodeQL Coding Standards is open sourced. +However the following errors might be troubleshooted if encountered. + +### Error: Code Scanning could not process the submitted SARIF file + +The error can occur using the action `github/codeql-action/analyze@v2` or `github/codeql-action/upload-sarif@v2` that uploads the results of the CodeQL analysis with the following reason + +`rejecting SARIF, as there are more results per run than allowed (25271 > 25000)` + +This can occur when the CodeQL Coding Standard queries are used on a project that doesn't adhere to the standard resulting a one or more queries returning a large number of alerts. +The following steps can be used to troubleshoot the issue: + +1. When using the `github/codeql-action/analyze@v2`, disable the automatic uploading of the SARIF file as follows: + ```yaml + - name: CodeQL Analyze + uses: github/codeql-action/analyze@v2 + with: + upload: "false" + ``` +2. Upload the SARIF file with the `actions/` as follows: + ```yaml + - name: Upload Sarif + uses: actions/upload-artifact@v2 + with: + name: results + path: "../results" + ``` +3. Analyze the SARIF file in [Visual Studio Code][https://code.visualstudio.com/] using the [Sarif Viewer](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer) extension. The *rules* tab of the Sarif Viewer gives a breakdown per rule and the number of alerts. +4. Note down the rule id (of the form `cpp/autosar/...`) of the rules with a high number of alerts. +5. Revert the above changes to return to the regular workflow. +6. Create a CodeQL query suite that excludes the identified rule(s). More information on creating CodeQL query suites can be found at [Creating CodeQL query suites](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/). The following is an example for AUTOSAR that excludes the rule `cpp/autosar/undocumented-user-defined-type`: + ```yaml + - description: AUTOSAR C++14 Guidelines 19-11 (Customized) + - import: codeql-suites/autosar-default.qls + from: autosar-cpp-coding-standards + - exclude: + id: + - cpp/autosar/undocumented-user-defined-type + ``` +7. Add the CodeQL query suite to the repository and refer to it in the `github/codeql-action/init@v2` step. The following example assumes the CodeQL query suite is stored at `.github/code-scanning/autosar.qls`: + ```yaml + - name: CodeQL Initialize + uses: github/codeql-action/init@v2 + with: + tools: codeql-coding-standards.tar.gz + queries: cert-default,.github/code-scanning/autosar.qls \ No newline at end of file