ivx research Difflicit Writing an engine
Writing an engine
An analysis engine is a command-line program that analyzes the change between two artifacts and writes it up as diffmd. Difflicit talks to it through two command-line options, and nothing else:
<engine> --aboutsays what the engine is;<engine> --difflicitreads a request on standard input and writes the analysis to standard output.
Everything else is yours: the language, the license, what the analysis covers, and whether it runs on the user's
computer or on your server. People will also run your engine from a terminal, so give it a command line of its
own too, as Viper does (viper old new).
This is protocol 1.
--about
<engine> --about prints one JSON object to standard output and exits with status 0:
{
"name": "Acme Deep",
"version": "1.2.0",
"description": "Disassembles both sides and traces what each changed function can reach.",
"license": "Proprietary",
"homepage": "https://acme.example/deep",
"protocol": 1
}
| Field | ||
|---|---|---|
name | required | Shown in Difflicit's Engine menu, and in failure messages. |
protocol | required | The request format the engine speaks: 1. Difflicit doesn't offer an engine that speaks another. |
version | Shown next to the name. | |
description | One sentence: what the analysis covers. Shown under the Engine menu and in Manage engines. | |
license | Shown as a label: MIT, GPL-3.0, Proprietary… | |
homepage | An https:// link, shown in Manage engines. |
Answer quickly, within 10 seconds, and without network access or side effects. Difflicit asks every time it lists engines.
--difflicit
<engine> --difflicit reads one JSON object from standard input, until it closes:
{
"protocol": 1,
"project": "/Users/you/Difflicit/CVE-2025-24085",
"before": {
"artifact": "AVFoundation",
"kind": "file",
"version": "2430.13",
"path": "/Users/you/Difflicit/CVE-2025-24085/artifacts/AVFoundation/2430.13"
},
"after": {
"artifact": "AVFoundation",
"kind": "file",
"version": "2430.13.1.0.0",
"path": "/Users/you/Difflicit/CVE-2025-24085/artifacts/AVFoundation/2430.13.1.0.0"
},
"diff": {
"kind": "binary",
"functions": [
{ "name": "sym.check_bounds", "status": "changed", "similarity": 0.82, "base_addr": "0x1a2f0", "head_addr": "0x1a310" }
]
}
}
| Field | |
|---|---|
protocol | 1. |
project | The project folder the analysis is for. |
before, after | The two sides: the older version and the newer one. |
diff | The diff Difflicit already made of the two, so you can build on it rather than start over. |
The two sides
Each side names an artifact (artifact, as the user named it) and one of its versions. The two can be
versions of the same artifact, or of two different ones. Where its files are depends on its kind:
kind | Where the files are |
|---|---|
file | path: the version's copy, a file or a folder. |
git | repo: the repository's folder. version is a ref in it (a tag or a commit): read it with git -C <repo> show <version>:<file>, or check it out somewhere of your own. Don't change the repository. |
A git artifact is only ever compared with its own versions, so both sides then name the same repo.
The diff
kind | Fields | For |
|---|---|---|
unified | text: a unified diff, as git diff prints it. Files are named relative to the artifact (a/src/x.c, b/src/x.c), or after the artifact when it's a single file. | Text: git versions, files and folders. |
binary | functions: radare2's comparison of two binaries, one entry per function: name, status (changed, added, removed or same), similarity (0 to 1; 1 is identical), base_addr and head_addr (hex strings, or null where the function doesn't exist). | Two binaries. |
The answer
Write the analysis to standard output as UTF-8 diffmd, and exit with status 0. Difflicit saves it in the project
as analysis-<artifact>-<before>-to-<after>.diffmd and opens it. An empty analysis counts as a failure.
Write it for the person reading it next to the diff:
- Lead with what matters. A heading that says what the change is, then the findings, most important first.
- Show your evidence. Put the lines each finding rests on in
```diffblocks, a few lines of context around them. Difflicit shows them as real diffs, so the reader can check you. - Say who wrote it. A line naming the engine and its version helps when the note is read later, or shared.
- Keep it finite. Cap long lists, and say what you left out.
The user edits the note afterwards, block by block, so plain Markdown structure (headings, paragraphs, lists, tables) works best.
Failing
Exit with any status other than 0. Difflicit shows the user the last five lines of standard error, so make them say what went wrong and what to do about it:
No licence key: run `acme-deep activate <key>`, or set ACME_DEEP_KEY.
Anything else on standard error is your log: Difflicit ignores it unless the engine fails. An analysis that runs for over an hour is stopped.
The environment
Difflicit runs the engine directly (not through a shell), with the user's environment and a PATH that includes
Homebrew's and Cargo's folders. Don't rely on the working directory; use the paths in the request.
Compatibility
Within protocol 1, Difflicit may add fields to the request: ignore the ones you don't know. A change that would
break engines gets a new protocol number, and engines say which one they speak in --about.
Engines that run on a server
An engine's analysis doesn't have to happen on the user's computer. A proprietary engine can ship a small
client as its command: --difflicit sends the request (and whatever of the two sides it needs) to your service,
and prints the analysis that comes back. Difflicit can't tell the difference.
Keep the user informed: say in description that the analysis is done remotely, and fail with a clear message on
standard error when there's no network or no valid account. Users of a security tool care where their binaries
go, so say what you upload.
Test it
Try both options by hand:
acme-deep --about
echo '{"protocol":1,"project":"/tmp","before":{"artifact":"x","kind":"file","version":"1","path":"/tmp/a.c"},
"after":{"artifact":"x","kind":"file","version":"2","path":"/tmp/b.c"},
"diff":{"kind":"unified","text":"--- a/x\n+++ b/x\n@@ -1 +1 @@\n-1\n+2\n"}}' | acme-deep --difflicit
echo $?
Then in Difflicit: Analyze → Manage engines…, add your command (or Browse… to the program you built), and
analyze two versions with it. If Difflicit refuses to add it, the message says why: usually --about printed
something other than JSON, or a different protocol.
Start from Viper
Viper is MIT-licensed so you can build on it. It's written in Rust and already has
everything around the analysis: the command line (viper old new, --patch), --about, --difflicit, comparing
paths with git and radare2, and tests that run it the way people and Difflicit do. To make it yours:
- Fork
ivxlabs/viper. - Rename the package in
Cargo.toml: that's your command's name. The library staysengine, and no code mentions Viper's name, so you can keep merging Viper's improvements. - Edit
about.json: your engine's name, version, description and license. - Replace the analysis in
src/lib.rs(analyze) with yours. cargo test, thencargo install --path .to try it in Difflicit.
Your fork can be under any license. Keep Viper's MIT notice for the parts that come from it.
An example in Python
A complete engine in a single file, counting what changed:
#!/usr/bin/env python3
import json, sys
if sys.argv[1:] == ["--about"]:
print(json.dumps({"name": "Change counter", "version": "1.0", "license": "MIT", "protocol": 1}))
sys.exit()
req = json.load(sys.stdin)
before, after, diff = req["before"], req["after"], req["diff"]
print(f"# {after['artifact']}: {before['version']} → {after['version']}\n")
print("> Written by Change counter 1.0.\n")
if diff["kind"] == "unified":
lines = diff["text"].splitlines()
added = sum(1 for l in lines if l.startswith("+") and not l.startswith("+++"))
removed = sum(1 for l in lines if l.startswith("-") and not l.startswith("---"))
print(f"{added} lines added and {removed} removed.\n")
print("```diff\n" + diff["text"][:4000] + "\n```")
else:
changed = [f["name"] for f in diff["functions"] if f["status"] == "changed"]
print(f"{len(changed)} functions changed:\n")
print("\n".join(f"- `{name}`" for name in changed[:50]))
Save it as change-counter in a folder on your PATH, chmod +x it, and add change-counter under Manage
engines….
Ship it
Your users install your engine like any command-line tool. Homebrew is the easiest way for most of them. A
formula for a prebuilt binary, in your own tap (brew install you/tap/acme-deep):
class AcmeDeep < Formula
desc "Analysis engine for Difflicit"
homepage "https://acme.example/deep"
version "1.2.0"
url "https://acme.example/downloads/acme-deep-1.2.0-macos-universal.tar.gz"
sha256 "…"
def install
bin.install "acme-deep"
end
test do
assert_match "\"protocol\": 1", shell_output("#{bin}/acme-deep --about")
end
end
Viper's repository builds its release archives and updates its Homebrew formula from GitHub Actions, if you want a working example to copy.
To have an instance of Difflicit offer your engine by default, with its install command, add it to engines in
the instance's difflicit.config.json (Run your own instance).
Licensing
Difflicit is under the GPL. An engine is a separate program: Difflicit starts it, and the two exchange data only through its command line, standard input and standard output, as described above. Engines don't include or link Difflicit's code, so their makers choose their own license, open source or proprietary. (If in doubt about your own case, ask a lawyer, not a docs page.)