Cloud Nexus LineageGuard

A DataHub-powered release-safety agent that uses live metadata and lineage to detect blast radius, assess risk, and stop unsafe data-platform changes before deployment.

Comment

Inspiration

Data-platform changes often look small in a pull request but can create a much larger blast radius across an organization.

A single renamed or removed field can silently break downstream transformation models, dashboards, quality checks, reports, and data consumers. The engineer proposing the change may not know every dependency, and a generic AI assistant can produce unsafe recommendations when it lacks reliable organizational context.

I built Cloud Nexus LineageGuard to answer a critical question before deployment:

What could this change break, what evidence supports that conclusion, and is it safe to proceed?

LineageGuard uses DataHub as its organizational context layer so that release-safety decisions are grounded in real metadata rather than assumptions or fabricated information.

What it does

Cloud Nexus LineageGuard is a metadata-grounded release-safety agent for proposed data-platform changes.

A user submits a structured change request, such as renaming a column. LineageGuard retrieves relevant metadata from DataHub through the official external DataHub MCP Server and evaluates available:

  • schema metadata
  • upstream and downstream lineage
  • ownership information
  • sensitive-data classifications
  • quality metadata
  • incident health
  • saved dataset queries

LineageGuard then:

  • calculates a deterministic risk score
  • determines blast radius from lineage
  • identifies security and data-quality concerns
  • preserves evidence provenance and retrieval status
  • reports missing, failed, unsupported, or truncated evidence explicitly
  • produces a deployment recommendation
  • generates review-required validation, migration, rollback, and summary guidance

Retrieved facts remain separate from generated recommendations.

The agent never treats missing evidence as proof that a change is safe.

How I used DataHub

DataHub is the grounding layer of the project.

The verified live workflow uses DataHub OSS through the official external mcp-server-datahub, launched with uvx and connected through stdio.

LineageGuard uses allowlisted, read-only MCP operations including:

  • search
  • get_entities
  • list_schema_fields
  • upstream and downstream get_lineage
  • get_dataset_queries

The provider also performs a real DataHub-backed readiness probe before reporting the connection as healthy. It does not assume that MCP tool discovery alone means the DataHub backend is reachable or authenticated.

DataHub writeback is intentionally disabled.

Verified live demonstration

The live workflow was verified against the DataHub Quickstart Order Details dataset.

The proposed change was:

order_details.cust_email → order_details.customer_email

DataHub confirmed that the field exists with a native string type and returned real upstream field lineage.

For this verified scenario, LineageGuard produced:

Risk score: 55

Deployment decision: NEEDS_HUMAN_REVIEW

DataHub did not provide a field-level sensitive classification for this field, so LineageGuard does not invent a PII classification.

This reflects a core design principle of the project:

Unknown evidence remains unknown rather than being fabricated.

Architecture

The workflow contains five main stages.

1. Proposed Data Change

A structured request describes the intended data-platform change. Pydantic models validate the request, reject unexpected fields, enforce length limits, and prevent inappropriate control characters.

2. LineageGuard API

A FastAPI service exposes deterministic local-analysis endpoints and a fail-closed live DataHub workflow.

Key endpoints include:

  • GET /health
  • GET /v1/demo
  • POST /v1/analyze
  • GET /v1/datahub/status
  • POST /v1/analyze/live

3. DataHub MCP Provider

The provider launches the official external DataHub MCP Server over stdio and permits only required read-only tools.

It verifies that:

  • the MCP process starts correctly
  • all required tools are available
  • the real DataHub backend is reachable
  • authentication is accepted
  • writeback remains disabled

4. Evidence and Risk Engine

MCP responses are converted into typed evidence containing:

  • source system
  • MCP source reference
  • retrieval timestamp
  • retrieval status
  • retrieved facts
  • missing-data reasons
  • trust state
  • completeness and truncation information

A deterministic risk engine evaluates schema, lineage, classification, quality, incident, query, and ownership evidence.

Lineage is used to calculate downstream blast radius. Missing or incomplete critical evidence prevents unconditional approval.

5. Decision and Artifacts

LineageGuard returns a deployment recommendation together with review-required:

  • validation steps
  • migration guidance
  • rollback guidance
  • findings
  • limitations
  • audit events
  • pull-request summary information

Generated SQL or migration guidance is text only and is never executed.

Safety by design

Release-safety tooling should not become another source of unsafe automation.

LineageGuard therefore maintains strict operational boundaries:

No DataHub writeback.

No SQL execution.

No autonomous migrations.

Metadata is treated as untrusted input.

Unsafe or incomplete evidence requires human review.

Suspicious prompt-injection phrases are flagged. Raw metadata is scanned before sanitization where needed, and credential-like content is sanitized on the metadata and query paths where redaction is implemented.

Live retrieval fails closed rather than silently falling back to mock evidence.

The project does not claim perfect prompt-injection protection, universal secret detection, or production-ready authentication.

Challenges I faced

The hardest part was not simply connecting to DataHub. It was making the integration trustworthy enough for a release-safety workflow.

Important challenges included:

  • preserving column-filtered lineage when DataHub returned qualified and unqualified field names
  • retaining known relationships when lineage results were truncated
  • preventing bounded schema, lineage, and query responses from being presented as complete
  • distinguishing retrieved facts from generated recommendations
  • enforcing one absolute deadline across each MCP request
  • terminating and reaping stalled MCP child processes safely
  • resolving the external MCP executable through PATH
  • propagating the intended DataHub URL and protected token configuration to the MCP child process
  • validating real DataHub backend readiness instead of checking only tool discovery
  • normalizing sensitive classifications without inventing them
  • marking missing, unsupported, and failed evidence as untrusted
  • scanning raw query and quality metadata before public sanitization
  • redacting credential-shaped content from implemented output paths
  • translating DataHub incident health into the risk engine’s incident contract
  • surfacing incomplete query history as a limitation rather than silently treating it as complete

Automated review and repeated regression testing surfaced several edge cases. Each confirmed issue was addressed with focused tests.

Accomplishments that I'm proud of

The final implementation includes a verified live DataHub MCP workflow rather than a placeholder integration.

The current submission verification includes:

  • 105 tests passed, 1 skipped
  • 77 real DataHub integration tests passed
  • Ruff lint passed
  • Ruff formatting passed
  • mypy passed
  • pip check passed
  • GitHub Actions CI passed
  • live API endpoints returned HTTP 200
  • public sanitized request, evidence-summary, and analysis-report artifacts are included in the repository

The verified live decision remains grounded in actual DataHub metadata:

Risk score: 55

Decision: NEEDS_HUMAN_REVIEW

I am also proud that the project remains conservative when evidence is incomplete. It does not convert uncertainty into false confidence.

What I learned

The biggest lesson was that metadata-aware agents need more than metadata access.

They need:

  • explicit provenance
  • retrieval status
  • completeness information
  • defensive handling of untrusted metadata
  • clear separation between facts and recommendations
  • policies for what happens when evidence is unavailable

For safety-critical platform decisions, knowing what you do not know can be as important as the metadata you successfully retrieve.

I also learned that deterministic reasoning can be highly valuable inside agentic workflows. The current hackathon implementation deliberately does not use an LLM for the final safety decision. Risk scoring and deployment policy remain reproducible, explainable, and testable.

What's next

Future development could include:

  • production authentication and authorization
  • support for more data-platform change types
  • richer field-level classification and quality context
  • deeper CI/CD and pull-request integration
  • broader DataHub metadata coverage
  • improved visualization of downstream blast radius
  • carefully controlled, human-approved writeback workflows
  • production monitoring and incident-response controls

The current version intentionally keeps all operational actions under human control while demonstrating the core idea:

Use DataHub context before deployment so data-platform changes can be evaluated with evidence—not guesswork.

Built With

Share this project:

Updates

Submission history