{"id":13809750,"url":"https://github.com/microsoft/codeql-container","last_synced_at":"2025-05-14T08:33:28.945Z","repository":{"id":45293226,"uuid":"275224395","full_name":"microsoft/codeql-container","owner":"microsoft","description":"Prepackaged and precompiled github codeql container for rapid analysis, deployment and development.","archived":false,"fork":false,"pushed_at":"2023-11-27T12:16:33.000Z","size":61,"stargazers_count":118,"open_issues_count":18,"forks_count":47,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-07T23:46:33.349Z","etag":null,"topics":["codeql","codeql-cli","codeql-command","codeql-container","codeql-queries","docker","quality-ql-pack","semmle"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/_/microsoft-cstsectools-codeql-container","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-26T18:41:34.000Z","updated_at":"2025-04-17T07:12:06.000Z","dependencies_parsed_at":"2024-08-04T02:01:52.539Z","dependency_job_id":null,"html_url":"https://github.com/microsoft/codeql-container","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcodeql-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcodeql-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcodeql-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcodeql-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/codeql-container/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254104946,"owners_count":22015571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["codeql","codeql-cli","codeql-command","codeql-container","codeql-queries","docker","quality-ql-pack","semmle"],"created_at":"2024-08-04T02:00:35.486Z","updated_at":"2025-05-14T08:33:23.912Z","avatar_url":"https://github.com/microsoft.png","language":"Python","readme":"## CodeQL Container\n\n\u003e **Note:** CodeQL container is currently in **public preview**. Please report any bugs to https://github.com/microsoft/codeql-container/issues.\n\u003e Current version of CodeQL only works for interpreted languages. We will add compiled languages support in future versions.\n\nThe CodeQL Container is a project aimed at making it easier to start using CodeQL (more about codeQL at https://github.com/github/codeql). This project\ncontains a Docker file which builds a container with the latest version of codeql-cli, and the latest codeql queries precompiled. \nIt also contains automation to keep the toolchain in the container updated. You can use this container to:\n\n* Start using codeql-cli and run queries on your projects without installing it on your local machine.\n* Use it as an environment to develop codeql queries and test them.\n* Test how the queries perform in windows and linux environments (and more...)\n\nWe shall continue to add more features and would be happy to accept contributions from the community.\n\n### TL;DR\n\nAnalyze the python project django located in the folder ```/tmp/django``` by running the security and quality QL pack on it:\n\n```\n/scripts/unix/analyze_security.sh /tmp/django/src /tmp/django/results python\n```\n\nThe results will be stored in /tmp/django/results/issues.sarif.\n\nAnalyze the Javascript project express located in /tmp/express/src by running the extended security QL pack on it:\n```\nscripts/unix/run_qlpack.sh /tmp/express/src /tmp/express/results javascript security-extended\n```\n\nThe results will be stored in /tmp/express/results/issues.sarif\n\nTo find a list of QL packs installed in the container:\n\n```\ndocker run --rm --name codeql-container -e CODEQL_CLI_ARGS=\"resolve qlpacks\"  mcr.microsoft.com/cstsectools/codeql-container\n```\n\n### Downloading a pre-built container\n\nWe keep updating the docker image periodically and uploading it to the Microsoft Container Registry at: ```mcr.microsoft.com/cstsectools/codeql-container```.\n\nYou can pull the image by running the command:\n```\n$ docker pull mcr.microsoft.com/cstsectools/codeql-container\n```\n\n\n### Building the container from Dockerfile\n\nBuilding the container should be pretty straightforward.\n\n```\ngit clone https://github.com/microsoft/codeql-container\ncd codeql-container\ndocker build . -f Dockerfile -t codeql-container\n```\n\n### Basic Usage\n \nThe codeQL container executes one codeQL command per invocation. We designed it this way because it makes it easy for the user to run any codeQL command, and not be bound by the automation scripts inside the container.\n\nThe basic example format of the container invocation is as follows:\n\n```\n$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS=\u003cquery run...\u003e mcr.microsoft.com/cstsectools/codeql-container\n```\n\nwhere `/dir/to/analyze` contains the source files that have to be analyzed, and `/dir/for/results` is where the result output \nneeds to be stored, and you can specify CODEQL_CLI_ARGS environment variable for specific QL packs to be run on the provided code, among other things. The CODEQL_CLI_ARGS will be passed over to codeQL command line as it is.\n\nFor more information on CodeQL and QL packs, please visit https://www.github.com/github/codeql.\n\n`CODEQL_CLI_ARGS` are the arguments that will be directly passed on to the codeql-cli. For example, in this case, if we supply:\n\n```\nCODEQL_CLI_ARGS=\"database create /opt/results/source_db -s /opt/src\"\n```\n\nit will create a codeQL db of your project (in ```/dir/to/analyze``` ) in the ```/dir/for/results``` folder.\n\n\u003e **Note:** If you map your source volume to some other mount point other than /opt/src, you will have to make the corresponding changes\n\u003e in the `CODEQL_CLI_ARGS`.\n\nThere are some additional docker environment flags that you can set/unset to control the execution of the container:\n\n* `CHECK_LATEST_CODEQL_CLI` - If there is a newer version of codeql-cli, download and install it\n* `CHECK_LATEST_QUERIES` - if there is are updates to the codeql queries repo, download and use it\n* `PRECOMPILE_QUERIES` - If we downloaded new queries, precompile all new query packs (query execution will be faster)\n\n\u003e **WARNING:** Precompiling query packs might take a few hours, depending on speed of your machine and the CPU/memory limits (if any)\n\u003e you have placed on the container.\n\nSince CodeQL first creates a database of the code representation, and then analyzes the said database for issues, we need to invoke the container more than once to analyze a source code repo. (Since the container only executes one codeQL command per invocation.)\n\nFor example, if you want to analyze a python project source code placed in `/dir/to/analyze` (or `C:\\dir\\to\\analyze` for example, in Windows), \nto analyze and get a SARIF result file, you will have to run:\n\n```\n# create the codeql db\n$ export language=\"python\"\n$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS=\"database create --language=${language} /opt/results/source_db -s /opt/src\" mcr.microsoft.com/cstsectools/codeql-container\n\n# upgrade the db if necessary\n$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS=\" database upgrade /opt/results/source_db\" mcr.microsoft.com/cstsectools/codeql-container\n\n# run the queries in the qlpack\n$ docker run --rm --name codeql-container -v /dir/to/analyze:/opt/src -v /dir/for/results:/opt/results -e CODEQL_CLI_ARGS=\"database analyze --format=sarifv2 --output=/opt/results/issues.sarif /opt/results/source_db ${language}-security-and-quality.qls\" mcr.microsoft.com/cstsectools/codeql-container\n```\n\nFor more information on CodeQL and QL packs, please visit https://www.github.com/github/codeql.\n\n### Convenience Scripts\nAnalyzing a source directory takes multiple invocations of the container, as mentioned above. To help with that, we've built some scripts for convenience, which does these invocations for you. \nThese scripts are in the ```scripts``` folder, under their respective platforms (unix or windows).\n\n#### analyze_security.sh\nscripts/unix/analyze_security.sh (or scripts/windows/analyze_security.bat for windows) runs the Security and Quality QL pack suite on your project. This is how you would run it:\n\n```\nscripts/unix/analyze_security.sh /path/to/analyze /path/to/results language\n```\n\nFor example for the python project can be analyzed thus:\n\n```\n/scripts/unix/analyze_security.sh /tmp/django/src /tmp/django/output python\n```\n\nfor JavaScript:\n```\n/scripts/unix/analyze_security.sh /tmp/express/src /tmp/express/output javascript\n```\n\n#### run_qlpack.sh\nIf you know which QL suite you would like to run on the code, use scripts/unix/run_qlpack.sh (or scripts/windows/run_qlpack.bat for windows). \n\n```\nscripts/unix/run_qlpack.sh /path/to/analyze /path/to/results language qlpack\n```\n\nFor example, on windows:\n\n```\nscripts\\windows\\run_ql_suite.bat e:\\temp\\express\\src e:\\temp\\express\\results javascript code-scanning \n```\n\n### Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","funding_links":[],"categories":["CodeQL Containers"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fcodeql-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fcodeql-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fcodeql-container/lists"}