codeql-security-analysis

CodeQL security analysis

Contract

Inputs

Required:

• Target project root path.
• Primary language(s) to analyze, or an existing reusable CodeQL database path.

Optional but needed when applicable:

• Build command for compiled languages (the real build must run under CodeQL extraction).
• Explicit query suite or ruleset selection.
• Project-specific source and sink models to author as CodeQL data extensions.
• Output directory path; defaults to a dedicated directory under the project root.
• User authority for any target-project dependency or query-pack installation.

Procedure

1. Create a dedicated output directory (for example <project-root>/.codeql-out); every database, log, data extension, suite, and SARIF artifact lands there. Do not write anywhere else. Done when: the output directory exists and no artifact is written outside it.
2. Resolve or build the database. If a reusable database path is supplied, resolve it with codeql database resolve and confirm it targets the requested language. Otherwise build with codeql database create using the project's real build command for compiled languages, or source-only --overwrite extraction for interpreted languages. Record the exact build command and its exit status as build evidence in the output directory. Done when: the database resolves or builds and build evidence is recorded.
3. Run the applicable quality gate. Inspect extraction warnings and source-file coverage with codeql database resolve and source-location inspection. If the database fails the gate (missing source files, zero extracted files, build errors, or unresolved language), stop and report the failure class; do not proceed to analysis. Done when: the database passes the quality gate or the failure class is reported and the skill stops.
4. Select an explicit query suite or ruleset and resolve it with codeql resolve queries --queries=<suite>. Confirm the resolved query count is nonzero. If it resolves to zero queries, stop and report the suite path. Done when: the query suite resolves nonzero or the zero-query suite path is reported.
5. If the user asks to model project-specific sources and sinks, author CodeQL data-extension YAML under the output directory and include it via --search-path or --additional-packs. Validate each extension against the CodeQL data-extension schema before use; reject invalid extensions and stop. Done when: all data extensions validate or an invalid extension is rejected.
6. Run analysis with codeql database analyze <database> <suite> --format=sarif-latest --output=<output>/raw.sarif, passing any data-extension search path. Capture stdout and stderr as an analysis log in the output directory. Tune --threads to available cores and memory; prefer --threads=0 only when memory is sufficient. Done when: analysis completes and raw SARIF plus the analysis log are in the output directory.
7. Post-process raw SARIF: de-duplicate results, apply severity filtering, attach the ruleset-selection metadata, and write final SARIF to the output directory. Record which ruleset and query suite were selected. Done when: final SARIF is written with ruleset metadata.
8. Explain coverage. If findings are zero, or if any language or path was skipped (for example a language that was not built), state explicitly why. Never report a clean result without stating the coverage basis. Done when: zero findings or skipped coverage is explained with the coverage basis.
9. Rollback path: to undo all side effects, delete the output directory. The target project source is never modified. Done when: the rollback path is stated and the target source is confirmed unmodified.