ivx research

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": "…" }]
}
KeyWhat
name, iconThe instance's name and emoji, shown on the website
projectRepoThe Difflicit repository, for the Star button
projects.ownerThe GitHub organization whose repositories are the published analyses
projects.idA regular expression every project id matches
projects.repoHow an analysis repository is named, with {id} for the project id, e.g. analysis-{id}
catalogWhere the catalog lives (a URL). Without one, the app lists the user's own projects
iamOptional: the OAuth client for Sign In with an ivx-style account server. Without it, users bring a GitHub token
enginesOptional: 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, partnersOptional: 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 CATALOG repository variable to your catalog's URL.
  • scrape runs the scraper weekly and uploads the catalog to any S3-compatible bucket: set the variables S3_ENDPOINT and S3_BUCKET (and optionally S3_PREFIX) and the secrets S3_ACCESS_KEY_ID and S3_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.