ivx research Difflicit Run your own instance
Run your own instance
Difflicit is generic: it knows nothing about CVEs. An instance gives it a catalog of projects and a naming convention. ivx/xnu is one: its projects are Apple's CVEs. Yours can track anything.
Settings
An instance is configured in difflicit.config.json at the root of the repository:
{
"name": "ivx/xnu",
"icon": "💀",
"projectRepo": "ivxlabs/difflicit",
"projects": {
"owner": "ivxlabs",
"id": "CVE-\\d{4}-\\d{4,}",
"repo": "{id}"
},
"iam": {
"supabaseUrl": "https://….supabase.co",
"clientId": "…",
"url": "https://iam.ivx.run"
},
"engines": [
{ "command": "viper", "install": "brew install ivxlabs/tap/viper" }
],
"sponsor": "https://github.com/sponsors/…",
"partners": [{ "name": "…", "description": "…", "url": "…" }]
}
| Key | What |
|---|---|
name, icon | The instance's name and emoji, shown on the website |
projectRepo | The Difflicit repository, for the Star button |
projects.owner | The GitHub organization whose repositories are the published analyses |
projects.id | A regular expression every project id matches |
projects.repo | How an analysis repository is named, with {id} for the project id, e.g. analysis-{id} |
catalog | Where the catalog lives (a URL). Without one, the app lists the user's own projects |
iam | Optional: the OAuth client for Sign In with an ivx-style account server. Without it, users bring a GitHub token |
engines | Optional: the analysis engines the desktop app offers by default: each one's command, and the install command shown while it isn't installed. One without install is listed only once it's installed |
sponsor, partners | Optional: the Sponsor button, and projects to recommend on the welcome page |
The build reads environment variables that override these, which suits CI: VITE_CATALOG,
VITE_PROJECT_REPO, and VITE_SUPABASE_URL, VITE_SUPABASE_CLIENT_ID and VITE_IAM_URL for Sign In.
The catalog
The catalog is static JSON on any web server or bucket. There's no server code and no database. It's three kinds of file:
index.json: the welcome page's title, intro and numbers, the facets to filter by (severity, year, component…), and the shards: slices of the catalog, so the browser only downloads the part it's looking at.- One file per shard: the summaries of its projects (id, one-line summary, date, badge, tags).
projects/<id>.json: everything about one project, as display sections, plus an optional toolbar menu of related links.
The format is defined, with comments, in
src/types.ts. ivx/xnu's catalog is written by
scripts/main.py, which scrapes Apple's
security advisories and NVD. Copy it as a starting point for your own.
Deploying
The repository's workflows do it for you on GitHub:
- pages builds the website and publishes it to GitHub Pages on every push. Set the
CATALOGrepository variable to your catalog's URL. - scrape runs the scraper weekly and uploads the catalog to any S3-compatible bucket: set the variables
S3_ENDPOINTandS3_BUCKET(and optionallyS3_PREFIX) and the secretsS3_ACCESS_KEY_IDandS3_SECRET_ACCESS_KEY. - desktop builds the desktop app for macOS, Windows and Linux on every
v*tag.
To work on it locally:
npm install
(cd scripts && uv run main.py --limit 20 --out ../public/api) # a small sample catalog
VITE_CATALOG=/api npm run dev
Difflicit is GPL-3.0: an instance that changes it must share its source the same way.