From a983d385c7849fe0c86ba94592d26d0fe607ebdb Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Wed, 29 Apr 2020 12:47:06 +0300 Subject: [PATCH] Update README.md * indentation fixes * fix `JavaScript` capitalization * minor grammar tweaks --- README.md | 108 +++++++++++++++++++++++++++++------------------------- 1 file changed, 58 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 219864679..a296ea3d4 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ - # CodeQL Action -This action runs GitHub's industry-leading static 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/semmle/ql), which have been developed by the community and the [GitHub Security Lab](https://securitylab.github.com/) to find common vulnerabilities in your code. - +# CodeQL Action + +This action runs GitHub's industry-leading static 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/semmle/ql), which have been developed by the community and the [GitHub Security Lab](https://securitylab.github.com/) to find common vulnerabilities in your code. + [Sign up for the Advanced Security beta](https://github.com/features/security/advanced-security/signup) - - ## Usage + +## Usage To get code scanning results from CodeQL analysis on your repo you can use the following workflow as a template: @@ -22,39 +23,38 @@ jobs: strategy: fail-fast: false - # CodeQL runs on ubuntu-latest, windows-latest, and macos-latest runs-on: ubuntu-latest steps: - - name: Checkout repository - uses: actions/checkout@v2 - - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v1 - # Override language selection by uncommenting this and choosing your languages - # with: - # languages: go, javascript, csharp, python, cpp, java - - # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). - # If this step fails, then you should remove it and run the build manually (see below). - - name: Autobuild - uses: github/codeql-action/autobuild@v1 - - # ℹī¸ Command-line programs to run using the OS shell. - # 📚 https://git.io/JvXDl - - # ✏ī¸ If the Autobuild fails above, remove it and uncomment the following three lines - # and modify them (or add more) to build your code if your project - # uses a compiled language - - #- run: | - # make bootstrap - # make release - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v1 + - name: Checkout repository + uses: actions/checkout@v2 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 + # Override language selection by uncommenting this and choosing your languages + # with: + # languages: go, javascript, csharp, python, cpp, java + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below). + - name: Autobuild + uses: github/codeql-action/autobuild@v1 + + # ℹī¸ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏ī¸ If the Autobuild fails above, remove it and uncomment the following + # three lines and modify them (or add more) to build your code if your + # project uses a compiled language + + #- run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v1 ``` If you prefer to integrate this within an existing CI workflow, it should end up looking something like this: @@ -73,19 +73,23 @@ If you prefer to integrate this within an existing CI workflow, it should end up - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v1 ``` + ### Actions triggers -The CodeQL action should be run on `push` events, and on a `schedule`. `Push` events allow us to do detailed analysis of the delta in a pull request, while the `schedule` event ensures that GitHub regularly scans the repository for the latest vulnerabilities, even if the repository becomes inactive. This action does not support the `pull_request` event. -### Configuration +The CodeQL action should be run on `push` events, and on a `schedule`. `Push` events allow us to do a detailed analysis of the delta in a pull request, while the `schedule` event ensures that GitHub regularly scans the repository for the latest vulnerabilities, even if the repository becomes inactive. This action does not support the `pull_request` event. + +### Configuration + You may optionally specify additional queries for CodeQL to execute by using a config file. The queries must belong to a [QL pack](https://help.semmle.com/codeql/codeql-cli/reference/qlpack-overview.html) and can be in your repository or any public repository. You can choose a single .ql file, a folder containing multiple .ql files, a .qls [query suite](https://help.semmle.com/codeql/codeql-cli/procedures/query-suites.html) file, or any combination of the above. To use queries from other repositories use the same syntax as when [using an action](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsuses). You can choose to ignore some files or folders from the analysis, or include additional files/folders for analysis. This *only* works for Javascript and Python analysis. Identifying potential files for extraction: -- Scans each folder that's defined as `paths` in turn, traversing subfolders and looking for relevant files. + +- Scans each folder that's defined as `paths` in turn, traversing subfolders, and looking for relevant files. - If it finds a subfolder that's defined as `paths-ignore`, stop traversing. - If a file or folder is both in `paths` and `paths-ignore`, the `paths-ignore` is ignored. -Use the config-file parameter of the init action to enable the configuration file. For example: +Use the `config-file` parameter of the init action to enable the configuration file. For example: ```yaml - uses: github/codeql-action/init@v1 @@ -103,8 +107,8 @@ queries: uses: ./my-queries - name: External Javascript QL pack (Runs a QL pack located in an external repo) uses: /Semmle/ql/javascript/ql/src/Electron@master - - name: External query (Runs a single query located in an external QL pack) - uses: Semmle/ql/javascript/ql/src/AngularJS/DeadAngularJSEventListener.ql@master + - name: External query (Runs a single query located in an external QL pack) + uses: Semmle/ql/javascript/ql/src/AngularJS/DeadAngularJSEventListener.ql@master - name: Select query suite (Runs a query suites) uses: ./codeql-querypacks/complex-python-querypack/rootAndBar.qls @@ -112,8 +116,8 @@ paths: - src/util.ts paths-ignore: - - src - - lib + - src + - lib ``` ## Troubleshooting @@ -128,6 +132,7 @@ Try passing env: GOFLAGS: "-mod=vendor" ``` + to `github/codeql-action/analyze`. ### If you do not use a vendor directory @@ -136,21 +141,24 @@ Dependencies on public repositories should just work. If you have dependencies o ```yaml steps: -- name: Configure git private repo access - env: - TOKEN: ${{ secrets.GITHUB_PAT }} - run: | - git config --global url."https://${TOKEN}@github.com/foo/bar".insteadOf "https://github.com/foo/bar" - git config --global url."https://${TOKEN}@github.com/foo/baz".insteadOf "https://github.com/foo/baz" + - name: Configure git private repo access + env: + TOKEN: ${{ secrets.GITHUB_PAT }} + run: | + git config --global url."https://${TOKEN}@github.com/foo/bar".insteadOf "https://github.com/foo/bar" + git config --global url."https://${TOKEN}@github.com/foo/baz".insteadOf "https://github.com/foo/baz" ``` -before any codeql actions. A similar thing can also be done with a SSH key or deploy key. + +before any codeql actions. A similar thing can also be done with an SSH key or deploy key. ### C# using dotnet version 2 on linux This currently requires invoking `dotnet` with the `/p:UseSharedCompilation=false` flag. For example: -``` + +```shell dotnet build /p:UseSharedCompilation=false ``` + Version 3 does not require the additional flag. ## License