{"id":34204962,"url":"https://github.com/codeql-agent-project/codeql-agent-docker","last_synced_at":"2026-03-07T02:36:48.616Z","repository":{"id":47078734,"uuid":"416779612","full_name":"codeql-agent-project/codeql-agent-docker","owner":"codeql-agent-project","description":":floppy_disk: The CodeQL for Docker. It supports static application security testing (SAST).","archived":false,"fork":false,"pushed_at":"2025-12-06T00:44:01.000Z","size":23156,"stargazers_count":18,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-12-09T14:38:36.662Z","etag":null,"topics":["audit","docker","docker-image","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeql-agent-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-10-13T14:35:28.000Z","updated_at":"2025-07-28T11:42:58.000Z","dependencies_parsed_at":"2023-02-18T03:16:21.453Z","dependency_job_id":"55ac6e47-82fa-4c71-a99e-800f3114efa8","html_url":"https://github.com/codeql-agent-project/codeql-agent-docker","commit_stats":null,"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/codeql-agent-project/codeql-agent-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeql-agent-project%2Fcodeql-agent-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeql-agent-project%2Fcodeql-agent-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeql-agent-project%2Fcodeql-agent-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeql-agent-project%2Fcodeql-agent-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeql-agent-project","download_url":"https://codeload.github.com/codeql-agent-project/codeql-agent-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeql-agent-project%2Fcodeql-agent-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29671803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit","docker","docker-image","static-analysis"],"created_at":"2025-12-15T19:34:36.061Z","updated_at":"2026-02-21T02:41:00.208Z","avatar_url":"https://github.com/codeql-agent-project.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeQL Agent for Docker\n[![Actions Status](https://github.com/docker/compose-cli/workflows/Continuous%20integration/badge.svg)](https://hub.docker.com/repository/docker/doublevkay/codeql-agent)[![Docker Pulls](https://badgen.net/docker/pulls/doublevkay/codeql-agent?icon=docker\u0026label=pulls)](https://hub.docker.com/repository/docker/doublevkay/codeql-agent)[![Docker Image Size](https://badgen.net/docker/size/doublevkay/codeql-agent?icon=docker\u0026label=image%20size)](https://hub.docker.com/repository/docker/doublevkay/codeql-agent)![Github stars](https://badgen.net/github/stars/codeql-agent-project/codeql-agent-docker?icon=github\u0026label=stars)\n\nCodeQL Agent is a project aimed at automating the use of CodeQL. The project helps create database and execute CodeQL analysis. CodeQL Agent is a Docker image.\n\nCodeQL Agent for Docker is also the base image of [CodeQL Agent for Visual Studio Code](https://github.com/vovikhangcdv/codeql-agent-extension) - an extension for [Visual Studio Code](https://code.visualstudio.com/) that simplifies CodeQL usage and executes code scanning automatically.\n\nThe CodeQL Agent image is released on **Docker Hub** under the name [`doublevkay/codeql-agent`](https://hub.docker.com/repository/docker/doublevkay/codeql-agent). You can use it without building locally.\n\n\n### Contents:\n  - [What is this for?](#what-is-this-for)\n  - [Getting started](#getting-started)\n  - [Examples usage](#examples-usage)\n  - [Supported options](#supported-options)\n  - [Build](#build)\n  - [How does it work?](#how-does-it-work)\n  - [Support](#support)\n  - [Contributing](#contributing)\n  - [Contributors](#contributors)\n  - [Release notes](#release-notes)\n  - [License](#license)\n\n\n## What is this for?\n\nCodeQL Agent for Docker provides these key features:\n- Detecting language automatically.\n- Creating CodeQL database.\n- Executing CodeQL database analysis.\n- Auto sync the latest version of CodeQL CLI and CodeQL library.\n\n## Getting Started\n[Bind mounts](https://docs.docker.com/storage/bind-mounts/) the source, the results folder and run `codeql-agent` image with the following docker command.\n\n```console\ndocker run --rm --name codeql-agent-docker \\\n  -v \"$PWD:/opt/src\" \\\n  -v \"$PWD/codeql-agent-results:/opt/results\" \\\n  doublevkay/codeql-agent\n```\n\nYou also can specify more options to run CodeQL Agent. See [Supported options](#supported-options) for more details. \n\n\n## Supported options\nYou can set environment variables to use the following supported options:\n| Variable  | Description |\n| ------- | ----------- |\n`LANGUAGE`| Value `\u003clanguage\u003e`. Set project language to build database or execute SAST. The `\u003clanguage\u003e` must be: `go`, `java`, `cpp`, `csharp`, `python`, `javascript`, `ruby`.\n`USERID` | Value `\u003cid\u003e`. Set the owner of the results folder to `\u003cid\u003e`.\n`GROUPID` | Value `\u003cgroup_id\u003e`. Set the group owner of the results folder to `\u003cgroup_id\u003e`.\n`THREADS` | Value `\u003cnumber_of_threads\u003e`. Use this many threads to build database and evaluate queries. Defaults to 1. You can pass 0 to use one thread per core on the machine.\n`OVERWRITE_FLAG` | Value `--overwrite`. Enable/disable overwrite database when database path exists and not an empty directory. This flag is useful for forcibly rebuilding the database.\n`QS`| Value `\u003cqueries-suite\u003e`. Specify a list of queries to run over your database. The default value is `\u003clanguage\u003e-security-extended.qls`. For more details, please see [Analyzing databases with the CodeQL CLI](https://codeql.github.com/docs/codeql-cli/analyzing-databases-with-the-codeql-cli/#running-codeql-database-analyze).\n`SAVE_CACHE_FLAG` | Value `--save-cache`. Aggressively save intermediate results to the disk cache. This may speed up subsequent queries if they are similar. Be aware that using this option will greatly increase disk usage and initial evaluation time. \n`ACTION` | Value `create-database-only`. Creating CodeQL database only without executing CodeQL analysis.\n`COMMAND` | Value `\u003ccommand\u003e`. The variable used when you create a CodeQL database for one or more compiled languages, omit if the only languages requested are Python and JavaScript. This specifies the build commands needed to invoke the compiler. If you don't set this variable, CodeQL will attempt to detect the build system automatically, using a built-in autobuilder. \n-----\n\n***Disclaimer:** CodeQL Agent directly forwards these options to the command arguments while running the container. Please take it as your security responsibility.*\n\n\n## Examples usage\n\n\u003cdetails\u003e\n    \u003csummary\u003eBasic code scanning.\u003c/summary\u003e\n\n```bash\ndocker run --rm --name codeql-agent-docker \\\n  -v \"$PWD:/opt/src\" \\\n  -v \"$PWD/codeql-agent-results:/opt/results\" \\\n  doublevkay/codeql-agent\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n    \u003csummary\u003eCode scanning with maximum threads available.\u003c/summary\u003e\n\n```bash\ndocker run --rm --name codeql-agent-docker \\\n  -v \"$PWD:/opt/src\" \\\n  -v \"$PWD/codeql-agent-results:/opt/results\" \\\n  -e \"THREADS=0\" \\\n  doublevkay/codeql-agent\n```\n  \u003c/details\u003e\n\n\u003cdetails\u003e\n    \u003csummary\u003eCreate database only.\u003c/summary\u003e\n\n```bash\ndocker run --rm --name codeql-agent-docker \\\n  -v \"$PWD:/opt/src\" \\\n  -v \"$PWD/codeql-agent-results:/opt/results\" \\\n  -e \"ACTION=create-database-only\" \\\n  doublevkay/codeql-agent\n```\n  \u003c/details\u003e\n\n\u003cdetails\u003e\n    \u003csummary\u003eSpecify the queries suite for Java source.\u003c/summary\u003e\n\n```bash\ndocker run --rm --name codeql-agent-docker \\\n  -v \"$PWD:/opt/src\" \\\n  -v \"$PWD/codeql-agent-results:/opt/results\" \\\n  -e \"LANGUAGE=java\" \\\n  -e \"QS=java-security-and-quality.qls\" \\\n  doublevkay/codeql-agent\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n    \u003csummary\u003eChange owner of the results folder.\u003c/summary\u003e\n    Because CodeQL Agent runs the script as root in Docker containers. So maybe you need to change the results folder owner to your own.\n\n```bash\ndocker run --rm --name codeql-agent-docker \\\n  -v \"$PWD:/opt/src\" \\\n  -v \"$PWD/codeql-agent-results:/opt/results\" \\\n  -e \"USERID=$(id -u ${USER})\" -e \"GROUPID=$(id -g ${USER}) \\\n  doublevkay/codeql-agent\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n    \u003csummary\u003e Specify the Java version and the build database command \u003c/summary\u003e\n\nBy default, we use JDK 11 and Maven 3.6.3 for the CodeQL agent image. We can change the versions of Java and Maven by mounting a volume and setting the JAVA_HOME and MAVEN_HOME environment variables in the CodeQL agent container. For example:\n\n1. Create a Dockerfile (named Dockerfile-java) for the specific versions of Java and Maven, and place it in the directory that will be used for mounting later:\n   ```Dockerfile\n    FROM --platform=amd64 maven:3-jdk-8-slim\n\n    RUN mkdir -p /opt/jdk/ /opt/maven/\n\n    RUN cp -r $JAVA_HOME/* /opt/jdk/\n\n    RUN cp -r $MAVEN_HOME/* /opt/maven/\n\n    CMD [\"echo\"]\n   ```\n2. Build and run the Docker container, mounting the JDK and Maven directories to the respective volumes:\n   ```bash\n    docker buildx build -t codeql-java -f Dockerfile-java .\n    docker run --rm  -v \"jdkvol:/opt/jdk\" -v \"mavenvol:/opt/maven\" codeql-java\n   ```\n3. Finally, run codeql-agent container with mounted volumes and set env variable JAVA_HOME, MAVEN_HOME to the mounted volumes\n\n  ```bash\n  docker run --rm --name codeql-agent-docker \\\n    -v \"$PWD:/opt/src\" \\\n    -v \"$PWD/codeql-agent-results:/opt/results\" \\\n    -v \"jdkvol:/opt/jdk\" \\\n    -v \"mavenvol:/opt/maven\" \\\n    -e \"LANGUAGE=java\" \\\n    -e \"JAVA_HOME=/opt/jdk\" \\\n    -e \"MAVEN_HOME=/opt/maven\" \\\n    -e \"COMMAND=mvn clean install\" \\\n    doublevkay/codeql-agent\n  ```\n\u003c/details\u003e\n\n## Build\nYou can use [CodeQL Agent Image](https://hub.docker.com/repository/docker/doublevkay/codeql-agent) on **Docker Hub** or customize and [build it locally](#build-locally).\n```bash\n# Build codeql-agent docker image locally \ncd codeql-agent\ndocker build -t codeql-agent .\n```\n\n\n## How does it work?\nCodeQL Agent is a Docker image. The following steps are done to achieve the goals of automating the use of CodeQL. \n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eSetting up environment\u003c/b\u003e\u003c/summary\u003e\n\n\u003eIn this step, the image prepares the environment for executing CodeQL. It includes: using Ubuntu base image; downloading and installing [CodeQL Bundle](https://github.com/github/codeql-action/releases) (which contains the CodeQL CLI and the precompiled library queries to reduce the CodeQL execution time); installing necessary softwares such as `java`, `maven`, `nodejs`, `typescript`,... to create a CodeQL database successfully.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e \u003csummary\u003e\u003cb\u003e Detecting language\u003c/b\u003e\u003c/summary\u003e\n\n\u003eCodeQL Agent uses [github/linguist](https://github.com/github/linguist) to detect the source code language.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e \u003csummary\u003e\u003cb\u003e Creating database \u003c/b\u003e\u003c/summary\u003e\n\n\u003e CodeQL Agent runs the CodeQL create database command.\n  ```bash\n  codeql database create --threads=$THREADS --language=$LANGUAGE $COMMAND $DB -s $SRC $OVERWRITE_FLAG\n  ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e \u003csummary\u003e\u003cb\u003e Specifying  query suites \u003c/b\u003e\u003c/summary\u003e\n\n\u003e Analyzing databases requires specifying a query suite. According to the goals of application static application security testing (SAST) goals, CodeQL Agent uses `\u003clanguage\u003e-security-extended.qls` as the default query suite.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e \u003csummary\u003e\u003cb\u003e Analyzing database \u003c/b\u003e\u003c/summary\u003e\n\n\u003e CodeQL Agent runs the CodeQL database analysis command.\n```bash\ncodeql database analyze --format=$FORMAT --threads=$THREADS $SAVE_CACHE_FLAG --output=$OUTPUT/issues.$FORMAT $DB $QS\n``` \n\n\u003c/details\u003e\n\n\u003cdetails\u003e \u003csummary\u003e\u003cb\u003e Converting result format \u003c/b\u003e\u003c/summary\u003e\n\n\u003eCodeQL Agent will convert the CodeQL result from [SARIF format](http://docs.oasis-open.org/sarif/sarif/v2.0/csprd01/sarif-v2.0-csprd01.html) to [Security Report Schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) (provided by Gitlab). This step is done by mapping the fields of two formats. The details of implementation are in the [sarif2sast](https://github.com/vovikhangcdv/codeql-agent/blob/main/scripts/sarif2sast.py) script. You can use this script independently as a workaround to solve the [Gitlab Issue 118496](https://gitlab.com/gitlab-org/gitlab/-/issues/118496).\n\n\u003c/details\u003e\n\n## Credits\nThis repo is based on [microsoft/codeql-container](https://github.com/microsoft/codeql-container) and [j3ssie/codeql-docker](https://github.com/j3ssie/codeql-docker) with more function options. Specifically:\n- Enhance environment setup to increase reliability.\n- Automatically detect language.\n- Support helpful CodeQL options.\n- Support Java language. \n\n## Support\n\nYou can open an issue on the [GitHub repo](https://github.com/codeql-agent-project/codeql-agent-docker/issues)\n\n## Contributing\n\nContributions are always welcome! Just create a pull request or contact me  \u003ca href=\"https://twitter.com/doublevkay\"\u003e\n    \u003cimg src=\"https://img.shields.io/twitter/url?style=for-the-badge\u0026label=%40doublevkay\u0026logo=twitter\u0026logoColor=00AEFF\u0026labelColor=black\u0026color=7fff00\u0026url=https%3A%2F%2Ftwitter.com%2Fdoublevkay\"\u003e  \u003c/a\u003e\n\n## Contributors\n\u003ca href=\"https://github.com/vovikhangcdv/codeql-agent-extension/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=codeql-agent-project/codeql-agent-docker\" /\u003e\n\u003c/a\u003e\n\n## Release Notes\n\n[See details](https://github.com/codeql-agent-project/codeql-agent-docker/releases)\n\n## License\n\nCodeQL Agent is use CodeQL CLI as the core engine. Please follow the [GitHub CodeQL Terms and Conditions](https://github.com/github/codeql-cli-binaries/blob/main/LICENSE.md) and take it as your own responsibility.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeql-agent-project%2Fcodeql-agent-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeql-agent-project%2Fcodeql-agent-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeql-agent-project%2Fcodeql-agent-docker/lists"}