ivx research

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 is diff or patch, in lowercase. Any other code block is shown as code.

  • A whole patch. The output of git diff, git format-patch or diff -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.