ivx research Difflicit Viper
Viper
Viper is ivx's free analysis engine. Give it two versions of something (files, folders, binaries) and it writes up what changed between them as diffmd: which files changed, by how much, and each change as a patch. For two binaries, it lists the functions that changed, appeared and went. It runs on its own from a terminal, or inside Difflicit through Analyze.
Viper is open source under the MIT license. HyperViper, the full version, is built on it.
Install
brew install ivxlabs/tap/viper
That installs the viper command on macOS (Apple silicon and Intel) and on Linux (x86-64). Without Homebrew,
download the archive for your platform from Viper's releases on GitHub: it holds a single program, viper. Put
it somewhere on your PATH. Or build it from source with Rust: cargo install --path . in a checkout of
ivxlabs/viper.
Viper uses two other tools:
- git compares files and folders. It comes with Xcode's command-line tools on macOS, and with your
distribution's
gitpackage on Linux. - radare2 compares binaries function by function:
brew install radare2. Without it, Viper still notices that a binary changed, but can't say where.
Use it on its own
viper <before> <after> [-o <file>]
viper --patch <file|-> [-o <file>]
| Command | What it does |
|---|---|
viper old new | Compares two files or two folders. The analysis goes to standard output. |
viper old new -o analysis.diffmd | The same, written to a file (--output works too). |
viper --patch fix.diff | Analyzes a unified diff you already have, from a file. |
git diff v1.0 v1.1 | viper --patch - | The same, from standard input: any git diff, diff -u or .patch. |
viper --about | What this engine is, as JSON (what Difflicit reads). |
viper --difflicit | Answers a Difflicit request on standard input. Difflicit runs this; you don't need to. |
viper --version, viper --help | Its version, and a summary of the above. |
Viper exits with status 0 when it wrote an analysis. Otherwise it explains the problem on standard error and
exits with 1, for example when a path doesn't exist or git isn't installed.
How it names things
When the two paths have the same name, Viper treats them as two versions of one thing, named by the folders
they're in. viper 1.0/libfoo 1.1/libfoo is titled libfoo: 1.0 → 1.1. Two differently named paths are just
themselves: viper a.c b.c is titled a.c → b.c. A patch is titled by its file name (The patch, when it
comes from standard input).
Inside two folders, files are named relative to the folder (src/check.c), so a file that exists in both is
compared with itself rather than shown as renamed.
What it writes
Comparing two versions of a small library:
viper 1.0/libfoo 1.1/libfoo
# libfoo: 1.0 → 1.1
> Written by Viper 0.1.0 from the diff of the two: what changed, and where. Check it against the diff, and make these notes your own.
**2 files changed** · +2 −1
## Overview
| File | Change | + | − |
| --- | --- | --: | --: |
| `src/check.c` | modified | 1 | 1 |
| `src/limits.h` | modified | 1 | 0 |
## `src/check.c`
```diff
--- a/src/check.c
+++ b/src/check.c
@@ -1,3 +1,3 @@
int check(size_t n) {
- return n < LIMIT;
+ return n <= LIMIT;
}
```
## `src/limits.h`
```diff
--- a/src/limits.h
+++ b/src/limits.h
@@ -1 +1,2 @@
#define LIMIT 64
+#define MAX_NAME 255
```
In Difflicit, each diff block shows as a real diff, with the changed part of each line marked.
For text and source, the analysis is:
- a title naming the two versions, and a line saying which engine wrote it;
- a one-line summary: how many files changed, and lines added and removed;
- an Overview table of every changed file: added, deleted, modified or renamed, with its line counts;
- a section per file with its changes as a patch. A renamed file says what it was called, and a binary file inside a folder is noted as changed.
For two binaries (with radare2), the analysis is:
- the summary: how many functions changed, were added and removed, and how many stayed the same;
- Changed functions: each with how alike its two versions still are and its address in each, least alike (the biggest changes) first;
- Added functions and Removed functions, with their addresses.
Limits
To keep an analysis readable, Viper shows patches for the first 50 files and up to 300 lines of each, and lists up to 100 functions per table. It always says what it left out ("…and 12 more lines in the diff"), and the overview still lists every file.
Viper writes up what changed, not why: it doesn't interpret the change. For that, check the patches yourself, or use an engine that goes further (Difflicit's built-in one predicts what a change was about, for example).
Use it in Difflicit
Once viper is installed, open a project in the desktop app and press Analyze: pick the two versions, choose
Viper as the engine, and Analyze. The analysis is saved in the project as a note and opened next to the
diff. If Viper isn't listed, Manage engines… shows whether Difflicit found it, and the command to install it
if not. See Analysis engines.
In Difflicit, Viper analyzes the diff Difflicit already made, so a git artifact's two commits or tags work too.
On the command line, compare them with git diff <old> <new> | viper --patch -.
Build on it
Viper is the starting point for your own engine. It already handles the command line, the protocol and comparing paths, and its analysis is small and easy to replace. It's MIT-licensed, so your engine can be open source or proprietary. See Writing an engine.