codeql-skill

CodeQL security audit pipeline: static scanning, SARIF triage, and QL query optimization. Trigger on: CodeQL, .ql, .sarif, taint tracking, source→sink, LGTM,...

Security Scan

The skill's files and instructions match a CodeQL audit tool, but the metadata omits required tooling and the scanner will run repository build commands (which can execute arbitrary code) without warning — these inconsistencies and risks warrant caution.

Purpose & Capability

The skill claims CodeQL scanning, SARIF triage, and QL tuning — that matches the included scripts. However the registry metadata lists no required binaries or credentials, while scripts clearly invoke external tools: 'codeql' (scan.sh), 'python3' (audit.py, tune.py) and standard build tools if present (mvn, gradle, make). The missing declaration of required binaries is an incoherence and should be fixed.

Instruction Scope

SKILL.md directs the agent to run the provided scripts. scan.sh will auto-detect language and may run project build commands (mvn/gradle/make) and passes them to 'codeql database create' via --command. Executing a repo's build can run arbitrary code from that repository (e.g., malicious build scripts or plugins). SKILL.md does not warn about this sandboxing risk or recommend isolating execution. audit.py and tune.py operate on local files and do not exfiltrate data, but the scan flow has significant scope creep (running builds, network fetching of CodeQL packs via 'codeql' CLI).

Install Mechanism

There is no install spec (instruction-only style) and the skill ships code files. That keeps platform-level install risk low, but runtime risk depends on external binaries being present. The absence of a declared install step is reasonable, but the skill should declare prerequisites (codeql CLI, python3, bash, optional build tools).

Credentials

The skill does not request environment variables or credentials in metadata and the scripts do not explicitly read secrets. However, running codeql and project builds may implicitly read local configuration (e.g., Maven/Gradle settings, ~/.m2/settings.xml, environment vars used by builds), which could expose secrets if the repo build process references them. This implicit access is not documented and is worth flagging.

Persistence & Privilege

The skill is not always-enabled and does not request permanent presence or modify other skills. It does write output files (SARIF/exp.md/optimized reports) under working directory when invoked, which is expected behavior.

What to consider before installing

This skill appears to implement what it says, but there are important mismatches and runtime risks to consider before installing or running it: - Missing prerequisite declaration: the metadata claims no required binaries, yet scripts call 'codeql', 'python3', and potentially 'mvn', 'gradle', or 'make'. Verify you have these tools and ask the publisher to update the metadata to list them. - Dangerous default behavior when scanning repos: scan.sh may execute repository build commands (via mvn/gradle/make and passing --command to codeql). Building an untrusted repository can execute arbitrary code (malicious build plugins, scripts). Do NOT run scans on untrusted code on your host. Run scans in an isolated environment (ephemeral VM, container, or sandbox) with limited network and no secret mounts. - Network and pack downloads: running 'codeql database analyze' or using codeql packs can fetch query suites/packs from registries. If you require air-gapped operation, confirm codeql behavior or prefetch packs from trusted sources. - Secrets exposure via build tooling: project builds may read local config (e.g., ~/.m2/settings.xml, environment variables) and could leak secrets to build steps. Avoid mounting sensitive files when scanning third-party code. - Audit the scripts yourself: the included scripts are short and readable; review them (scan.sh, audit.py, tune.py) before running. If you want safer operation: create the CodeQL database yourself (without --command), or run codeql with builds performed in a controlled way; run codeql and script invocations as a non-privileged user. If you plan to use this skill, request that the publisher: (1) declare required binaries and optional build tools in metadata, (2) add explicit warnings about building repositories and best practices for sandboxing, and (3) provide an option to skip automatic build/--command to avoid executing repo code.

CodeQL Security Audit Skill

Three independent modes — identify which one the user needs and run the corresponding script.

User Intent	Mode	Script
Scan a repo / create a DB / generate SARIF	[SCAN]	scripts/scan.sh
Read SARIF / triage vulns / generate report	[AUDIT]	scripts/audit.py
Optimize or debug a .ql query file	[TUNE]	scripts/tune.py

---

[SCAN]

bash scripts/scan.sh <repo_path> [language] [output.sarif]
# language: java | javascript | python | cpp | auto (default)

The script handles: language detection → build command selection → CodeQL DB creation → security suite scan → SARIF output.

For writing custom queries, refer to the relevant language reference: references/lang-java.md / lang-javascript.md / lang-python.md / lang-cpp.md

---

[AUDIT]

python3 scripts/audit.py <results.sarif> --output exp.md

The script handles: SARIF parsing → attack surface inventory → vuln family grouping → source→sink evidence chain extraction → exp.md output.

Claude's responsibility (what the script cannot do):

• Manually assess [SUSPICIOUS] entries with no data flow — determine if they are real vulnerabilities
• Write POC requests based on business context
• Provide concrete remediation code

---

[TUNE]

python3 scripts/tune.py <query.ql>

The script outputs a tuning checklist covering seven checks: coverage, false positives, performance, and metadata completeness.

Claude's responsibility (what the script cannot do):

• Rewrite source / sink / sanitizer logic based on checklist findings
• Debug queries with no results or unexpected output — refer to references/debugging.md