Skip to content

Client HTTP API Reference

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

Client HTTP API Reference

Back to Home

Overview

CoreTrace exposes an HTTP server with --ipc serve.

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

Endpoints:

  • POST /api
  • POST /shutdown
  • OPTIONS /api and OPTIONS /shutdown (CORS preflight)

Transport Behavior

  • Body limit. Requests carry a file list, not file contents, so the body is capped at server.max_body_bytes (default 1 MiB). A larger body is rejected by the HTTP layer.
  • CORS is opt-in. No Access-Control-Allow-Origin header is sent unless server.cors_origin is configured, so a page on another origin cannot read the response. When it is set, the server also answers preflight with POST, OPTIONS and Content-Type.
  • Shutting down. While a graceful shutdown is in progress, /api answers 503 with error.code=ServerShuttingDown, and OPTIONS answers 503.
  • Bad body. A body that is not valid JSON, or an exception while handling the request, answers 400 with error.code=InvalidRequest.

Both settings live in the server section of the config file; there is no CLI flag for them.

Request Contract (POST /api)

Top-level request fields:

  • proto (string, optional; echoed back, default coretrace-1.0)
  • id (number, optional; echoed back, default 0)
  • type (not validated by the handler)
  • method (string) — only run_analysis is supported
  • params (object)

An unknown method answers status=error with error.code=UnknownMethod.

params for run_analysis

Every parameter is flat in the request and is translated into the sectioned configuration document, then applied through the same loader as the config file and the CLI — one validation path for all three. docs/configuration.md documents the semantics of each target key.

Parameter Config key Type
verbose output.verbose bool
quiet output.quiet bool
demangle output.demangle bool
sarif_format output.sarif_format bool
report_file output.report_file string
output_file output.output_file string
static_analysis analysis.static bool
dynamic_analysis analysis.dynamic bool
invoke analysis.invoke list
fail_on analysis.fail_on string (error|warning|none)
input files.input list
entry_points files.entry_points list
compile_commands files.compile_commands string
include_compdb_deps files.include_compdb_deps bool
async runtime.async bool
ipc_path runtime.ipc_path string
timing stack_analyzer.timing bool
analysis_profile stack_analyzer.analysis_profile string
smt stack_analyzer.smt string (on|off)
smt_backend stack_analyzer.smt_backend string
smt_secondary_backend stack_analyzer.smt_secondary_backend string
smt_mode stack_analyzer.smt_mode string
smt_timeout_ms stack_analyzer.smt_timeout_ms uint
smt_budget_nodes stack_analyzer.smt_budget_nodes uint
smt_rules stack_analyzer.smt_rules list
stack_limit stack_analyzer.stack_limit uint
resource_model stack_analyzer.resource_model string
escape_model stack_analyzer.escape_model string
buffer_model stack_analyzer.buffer_model string
stack_analyzer_mode stack_analyzer.mode string
stack_analyzer_output_format stack_analyzer.output_format string
stack_analyzer_extra_args stack_analyzer.extra_args list

Two parameters are handled outside the table:

  • config (string): path to a JSON config file, loaded before the request parameters. Precedence is defaults < config file < request parameters. A load failure answers InvalidParams with Failed to load config: ....
  • ipc (string): standardIO, socket or serve, with serv and server accepted as aliases of serve. Inside a request, serve means the analysis runs in-process, so it is normalized to standardIO for tool execution.

List parameters

A list parameter accepts either a JSON array of strings or a comma-separated string; empty items are dropped. input items are themselves split on commas, so "input": "a.c,b.c" and "input": ["a.c", "b.c"] are equivalent.

Validation

A wrong JSON type answers status=error with error.code=InvalidParams. Loader diagnostics are rewritten to name the flat parameter the client sent rather than the internal section key. Deprecated config-file spellings found in a config file are logged as warnings, not errors.

Success Response Shape

status=ok, with result containing:

Findings

  • diagnostics: every finding in one model, whatever tool produced it — tool, rule_id, file, line, column, severity, message, cwe.
  • diagnostics_summary_total: counts by severity (info, warning, error).
  • sarif: the merged SARIF 2.1.0 log, present when sarif_format is true. It is the same document the CLI prints, and it is also written to report_file.
  • uninterpreted_tools: tools that ran without ever reporting structured findings. Their output is in outputs but is not counted — this is distinct from a tool with zero findings.

Verdict

  • gate: the verdict the CLI would exit with, so a client applies one policy — fail_on, exit_code (see Exit Codes) and failed_tools.

Echo of the effective configuration

files (number of processed files), static_analysis, dynamic_analysis, invoked_tools, sarif_format, report_file, config, include_compdb_deps, resource_model, escape_model, buffer_model, analysis_profile, smt, smt_backend, smt_secondary_backend, smt_mode, smt_timeout_ms, smt_budget_nodes, smt_rules, timing, stack_limit, stack_analyzer_mode, stack_analyzer_output_format, stack_analyzer_extra_args.

Raw tool output

  • outputs: an object keyed by tool name. Each entry has stream (stdout or stderr) and message — a string, or a parsed JSON object/array when the captured text is valid JSON.

Each request gets the same shipped defaults as the CLI: the stack analyzer models and the bundled tools found next to the server's ctrace binary fill whatever the request and its config file leave empty.

Error Codes

Code HTTP Meaning
InvalidRequest 400 Body is not valid JSON, or the handler threw
UnknownMethod 200 method is not run_analysis
InvalidParams 200 Parameter type/validation failure, bad ipc value, or a config file that failed to load
NoAnalysisSelected 200 None of static_analysis, dynamic_analysis, invoke selected
InvalidInput 200 Input resolution failed (e.g. a .json input that is not a compile database)
MissingInput 200 Resolution produced no source file
ServerShuttingDown 503 Server is closing and rejects new /api work
Unauthorized 403 /shutdown token missing or invalid

Application-level errors are returned inside a 200 envelope; only transport-level failures change the HTTP status.

Shutdown Endpoint (POST /shutdown)

Auth headers (either one):

  • Authorization: Bearer <token>
  • X-Admin-Token: <token>

Behavior:

  • Token missing, invalid, or no token configured on the server → 403, error.code=Unauthorized.
  • Accepted → 202 with status=accepted, timeout_ms and message. The server stops accepting new requests and lets in-flight requests finish, up to --shutdown-timeout-ms (indefinitely when 0).
  • Shutdown already in progress → 202 with message: "Shutdown already in progress.".

Example: Analysis 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,
      "invoke": ["cppcheck", "ctrace_stack_analyzer"],
      "sarif_format": true,
      "fail_on": "warning",
      "report_file": "ctrace-report.txt",
      "verbose": true
    }
  }'

Reading the answer in a CI client:

# 0/1/2/3, the same verdict the CLI would exit with
jq -r '.result.gate.exit_code' response.json
jq -r '.result.diagnostics_summary_total' response.json

Example: Parallel Scheduling (async=true)

async=true enables internal parallel tool scheduling; it does not create a background job API, and the response is still returned synchronously.

curl -X POST http://127.0.0.1:8080/api \
  -H "Content-Type: application/json" \
  -d '{
    "method": "run_analysis",
    "params": {
      "input": "./tests/buffer_overflow.cc,./tests/null_pointer.c",
      "static_analysis": true,
      "invoke": ["flawfinder", "tscancode"],
      "async": true
    }
  }'

Example: Shutdown

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

Back to Home

Clone this wiki locally