FOD Oracle

fod-oracle

Watching over nixpkgs for FOD discrepancies

Static Badge

Temet Nosce

Overview

FOD Oracle is a tool for tracking and analyzing fixed-output derivations (FODs) across different revisions of nixpkgs. It helps identify discrepancies and changes in FODs that might indicate issues with build reproducibility.

Features

Components

Usage

CLI

FOD Oracle outputs all results as streaming JSON Lines to stdout, making it easy to process with tools like jq or pipe to other programs.

# Process a simple Nix expression (outputs JSON Lines)
./fod-oracle -expr "(import <nixpkgs> {}).hello"

# Process a specific nixpkgs revision  
./fod-oracle 1d250f4

# Reevaluate FODs by rebuilding them (includes rebuild status in JSON)
./fod-oracle -reevaluate -parallel=4 -build-delay=5 1d250f4

# Enable debug logging
./fod-oracle -debug -expr "(import <nixpkgs> {}).hello"

# Process and filter with jq
./fod-oracle -expr "(import <nixpkgs> {}).hello" | jq '.Hash'

# Save JSON Lines to file
./fod-oracle 1d250f4 > fods.jsonl

Output Formats

Normal Mode: Outputs basic FOD information as JSON Lines

{"DrvPath":"/nix/store/...","OutputPath":"/nix/store/...","ExpectedHash":"sha256-..."}

Reevaluate Mode: Includes rebuild verification results

{"DrvPath":"/nix/store/...","OutputPath":"/nix/store/...","ExpectedHash":"sha256-...","ActualHash":"sha256-...","RebuildStatus":"success","HashMismatch":false}

All hashes are in SRI format (generated using nix hash convert) and are directly greppable in the nixpkgs codebase.

Scanning a complete nixpkgs revision takes around 10+ minutes on a 7950 AMD Ryzen 9 16-core CPU with 62GB RAM.

Command-line Arguments

Usage: ./fod-oracle [options] <nixpkgs-revision> [<nixpkgs-revision2> ...]

Options:
  -debug
        Enable debug logging to stderr
  -drv string
        Derivation path for test mode
  -expr string
        Process a Nix expression instead of a revision
  -help
        Show help
  -parallel int
        Number of parallel rebuild workers (default: 1, use higher values for testing)
  -reevaluate
        Reevaluate FODs by rebuilding them and include rebuild status in output
  -build-delay int
        Delay between builds in seconds (default 10)
  -test
        Test mode - process a single derivation
  -workers int
        Number of worker threads (default 1)

Environment Variables

Rebuild-FOD Tool

The project includes a standalone rebuild-fod tool that can be used to rebuild and verify fixed-output derivations. This tool is built in Go and can be used both as a command-line utility and as a library in the main application.

Building and Using the Tool with Nix

nix build .#rebuild-fod -- /nix/store/0m4y3j4pnivlhhpr5yqdvlly86p93fwc-busybox.drv

The rebuild-fod tool uses multiple methods to determine the correct hash of a fixed-output derivation:

  1. Extracting from derivation JSON (Method 1)
  2. Querying the Nix store (Method 2)
  3. Computing from the output (Method 3)
  4. Building the derivation if needed (Method 4)

It then compares the results to find any hash mismatches, which could indicate reproducibility issues.

API Endpoints

The following API endpoints are available: