From 0f63feeaf81ebd9c7a355c50613edf8ac1dee90e Mon Sep 17 00:00:00 2001 From: Andrew Eisenberg Date: Fri, 9 Aug 2024 13:29:40 -0700 Subject: [PATCH] Clean up README Restructured the change to the README. Instead of directly including the descriptions of the language inputs, added links to the inputs for each action. --- README.md | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index b94bd6d642..a7a01c4623 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,24 @@ We recommend using default setup to configure CodeQL analysis for your repositor You can also configure advanced setup for a repository to find security vulnerabilities in your code using a highly customizable code scanning configuration. For more information, see "[Configuring advanced setup for code scanning](https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning)" and "[Customizing your advanced setup for code scanning](https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning)." -### Inputs +### Actions + +This repository contains several actions that enable you to create and upload your CodeQL analyses to GitHub Code Scanning. Also, you can upload analyses generated by any SARIF-producing SAST tool using actions in this repository. + +Actions for CodeQL analyses: + +- `init`: Sets up CodeQL for analysis. For information about input parameters, see the [init action definition](https://github.com/github/codeql-action/blob/main/init/action.yml). +- `analyze`: Finalizes the CodeQL database and runs the analysis. For information about input parameters, see the [analyze action definition](https://github.com/github/codeql-action/blob/main/analyze/action.yml). + +Actions for uploading analyses generated by third-party tools: -The CodeQL Action supports various inputs to customize the analysis. Here are some important inputs: +- `upload-sarif`: Uploads a SARIF file to Code Scanning. For information about input parameters, see the [upload-sarif action definition](https://github.com/github/codeql-action/blob/main/upload-sarif/action.yml). -- `config`: Path of the config file to use. This input allows you to specify a custom configuration file for the analysis. -- `languages`: A comma-separated list of CodeQL languages to analyze. -- `queries`: Comma-separated list of additional queries to run. By default, this overrides the same setting in a configuration file; prefix with "+" to use both sets of queries. -- `packs`: Comma-separated list of packs to run. Reference a pack in the format `scope/name[@version]`. If `version` is not specified, then the latest version of the pack is used. By default, this overrides the same setting in a configuration file; prefix with "+" to use both sets of packs. -- `db-location`: Path where CodeQL databases should be created. If not specified, a temporary directory will be used. -- `ram`: The amount of memory in MB that can be used by CodeQL extractors. -- `threads`: The number of threads that can be used by CodeQL extractors. -- `source-root`: Path of the root source code directory, relative to $GITHUB_WORKSPACE. +Actions with special purposes and unlikely to be used directly: + +- `autobuild`: Attempts to automatically build the code. Only used for analyzing languages that require a build. Now deprecated. Use the `build-mode: autobuild` input in the `init` action instead. For information about input parameters, see the [autobuild action definition](https://github.com/github/codeql-action/blob/main/autobuild/action.yml). +- `resolve-environment`: Attempts to infer a build environment suitable for automatic builds. For information about input parameters, see the [resolve-environment action definition](https://github.com/github/codeql-action/blob/main/resolve-environment/action.yml). +- `start-proxy`: Starts an HTTP proxy server for downloading dependencies in private registries. For information about input parameters, see the [start-proxy action definition](https://github.com/github/codeql-action/blob/main/start-proxy/action.yml). ### Workflow Permissions @@ -41,16 +47,16 @@ The CodeQL Action supports different build modes for analyzing the source code. - `autobuild`: The database will be created by attempting to automatically build the source code. Available for all compiled languages. - `manual`: The database will be created by building the source code using a manually specified build command. To use this build mode, specify manual build steps in your workflow between the `init` and `analyze` steps. Available for all compiled languages. -### Actions +#### Which build mode should I use? + +Interpreted languages must use `none` for the build mode. + +For compiled languages: -The CodeQL Action includes several actions that can be used in your workflows. Here are the available actions and how to use them: +- `manual` build mode will typically produce the most precise results, but it is more difficult to set up and will cause the analysis to take slightly more time to run. +- `autobuild` build mode is simple to set up, but will only work for projects with simple build steps that can be guessed by the heuristics of the autobuild scripts. If `autobuild` fails, then you must choose `manual` or `none`. If it works, then the results and run time will be the same as `manual` mode. +- `none` build mode is also simple to set up and is slightly faster to run, but there is a possibility that some alerts will be missed. This may happen if your repository does any code generation during compilation or if there are any dependencies downloaded from registries that the workflow does not have access to. Also, `none` is not yet supported by C/C++, Swift, Go, or Kotlin. -- `init`: Sets up CodeQL for analysis. For more information, see the [init action documentation](https://github.com/github/codeql-action/blob/main/init/action.yml). -- `autobuild`: Attempts to automatically build the code. For more information, see the [autobuild action documentation](https://github.com/github/codeql-action/blob/main/autobuild/action.yml). -- `analyze`: Finalizes the CodeQL database and runs the analysis. For more information, see the [analyze action documentation](https://github.com/github/codeql-action/blob/main/analyze/action.yml). -- `upload-sarif`: Uploads a SARIF file to Code Scanning. For more information, see the [upload-sarif action documentation](https://github.com/github/codeql-action/blob/main/upload-sarif/action.yml). -- `resolve-environment`: Attempts to infer a build environment suitable for automatic builds. For more information, see the [resolve-environment action documentation](https://github.com/github/codeql-action/blob/main/resolve-environment/action.yml). -- `start-proxy`: Starts an HTTP proxy server. For more information, see the [start-proxy action documentation](https://github.com/github/codeql-action/blob/main/start-proxy/action.yml). ## Supported versions of the CodeQL Action