ivx research

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.

ArtifactIts versionsDiffed with
A git repository: a folder or a clone URLits tags and commitsgit diff
A file or folder: a binary, a source tree…the copies you add under its nameradare2 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/lib and /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:

FindingWhat gives it away
Bounds checka comparison tightened (< to <=), new checks on lengths, sizes and indices
Integer overflowos_mul_overflow and friends, explicit *_MAX limits
Integer width or signednessan int that became a size_t in otherwise identical code
NULL / validity checka pointer now checked before use
Lifetime / use-after-freereferences taken or dropped differently, freed pointers cleared
Race conditionlocks and atomics added around shared state
Uninitialized memory / info leakmemory zeroed before it's used or copied out
Type confusionan object's type or kind checked before it's used as one
Permission checkentitlement, sandbox, credential and privilege checks
Unsafe copystrcpy and friends replaced, copy sizes changed
Hardeningassertions, panics and mitigations (PAC, typed allocations, zone checks)
Code removedfar more deleted than added
Not a fixonly 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.