From f42aa918a00b879e5e66a1591484d74975a7ffc5 Mon Sep 17 00:00:00 2001 From: ROHAN KAPRI <165539527+RohanKapri@users.noreply.github.com> Date: Tue, 20 Jan 2026 22:50:40 +0530 Subject: [PATCH] Revise CodeQL workflow for improved security analysis Updated CodeQL workflow file to enhance security analysis and documentation. Signed-off-by: ROHAN KAPRI <165539527+RohanKapri@users.noreply.github.com> --- .github/workflows/codeql.yml | 254 +++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 .github/workflows/codeql.yml diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..268803f --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,254 @@ +# ----------------------------------------------------------------------------- +# CodeQL Advanced Security Analysis Workflow +# ----------------------------------------------------------------------------- +# +# This workflow defines the authoritative static analysis policy for this +# repository. It establishes how, when, and under which constraints CodeQL +# performs security and quality analysis across supported languages. +# +# This file is intentionally verbose. Comments exist to document intent, +# not to explain syntax. Syntax can be relearned; intent must be preserved. +# +# Location (mandatory): +# .github/workflows/codeql.yml +# +# Any deviation in filename or directory may disable analysis silently. +# +# ----------------------------------------------------------------------------- + +name: "CodeQL Advanced" + +# ----------------------------------------------------------------------------- +# Trigger Strategy +# ----------------------------------------------------------------------------- +# +# Code scanning is triggered under three conditions: +# +# 1. Direct pushes to the default branch (main) +# Ensures that security posture is continuously evaluated as code evolves. +# +# 2. Pull requests targeting the default branch +# Ensures vulnerabilities are detected before merge, not after release. +# +# 3. Scheduled execution +# Ensures newly discovered vulnerabilities are detected even when the +# codebase itself has not changed. +# +# ----------------------------------------------------------------------------- + +on: + push: + branches: [ "main" ] + + pull_request: + branches: [ "main" ] + + schedule: + # Weekly scheduled scan + # Chosen deliberately to balance freshness with CI load. + - cron: '44 3 * * 1' + +# ----------------------------------------------------------------------------- +# Jobs +# ----------------------------------------------------------------------------- + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + + # ----------------------------------------------------------------------------- + # Runner Selection + # ----------------------------------------------------------------------------- + # + # CodeQL analysis is resource-intensive. Runner choice impacts both + # execution time and analysis completeness. + # + # Swift requires macOS. All other supported languages default to Linux. + # + # ----------------------------------------------------------------------------- + + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + + # ----------------------------------------------------------------------------- + # Permissions Model + # ----------------------------------------------------------------------------- + # + # Principle of least privilege is enforced. + # + # - security-events: required to upload SARIF results + # - packages: required for internal CodeQL packs + # - actions / contents: read-only, required for workflow execution + # + # No write access to repository contents is granted. + # + # ----------------------------------------------------------------------------- + + permissions: + security-events: write + packages: read + actions: read + contents: read + + # ----------------------------------------------------------------------------- + # Matrix Strategy + # ----------------------------------------------------------------------------- + # + # Each language is analyzed independently. Fail-fast is disabled to ensure + # that a failure in one language does not suppress findings in another. + # + # Language selection reflects the actual attack surface of the repository. + # Expanding this list without justification is discouraged. + # + # ----------------------------------------------------------------------------- + + strategy: + fail-fast: false + matrix: + include: + # --------------------------------------------------------------------- + # GitHub Actions + # --------------------------------------------------------------------- + # + # Workflow files are code. They can be exploited. + # This analysis detects insecure workflow patterns. + # + # --------------------------------------------------------------------- + + - language: actions + build-mode: none + + # --------------------------------------------------------------------- + # C / C++ + # --------------------------------------------------------------------- + # + # Includes memory safety, undefined behavior, and common vulnerability + # classes associated with native code. + # + # Autobuild is used unless project-specific constraints require manual + # compilation. + # + # --------------------------------------------------------------------- + + - language: c-cpp + build-mode: autobuild + + # --------------------------------------------------------------------- + # Supported CodeQL languages (reference) + # --------------------------------------------------------------------- + # + # actions + # c-cpp + # csharp + # go + # java-kotlin + # javascript-typescript + # python + # ruby + # rust + # swift + # + # Add languages only when they materially exist in the repository. + # + # --------------------------------------------------------------------- + + # ----------------------------------------------------------------------------- + # Steps + # ----------------------------------------------------------------------------- + + steps: + # ------------------------------------------------------------------------- + # Source Checkout + # ------------------------------------------------------------------------- + # + # Full repository checkout is required for accurate data flow and + # inter-file analysis. + # + # ------------------------------------------------------------------------- + + - name: Checkout repository + uses: actions/checkout@v4 + + # ------------------------------------------------------------------------- + # CodeQL Initialization + # ------------------------------------------------------------------------- + # + # Initializes the CodeQL engine and prepares the database. + # + # build-mode: + # - none → for interpreted or config-only languages + # - autobuild → CodeQL attempts to infer build steps + # - manual → Maintainer-defined build commands + # + # ----------------------------------------------------------------------------- + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + + # --------------------------------------------------------------------- + # Query Configuration + # --------------------------------------------------------------------- + # + # By default, CodeQL uses the standard security query suite. + # Extended or custom queries may be added only with justification. + # + # Example: + # queries: security-extended,security-and-quality + # + # --------------------------------------------------------------------- + + # ------------------------------------------------------------------------- + # Manual Build Hook (Disabled by Default) + # ------------------------------------------------------------------------- + # + # If autobuild fails or is insufficient, switch build-mode to "manual" + # and replace the placeholder commands below with the authoritative + # build process. + # + # Manual builds must be deterministic and documented. + # + # ------------------------------------------------------------------------- + + - name: Run manual build steps + if: matrix.build-mode == 'manual' + shell: bash + run: | + echo 'Manual build mode selected.' + echo 'Replace this block with deterministic build commands.' + exit 1 + + # ------------------------------------------------------------------------- + # Analysis and Result Upload + # ------------------------------------------------------------------------- + # + # This step executes the analysis and uploads SARIF results to GitHub + # Security Code Scanning. + # + # Category separation ensures findings remain scoped per language. + # + # ------------------------------------------------------------------------- + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 + with: + category: "/language:${{ matrix.language }}" + +# ----------------------------------------------------------------------------- +# Operational Guarantees +# ----------------------------------------------------------------------------- +# +# This workflow guarantees: +# +# - No code reaches the default branch without security analysis +# - New vulnerability classes are detected via scheduled scans +# - Results are centrally visible in GitHub Security +# - Analysis is reproducible and reviewable +# +# ----------------------------------------------------------------------------- +# +# This file is part of the repository’s security perimeter. +# Changes must be reviewed with the same rigor as production code. +# +# -----------------------------------------------------------------------------