ivx research Difflicit Analyses
Analyses
An analysis answers one question: what changed, and why does it matter? In Difflicit that's a project, a
folder with a difflicit.json in it. Open any folder in the desktop app (Open folder…, or ⌘O) and
it becomes one. There's no setup: the project file just marks the folder.
Artifacts and versions
A project holds artifacts, the things you compare. Each has versions, and Analyze diffs two of them. The Artifacts menu lists the project's artifacts, adds them and removes them.
| Artifact | Its versions | Diffed with |
|---|---|---|
| A git repository: a folder or a clone URL | its tags and commits | git diff |
| A file or folder: a binary, a source tree… | the copies you add under its name | radare2 for two binaries, git diff --no-index otherwise |
Add artifact… takes nothing but a path or a URL. A repository is cloned into the project
(artifacts/<name>); a file or folder is copied in (artifacts/<name>/<version>). So a project stays
self-contained, and you can commit it, share it, or zip it up.
An artifact is named after what you add. Add a file (or a dylib from a shared cache) with the same name as a file artifact the project already has, and it becomes another version of that artifact, not a second artifact: the same thing in two versions is what you compare.
Removing an artifact (the trash icon, then Remove) takes it out of the project and deletes its copies in
artifacts/<name>.
Instead of browsing for a file, you can also pick:
- An installed app or library. The dropdown lists the apps in
/Applications(the executable inside the bundle) and the libraries in/opt/homebrew/lib,/usr/local/liband/opt/local/lib(on Linux, the system library folders). - A dylib from a dyld shared cache. Apple's system frameworks aren't on disk: they live in the shared cache. The Shared cache tab uses ipsw to extract one. The cache can be this Mac's, one pulled out of an IPSW or OTA file, or one downloaded by device and build. Extract the same framework from another cache and it becomes another version of it, which is how you diff it across two OS builds. Compare… lists the dylibs that changed between two caches, to find where to look.
Reading a diff
Text shows as a unified or side-by-side diff. For two binaries, radare2 matches their functions first: the sidebar lists them, changed ones first with how alike they still are, and each opens a diff of its disassembly.
The sidebar has the project's Artifacts, each opening to its versions, and its Notes, above the diff. Pick an artifact or a version to see what it is: a binary's format, headers, load commands, linked libraries and sections; a folder's contents, each of which opens the same way; anything else as text. Right-click for more: open, analyze, reveal in Finder, copy the path, or remove an artifact.
Notes
The Notes item shows the project's notes, written in diffmd: Markdown that carries patch diffs inside it, so the explanation and the patch stay together. You write them in the app, a block at a time: + next to Notes starts a note, and Analyze writes one for each change it analyzes.
Stored patches
A project doesn't need artifacts. Any *.diff or *.patch file in it is listed and shown as is, on the website
too, which suits an analysis that only needs the fix itself.
Analyze
Analyze answers "what was this change about?" and writes the answer into the project as a diffmd note. An analysis engine does the analyzing: the built-in one, described here, works without AI, and you can install others. It's in the desktop app, in a project folder. Pick an artifact (or one of its versions) in the sidebar and press Analyze there: it starts with that as the after and the version before it as the before, and ⇄ swaps the two. Or pick both yourself: two versions of one artifact, or versions of two different file artifacts (say, two builds of a binary added separately). A git repository can only be compared with its own versions. Difflicit diffs the two and looks for the patterns fixes leave behind:
| Finding | What gives it away |
|---|---|
| Bounds check | a comparison tightened (< to <=), new checks on lengths, sizes and indices |
| Integer overflow | os_mul_overflow and friends, explicit *_MAX limits |
| Integer width or signedness | an int that became a size_t in otherwise identical code |
| NULL / validity check | a pointer now checked before use |
| Lifetime / use-after-free | references taken or dropped differently, freed pointers cleared |
| Race condition | locks and atomics added around shared state |
| Uninitialized memory / info leak | memory zeroed before it's used or copied out |
| Type confusion | an object's type or kind checked before it's used as one |
| Permission check | entitlement, sandbox, credential and privilege checks |
| Unsafe copy | strcpy and friends replaced, copy sizes changed |
| Hardening | assertions, panics and mitigations (PAC, typed allocations, zone checks) |
| Code removed | far more deleted than added |
| Not a fix | only comments, only formatting, only renames |
Binaries are read the same way through their disassembly: Difflicit disassembles the most changed functions and
looks for new comparisons and conditional branches, new NULL tests (cbz), and calls to functions such as
lck_mtx_lock or bzero.
The note, analysis-<artifact>-<before>-to-<after>.diffmd at the project's root, leads with the most likely
explanation and where it is. Every finding follows, with its strength and reason and the lines it rests on, as an
excerpt of the patch. Analyzing again writes a new note (-2, -3…) and never replaces your edits. The note is a
prediction from patterns, so check the evidence. It's a starting point: rewrite it block by block, delete what's
wrong, and add what you find. If the project has no notes yet, this one becomes them.
On the website
On an instance such as ivx/xnu, Get a copy gets you your own analysis repository on
GitHub: a fork of the published analysis, if there is one, or a new repository named after the project. Then it
opens that repository in the desktop app, which clones it to ~/Difflicit/<owner>/<repo>. See
GitHub and the desktop app.
Share links to the whole project: its notes, patches and artifacts, not just the file open on screen. To put a note into an article instead, Embed the notes (embedding a note).
Getting around
⌘O opens a project, ⌘K searches the open analysis (notes and every line of its patches) and ⌘P runs a command. Use Ctrl instead of ⌘ on Windows and Linux.