Cloudflare DDNS

The security model for cloudflare-ddns focuses on the correctness of the raw data used for public-IP detection. The primary goal is to prevent an attacker from forcing the updater to publish an attacker-chosen IP address in managed DNS records or WAF content.

Trust Boundary and Attacker Model

• Trust Boundary: The network path used by public-IP detection.
• Attacker Model: The system is designed to resist off-path attacks (where an attacker injects traffic without controlling the route).
• Limitation: If an attacker is on-path (can observe or alter traffic on the route), no DDNS updater can guarantee security through application-layer logic alone.

Security Protections

• The updater uses HTTPS for connections to Cloudflare. This provides higher resistance to off-path packet forgery and DNS spoofing compared to traditional DNS-based public-IP detection.

Unsafe Scenarios (When to use Static IPs instead)

Do not rely on this updater if an attacker can become on-path for the network path. Secure public-IP detection is impossible in the following scenarios:

1. Unsafe Wi-Fi: Using networks like WPA2 Enterprise without server identity verification.
2. Traffic Interception: If an adversary can intercept traffic near Cloudflare's servers.
3. Network Path Access: If an adversary can access the physical cable, broader network path, or country-scale firewalls.

Note: HTTPS protects the content of the communication but does not protect source or destination IP addresses.

The reconciliation algorithm is the core logic used to synchronize managed resources (like DNS records or WAF rules) with a desired state. It is designed to be a 'satisfier' rather than a full canonicalizer, meaning it prioritizes preserving existing objects that already meet requirements to minimize unnecessary mutations.

Intent Handling

The algorithm behaves differently based on the reconciliation intent:

• preserve: Keep all existing managed content unchanged (resource is out of scope).
• abort: Keep all existing managed content unchanged (resource is in scope, but data was unavailable).
• clear: Proceed with an empty desired target set.
• update: Proceed with the derived desired target set.

Core Reconciliation Logic

For every managed resource unit, the algorithm follows these steps:

1. Keep owned objects that already satisfy at least one desired target.
2. Recycle remaining owned objects to satisfy uncovered desired targets.
3. Create new objects only if recycling cannot satisfy all desired targets.
4. Delete leftover owned objects that satisfy no desired target.

The project follows a structured lifecycle model divided into two timelines: the process lifecycle (startup, waiting/triggering, and shutdown) and the update-round lifecycle (detection, derivation, reconciliation). This model ensures that raw data is validated and admissible before any mutations occur on remote resources.

Core Phases

1. Startup: Prepares the runtime (output, reporters, config validation, API handles).
2. Waiting and Triggering: The process waits for the next trigger via startup policy or cron scheduling.
3. Detection: Yields reconciliation intents based on observed raw data.
4. Derivation: Transforms admissible raw data into resource-specific targets (e.g., DNS addresses or WAF prefixes).
5. Reconciliation: Mutates managed remote state toward the desired result based on intents and targets.
6. Cleanup: Performs shutdown-time mutations, deleting resources eligible for deletion upon process stop.

The project uses an ownership model to determine which DNS records, WAF lists, and IP addresses the updater is permitted to manage, mutate, or delete. Ownership is determined by the intersection of three static predicates: Resource Ownership, IP-Family Ownership, and Attribute-Based Ownership. If a resource does not satisfy all three, it is considered out of scope.

Resource Ownership

Determines if a DNS domain or WAF list is a managed resource root. If a domain or list is not explicitly configured, it is out of scope for all operations.

IP-Family Ownership

Determines if an IP family (IPv4 or IPv6) is in scope.

• Set IP4_PROVIDER=none or IP6_PROVIDER=none to exclude that specific family from management.
• Any other provider mode enables management for that family.

Attribute-Based Ownership

Determines which specific records or WAF items are recognized as belonging to the updater. This is typically handled via comments. To prevent the updater from orphaning its own objects, write-side values must satisfy the ownership selectors:

• For DNS: Uses RECORD_COMMENT.
• For WAF: Uses WAF_LIST_ITEM_COMMENT.

Deletion Eligibility

An item is only eligible for deletion during a shutdown/reconciliation if the updater can recreate the fully reconciled state of that resource using only the current configuration.

Standalone Go modules located under scripts/github-actions/* are permitted to define their own module-local .golangci.yaml files. This allows these scripts to have a linting policy tailored to their specific, standalone purpose rather than following the repository-wide configuration.

When to use module-local .golangci.yaml:

• For stable, module-wide exceptions that arise from the script's context.
• When relaxing rules that primarily address ceremony or refactoring pressure specific to small, standalone runner shapes.
• When scale-sensitive maintainability or style rules do not materially impact the project's core priorities (correctness, security, resilience, and operator-clarity).

When NOT to use module-local .golangci.yaml:

• Repository-wide judgments: These must be placed in the root .golangci.yaml.
• Statement-local exceptions: Use inline suppression //nolint:<linter> // reason for specific declarations or statements.
• Relaxing core protections: Do not relax linters that protect security, failure handling, or operator-facing clarity.