|
2 | 2 |
|
3 | 3 | This repository contains CodeQL queries developed by Trail of Bits and made available to the public. They are part of our ongoing development efforts and are used in our security audits, vulnerability research, and internal projects. They will evolve over time as we identify new techniques. |
4 | 4 |
|
5 | | -## Using custom CodeQL queries |
| 5 | +## Setup |
6 | 6 |
|
7 | | -The easiest is to [download all packs](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#running-codeql-pack-download-scopepack) from the GitHub registry: |
8 | | -```sh |
9 | | -codeql pack download trailofbits/cpp-queries trailofbits/go-queries |
| 7 | +```bash |
| 8 | +make download |
| 9 | +codeql resolve packs | grep trailofbits |
10 | 10 | ``` |
11 | 11 |
|
12 | | -Then verify that new queries are installed: |
13 | | -```sh |
14 | | -codeql resolve qlpacks | grep trailofbits |
15 | | -``` |
| 12 | +See [QUERIES.md](doc/QUERIES.md) for the full list of queries. |
16 | 13 |
|
17 | | -And use the queries for analysis: |
18 | | -```sh |
| 14 | +## Usage |
| 15 | + |
| 16 | +```bash |
19 | 17 | codeql database analyze database.db --format=sarif-latest --output=./tob.sarif -- trailofbits/cpp-queries |
20 | | -# or |
21 | 18 | codeql database analyze database.db --format=sarif-latest --output=./tob.sarif -- trailofbits/go-queries |
| 19 | +codeql database analyze database.db --format=sarif-latest --output=./tob.sarif -- trailofbits/java-queries |
22 | 20 | ``` |
23 | 21 |
|
24 | | -## Queries |
25 | | - |
26 | | -### C and C++ |
27 | | - |
28 | | -#### Cryptography |
29 | | - |
30 | | -| Name | Description | Severity | Precision | |
31 | | -| --- | ----------- | :----: | :--------: | |
32 | | -|[BN_CTX_free called before BN_CTX_end](./cpp/src/docs/crypto/BnCtxFreeBeforeEnd.md)|Detects BN_CTX_free called before BN_CTX_end, which violates the required lifecycle|error|medium| |
33 | | -|[Unbalanced BN_CTX_start and BN_CTX_end pair](./cpp/src/docs/crypto/UnbalancedBnCtx.md)|Detects if one call in the BN_CTX_start/BN_CTX_end pair is missing|warning|medium| |
34 | | -|[Crypto variable initialized using static key](./cpp/src/docs/crypto/StaticKeyFlow.md)|Finds crypto variables initialized using static keys|error|high| |
35 | | -|[Crypto variable initialized using static password](./cpp/src/docs/crypto/StaticPasswordFlow.md)|Finds crypto variables initialized using static passwords|error|high| |
36 | | -|[Crypto variable initialized using weak randomness](./cpp/src/docs/crypto/WeakRandomnessTaint.md)|Finds crypto variables initialized using weak randomness|error|high| |
37 | | -|[Invalid key size](./cpp/src/docs/crypto/InvalidKeySize.md)|Tests if keys passed to EVP_EncryptInit and EVP_EncryptInit_ex have the same size as the key size of the cipher used|warning|medium| |
38 | | -|[Memory leak related to custom allocator](./cpp/src/docs/crypto/CustomAllocatorLeak.md)|Finds memory leaks from custom allocated memory|warning|medium| |
39 | | -|[Memory use after free related to custom allocator](./cpp/src/docs/crypto/CustomAllocatorUseAfterFree.md)|Finds use-after-frees related to custom allocators like `BN_new`|warning|medium| |
40 | | -|[Missing OpenSSL engine initialization](./cpp/src/docs/crypto/MissingEngineInit.md)|Finds created OpenSSL engines that may not be properly initialized|warning|medium| |
41 | | -|[Missing error handling](./cpp/src/docs/crypto/MissingErrorHandling.md)|Checks if returned error codes are properly checked|warning|high| |
42 | | -|[Missing zeroization of potentially sensitive random BIGNUM](./cpp/src/docs/crypto/MissingZeroization.md)|Determines if random bignums are properly zeroized|warning|medium| |
43 | | -|[Random buffer too small](./cpp/src/docs/crypto/RandomBufferTooSmall.md)|Finds buffer overflows in calls to CSPRNGs|warning|high| |
44 | | -|[Use of legacy cryptographic algorithm](./cpp/src/docs/crypto/UseOfLegacyAlgorithm.md)|Detects potential instantiations of legacy cryptographic algorithms|warning|medium| |
45 | | - |
46 | | -#### Security |
47 | | - |
48 | | -| Name | Description | Severity | Precision | |
49 | | -| --- | ----------- | :----: | :--------: | |
50 | | -|[Async unsafe signal handler](./cpp/src/docs/security/AsyncUnsafeSignalHandler/AsyncUnsafeSignalHandler.md)|Async unsafe signal handler (like the one used in CVE-2024-6387)|warning|high| |
51 | | -|[Decrementation overflow when comparing](./cpp/src/docs/security/DecOverflowWhenComparing/DecOverflowWhenComparing.md)|This query finds unsigned integer overflows resulting from unchecked decrementation during comparison.|error|high| |
52 | | -|[Find all problematic implicit casts](./cpp/src/docs/security/UnsafeImplicitConversions/UnsafeImplicitConversions.md)|Find all implicit casts that may be problematic. That is, casts that may result in unexpected truncation, reinterpretation or widening of values.|error|high| |
53 | | -|[Inconsistent handling of return values from a specific function](./cpp/src/docs/security/InconsistentReturnValueHandling/InconsistentReturnValueHandling.md)|Detects functions whose return values are compared inconsistently across call sites, which may indicate bugs|warning|medium| |
54 | | -|[Invalid string size passed to string manipulation function](./cpp/src/docs/security/CStrnFinder/CStrnFinder.md)|Finds calls to functions that take as input a string and its size as separate arguments (e.g., `strncmp`, `strncat`, ...) and the size argument is wrong|error|low| |
55 | | -|[Iterator invalidation](./cpp/src/docs/security/IteratorInvalidation/IteratorInvalidation.md)|Modifying a container while iterating over it can invalidate iterators, leading to undefined behavior.|warning|medium| |
56 | | -|[Missing null terminator](./cpp/src/docs/security/NoNullTerminator/NoNullTerminator.md)|This query finds incorrectly initialized strings that are passed to functions expecting null-byte-terminated strings|error|high| |
57 | | - |
58 | | -### Go |
59 | | - |
60 | | -#### Cryptography |
61 | | - |
62 | | -| Name | Description | Severity | Precision | |
63 | | -| --- | ----------- | :----: | :--------: | |
64 | | -|[Message not hashed before signature verification](./go/src/docs/crypto/MsgNotHashedBeforeSigVerfication/MsgNotHashedBeforeSigVerfication.md)|Detects calls to (EC)DSA APIs with a message that was not hashed. If the message is longer than the expected hash digest size, it is silently truncated|error|medium| |
65 | | - |
66 | | -#### Security |
67 | | - |
68 | | -| Name | Description | Severity | Precision | |
69 | | -| --- | ----------- | :----: | :--------: | |
70 | | -|[Invalid file permission parameter](./go/src/docs/security/FilePermsFlaws/FilePermsFlaws.md)|Finds non-octal (e.g., `755` vs `0o755`) and unsupported (e.g., `04666`) literals used as a filesystem permission parameter (`FileMode`)|error|medium| |
71 | | -|[Missing MinVersion in tls.Config](./go/src/docs/security/MissingMinVersionTLS/MissingMinVersionTLS.md)|Finds uses of tls.Config where MinVersion is not set and the project's minimum Go version (from go.mod) indicates insecure defaults: Go < 1.18 for clients or Go < 1.22 for servers. Does not mark explicitly set versions (including explicitly insecure ones).|error|medium| |
72 | | -|[Trim functions misuse](./go/src/docs/security/TrimMisuse/TrimMisuse.md)|Finds calls to `string.{Trim,TrimLeft,TrimRight}` with the 2nd argument not being a cutset but a continuous substring to be trimmed|error|low| |
73 | | - |
74 | | -### Java-kotlin |
75 | | - |
76 | | -#### Security |
77 | | - |
78 | | -| Name | Description | Severity | Precision | |
79 | | -| --- | ----------- | :----: | :--------: | |
80 | | -|[Recursive functions](./java-kotlin/src/docs/security/Recursion/Recursion.md)|Detects possibly unbounded recursive calls|warning|low| |
81 | | - |
82 | 22 | ## Query suites |
83 | 23 |
|
84 | | -CodeQL queries are grouped into "suites". To execute queries from a specific suit add its name after a colon: `trailofbits/cpp-queries:codeql-suites/tob-cpp-full.qls`. |
| 24 | +CodeQL queries are grouped into suites. To execute queries from a specific suite add its name after a colon: `trailofbits/cpp-queries:codeql-suites/tob-cpp-full.qls`. |
85 | 25 |
|
86 | | -The recommended suit - `tob-cpp-code-scanning.qls` - is chosen and executed when you do not explicitly specify any suit. Other suits in this repository are: |
| 26 | +The recommended suite - `tob-cpp-code-scanning.qls` - is chosen and executed when you do not explicitly specify any suite. Other suites in this repository are: |
87 | 27 |
|
88 | 28 | * `tob-<lang>-crypto.qls` - queries targeting cryptographic vulnerabilities |
89 | 29 | * `tob-<lang>-security.qls` - queries targeting standard security issues |
90 | 30 | * `tob-<lang>-full.qls` - all queries, including experimental ones |
91 | 31 |
|
92 | 32 | ## Development |
93 | 33 |
|
94 | | -#### Prepare environment |
| 34 | +### Prepare environment |
| 35 | + |
| 36 | +Configure global CodeQL's search path: |
95 | 37 |
|
96 | | -Clone this repository and configure global CodeQL's search path: |
97 | | -```sh |
98 | | -git clone git@github.com:trailofbits/codeql-queries.git |
| 38 | +```bash |
| 39 | +git clone https://github.com/trailofbits/codeql-queries |
99 | 40 | mkdir -p "${HOME}/.config/codeql/" |
100 | 41 | echo "--search-path '$PWD/codeql-queries'" > "${HOME}/.config/codeql/config" |
101 | | -``` |
102 | | - |
103 | | -Check that CodeQL CLI detects the new qlpacks: |
104 | | -```sh |
105 | | -codeql resolve packs | grep trailofbits |
106 | | -``` |
107 | 42 |
|
108 | | -#### Before committing |
| 43 | +cd codeql-queries/ |
| 44 | +make pack-install |
109 | 45 |
|
110 | | -Run tests: |
111 | | - |
112 | | -```sh |
113 | | -make test |
114 | | -``` |
115 | | - |
116 | | -Format queries: |
117 | | - |
118 | | -```sh |
119 | | -make format |
120 | | -``` |
121 | | - |
122 | | -Install dependencies: |
123 | | - |
124 | | -```sh |
125 | | -make install |
| 46 | +codeql resolve packs | grep trailofbits |
126 | 47 | ``` |
127 | 48 |
|
128 | | -Generate query tables and copy-paste it to README.md file |
129 | | -```sh |
130 | | -python ./scripts/queries_table_generator.py 2>/dev/null |
131 | | -``` |
| 49 | +### Before committing |
132 | 50 |
|
133 | | -Generate markdown query help files |
134 | | -```sh |
135 | | -codeql generate query-help ./cpp/src/ --format=markdown --output ./cpp/src/docs |
136 | | -codeql generate query-help ./go/src/ --format=markdown --output ./go/src/docs |
137 | | -codeql generate query-help ./java/src/ --format=markdown --output ./java/src/docs |
| 51 | +```bash |
| 52 | +make pack-upgrade |
| 53 | +make test format |
| 54 | +make generate-table generate-help |
138 | 55 | ``` |
0 commit comments