🏃 Usage on oinkie

5. All-in-One Execution (`run` command)

Mon, 22 Jun 2026 00:00:00 +0000

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:

4. Reaggregating Scores (`reaggregate` command)

Mon, 22 Jun 2026 00:00:00 +0000

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:

3. Comparing Birthmarks (`compare` command)

Mon, 22 Jun 2026 00:00:00 +0000

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:

2. Extracting Birthmarks (`extract` command)

Mon, 22 Jun 2026 00:00:00 +0000

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.

1. Lifting Binaries (`lift` command)

Mon, 22 Jun 2026 00:00:00 +0000

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.

Application Information (`info` command)

Mon, 22 Jun 2026 00:00:00 +0000

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:

🏃 Usage on oinkie

5. All-in-One Execution (`run` command)

🏃 Usage #

Arguments #

Options #

🔬 Specifying Analysis Modes (--analysis) #

4. Reaggregating Scores (`reaggregate` command)

🏃 Usage #

Arguments #

Options #

💡 Practical Workflow Example #

3. Comparing Birthmarks (`compare` command)

🏃 Usage #

Arguments #

Options #

🧦 Pairing Strategies (--strategy) #

2. Extracting Birthmarks (`extract` command)

🏃 Usage #

Arguments #

Options #

🧪 Birthmark Types and Structural Representation #

1. Lifting Binaries (`lift` command)

🏃 Usage #

Application Information (`info` command)

🏃 Usage #

Options #

📊 Example Output #

🏃 Usage
#

Arguments
#

Options
#

🔬 Specifying Analysis Modes (`--analysis`)
#

🏃 Usage
#

Arguments
#

Options
#

💡 Practical Workflow Example
#

🏃 Usage
#

Arguments
#

Options
#

🧦 Pairing Strategies (`--strategy`)
#

🏃 Usage
#

Arguments
#

Options
#

🧪 Birthmark Types and Structural Representation
#

🏃 Usage
#

🏃 Usage
#

Options
#

📊 Example Output
#