[Enhancement] Add schema-rich JSON and batch analysis

Open
  • Is something wrong?
#13 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
cpp
Domain
cli, devtools

Research direction

The --json restriction to info, functions and decompile is enforced around src/main.cpp:309-310, so start there to see how commands and output modes are dispatched. The issue asks for a new versioned schema and a batch mode, which is design work rather than a single edit, so agree on the schema shape with the maintainers first. Done means one documented, versioned JSON artifact that a standard parser accepts, with deterministic output and a nonzero exit when any batch input fails.

Written by the indexing model from the issue text.

Description

enhancement

Summary

Add a unified, schema-rich JSON analysis command with optional batch/JSONL operation for automation and downstream reverse-engineering tools.

Current limitation

JSON output is currently split across command-specific paths. src/main.cpp:309-310 permits --json only for info, functions, and decompile; CFGs, instructions, sections, symbols, relocations, callgraphs, and xrefs are otherwise text-only. The decompile JSON artifact contains functions, recovered data, xrefs, and rendered code, but does not expose the complete basic-block/instruction graph described by the text commands.

The CLI also accepts one binary per invocation, forcing scripts that analyze collections of binaries to repeatedly start the process and independently associate outputs with inputs.

Proposed capability

Introduce a versioned machine-readable analysis contract, for example:

caraxes analyze ./sample --json --output sample.caraxes.json
caraxes analyze --manifest binaries.txt --jsonl --output-dir reports/

The unified artifact should include:

  • input identity and ELF header/program/section metadata;
  • disassembled instructions with bytes, operands, validity, and flow classification;
  • functions with names, sizes, blocks, predecessor/successor edges, callers, and callees;
  • call, branch, data, and function-pointer xrefs;
  • symbols, relocations, recovered strings/data, warnings, unsupported-operation records, and selected analysis section;
  • an explicit schema version and deterministic ordering rules.

Batch mode should support a manifest or repeated input paths, produce one independent result per input (JSON Lines or an output directory), and report per-file failures without corrupting successful results.

Acceptance criteria

  • All information currently available through cfg, callgraph, xrefs, sections, symbols, and relocations can be consumed without parsing human-oriented text.
  • The schema is documented, versioned, and tested by parsing generated output with a standard JSON parser.
  • Repeated runs on the same binary produce byte-for-byte deterministic JSON apart from explicitly documented input metadata.
  • Batch output keeps results isolated by input path and preserves a nonzero overall status when any input fails.
  • Existing --json modes remain compatible or receive a documented schema migration path.
Dominant language
C++
Stars
0
Forks
0
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from TiElixir/caraxes

All issues in TiElixir/caraxes

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.