You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-154Lines changed: 3 additions & 154 deletions
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# CodeQL Action
2
2
3
-
This action runs GitHub's industry-leading semantic code analysis engine, [CodeQL](https://codeql.github.com/), 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.
3
+
This action runs GitHub's industry-leading semantic code analysis engine, [CodeQL](https://codeql.github.com/), against a repository's source code to find security vulnerabilities. It then automatically uploads the results to GitHub so they can be displayed on pull requests and 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.
4
4
5
5
For a list of recent changes, see the CodeQL Action's [changelog](CHANGELOG.md).
6
6
@@ -12,160 +12,9 @@ The underlying CodeQL CLI, used in this action, is licensed under the [GitHub Co
12
12
13
13
## Usage
14
14
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).
15
+
We recommend using default setup to configure CodeQL analysis for your repository. For more information, see "[Configuring default setup for code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning)."
16
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]
28
-
schedule:
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
-
53
-
steps:
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
# Autobuild attempts to build any compiled languages (C/C++, C#, Go, 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
99
-
```
100
-
101
-
### Configuration file
102
-
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`.
104
-
105
-
```yaml
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.
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)."
121
-
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
-
### Configuration via `config` input
139
-
140
-
You can alternatively configure CodeQL using the `config` input to the `init` Action. The value of this input must be a YAML string that follows the configuration file format documented at "[Using a custom configuration file](https://aka.ms/code-scanning-docs/config-file)."
141
-
142
-
#### Example configuration
143
-
144
-
```yaml
145
-
- uses: github/codeql-action/init@v2
146
-
with:
147
-
languages: ${{ matrix.language }}
148
-
config: |
149
-
disable-default-queries: true
150
-
queries:
151
-
- uses: security-extended
152
-
- uses: security-and-quality
153
-
query-filters:
154
-
- include:
155
-
tags: /cwe-020/
156
-
```
157
-
158
-
159
-
#### Sharing configuration across multiple repositories
160
-
161
-
You can use Actions or environment variables to share configuration across multiple repositories and to modify configuration without needing to edit the workflow file. In the following example, `vars.CODEQL_CONF` is an [Actions configuration variable](https://docs.github.com/en/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows):
162
-
163
-
```yaml
164
-
- uses: github/codeql-action/init@v2
165
-
with:
166
-
languages: ${{ matrix.language }}
167
-
config: ${{ vars.CODEQL_CONF }}
168
-
```
17
+
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/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning)" and "[Customizing code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning)."
0 commit comments