ctrace

BUILD

mkdir -p build && cd build

Depending on your configuration, you can pass these parameters to cmake. The parameters will be documented here.

cmake ..                        \
    -DPARSER_TYPE=CLI11         \
    -DUSE_THREAD_SANITIZER=ON   \
    -DUSE_ADDRESS_SANITIZER=OFF

make -j4

CODE STYLE (clang-format)

• Version cible : clang-format 17 (utilisée dans la CI).
• Formater localement : ./scripts/format.sh
• Vérifier sans modifier : ./scripts/format-check.sh
• CMake : cmake --build build --target format ou --target format-check
• CI : le job GitHub Actions clang-format échoue si un fichier n’est pas formaté.

DEBUG

You can pass arguments to CMake and invoke ASan.

-DUSE_THREAD_SANITIZER=ON

or

-DUSE_ADDRESS_SANITIZER=ON

⚠️ Warning: You cannot use -DUSE_THREAD_SANITIZER=ON and -DUSE_ADDRESS_SANITIZER=ON at the same time.

ARGUMENT

./ctrace [-h|--help]
ctrace - Static & Dynamic C/C++ Code Analysis Tool

Usage:
  ctrace [options]

Options:
  --help                   Displays this help message.
  --verbose                Enables detailed (verbose) output.
  --quiet                  Suppresses non-essential output.
  --sarif-format           Generates a report in SARIF format.
  --report-file <path>     Specifies the path to the report file (default: ctrace-report.txt).
  --output-file <path>     Specifies the output file for the analysed binary (default: ctrace.out).
  --entry-points <names>   Sets the entry points for analysis (default: main). Accepts a comma-separated list.
  --config <path>          Loads settings from a JSON config file.
  --compile-commands <path> Path to compile_commands.json for tools that support it.
  --include-compdb-deps    Includes dependency entries (e.g. _deps) when auto-loading files from compile_commands.json.
  --analysis-profile <p>   Stack analyzer profile: fast|full.
  --smt <on|off>           Enables/disables SMT refinement in stack analyzer.
  --smt-backend <name>     Primary SMT backend (e.g. z3, interval).
  --smt-secondary-backend <name> Secondary backend for multi-solver modes.
  --smt-mode <mode>        SMT mode: single|portfolio|cross-check|dual-consensus.
  --smt-timeout-ms <n>     SMT timeout in milliseconds.
  --smt-budget-nodes <n>   SMT node budget per query.
  --smt-rules <list>       Comma-separated SMT-enabled rules.
  --resource-model <path>  Path to the resource lifetime model for stack analyzer.
  --escape-model <path>    Path to the stack escape model for stack analyzer.
  --buffer-model <path>    Path to the buffer overflow model for stack analyzer.
  --timing                 Enables stack analyzer timing output.
  --demangle               Displays demangled function names in supported tools.
  --static                 Enables static analysis.
  --dyn                    Enables dynamic analysis.
  --invoke <tools>         Invokes specific tools (comma-separated).
                           Available tools: flawfinder, ikos, cppcheck, tscancode, ctrace_stack_analyzer.
  --input <files>          Specifies the source files to analyse (comma-separated).
  --ipc <method>           Specifies the IPC method to use (e.g., fifo, socket).
  --ipc-path <path>        Specifies the IPC path (default: /tmp/coretrace_ipc).
  --serve-host <host>      HTTP server host when --ipc=serve.
  --serve-port <port>      HTTP server port when --ipc=serve.
  --shutdown-token <tok>   Token required for POST /shutdown (server mode).
  --shutdown-timeout-ms <ms> Graceful shutdown timeout in ms (0 = wait indefinitely).
  --async                  Enables asynchronous execution.

Examples:
  ctrace --input main.cpp,util.cpp --static --invoke=cppcheck,flawfinder
  ctrace --verbose --report-file=analysis.txt --sarif-format

Description:
  ctrace is a modular C/C++ code analysis tool that combines both static and dynamic
  analysis. It can be finely configured to detect vulnerabilities, security issues,
  and memory misuse.

CONFIGURATION

• Canonical default config: config/tool-config.json
• Full schema and semantics: docs/configuration.md
• Precedence: built-in defaults < config file < CLI

./ctrace --input ../tests/EmptyForStatement.cc --entry-points=main --verbose --static --dyn

SERVER MODE

Start the HTTP server:

./ctrace --ipc serve --serve-host 127.0.0.1 --serve-port 8080 --shutdown-token mytoken

Send a request:

curl -X POST http://127.0.0.1:8080/api \
  -H "Content-Type: application/json" \
  -d '{
    "proto": "coretrace-1.0",
    "id": 1,
    "type": "request",
    "method": "run_analysis",
    "params": {
      "input": ["./tests/buffer_overflow.cc"],
      "entry_points": ["main"],
      "static_analysis": true,
      "dynamic_analysis": false,
      "invoke": ["flawfinder"],
      "sarif_format": true,
      "report_file": "ctrace-report.txt",
      "output_file": "ctrace.out",
      "ipc": "serve",
      "ipc_path": "/tmp/coretrace_ipc",
      "async": false,
      "verbose": true
    }
  }'

Response notes:

• status is ok or error.
• result.outputs groups tool output by tool name.
• Each output entry has stream and message. If a tool emits JSON, message is returned as a JSON object.

Shutdown the server (HTTP request):

curl -i -X POST http://127.0.0.1:8080/shutdown \
  -H "Authorization: Bearer mytoken"

Alternative header:

curl -i -X POST http://127.0.0.1:8080/shutdown \
  -H "X-Admin-Token: mytoken"

The server responds with 202 Accepted and stops accepting new requests while allowing in-flight requests to finish (up to --shutdown-timeout-ms if configured).

Mangle/Demangle API

bool hasMangled = ctrace_tools::mangle::isMangled(entry_points);

std::cout << "Is mangled : " << hasMangled << std::endl;
if (hasMangled)
    std::cout << abi::__cxa_demangle(entry_points.c_str(), 0, 0, &status) << std::endl;

std::vector<std::string> params1 = {};
std::string mangled1 = ctrace_tools::mangle::mangleFunction("", "single_compute()", params1);
std::cout << "Mangled single_compute(): " << mangled1 << "\n";
std::cout << abi::__cxa_demangle(mangled1.c_str(), 0, 0, &status) << std::endl;

// Example 2 : with namespace
std::vector<std::string> params2 = {"std::string", "int"};
std::string mangled2 = ctrace_tools::mangle::mangleFunction("math", "compute", params2);
std::cout << "Mangled math::compute(std::string, int): " << mangled2 << "\n";

// Example 3 : without parameters with namespace
std::vector<std::string> params3;
std::string mangled3 = ctrace_tools::mangle::mangleFunction("utils", "init", params3);
std::cout << "Mangled utils::init(): " << mangled3 << "\n";

TODO

- Mangle function with parameters
- Thread execution : datarace condition detected
- 'Format log' function needs to be implement
- Handle multi-file parsing
- Add mangling for windows
- Add lvl verbosity to --verbose like : --verbose=[1|2|3|4]
- sanitazier explication ...
- passer du code au lieu du fichier