The info command displays general details about the oinkie application, including the version, author, and all currently supported birthmark configurations and comparison algorithms.
🏃 Usage # oinkie info [OPTIONS] Options # -h, --help
Print help information. 📊 Example Output # Running the info command provides detailed listings of supported formats and algorithms in your current environment:
The lift command converts compiled binary executable files into the Oinkie Intermediate Representation (OIR) JSON format. The current implementation utilizes Ghidra in headless mode (without GUI) to translate machine-specific assembly instructions into platform-agnostic P-code.
🏃 Usage # You can lift multiple binary files at once. The default behavior is to use Ghidra to analyze the executables and output the resulting JSON files to the ./pcodes directory.
The extract command analyzes the lifted OIR (JSON) files and extracts specified types of birthmarks. A software birthmark represents a distinct structural or semantic characteristic of a program (like instruction types or external function dependencies) that remains stable across compilation variations.
🏃 Usage # oinkie extract [OPTIONS] [FILES]... Arguments # <FILES>...
Path to the OIR JSON files (previously generated via the lift command) from which to extract birthmarks. Options # -d, --dest <DIRECTORY>
Specify the destination directory for saving the extracted birthmark files. Defaults to the ./birthmarks directory. [default: birthmarks] -b, --birthmark-type <BIRTHMARK_TYPE>
The type and representation structure of the birthmark to extract. Defaults to op-seq. [default: op-seq]
Refer below for a full list of supported birthmark types. -B, --binary-type <BINARY_TYPE>
The binary input parser type. The current version only supports ghidra. [default: ghidra] [possible values: ghidra, llvm, binary-ninja] -S, --skip
Skip the extraction process if the output birthmark file already exists. 🧪 Birthmark Types and Structural Representation # Software birthmarks are categorized by their underlying element types and their representation structures.
The compare command performs pairwise comparison between extracted birthmarks to measure their similarity. This step calculates a score between \(0.0\) (entirely different) and \(1.0\) (identical), indicating the level of structural similarity between the programs.
🏃 Usage # oinkie compare [OPTIONS] [JSON_FILES]... Arguments # <JSON_FILES>...
Paths to the birthmark JSON files (generated using the extract command) to compare. Options # -a, --algorithm <ALGORITHM>
Specify the similarity calculation algorithm to compare birthmarks. [default: jaccard]
Refer below for a full list of algorithms. -A, --aggregator <METHOD>
Specify the method for combining individual element-wise (function-to-function) similarities into a single program-wide similarity score. [default: hungarian]
Refer below for a full list of aggregators. -s, --strategy <STRATEGY>
The pairing strategy to use when comparing files. [default: all-and-self]
[possible values: all-and-self, all, self-coverage, adjacent, first-vs-others, last-vs-others] Refer below for a full list of strategies. -d, --dest <DIRECTORY>
The output directory where comparison results are saved (typically as CSV files). [default: similarities] -S, --skip
Skip the comparison if the output file already exists for the current file pair. 🧦 Pairing Strategies (--strategy) # When comparing multiple files, you can configure which file pairs are compared using the following strategy options:
The reaggregate command allows you to recalculate the program-wide similarity score from previously computed element-wise (function-to-function) similarity files. This avoids having to completely rerun expensive pairwise comparisons if you simply want to test a different aggregation method (e.g., swapping between hungarian and topn:N).
🏃 Usage # oinkie reaggregate [OPTIONS] <SCORE_DIRECTORY> Arguments # <SCORE_DIRECTORY>
Path to the directory containing the saved element-wise function similarity scores (often located inside the output folder generated by the compare command). Options # -A, --aggregator <METHOD>
Specify the aggregator method to combine function-to-function scores into a single program-wide score. [default: hungarian] hungarian: Optimal overall bipartite matching between functions. topn:N: Only average the top \(N\) closest matches for each function. -d, --dest-file <RESULT.CSV>
The path to the destination CSV file where the reaggregated program-wise similarity scores list will be saved. [default: reaggregate.csv] 💡 Practical Workflow Example # Imagine you have run a large comparison across hundreds of files using the standard hungarian aggregator:
The run command is an all-in-one command designed to perform both extraction and comparison of software birthmarks in a single transaction. This is ideal for quick checks or automated CI pipelines, saving the intermediate step of writing extracted birthmarks manually to separate folders.
🏃 Usage # oinkie run [OPTIONS] [FILES]... Arguments # <FILES>...
Paths to the OIR JSON files (previously generated via the lift command) to extract and compare. Options # -a, --analysis <ANALYSIS>
The combination of birthmark-type, representation, and similarity-algorithm to evaluate.
[default: op-set-jaccard]
Refer below for a list of common configuration formats. -A, --aggregator <METHOD>
Specify the method for combining individual element-wise (function-to-function) similarities into a single program-wide similarity score. [default: hungarian]
Refer below for a full list of aggregators. -s, --strategy <STRATEGY>
The pairing strategy to use when comparing files. [default: all-and-self]
[possible values: all-and-self, all, self-coverage, adjacent, first-vs-others, last-vs-others] Refer a full list in compare subcommand. -d, --dest <DIRECTORY>
Destination directory for output CSV files containing the similarity results. [default: similarities] -S, --skip
Skip comparison if a similarity output already exists for a specific pair. 🔬 Specifying Analysis Modes (--analysis) # The format for --analysis strings is structured as:
