devrvk/codeql-docker repository overview

⁠CodeQL APK Analyzer Docker Image (devrvk/codeql-docker)

This Docker image provides a self-contained environment for analyzing Android APK files using JADX for decompilation and GitHub's CodeQL for static analysis. It is designed as a worker: it takes an APK from a mounted input volume, performs the analysis, stores results in a mounted output volume, logs its progress, and then exits.

⁠Architecture Notice: amd64 Only

Important: This Docker image is built exclusively for the linux/amd64 (x86_64) architecture. Due to stability issues encountered when running certain package installation scripts (like ca-certificates, openjdk) under QEMU emulation on ARM hosts (e.g., Apple Silicon M1/M2/M3), this image forces the amd64 architecture during build and uses amd64 specific binaries.

Do not attempt to run this image on arm64 hosts without a compatible amd64 emulation layer. For best performance and stability, run this image on a native linux/amd64 machine or VM.

⁠Included Tools

• CodeQL CLI: (Version used during build, e.g., v2.20.6) For creating code databases and running static analysis queries. Includes standard Java query packs.
• JADX: (Version used during build, e.g., v1.5.1) For decompiling Android APK files to Java source code.
• OpenJDK 17 (Temurin): Java runtime required by JADX and CodeQL for Java analysis.
• Python 3: Used by the entrypoint and analysis orchestration scripts.
• Bash & Core Utilities: Standard Linux utilities used by helper scripts.

⁠Prerequisites

• Docker installed and running on your amd64 host machine.
• An APK file you wish to analyze.

⁠Usage

⁠1. Pull the Image

docker pull devrvk/codeql-docker

⁠2. Prepare Host Directories

You need two directories on your host machine:

• input/: Place the single APK file you want to analyze in this directory.
• output/: An empty directory where the analysis results will be stored.

Example structure:

my_analysis_project/
├── input/
│   └── my_app.apk  # Your APK file here
└── output/         # Results will appear here

⁠3. Run the Container

Execute the following command from the directory containing your input and output folders (e.g., my_analysis_project/):

docker run -v "$(pwd)/input:/app/input" -v "$(pwd) output:/app/output" devrvk/codeql-docker

Explanation of Flags:

• --rm: Automatically removes the container filesystem when the analysis finishes and the container exits. Keeps your system clean.
• -v "$(pwd)/input:/app/input": Mounts your local input directory to /app/input inside the container. The container reads the APK from here.
• -v "$(pwd)/output:/app/output": Mounts your local output directory to /app/output inside the container. All results and logs are written here.
• devrvk/codeql-docker: Specifies the Docker image to run.

⁠How it Works

1. The container starts.
2. The entrypoint.py script executes.
3. It finds the first .apk file in the mounted /app/input directory.
4. It calls the main analysis script (/app/tool/analyze_apk.py).
5. analyze_apk.py:
   • Uses jadx to decompile the APK into the /app/output/<apk_name>/ directory.
   • Creates a CodeQL database from the decompiled Java source code in /app/output/<apk_name>_qldb using --build-mode=none.
   • Runs the standard CodeQL Java queries (codeql/java-queries) against the database, saving raw CSV results.
   • Converts the standard query CSV results to JSON.
   • If custom queries exist within the image (/app/tool/custom_queries/), it executes /app/tool/run_all_queries.sh.
   • run_all_queries.sh runs each custom .ql query, decodes results to individual JSON files within /app/tool/custom_queries/outputs/.
   • analyze_apk.py aggregates these individual custom JSON results into a single file.
6. All console output (stdout/stderr) from the process is captured in a log file.
7. The container exits.

⁠Output Files

After the container finishes, the following files will appear in your local output/ directory:

• <apk_name>/: Directory containing the decompiled source code generated by JADX. (e.g., output/my_app/)
• <apk_name>_qldb/: The CodeQL database directory. Can be large. (e.g., output/my_app_qldb/)
• <apk_name>.json: JSON file containing the results from the standard CodeQL Java security queries (codeql/java-queries). (e.g., output/my_app.json)
• custom_queries_result.json: (Only if custom queries were included in the image build) A JSON file containing the combined results from all custom .ql queries found in /app/tool/custom_queries. The structure is an object where keys are the query filenames (without .ql) and values are the full JSON result objects from codeql bqrs decode.
• analysis.log: A text file containing all the console output generated during the container's run, useful for debugging.

⁠Example

# 1. Create directories
mkdir -p my_analysis/input my_analysis/output

# 2. Place your APK
cp /path/to/your/app.apk my_analysis/input/

# 3. Navigate to the project directory
cd my_analysis

# 4. Run the analysis
docker run --rm \
  -v "$(pwd)/input:/app/input" \
  -v "$(pwd)/output:/app/output" \
  devrvk/codeql-docker

# 5. Check results in the 'output' directory
ls output/
# Expected: analysis.log, app.json, app_qldb/, app/, custom_queries_result.json (if applicable)

⁠Customization

The analysis logic (analyze_apk.py), custom queries (custom_queries/), and the custom query runner (run_all_queries.sh) are located within the /app/tool/ directory inside the image. To modify the analysis process or add/change custom queries, you would need to rebuild the Docker image with your updated files in the tool/ directory of your build context.