Zero Trust Syncd

Business identity meets network policy

ERPNext knows the organization: employees, departments, branches, roles, and employment state. NetBird enforces network access through users, groups, peers, and policies. Zero Trust Syncd is the governance boundary between them. It converts organizational intent into explicit, reviewable network state without coupling the two systems through ad-hoc scripts.

Control-plane boundary

ERPNext is the desired-state source. NetBird is the observed enforcement plane. Syncd owns mapping, reconciliation decisions, validation, guardrails, retries, audit records, and operator explanations. Syncd is not a packet relay, firewall, proxy, or replacement for NetBird; existing WireGuard traffic remains on the NetBird data path.

Reconciliation flow

1. Read employees, departments, branches, roles, and enabled state from ERPNext.
2. Normalize them into stable managed identity and resource group boundaries.
3. Compare desired state with observed NetBird users, groups, peers, and policies.
4. Generate proposed creates, updates, moves, or no-op decisions.
5. Run policy validation and high-risk guardrails.
6. Preview or apply only allowed changes and record an audit event.
7. Retry and detect drift without converting upstream failures into destructive empty state.

Managed boundaries

Syncd manages explicit namespaces such as dep:, loc:, scp:, status:, role:, and peer:. Groups and policies outside the managed boundary are treated as manual administrator state and remain untouched. Peer groups are kept separate from human identity groups.

Policy safety

• Automatic deletion of policies is forbidden.
• Manual NetBird policies are never silently modified.
• Managed-policy drift requires an explicit administrator review before remediation.
• Global administrator access and broad site access are blocked by default.
• Policy application defaults to dry-run and creates a snapshot before operations.
• Idempotent reconciliation avoids duplicate managed policies.

Failure model and audit

If ERPNext is unavailable or returns an authentication/timeout failure, reconciliation freezes rather than interpreting an empty response as “all employees disappeared.” If NetBird is unavailable, the cycle is retried or logged while local state is preserved. JSONL audit readers skip malformed lines, count parse errors, and continue without crashing the UI or control plane. The audit trail records before state, managed after state, retained manual groups, desired groups, reason, and dry-run status.

Implementation and deployment

The backend is FastAPI with ERPNext and NetBird API clients, reconciliation, retry, drift, policy generation, validation, and SQLite state/audit persistence. The operator console is React/Vite. Docker Compose deploys one Syncd container beside the external NetBird stack through its internal Docker network; Traefik exposes only the web service while NetBird Management API remains internal.

Current status

The deployed console demonstrates health, identity mapping, group mapping, policy review, audit, configuration, and SSO surfaces. The project remains governed infrastructure software: deployment requires protected credentials, internal API reachability, explicit guardrail configuration, backups, and a dry-run period before policy application. It is not a generic network-management replacement.

Technical references

Source repository: erpnext-netbird-bridge. Live console: syncd.thaiduy.store. Read the README, architecture contract, policy sync contract, and guardrails.