Skip to content

Quick Start Guide

In this section, you will learn how to use CodeSecTools.

This guide mainly used the tool on Java projects, it is perfectly possible to run it on any project that language is supported.

1. Prerequisites

For this guide, there are two ways to install the tool:

Normal installation

Docker image

A Docker image used to run tests is available with the prerequisites installed. You can use it to test CodeSecTools without installing extra packages on your system.

⚠️ However, this container is intended for running tests, not for normal usage. Therefore, any data and results inside the container will be deleted when you exit.

Please perform a normal installation if you want to keep your results.

2. Installation

Normal installation

  • Clone the repository: 

    git clone https://github.com/OPPIDA/CodeSecTools.git
cd CodeSecTools

  • Install the project:

    • Using uv: 

      uv tool install .

    • Using pipx: 

      pipx install .

    • Using pip (not recommended, as it can break your system packages): 

      pip install .

Docker image

To start the Docker container, run the command: 

make test-debug

⚠️ The container will be deleted when you exit.

3. First run

Install completion (optional)

cstools --install-completion 
# For bash
source ~/.bash_completions/cstools.sh

Download external resources

This command downloads datasets, rules, and plugins required for the SAST tools.

For each external resource, you will be prompted with resource information and, most importantly, its license/term. 

cstools download all

Check the integration status

This command allows you to check if a SAST tool or dataset is available.

If not, it will specify what is missing. 

cstools status

For this guide, the status for Bearer, SemgrepCE, and SpotBugs should be Full ✅.

4. Common Use Cases

Analysis with multiple SAST tools

One important feature of CodeSecTools is the ability to run multiple SAST tools in order to:

  • aggregate all the results to take advantage of each SAST tool's strengths (detecting specific vulnerabilities);
  • cross-verify results and increase the confidence that a finding is a true positive.

Here are some analyses running CodeSecTools on vulnerable projects:

cyclonedx-core-java (CVE-2025-64518)

Vulnerability details are from Github Advisory.

Download the vulnerable version of the project: 

git clone https://github.com/CycloneDX/cyclonedx-core-java
cd cyclonedx-core-java
git checkout 162aa59

Compile the project to generate Java bytecode for SAST tools that require it: 

mvn clean compile

Run analysis with all SAST tools: 

cstools allsast analyze java --artifacts target/classes/

Generate figures and report: 

cstools allsast plot cyclonedx-core-java
cstools allsast report cyclonedx-core-java

Open the project report (~/.codesectools/output/AllSAST/cyclonedx-core-java/report/home.html).

The report of the vulnerable file is shown here:

Some issues have been found by the tools in the vulnerable file, and the file is ranked high (high score) overall among all other files where issues were found.

SpotBugs is the only tool that detected issues and correctly identified the vulnerability (exact CWE ID).

conductor (CVE-2025-26074)

Vulnerability details are from Github Advisory.

Download the vulnerable version of the project: 

git clone https://github.com/conductor-oss/conductor
cd conductor
git checkout 5976cad

Compile the project to generate Java bytecode for SAST tools that require it: 

./gradlew compileJava

Run analysis with all SAST tools: 

cstools allsast analyze java --artifacts .

Generate figures and report: 

cstools allsast plot conductor
cstools allsast report conductor

Open the project report (~/.codesectools/output/AllSAST/conductor/report/home.html).

The report of the vulnerable file is shown here:

Only one issue has been found by the tools in the vulnerable file, and the file is ranked low (low score) overall among all other files where issues were found.

SemgrepCE is the only tool that detected issues and partially identified the vulnerability. It has detected a code injection that could leads to an OS command injection.

Note: If we did not know that a vulnerability existed, we would have had to verify it (by attempting to exploit it) because the eval function is a feature.

Benchmarking SAST tool

It is possible to benchmark any SAST tool on any dataset that are integrated to CodeSecTools thanks to the prior integration:

cstools spotbugs benchmark BenchmarkJava_java

If the SAST tool requires artifacts, the expected artifacts and build command are provided:

cstools spotbugs benchmark BenchmarkJava_java 
╭──────────────────────── SpotBugs - PrebuiltSAST ────────────────────────╮
│                                                                         │
│ Please build BenchmarkJava before running the benchmark                 │
│ Build command:          mvn clean compile                               │
│ Full command:           (cd                                             │
│ /home/michel/.codesectools/cache/BenchmarkJava && mvn clean compile)    │
│ Expected arteficts:                                                     │
│ /home/michel/.codesectools/cache/BenchmarkJava/target/classes/org/owasp │
│ /benchmark/testcode/*.class                                             │
╰─────────────────────────────────────────────────────────────────────────╯

Then generating figures using the analysis output:

cstools spotbugs plot BenchmarkJava_java --overwrite
Figure overview saved at /home/michel/.codesectools/output/SpotBugs/BenchmarkJava_java/_figures/overview.png
Figure top_cwes saved at /home/michel/.codesectools/output/SpotBugs/BenchmarkJava_java/_figures/top_cwes.png

Figures:

Overview

Top CWEs