Catalog Canary

A lineage-aware firewall that stops poisoned DataHub context before AI agents trust it.

Comment

Inspiration

AI agents increasingly use catalog descriptions, context documents, schemas, ownership, and lineage as trusted grounding. That solves hallucination—but it creates a new supply chain. If a compromised ingestion source puts “ignore policy,” a tool command, or a secret request into catalog metadata, the payload can be retrieved by every agent that trusts that context.

A text linter can flag the original description. It cannot answer the operational question: which datasets, dashboards, features, models, and agents must stop trusting this context right now? DataHub's context graph makes that answer possible.

What it does

Catalog Canary runs a bounded five-stage loop:

  1. Collect and ground: use DataHub Agent Context Kit search, search_documents, get_entities, and get_dataset_queries to read candidate assets, descriptions, documents, ownership, tags, and schema/query context.
  2. Detect: treat every catalog string as untrusted data and apply deterministic, explainable checks for instruction overrides, exfiltration, tool coercion, role hijacking, secret requests, hidden HTML, invisible Unicode, and encoded payloads.
  3. Trace: use get_lineage to retrieve descendants missing from the initial search page and propagate risk downstream for at most three hops with decay, retaining the taint source and shortest path for every affected asset.
  4. Act: stage Context-Quarantined and Context-At-Risk tags through add_tags and a linked decision receipt through save_document.
  5. Remember: emit the same canonical evidence as a visual HTML report, human-readable Markdown, automation-ready JSON, and SARIF for CI.

The default is always a dry-run. Live writes require both --apply and the literal confirmation --confirm-writeback APPLY. Catalog Canary never executes catalog text, sends it to an instruction-following model, deletes an entity, or silently edits a source description.

How we built it

Catalog Canary is a Python 3.10+ command-line application with a small source-adapter boundary. DataHubAgentContextSource calls the official Agent Context Kit tools against DataHub OSS or Cloud. FixtureSource supplies the same normalized entity and lineage contract from a local JSON file, so judges can reproduce the complete collect → detect → trace → stage → report loop without an account or secret.

The policy engine emits stable evidence fingerprints and reduces confidence when dangerous words appear in clearly quoted security guidance. The lineage engine performs a bounded breadth-first traversal with hop decay and a criticality adjustment. A receipt SHA-256 commits to the source identity, normalized graph edges, evidence fingerprints, asset decisions, staged actions, and policy version.

The included fixture models ten entities and eleven text fields. A customer-support source hides one attack in an HTML comment and another in Base64. The verified result quarantines that source, marks seven downstream assets for block/review across three lineage hops, lowers a benign training document to MONITOR, and leaves an unrelated finance dataset TRUSTED.

The fixture is a reproducible example, not a claim of a live hosted DataHub query. Live mode requires a DataHub GMS URL and a Personal Access Token when the deployment enforces authentication; a local deployment configured for unauthenticated GMS access can omit the token.

Challenges we ran into

The hardest design problem was separating dangerous instructions from documentation that merely discusses them. Keyword matching alone would quarantine security guidance. Catalog Canary therefore keeps rule-level evidence, recognizes reference-language cues, and lowers confidence instead of discarding the evidence.

The second challenge was modeling blast radius without turning one finding into a graph-wide panic. We bounded traversal to three downstream hops, decay risk at every hop, and keep the exact source and path length behind each verdict.

Finally, write-back needed to be useful without becoming another unsafe autonomous action. Reversible tags, a persistent decision document, dry-run defaults, and explicit double confirmation make the response auditable and operator-controlled.

Accomplishments that we're proud of

  • DataHub is not decorative: identity, metadata, downstream lineage, governance tags, and the durable incident document are all central to the product loop.
  • The one-command fixture is deterministic, secret-free, and judgeable without infrastructure.
  • Direct compromise and downstream exposure are represented separately, with evidence and hop distance.
  • Benign quoted guidance and unrelated assets demonstrate negative behavior, not only a planted true positive.
  • Every run produces useful views for executives, incident responders, automation, and CI.
  • The live adapter never logs credentials, and mutation is impossible without deliberate operator confirmation.
  • The finished 2:40 demo uses real fixture execution and a real DataHub SDK 1.6.0.17 no-network dry-run, with explicit labels that no live GMS write-back is claimed.

What we learned

Grounding an agent is not only a relevance problem; it is a trust and provenance problem. Lineage can serve as a security primitive because it describes where compromised context can flow. We also learned that the most useful agent action is often not an irreversible fix—it is a bounded decision that changes shared context, preserves evidence, and gives the next human or agent a safe recovery gate.

What's next for Catalog Canary

  • Add multilingual and embedding-assisted detection behind the deterministic safety boundary.
  • Ingest metadata change events for continuous scanning instead of periodic runs.
  • Add owner routing, policy exceptions, and automatic re-scan workflows before tag removal.
  • Evaluate column-level lineage and retrieval-policy integrations so quarantined context is excluded automatically.
  • Contribute a reusable Catalog Canary skill and any generally useful adapter or documentation improvements upstream after maintainer review.

Built With

Share this project:

Updates