Eve library

Isis Output Lineage and Provenance Audit Runbook

Runbook

Revision 1

On this page

Last Updated: 2026-02-25
Scope: Output integrity audit coverage for orphaned outputs, broken lineage edges, and missing provenance links.

Purpose#

Provide deterministic audit evidence for WS17-007 integrity requirements:

  1. Orphaned outputs (eligible outputs detached from provenance and lineage).
  2. Broken lineage edges (lineage_edges rows pointing to missing outputs or self-referential edges).
  3. Missing provenance coverage from both output and provenance perspectives.

Audit Automation#

Use scripts/isis/generate_output_lineage_provenance_audit_report.sh.

Report outputs:

  • JSON: tmp/isis-audits/output-lineage-provenance-audit-*.json
  • Markdown: tmp/isis-audits/output-lineage-provenance-audit-*.md

Prerequisites#

  • psql and jq installed.
  • ISIS_DATABASE_URL (or DATABASE_URL) configured.
  • Read access to outputs, provenance, and lineage_edges.

Execution#

bash
STRICT=true \
ISIS_DATABASE_URL="postgres://..." \
scripts/isis/generate_output_lineage_provenance_audit_report.sh

Threshold Controls#

Variable Default Description
SAMPLE_LIMIT 25 Maximum samples per issue class in report payloads.
MAX_ORPHANED_OUTPUTS 0 Allowed orphaned output count.
MAX_BROKEN_LINEAGE_EDGES 0 Allowed broken lineage edge count.
MAX_OUTPUTS_MISSING_PROVENANCE 0 Allowed count of eligible outputs missing provenance linkage.
MAX_ORPHAN_PROVENANCE_ROWS 0 Allowed count of provenance rows that reference missing outputs.

Remediation Guidance#

If the audit fails:

  1. Run provenance backfill:
    • POST /api/v1/outputs/admin/provenance/backfill
    • isis outputs backfill-provenance
  2. Repair or remove invalid lineage edges.
  3. Re-run the audit script until all threshold checks pass.