Azure Private Link Doctor

An offline-first, evidence-driven diagnostic engine for Azure Private Endpoint, Private DNS, hybrid DNS, routing, NSG, and service-firewall failures. It turns a sanitized JSON evidence bundle into deterministic root causes, a path visualization, support evidence, and Terraform/Bicep remediation scaffolds—without changing Azure.

The expensive problem is rarely creating a private endpoint. It is proving why an application still cannot reach it across DNS, routing, policy, and hybrid-network boundaries.

• Azure Private Link and Private Endpoint troubleshooting
• Azure Private DNS and split-horizon DNS diagnostics
• Azure DNS Private Resolver and hybrid/on-premises forwarding design
• Network security group and user-defined route analysis
• Infrastructure as Code with Terraform and Bicep
• CI/CD validation, sanitized evidence, and support-ready incident artifacts
• Production-minded automation: deterministic findings, explicit confidence, no autonomous mutation

flowchart LR
    A[Sanitized evidence bundle] --> B[Schema validation]
    B --> C[Deterministic rule engine]
    C --> D[Root-cause report]
    C --> E[Network path diagram]
    C --> F[Terraform/Bicep scaffold]
    C --> G[Sanitized support bundle]
    D --> H[Engineer review and controlled rollout]
    F --> H
    H --> I[Azure deployment pipeline]

The checked-in evidence/ outputs make the results reviewable without an Azure subscription. They are generated from synthetic, sanitized fixtures and are not presented as live tenant evidence.

Requires Python 3.11+ and has no runtime dependencies.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
linkdoctor examples/missing-vnet-link.json --output generated/missing-vnet-link --fail-on-diagnosis

Exit codes are automation-friendly: 0 for a complete healthy report, and 2 for incomplete evidence or a diagnosis when --fail-on-diagnosis is set.

Run the complete validation suite:

bash scripts/validate.sh

The suite executes unit tests, diagnoses all six fixtures, and compiles the generated Bicep template when Azure CLI is available.

Every run emits:

• diagnosis.json — machine-readable status, findings, evidence references, and recommended actions
• diagnosis.md — incident-review report
• network-path.mmd — Mermaid path and failure markers
• remediation/main.tf — conservative Terraform scaffold
• remediation/main.bicep — conservative Bicep scaffold
• remediation/README.md — review and rollout guidance
• support-bundle.zip — sanitized inputs and outputs for escalation

The remediation is deliberately a scaffold, not an autonomous production change. An engineer must confirm the intended DNS ownership, IP addresses, network boundaries, and change window.

- uses: AAH20/azure-private-link-doctor@main
  with:
    bundle: examples/missing-vnet-link.json
    output: generated/linkdoctor
    fail-on-diagnosis: "true"

Private connectivity failures block application releases, database migrations, zero-trust programs, and cloud modernization. The same cross-layer investigation recurs across engineering, platform, network, security, and vendor support teams. A repeatable evidence contract reduces triage time, makes escalation reproducible, and converts expert troubleshooting knowledge into a distributable workflow.

See unit economics, architecture, and production roadmap.

Version 0.1.0 analyzes supplied evidence only. It does not query Azure, deploy resources, validate live packets, or claim that a generated remediation is safe for every topology. Live Azure Resource Graph, Network Watcher, DNS probe, and policy adapters are explicitly roadmap items. The rule assumptions follow Microsoft's Private Endpoint DNS troubleshooting and Private Endpoint connectivity troubleshooting guidance.

Need this adapted to a landing zone, hub-and-spoke network, Azure Virtual WAN, on-premises DNS, or an MSP incident workflow? Request an architecture and diagnostic engagement.

MIT licensed. See SECURITY.md before attaching evidence from a real tenant.