Skip to content

Client CLI Guide

Jump to bottom
Hugo edited this page Sep 25, 2026 · 2 revisions

Client CLI Guide

Back to Home

Scope

How to run CoreTrace from the terminal, with the behavior of the current implementation.

The option list is generated from the option table in src/App/Config.cpp, so ctrace --help is the single source of truth. The full configuration schema (types, defaults, allowed values, impact) lives in docs/configuration.md in the repository and is not duplicated here.

Quickstart (Build + Help)

mkdir -p build && cd build
cmake .. -DUSE_THREAD_SANITIZER=OFF -DUSE_ADDRESS_SANITIZER=OFF
make -j4
./ctrace --help
./ctrace --version

Common Workflows

1) Static analysis on explicit files

./ctrace --input ../tests/buffer_overflow.cc --static --verbose

2) Specific tools only

./ctrace --input ../tests/buffer_overflow.cc --invoke tscancode,flawfinder

3) Mixed C/C++ and Python sources

./ctrace --input app.py,src/main.c --invoke coretrace-python-analyzer,cppcheck

Each input goes to the tools of its language: .py files to coretrace-python-analyzer, C and C++ files to the others. A tool declares the languages it analyses through IAnalysisTool::analyzes(); the default is C and C++.

4) Analysis driven by a config file

./ctrace --config ../config/tool-config.json --static

5) SARIF for a CI pipeline

./ctrace --sarif-format --invoke cppcheck,flawfinder,ctrace_stack_analyzer \
    --input src/main.c --report-file ctrace.sarif --fail-on warning

6) Start HTTP server mode

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

Exit Codes

ctrace is meant to gate a pipeline, so its exit code is a verdict on the run:

Code Meaning
0 Analysis complete, no finding at or above --fail-on
1 Usage or configuration error
2 Findings at or above --fail-on (default: error)
3 Analysis incomplete: a tool could not be started, crashed or exited abnormally

--fail-on error|warning|none (config key analysis.fail_on) sets the threshold. none never fails on findings but still returns 3 on a broken toolchain: an incomplete run wins over findings, because its counters cannot be trusted. Server mode returns the same verdict in result.gate instead of exiting.

Option Reference (Current Behavior)

Analysis selection

  • --static: run the static tool group (cppcheck, flawfinder, tscancode, ikos, ctrace_stack_analyzer, coretrace-python-analyzer).
  • --dyn: run the dynamic tool group (dyn_tools_1..3).
  • --invoke <csv>: run specific tools. Accepted names are validated against the supported list (include/App/SupportedTools.hpp): flawfinder, ikos, cppcheck, tscancode, ctrace_stack_analyzer, coretrace-python-analyzer. An unknown name is now a hard error naming the allowed list, not a silent drop.
  • --fail-on <error|warning|none>: exit-code gate, see Exit Codes.

Input and source resolution

  • --input <csv>: source files and/or compile_commands.json documents.
  • --compile-commands <path>: compile database (file or the directory holding it) used for analyzer context and for file resolution when no --input is given.
  • --include-compdb-deps: keep entries under _deps paths when resolving from a compile database.
  • --entry-points <csv>: entry-point filter forwarded to the tools that support it (default main).

Configuration

Stack analyzer configuration

  • --analysis-profile <fast|full>
  • --smt <on|off>
  • --smt-backend <name>
  • --smt-secondary-backend <name>
  • --smt-mode <single|portfolio|cross-check|dual-consensus>
  • --smt-timeout-ms <n>
  • --smt-budget-nodes <n>
  • --smt-rules <csv>
  • --resource-model <path>
  • --escape-model <path>
  • --buffer-model <path>
  • --stack-limit <bytes> (default 8388608)
  • --timing

The three model paths are filled from the models shipped next to the binary when left empty; see Shipped Defaults.

Runtime and output behavior

  • --verbose / -v: debug-level logger output.
  • --quiet / -q: suppress non-essential output.
  • --demangle: demangled function names in the tools that support it.
  • --sarif-format: report the whole run as one SARIF 2.1.0 log, see SARIF Output.
  • --report-file <path> (default ctrace-report.txt)
  • --output-file <path> (default ctrace.out)
  • --async: parallel tool scheduling through the internal thread pool.
  • --ipc <standardIO|socket|serve> (default standardIO; socket is deprecated)
  • --ipc-path <path> (default /tmp/coretrace_ipc)
  • --serve-host <host> (default 127.0.0.1)
  • --serve-port <port> (default 8080)
  • --shutdown-token <token>
  • --shutdown-timeout-ms <ms> (0 = wait indefinitely)
  • --version / -V, --help / -h

SARIF Output

--sarif-format reports the whole run as one SARIF 2.1.0 log, whatever tools ran: one run per tool, rules collected per tool, a coretrace/v1 partial fingerprint per result for stable alerts across runs, and the CWE as a result property. The document is printed to stdout and written to --report-file, ready for github/codeql-action/upload-sarif.

Two behaviors worth knowing:

  • Uniform file spelling. An input is spelled as it was typed on the command line; any other file relative to the working directory when below it, else absolute. Locations and fingerprints are therefore identical whichever tool reports the finding and on whichever machine the run happens, when it runs from the repository root.
  • Deduplication. A weakness reported by several tools — same file, same line, same CWE — is one result: the most severe report is kept in its tool's run, and its alsoReportedBy property names the other tools and rules. Reports without a CWE cannot be matched and are all kept. Console output and the counters still show every tool's report.

In SARIF mode the tools print nothing else to stdout, and the stack analyzer's own report is not written separately: its findings are in the merged document.

--config JSON Usage

The config file is sectioned, mirroring ProgramConfig (include/Config/config.hpp):

{
  "schema_version": 1,
  "analysis": { "static": true, "invoke": ["cppcheck"], "fail_on": "warning" },
  "files":    { "input": ["src/main.c"], "entry_points": ["main"] },
  "output":   { "sarif_format": true, "report_file": "ctrace.sarif" },
  "runtime":  { "async": true },
  "server":   { "host": "127.0.0.1", "port": 8080 },
  "stack_analyzer": { "analysis_profile": "full", "smt": "on" },
  "tools":    { "paths": { "cppcheck": "/usr/local/bin/cppcheck" },
                "args":  { "cppcheck": ["--disable=style"] } }
}
  • Precedence is built-in defaults < config file < CLI options. CLI values go through the same loader as the file, so validation and normalization are identical.
  • Relative paths in the file are resolved from the config file's directory.
  • The flat pre-section spellings (root invoke, root input, root stack-analyzer keys, tools.ctrace_stack_analyzer) still load, and each one prints a Deprecated config key ... warning naming its replacement.
  • Loader diagnostics are rewritten to name the option the user typed rather than the internal section key.
  • config/tool-config.json is the canonical default file; docs/configuration.md documents every key.

Source File Resolution Rules

  1. Start from files.input entries (--input).
  2. If no input and files.compile_commands (--compile-commands) is set: when the path is a directory, append compile_commands.json; if the resulting file exists, use it as a manifest.
  3. A .json input is only accepted when it is a Clang compile database — an array of objects carrying a file field and an optional directory. Any other JSON document is rejected with an explicit error instead of being guessed at.
  4. Entries are resolved from their own directory; relative paths of the config file are resolved from its directory.
  5. Paths are normalized and deduplicated.
  6. For an auto-discovered compile database, entries containing a _deps segment are dropped unless --include-compdb-deps is given.

If resolution yields no source file, the run fails with a usage error (exit 1), or MissingInput / InvalidInput over HTTP.

Server Mode Entry Command

./ctrace --ipc serve --serve-host 127.0.0.1 --serve-port 8080 \
         --shutdown-token mytoken --shutdown-timeout-ms 5000

Analysis requests are then handled over HTTP on /api. See Client HTTP API Reference.

--serve-host or --serve-port without --ipc=serve is refused with an explicit message and exit code 1.

Current Limitations (Reproducible)

  • The --invoke help text lists five tools and omits coretrace-python-analyzer, which the validator accepts. The supported list in include/App/SupportedTools.hpp is authoritative.
  • --output-file is parsed and carried in the configuration (output.output_file), but no tool currently consumes it; only --report-file produces a file.
  • --ipc=socket is deprecated: only some tools ever wrote to the Unix socket and nothing in the project reads from it. Using it prints a warning and it will be removed in a future release. Use --ipc=standardIO, or --ipc=serve to consume results over HTTP.
  • ikos output is not interpreted: its findings are shown but not turned into diagnostics, so they are not counted and do not take part in the exit-code gate. It is reported as an uninterpreted tool (result.uninterpreted_tools in server mode), and its CMake integration is currently commented out of the build.
  • External tools are resolved through tools.paths, then the copy bundled next to the binary, then PATH. A tool that is neither bundled nor installed makes the run exit 3 rather than reporting a clean result.

Back to Home

Clone this wiki locally