Permalink
codeql-action/README.md
Newer
100644
141 lines (103 sloc)
5.73 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
# CodeQL runs on ubuntu-latest, windows-latest, and macos-latest
43
runs-on: ubuntu-latest
44
45
permissions:
46
# required for all workflows
47
security-events: write
48
49
# only required for workflows in private repositories
50
actions: read
51
contents: read
52
54
- name: Checkout repository
55
uses: actions/checkout@v3
56
57
# Initializes the CodeQL tools for scanning.
58
- name: Initialize CodeQL
59
uses: github/codeql-action/init@v2
60
# Override language selection by uncommenting this and choosing your languages
61
# with:
62
# languages: go, javascript, csharp, python, cpp, java
63
64
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
65
# If this step fails, then you should remove it and run the build manually (see below).
66
- name: Autobuild
67
uses: github/codeql-action/autobuild@v2
68
69
# ℹ️ Command-line programs to run using the OS shell.
70
# 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
71
72
# ✏️ If the Autobuild fails above, remove it and uncomment the following
73
# three lines and modify them (or add more) to build your code if your
74
# project uses a compiled language
75
76
#- run: |
77
# make bootstrap
78
# make release
79
80
- name: Perform CodeQL Analysis
81
uses: github/codeql-action/analyze@v2
82
```
83
84
If you prefer to integrate this within an existing CI workflow, it should end up looking something like this:
85
86
```yaml
87
- name: Initialize CodeQL
88
uses: github/codeql-action/init@v2
89
with:
90
languages: go, javascript
91
92
# Here is where you build your code
93
- run: |
94
make bootstrap
95
make release
96
97
- name: Perform CodeQL Analysis
98
uses: github/codeql-action/analyze@v2
101
### Configuration file
103
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`.
106
- uses: github/codeql-action/init@v2
107
with:
108
config-file: ./.github/codeql/codeql-config.yml
109
```
110
111
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.
112
113
```yaml
114
- uses: github/codeql-action/init@v2
115
with:
116
config-file: owner/repo/codeql-config.yml@branch
117
external-repository-token: ${{ secrets.EXTERNAL_REPOSITORY_TOKEN }}
118
```
119
120
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)."
122
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:
123
124
```yaml
125
- uses: github/codeql-action/init@v2
126
with:
127
queries: <local-or-remote-query>,<another-query>
128
```
129
130
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 `+`:
131
132
```yaml
133
- uses: github/codeql-action/init@v2
134
with:
135
queries: +<local-or-remote-query>,<another-query>
136
```
137
138
## Troubleshooting
139
140
Read about [troubleshooting code scanning](https://help.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-code-scanning).
141