From 5804e507cd832a9944702fff4222066347535ba3 Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Sat, 2 May 2026 16:01:31 +0100 Subject: [PATCH 1/9] ci: add CodeQL query to enforce OpenSSL return code handling Adds a custom CodeQL query (.github/codeql/openssl-return-check.ql) that detects calls to OpenSSL EVP_* functions whose return value is not guarded by the OQS_OPENSSL_GUARD macro. Integrates the query into a new CodeQL workflow (.github/workflows/codeql.yml) that runs on every PR and push to main. The query was originally written by Trail of Bits during their audit of liboqs and reported in issue #1867. Closes #1867 Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/codeql/openssl-return-check.ql | 26 ++++++++++++++++++ .github/workflows/codeql.yml | 37 ++++++++++++++++++++++++++ .github/workflows/pr.yml | 8 ++++++ 3 files changed, 71 insertions(+) create mode 100644 .github/codeql/openssl-return-check.ql create mode 100644 .github/workflows/codeql.yml diff --git a/.github/codeql/openssl-return-check.ql b/.github/codeql/openssl-return-check.ql new file mode 100644 index 0000000000..5ef7e8dd94 --- /dev/null +++ b/.github/codeql/openssl-return-check.ql @@ -0,0 +1,26 @@ +/** + * @name Unchecked OpenSSL EVP return value + * @description Calls to OpenSSL EVP functions whose return value is not + * checked by the OQS_OPENSSL_GUARD macro may silently ignore + * errors, leading to undefined behaviour. + * @kind problem + * @problem.severity warning + * @precision medium + * @id cpp/openssl-unchecked-return + * @tags security + * correctness + */ + +import cpp + +from FunctionCall call, Function f +where + f = call.getTarget() and + f.getName().matches("EVP%") and + not f.getType() instanceof PointerType and + not f.getType() instanceof VoidType and + not exists(MacroAccess m | + m.getLocation().subsumes(call.getLocation()) and + m.getMacroName() = "OQS_OPENSSL_GUARD" + ) +select call, "Return value of " + f.getName() + "() is not checked by OQS_OPENSSL_GUARD." diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000000..e7312b0927 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,37 @@ +name: CodeQL analysis + +permissions: + contents: read + security-events: write + +on: + workflow_call: + workflow_dispatch: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + codeql: + name: CodeQL + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3 + with: + languages: cpp + queries: .github/codeql/openssl-return-check.ql + + - name: Build liboqs + run: | + cmake -S . -B build -DOQS_MINIMAL_BUILD="KEM_ml_kem_768;SIG_ml_dsa_65" + cmake --build build --parallel $(nproc) + + - name: Perform CodeQL analysis + uses: github/codeql-action/analyze@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3 + with: + category: "/language:cpp" diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index b97daf3be0..af5ce73972 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -31,3 +31,11 @@ jobs: contents: read id-token: write security-events: write + + codeql: + needs: basic-checks + uses: ./.github/workflows/codeql.yml + secrets: inherit + permissions: + contents: read + security-events: write From feb12ad5f43da512fecad834b59fdc6c4f0709c1 Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Sat, 2 May 2026 16:30:50 +0100 Subject: [PATCH 2/9] ci: move security-events permission to job level in CodeQL workflow Addresses Scorecard Token-Permissions finding: security-events write permission scoped to codeql job only, not workflow level. Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/workflows/codeql.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index e7312b0927..078f85c99c 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -2,7 +2,6 @@ name: CodeQL analysis permissions: contents: read - security-events: write on: workflow_call: @@ -14,6 +13,10 @@ on: jobs: codeql: + permissions: + contents: read + security-events: write + name: CodeQL runs-on: ubuntu-latest steps: From 4236b26d658eab570ead8a74014433c8fb86c404 Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Tue, 5 May 2026 15:43:26 +0100 Subject: [PATCH 3/9] ci: fix CodeQL query path using config file Replace inline queries: path with a codeql-config.yml config file. The CodeQL init action requires local queries to be referenced via a config file rather than a direct relative path in the queries field. Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/codeql/codeql-config.yml | 3 +++ .github/workflows/codeql.yml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 .github/codeql/codeql-config.yml diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml new file mode 100644 index 0000000000..f75f16dd7d --- /dev/null +++ b/.github/codeql/codeql-config.yml @@ -0,0 +1,3 @@ +name: "OQS CodeQL config" +queries: + - uses: ./.github/codeql/openssl-return-check.ql diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 078f85c99c..fe0856a524 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -27,7 +27,7 @@ jobs: uses: github/codeql-action/init@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3 with: languages: cpp - queries: .github/codeql/openssl-return-check.ql + config-file: ./.github/codeql/codeql-config.yml - name: Build liboqs run: | From fbb718c72decdbe0b51ae8fcfc7cc596690c3544 Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Tue, 5 May 2026 15:50:42 +0100 Subject: [PATCH 4/9] ci: disable CodeQL TRAP caching to fix pre-finalize crash The CodeQL cpp extractor pre-finalize script crashes with exit code 134 when the trapCaches/cpp/tarballs directory does not exist on the runner. Disabling TRAP caching avoids the crash. Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/workflows/codeql.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index fe0856a524..f4982944f3 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -19,6 +19,8 @@ jobs: name: CodeQL runs-on: ubuntu-latest + env: + CODEQL_EXTRACTOR_CPP_TRAP_CACHING: false steps: - name: Checkout code uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 From 43313b33ba08130eb8b8e5519e6743df32bf59b3 Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Mon, 11 May 2026 21:30:55 +0100 Subject: [PATCH 5/9] ci: use inline queries field per maintainer suggestion Replace config-file approach with inline queries field combining security-and-quality suite with the custom EVP return check query, as suggested by @baentsch. Remove codeql-config.yml. Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/codeql/codeql-config.yml | 3 --- .github/workflows/codeql.yml | 11 +---------- 2 files changed, 1 insertion(+), 13 deletions(-) delete mode 100644 .github/codeql/codeql-config.yml diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml deleted file mode 100644 index f75f16dd7d..0000000000 --- a/.github/codeql/codeql-config.yml +++ /dev/null @@ -1,3 +0,0 @@ -name: "OQS CodeQL config" -queries: - - uses: ./.github/codeql/openssl-return-check.ql diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index f4982944f3..68d2e41d6f 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,8 +1,6 @@ name: CodeQL analysis - permissions: contents: read - on: workflow_call: workflow_dispatch: @@ -10,32 +8,25 @@ on: branches: [main] pull_request: branches: [main] - jobs: codeql: permissions: contents: read security-events: write - name: CodeQL runs-on: ubuntu-latest - env: - CODEQL_EXTRACTOR_CPP_TRAP_CACHING: false steps: - name: Checkout code uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 - - name: Initialize CodeQL uses: github/codeql-action/init@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3 with: languages: cpp - config-file: ./.github/codeql/codeql-config.yml - + queries: security-and-quality,./.github/codeql/openssl-return-check.ql - name: Build liboqs run: | cmake -S . -B build -DOQS_MINIMAL_BUILD="KEM_ml_kem_768;SIG_ml_dsa_65" cmake --build build --parallel $(nproc) - - name: Perform CodeQL analysis uses: github/codeql-action/analyze@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3 with: From 75bee09dcbbae65191f67223fe0173e0ba9cf2d3 Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Mon, 11 May 2026 21:34:11 +0100 Subject: [PATCH 6/9] ci: re-add TRAP caching workaround after queries field change Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/workflows/codeql.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 68d2e41d6f..5afb9bf4ee 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -13,6 +13,8 @@ jobs: permissions: contents: read security-events: write + env: + CODEQL_EXTRACTOR_CPP_TRAP_CACHING: false name: CodeQL runs-on: ubuntu-latest steps: From 1d1048bd0ee678a00c27174c9535e6e69d648ebd Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Mon, 11 May 2026 21:43:21 +0100 Subject: [PATCH 7/9] ci: disable SARIF upload to avoid default setup conflict Adding upload: false to the analyze step prevents the SARIF conflict with GitHub's default CodeQL setup which is enabled on this repo. The query still runs and catches issues but does not upload results. Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/workflows/codeql.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 5afb9bf4ee..cc85ffdc54 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -33,3 +33,4 @@ jobs: uses: github/codeql-action/analyze@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3 with: category: "/language:cpp" + upload: false From 7846e61038e65c79324f47dedb5f47cdc0b25ffc Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Tue, 14 Jul 2026 23:56:47 +0100 Subject: [PATCH 8/9] ci: add CodeQL query test example and CONTRIBUTING docs Add bad example at .github/codeql/test/openssl-return-check-bad.c to confirm the query catches unchecked EVP_* calls. Document verification steps in CONTRIBUTING.md. Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/codeql/test/openssl-return-check-bad.c | 5 +++++ CONTRIBUTING.md | 8 ++++++++ 2 files changed, 13 insertions(+) create mode 100644 .github/codeql/test/openssl-return-check-bad.c diff --git a/.github/codeql/test/openssl-return-check-bad.c b/.github/codeql/test/openssl-return-check-bad.c new file mode 100644 index 0000000000..dad16fba01 --- /dev/null +++ b/.github/codeql/test/openssl-return-check-bad.c @@ -0,0 +1,5 @@ +/* expect-fail: EVP return value not checked via OQS_OPENSSL_GUARD */ +#include +void bad_example(EVP_MD_CTX *ctx, const EVP_MD *md) { + EVP_DigestInit_ex(ctx, md, NULL); +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5633897d8e..b22eeaaf47 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,3 +106,11 @@ If you feel like contributing but don't know what specific topic to work on, please check the [open issues tagged "good first issue" or "help wanted"](https://github.com/open-quantum-safe/liboqs/issues). You can also take a look at the [contribution wishlist](https://github.com/open-quantum-safe/liboqs/wiki/Contribution-wishlist) for more substantial contributions we are interested in. + +## Verifying the CodeQL OpenSSL return-check query +The query detects EVP_* calls not wrapped in OQS_OPENSSL_GUARD. +A deliberately bad example lives in +.github/codeql/test/openssl-return-check-bad.c. +When CodeQL runs, any match against this file confirms the query +is scanning correctly. CI will flag new violations automatically +on every PR. From 81255c48b046c79de334853e5c10f1cd344f86fe Mon Sep 17 00:00:00 2001 From: Vishnu Ajith <27vishnu07@gmail.com> Date: Wed, 15 Jul 2026 00:06:04 +0100 Subject: [PATCH 9/9] ci: add SPDX header to CodeQL test file Signed-off-by: Vishnu Ajith <27vishnu07@gmail.com> --- .github/codeql/test/openssl-return-check-bad.c | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/codeql/test/openssl-return-check-bad.c b/.github/codeql/test/openssl-return-check-bad.c index dad16fba01..42d8fb0e86 100644 --- a/.github/codeql/test/openssl-return-check-bad.c +++ b/.github/codeql/test/openssl-return-check-bad.c @@ -1,3 +1,4 @@ +// SPDX-License-Identifier: MIT /* expect-fail: EVP return value not checked via OQS_OPENSSL_GUARD */ #include void bad_example(EVP_MD_CTX *ctx, const EVP_MD *md) {