ivx research Difflicit diffmd
diffmd
A diffmd file is Markdown in which fenced code blocks tagged diff or patch hold patch diffs. Difflicit
shows those blocks in its diff viewer (unified or side by side, with line numbers and +/− counts) and
everything else as ordinary Markdown. Files end in .diffmd.
It's plain text, so notes diff and merge in Git like code. And it's still Markdown, so a diffmd file reads fine
in any editor or Markdown viewer: the diffs just show as diff-highlighted code there.
An example
# CVE-2024-54494: an off-by-one in check()
The bound was compared with `<` where it needed `<=`, letting a length of exactly
`LIMIT` through:
```diff
--- a/example.c
+++ b/example.c
@@ -1,3 +1,3 @@
int check(size_t n) {
- return n < LIMIT;
+ return n <= LIMIT;
}
```
Callers then copy `n` bytes into a `LIMIT`-sized buffer.
Difflicit shows the block as a diff of example.c, with the paragraphs around it.
Diff blocks
-
Fence. A fenced code block (
```or~~~) whose info string isdifforpatch, in lowercase. Any other code block is shown as code. -
A whole patch. The output of
git diff,git format-patchordiff -u. A block that changes several files shows each file in its own viewer, one after another. -
Or just the changed lines. Lines starting with
-,+or a space, without file headers. Difflicit adds the hunk header, numbering lines from 1, so a snippet needs no ceremony:- return n < LIMIT; + return n <= LIMIT; -
Stored inline. The diff is part of the notes. It doesn't point anywhere, so the notes keep showing the patch they explain after the source moves on.
Notes in a project
A project's project file says which file holds its notes:
{
"project": "CVE-2024-54494",
"notes": "README.diffmd",
"artifacts": []
}
Without notes, Difflicit uses README.diffmd, then README.md. Those are the notes a project opens with. Every
.diffmd file in it is a note too, listed under Notes in the sidebar, wherever it is in the project (except
artifacts/, which holds what's compared).
Blocks
A diffmd note is a sequence of blocks: a heading, a paragraph (or a list, quote or table), or a fenced block such
as a diff. Blank lines separate blocks. Headings and fences are always blocks of their own.
The desktop app shows a note block by block, every block rendered. Hover over a block and choose Edit, or double-click it, and only that block opens as source. Finish with Done or ⌘Enter, and it's saved to the file. Esc cancels. Type blank lines into a block and it becomes several blocks. Empty a block and it's deleted. The ⋯ menu adds a block below or deletes the block, and Add block at the end appends one. A block being edited is saved when you leave the note too.
Writing notes
You write notes yourself. In the desktop app, the + next to Notes starts a new one: name it, and it's
created as <name>.diffmd. Analyze writes one for each change it analyzes, with the evidence for each
finding as diff blocks, for you to check and rewrite (Analyze). The
project's first note becomes its notes. Pick any note under Notes to read or edit it. Prefer your own
editor? Open in your editor, and Difflicit picks up the changes when you switch back.
Any Markdown works as notes. The diff blocks of a plain README.md are shown as diffs too. The .diffmd
extension says the file is meant to be read that way.
On GitHub
A published analysis is a GitHub repository. Difflicit's website renders its notes, diffmd included. GitHub
itself doesn't know the .diffmd extension and shows such a file as plain text. To have it highlighted as
Markdown there, add this to the repository's .gitattributes:
*.diffmd linguist-language=Markdown
Embedding a note
A published analysis's notes can go into any HTML page, such as a blog post or a write-up. On the website,
Share → Embed the notes copies an <iframe> that shows the project's notes and nothing else, with their
diff blocks as real diffs and a link to the whole project. To embed a different note, add its path to the
iframe's URL: &path=notes/root-cause.diffmd. Only published analyses can be embedded, since a page elsewhere
can't reach a folder on your computer.
Details
- Files are UTF-8 Markdown: CommonMark with GitHub's extensions (tables, task lists, strikethrough, footnotes).
- Raw HTML in notes is sanitized before it's shown: no scripts, no event handlers.
- Notes over 512 KB are shown read-only in the app; edit them in your own editor.