Skip to content

Commit c0c4ef1

Browse files
rvermeulenrvermeulen
committed
Add README.md
1 parent c89dcf9 commit c0c4ef1

File tree

1 file changed

+139
-0
lines changed

1 file changed

+139
-0
lines changed

‎README.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# CodeQL bundle action
2+
3+
This action retrofits an existing [CodeQL bundle](https://github.com/github/codeql-action/releases) with additional [CodeQL packs](https://codeql.github.com/docs/codeql-cli/creating-and-working-with-codeql-packs/) using the [CodeQL bundle CLI](https://github.com/rvermeulen/codeql-bundle)
4+
The bundle will be a single deployable artifact containing the CodeQL standard library, the CodeQL standard queries, and any other libraries or queries that are relevant.
5+
Additionally, the CodeQL standard library and standard queries can be customized to consider additional sources, sinks, data-flow/taint steps, sanitizers and barriers.
6+
7+
A custom codeql bundle has the following benefits:
8+
9+
- A single artifact containing the standard queries and other queries of interest.
10+
- A compilation cache for all the included queries resulting in a faster analysis.
11+
- All the included queries can benefit from customizations that improve the coverage of the analysis.
12+
13+
## Usage
14+
15+
The following Action workflow is a minimal example showing how to use this action to create a bundle containing the CodeQL packs listed in `packs` and how to upload it as an artifact.
16+
17+
```yaml
18+
name: "Build custom bundle"
19+
on:
20+
push:
21+
branches:
22+
- main
23+
pull_request:
24+
branches:
25+
- main
26+
workflow_dispatch:
27+
28+
jobs:
29+
test:
30+
name: "Create custom bundle"
31+
runs-on: ubuntu-latest
32+
steps:
33+
- uses: actions/checkout@v3
34+
- uses: advanced-security/codeql-bundle-action/download-bundle@v2
35+
id: download-bundle
36+
with:
37+
tag: "latest"
38+
- uses: advanced-security/codeql-bundle-action/create-bundle@v2
39+
id: create-bundle
40+
with:
41+
bundle-path: ${{ steps.download-bundle.outputs.bundle-path }}
42+
packs: "octo/cpp-queries,octo/cpp-all,octo/cpp-customizations"
43+
- uses: actions/upload-artifact@v3
44+
with:
45+
name: codeql-bundle.tar.gz
46+
path: ${{ steps.create-bundle.outputs.output-path }}
47+
```
48+
49+
The following Action workflow excerpt shows how a custom bundle can be used in a CodeQL analysis workflow.
50+
It assumes the custom bundle is available as a release, but any other location works as long as it is made
51+
available before the `github/codeql-action/init` step and its path is made available to the `tools` input.
52+
53+
```yaml
54+
- name: Download benchmark bundle
55+
env:
56+
GH_TOKEN: ${{ github.token }}
57+
run: |
58+
gh release download -R octo-org/codeql-bundle --pattern 'codeql-bundle.tar.gz'
59+
60+
- name: CodeQL Initialize
61+
uses: github/codeql-action/init@v2
62+
with:
63+
tools: codeql-bundle.tar.gz
64+
```
65+
66+
## Locating your CodeQL packs
67+
68+
The action relies on a CodeQL Workspace to resolve the location of the specified CodeQL packs.
69+
A CodeQL Workspace can be defined using a `codeql-workspace.yml` file that should contain a key `provide` with an array of locations to your CodeQL packs (i.e., the location of the `qlpack.yml` files).
70+
71+
For an example you can consult the test [CodeQL Workspace](tests/codeql-workspace.yml)
72+
73+
By default the action looks at the root of the repository. If the CodeQL Workspace specification is located in a subfolder then you can use the `workspace` input to specify its location.
74+
75+
## Customizations
76+
77+
The CodeQL standard library can be customized by adding implementations of available extension points to a special CodeQL library called `Customizations.qll` that is available for most of the languages (this is not available for C++).
78+
This action uses that mechanism to inject customizations defined in a so called CodeQL customization pack.
79+
80+
A CodeQL customization pack is a concept that doesn't exists outside this action and consists of a CodeQL library pack with extra meta information and structure.
81+
To create a CodeQL customization pack follow these steps:
82+
83+
1. Initialize a new qlpack using the CodeQL CLI as follows (we use Java as an example target): `codeql pack init octo/java-customizations`
84+
2. Change the value of `library` to `true` in the generated file `java-customizations/qlpack.yml`
85+
3. Create the CodeQL module `java-customizations/octo/java_customizations/Customizations.qll` **Note: the directory structure contains the scope and name where the characters `-` are substituted with `_`!**
86+
4. Add the Java standard library as a dependency for development of the customizations using the CodeQL CLI as follows: `codeql pack add --dir=java-customizations codeql/java-all` **Note: ensure the version is compatible with the CodeQL bundle being targeted!**
87+
88+
You can now add your customizations directly in the `Customizations.qll` or other modules that are imported by the `Customizations.qll`.
89+
90+
## Creating platform specific bundles
91+
92+
By default the `download-action` uses the platform agnostic CodeQL bundle that supports all the platforms supported by the CodeQL CLI.
93+
To reduce the size of the final artifact you can use a platform specific bundle by specifying the `platforms` input with one of `osx64`, `linux64`, or `win64`.
94+
Note that the runner **MUST** be compatible with the platform!
95+
96+
The `create-bundle` is capable of building platform specific CodeQL bundles from the platform agnostic bundle.
97+
It will build a bundle for each of the platforms provided in the `platforms` input.
98+
99+
This combination provides the flexibility to build bundles for platforms that are not supported by the Action runner.
100+
For example, the following workflow creates separate bundles for each platform.
101+
102+
```yaml
103+
name: "Build custom bundle"
104+
on:
105+
push:
106+
branches:
107+
- main
108+
pull_request:
109+
branches:
110+
- main
111+
workflow_dispatch:
112+
113+
jobs:
114+
test:
115+
name: "Create custom bundle"
116+
runs-on: ubuntu-latest
117+
steps:
118+
- uses: actions/checkout@v3
119+
- uses: advanced-security/codeql-bundle-action/download-bundle@v2
120+
id: download-bundle
121+
with:
122+
tag: "latest"
123+
- uses: advanced-security/codeql-bundle-action/create-bundle@v2
124+
id: create-bundle
125+
with:
126+
bundle-path: ${{ steps.download-bundle.outputs.bundle-path }}
127+
packs: "octo/cpp-queries,octo/cpp-all,octo/cpp-customizations"
128+
platforms: osx64,win64,linux64
129+
- uses: actions/upload-artifact@v3
130+
with:
131+
name: codeql-bundles
132+
path: ${{ steps.create-bundle.outputs.output-path }}
133+
```
134+
135+
When providing multiple platforms the `output-path` output is a directory containing the bundles, each named according to pattern `codeql-bundle-$PLATFORM.tar.gz`.
136+
137+
## Limitations
138+
139+
This Action uses the [CodeQL bundle CLI](https://github.com/rvermeulen/codeql-bundle) and inherits its limitations.

0 commit comments

Comments
 (0)