Permalink
codeql-action/README.md
Newer
100644
149 lines (108 sloc)
7.1 KB
3
This action runs GitHub's industry-leading semantic code analysis engine, CodeQL, against a repository's source code to find security vulnerabilities. It then automatically uploads the results to GitHub so they can be displayed in the repository's security tab. CodeQL runs an extensible set of [queries](https://github.com/github/codeql), which have been developed by the community and the [GitHub Security Lab](https://securitylab.github.com/) to find common vulnerabilities in your code.
5
For a list of recent changes, see the CodeQL Action's [changelog](CHANGELOG.md).
6
7
## License
8
9
This project is released under the [MIT License](LICENSE).
10
11
The underlying CodeQL CLI, used in this action, is licensed under the [GitHub CodeQL Terms and Conditions](https://securitylab.github.com/tools/codeql/license). As such, this action may be used on open source projects hosted on GitHub, and on private repositories that are owned by an organisation with GitHub Advanced Security enabled.
12
15
This is a short walkthrough, but for more information read [configuring code scanning](https://help.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning).
16
17
To get code scanning results from CodeQL analysis on your repo you can use the following workflow as a template:
18
19
```yaml
20
21
name: "Code Scanning - Action"
22
23
on:
24
push:
25
branches: [main]
26
pull_request:
27
branches: [main]
29
# ┌───────────── minute (0 - 59)
30
# │ ┌───────────── hour (0 - 23)
31
# │ │ ┌───────────── day of the month (1 - 31)
32
# │ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
33
# │ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
34
# │ │ │ │ │
35
# │ │ │ │ │
36
# │ │ │ │ │
37
# * * * * *
38
- cron: '30 1 * * 0'
39
40
jobs:
41
CodeQL-Build:
42
# If you're only analyzing JavaScript or Python, CodeQL runs on ubuntu-latest, windows-latest, and macos-latest.
43
# If you're analyzing C/C++, C#, Go, or Java, CodeQL runs on ubuntu-latest, windows-2019, and macos-latest.
44
runs-on: ubuntu-latest
45
46
permissions:
47
# required for all workflows
48
security-events: write
49
50
# only required for workflows in private repositories
51
actions: read
52
contents: read
53
55
- name: Checkout repository
56
uses: actions/checkout@v2
57
58
# Initializes the CodeQL tools for scanning.
59
- name: Initialize CodeQL
60
uses: github/codeql-action/init@v1
61
# Override language selection by uncommenting this and choosing your languages
62
# with:
63
# languages: go, javascript, csharp, python, cpp, java
64
65
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
66
# If this step fails, then you should remove it and run the build manually (see below).
67
- name: Autobuild
68
uses: github/codeql-action/autobuild@v1
69
70
# ℹ️ Command-line programs to run using the OS shell.
71
# 📚 https://git.io/JvXDl
72
73
# ✏️ If the Autobuild fails above, remove it and uncomment the following
74
# three lines and modify them (or add more) to build your code if your
75
# project uses a compiled language
76
77
#- run: |
78
# make bootstrap
79
# make release
80
81
- name: Perform CodeQL Analysis
82
uses: github/codeql-action/analyze@v1
83
```
84
85
If you prefer to integrate this within an existing CI workflow, it should end up looking something like this:
86
87
```yaml
88
- name: Initialize CodeQL
89
uses: github/codeql-action/init@v1
90
with:
91
languages: go, javascript
92
93
# Here is where you build your code
94
- run: |
95
make bootstrap
96
make release
97
98
- name: Perform CodeQL Analysis
99
uses: github/codeql-action/analyze@v1
100
```
102
### Configuration file
104
Use the `config-file` parameter of the `init` action to enable the configuration file. The value of `config-file` is the path to the configuration file you want to use. This example loads the configuration file `./.github/codeql/codeql-config.yml`.
105
106
```yaml
107
- uses: github/codeql-action/init@v1
108
with:
109
config-file: ./.github/codeql/codeql-config.yml
110
```
111
112
The configuration file can be located in a different repository. This is useful if you want to share the same configuration across multiple repositories. If the configuration file is in a private repository you can also specify an `external-repository-token` option. This should be a personal access token that has read access to any repositories containing referenced config files and queries.
113
114
```yaml
115
- uses: github/codeql-action/init@v1
116
with:
117
config-file: owner/repo/codeql-config.yml@branch
118
external-repository-token: ${{ secrets.EXTERNAL_REPOSITORY_TOKEN }}
119
```
120
121
For information on how to write a configuration file, see "[Using a custom configuration file](https://help.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#using-a-custom-configuration-file)."
123
If you only want to customise the queries used, you can specify them in your workflow instead of creating a config file, using the `queries` property of the `init` action:
124
125
```yaml
126
- uses: github/codeql-action/init@v1
127
with:
128
queries: <local-or-remote-query>,<another-query>
129
```
130
131
By default, this will override any queries specified in a config file. If you wish to use both sets of queries, prefix the list of queries in the workflow with `+`:
132
133
```yaml
134
- uses: github/codeql-action/init@v1
135
with:
136
queries: +<local-or-remote-query>,<another-query>
137
```
138
139
## Troubleshooting
140
141
Read about [troubleshooting code scanning](https://help.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-code-scanning).
142
143
### Note on "missing analysis" message
144
145
The very first time code scanning is run and if it is on a pull request, you will probably get a message mentioning a "missing analysis". This is expected.
146
147
After code scanning has analyzed the code in a pull request, it needs to compare the analysis of the topic branch (the merge commit of the branch you used to create the pull request) with the analysis of the base branch (the branch into which you want to merge the pull request). This allows code scanning to compute which alerts are newly introduced by the pull request, which alerts were already present in the base branch, and whether any existing alerts are fixed by the changes in the pull request. Initially, if you use a pull request to add code scanning to a repository, the base branch has not yet been analyzed, so it's not possible to compute these details. In this case, when you click through from the results check on the pull request you will see the "Missing analysis for base commit SHA-HASH" message.
148
149
For more information and other causes of this message, see [Reasons for the "missing analysis" message](https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository#reasons-for-the-missing-analysis-message)