Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README with detailed information #2415

Merged
merged 4 commits into from
Oct 4, 2024
Merged

Update README with detailed information #2415

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
873c91c
Update README with detailed information
aeisenberg Aug 7, 2024
c768f67
Clean up README
aeisenberg Aug 9, 2024
3b143d4
Update readme
aeisenberg Oct 3, 2024
bed2a47
Update autobuild/action.yml
aeisenberg Oct 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,48 @@ 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)."

### Permissions
### Actions

This repository contains several actions that enable you to analyze code in your repository using CodeQL and upload the analysis to GitHub Code Scanning. Actions in this repository also allow you to upload to GitHub analyses generated by any SARIF-producing SAST tool.

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, runs the analysis, and uploads the results to Code Scanning. 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:

- `upload-sarif`: Uploads a SARIF file to Code Scanning. If you are using the `analyze` action, there is no reason to use this action as well. For information about input parameters, see the [upload-sarif action definition](https://github.com/github/codeql-action/blob/main/upload-sarif/action.yml).

Actions with special purposes and unlikely to be used directly:

- `autobuild`: (Deprecated) Attempts to automatically build the code. Only used for analyzing languages that require a build. 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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is autobuild officially deprecated? I might have missed that 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not deprecated yet. I should probably remove the tag, but it's a good discussion to have.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense 👍 I think we should also remove it from the description in the .yml file too then!

- `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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want to label these experimental (they're labeled that way in the definitions). Also, start-proxy is explicitly for internal GH use only — not sure if we want to advertise it in the README?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's worth keeping start-proxy since the action exists and users can see it, but I will make sure it's clear that it's internal use only.


### Workflow Permissions

All advanced setup code scanning workflows must have the `security-events: write` permission. Workflows in private repositories must additionally have the `contents: read` permission. For more information, see "[Assigning permissions to jobs](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs)."

### Build Modes

The CodeQL Action supports different build modes for analyzing the source code. The available build modes are:

- `none`: The database will be created without building the source code. Available for all interpreted languages and some compiled languages.
- `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.

#### Which build mode should I use?

Interpreted languages must use `none` for the build mode.

For compiled languages:

- `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 simpler to set up, but will only work for projects with generic build steps that can be guessed by the heuristics of the autobuild scripts. If `autobuild` fails, then you must switch to `manual` or `none`. If `autobuild` succeeds, then the results and run time will be the same as `manual` mode.
- `none` build mode is also simpler 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. `none` is not yet supported by C/C++, Swift, Go, or Kotlin.


## Supported versions of the CodeQL Action

The following versions of the CodeQL Action are currently supported:
Expand All @@ -45,7 +83,7 @@ We typically release new minor versions of the CodeQL Action and Bundle when a n
| `v2.22.1` | `2.14.6` | Enterprise Server 3.11 | Supports CodeQL Action v3, but did not ship with CodeQL Action v3. For more information, see "[Code scanning: deprecation of CodeQL Action v2](https://github.blog/changelog/2024-01-12-code-scanning-deprecation-of-codeql-action-v2/#users-of-github-enterprise-server-311)." |
| `v2.20.3` | `2.13.5` | Enterprise Server 3.10 | Does not support CodeQL Action v3. |

CodeQL Action v2 will stop receiving updates when GHES 3.11 is deprecated.
CodeQL Action v2 will stop receiving updates when GHES 3.11 is deprecated.

See the full list of GHES release and deprecation dates at [GitHub Enterprise Server releases](https://docs.github.com/en/enterprise-server/admin/all-releases#releases-of-github-enterprise-server).

Expand Down
2 changes: 1 addition & 1 deletion autobuild/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: 'CodeQL: Autobuild'
description: 'Attempt to automatically build code'
description: '(Deprecated) Attempt to automatically build the code. Only used for analyzing languages that require a build. Use the `build-mode: autobuild` input in the `init` action instead.'
aeisenberg marked this conversation as resolved.
Show resolved Hide resolved
author: 'GitHub'
inputs:
token:
Expand Down
Loading