Domains Internal Monitoring Design

Internal monitoring in Domains - design (#203)

Status: proposal - slice 0 is built (4.0), the rest is not. This page sets out how I plan to build issue #203, written before the code so the approach can be checked first. Comments on the issue are welcome. The open decisions are in section 10.

The request, from issue #203 (raised by @Dr4inder):

"The current assessment assumes public domain registration and public web/mail policy ... For a host used only for an internal application, those checks do not describe its intended operation."

In plain words

Domains was built for public names: it checks the registration, the email-security records and the website certificate, and gives an A+ to F grade. Add an internal name - an intranet, an internal application - and it is graded F for lacking public things it was never meant to have. Worse, some of its lookups send the name outside: to Google's DNS service, to the domain registries, and to crt.sh.

This design adds an Internal setting to a domain. An internal domain:

1. Never leaves the network. No public DNS, no registry lookup, no Certificate Transparency, no look-alike scan - not even as a fallback.
2. Skips what does not apply. Registration, renewal and email security show as not applicable, not as failures.
3. Is checked for what matters inside: does each name resolve, and is the HTTPS certificate on each endpoint (any port) valid, trusted and in date.
4. Gets a health status, not a grade. Healthy, a problem, not checked, or stale - never a pass made up from checks that did not run.

It is built in slices. Slice 0 shipped in 4.0. The rest are proposals, smallest first.

---

1. What Domains does today

	Today
DNS	domainDns() - the server's resolver, or Google / Cloudflare DNS-over-HTTPS. Automatic is DoH on Windows. With the server's resolver, a lookup it cannot answer falls back to Google, and DS / DNSKEY always go to Google.
Registration	RDAP via IANA's bootstrap file, then the registry - includes/domains/lookup.php
Certificates	domainTlsCertificate(host, 443) on the domain, www. and the ssl_hosts list. Port 443 only. The connection resolves the name through the operating system - not through domainDns() - so DNS checks and the certificate check can see different answers. Validation uses the server's CA bundle (SSL_CA_BUNDLE).
Watches	Certificate Transparency (crt.sh) and a look-alike scan - both send the name, or names built from it, to public services
Grade	A+ to F from weighted findings; withheld when DNS lookups failed (3.16.0)
Purpose	primary, secondary, email-only, campaign, defensive, parked, redirect - decides which checks weigh, not whether the name is public
Schedule	cron/domains.php hourly: registry weekly, checks daily, watches weekly; lock, time budget, job health (#182)

The reporter's observations all hold. An internal HTTPS name gets its certificate read correctly, then an F for missing NS, SPF and DMARC, plus a failed registry lookup.

2. Slice 0 - done in 4.0: "This server only"

Domains → Settings → Monitoring → DNS resolver → This server only - never public DNS.

• Every DNS question goes to the FreeITSM server's own resolver, and nothing else - no DoH, no fallback.
• Record types that can only be asked over DoH (DS, DNSKEY, and CAA where PHP cannot ask for it) are not asked. One information finding - "Not checked: DS" - says so, costs nothing, and does not withhold the grade.
• tests/domains-dns-failures.php proves a full check run makes no public DNS call, with a control showing the old server's own resolver does.

It is install-wide and covers DNS only. The registry lookup, the CT watch and the look-alike scan keep their own switches. Slice 1 makes all of this automatic, per domain.

3. The shape: Scope, separate from Purpose

A new per-domain field, Scope: Public (today's behaviour, and the upgrade default) or Internal.

It is deliberately not another Purpose. The reporter is right that a name should not have to pretend to be parked to stop the email checks. Purpose says what a public name is for. Scope says whether it is public at all. An internal domain has no Purpose (it does not apply), so the Purpose field is hidden.

Nothing is guessed from the name: .local, .corp or .internal do not make a domain internal. An internal subdomain of a public domain (intranet.example.com) is just a domain with Scope = Internal. The subdomain support from 3.16.0 already lets it sit beside its public parent.

4. Slice 1 - Internal scope (the core)

What an internal domain never does:

Lookup	Internal
DNS	This server's resolver only, whatever the install-wide setting - the same code as slice 0
Registry (RDAP / WHOIS)	Never asked. Registration, transfer lock, registry lock and renewal show Not applicable
Certificate Transparency watch	Never
Look-alike scan	Never
Email security (SPF, DKIM, DMARC, MTA-STS, TLS-RPT)	Not checked - Not applicable
Name servers, DNSSEC, CAA	Not checked by default - an internal host is not assumed to be a delegated zone (slice 3 can add NS / SOA as an expectation)

The rule lives in one function that every outbound path asks - domainMayLeaveNetwork($domain). The registry lookup, the watches, the on-add processing and Check now all call it, so no route out is forgotten. The tests use the same trace as slice 0 on every one of those paths, including the failure and fallback cases.

What it does check: each name it knows - the domain, plus the ssl_hosts list - resolves (A / AAAA, through this server), and its HTTPS certificate on port 443 is valid, matches the name, is trusted and is in date. That is today's certificate code, unchanged.

Health instead of a grade. The A+ to F grade is a public security score, so an internal domain does not get one. It gets a health status:

Health	Means
✅ Healthy	Every configured check ran, and passed
⚠️ Expiring	A certificate is valid but inside its warning window
❌ Problem	A confirmed problem: the name does not resolve (a real "no such name"), the certificate is expired, does not match, or is not trusted, or nothing answers on the port
❓ Not checked	A probe could not run - a resolver error, a timeout - which says nothing about the target; or there is nothing configured to check
🕒 Stale	The last successful check is older than twice its interval. Worked out when the page is read, so a stopped scheduler shows up without another run

A domain with no usable checks is Not checked, never Healthy. Unknown, skipped or stale is never shown as a pass. The last good observation is kept, with its age.

On screen: the register gains a Scope filter and a Health column. An internal domain's Overview shows its health, last check and next due time, and says plainly "Internal - registration and email checks do not apply" instead of a wall of warnings. The Security and email tab becomes Health for an internal domain.

Size: a new column, the gate function, a health calculation, and the screens. Comparable to the subdomains work in 3.16.0.

5. Slice 2 - HTTPS endpoints and internal trust

Endpoints. A Monitoring tab on an internal domain lists the endpoints to check: host, port (8443 is as good as 443), certificate warning window, and trust profile. The endpoint's full identity - host and port - is kept everywhere, in certificates and history. A host is not required to have an apex or www record.

Same perspective for DNS and the connection. The endpoint's address is looked up through this server's resolver (domainDns, system only), and the connection goes to that address, with the host name still used for SNI and for checking the certificate's name. So the DNS check and the certificate check can never quietly look at two different machines. Today they can.

Trust profiles. Most internal certificates are issued by the organisation's own certificate authority. Under Domains → Settings → Monitoring, an administrator adds a trust profile: a name and the CA certificate(s), pasted as PEM. An endpoint uses the server's normal CA bundle, or a profile. Validation is never switched off. "Internal" is not permission to accept any certificate; an untrusted chain is a Problem, reported as untrusted, separately from expired and wrong name.

Which addresses may be probed. Slice 2 is the first time FreeITSM connects to addresses an administrator types in, so it must not become a tool for scanning the network:

• Endpoints, trust profiles and the limits below are administrator-only (a new capability, domains.internal). Read-only users and everyday Domains users can see results, not change or run checks.
• Permitted networks (CIDR ranges, IPv4 and IPv6) and permitted ports, set under Settings, are checked against the resolved address, not the typed name, at every connection, and a name that resolves somewhere else is refused.
• No redirects are followed by the certificate check. The slice 3 HTTP check follows none either, unless the target is also permitted.

6. Slice 3 - expected records, split DNS, and an HTTP check

Expected records. For each name, the record types expected - A / AAAA and CNAME to start, NS / SOA where the name is a zone - each with optional expected values. Sets are compared sorted and normalised, so order alone is never a change. A different address is reported only when the domain asks for it (many internal addresses are dynamic).

Split DNS. One domain record can have two perspectives: the public one (today's checks and grade) and the internal one (health). Each keeps its own findings, baselines and timestamps. The internal result never replaces the public grade, or the other way round. This needs perspective added to findings, history and certificates, which is the biggest data-model change in the design, and why it comes last.

HTTP check (optional). For an endpoint, a path and the expected status codes: "the web application answers", beyond "the TLS handshake works". No logins, no page-content scripting. The reporter suggests it can ship separately, and it can.

7. Scheduling, history and alerts

• One scheduler. cron/domains.php gains an internal-checks step with its own interval (from 15 minutes to a day, default hourly), inside the existing lock and time budget, recorded in Background jobs (#182). "The probe ran and found the target down" is a check result. "The job could not run the probe" is a job failure. Neither is confused with the other.
• History records each change of health and each certificate change, labelled by host:port. Changing an endpoint never rewrites earlier observations.
• Alerts reuse the existing deduplication and owner notifications. Workflow gets the same domain events. The Watchtower Domains card counts internal problems and stale checks.
• Service Status and incidents: suggest, never act. An internal failure can suggest the linked services, but does not raise an incident, publish an outage, or close one because later data is missing - unless a later, explicit setting says so.

8. REST API

Additive. Scope, health and endpoints appear on the domain resource, and endpoints and trust profiles get their own routes, all through the same DomainsService validation, company scope and audit as the screens. Documented in the OpenAPI contract. Existing fields and behaviour do not change for public domains.

9. The issue's acceptance criteria

#	Criterion	Where
1	An internal target can be healthy without registration, SPF / DMARC, www or CT	Slice 1 - not applicable, health not grade
2	Internal names never leave the configured context, including failure and fallback	Slice 0 (DNS) and slice 1 (domainMayLeaveNetwork, traced on every path)
3	Split DNS, ports and trust stay distinct; a changed profile does not rewrite history	Slices 2 and 3
4	Negative answers, probe errors and stale results stay distinguishable	Slice 1 - the five health states, across UI, API and notifications
5	Public records and APIs unchanged until opted in; REST through the same service	Scope defaults to Public; section 8
6	Administrator-controlled targets, networks, ports, trust; resolved-address and redirect limits	Slice 2
7	Runs from the FreeITSM server, no agent	Throughout - no new service

10. Open decisions

1. Scope per domain, or per host? This design puts it on the domain, with internal subdomains as their own domains. Per-host Scope inside one domain is split DNS (slice 3) by another name.
2. Should an internal domain count in the register's grade summary? Proposed: no. It appears under health instead, so an F-free dashboard is not padded by names that were never graded.
3. Trust profiles: Domains only, or install-wide? Proposed: Domains only to start. Other integrations already have their own CA handling.
4. Default interval for internal checks: hourly is proposed.

11. Order to build

1. ✅ Slice 0 - This server only (4.0).
2. Slice 1 - Scope, the gate on every outbound path, health, the screens. The core, and useful on its own.
3. Slice 2 - endpoints with ports, trust profiles, the network and port limits.
4. Slice 3 - expected records, split DNS, then the HTTP check.

Each slice ships with its own tests, and a write-up for the issue.

12. Deliberately out of scope

As the issue says: AD replication monitoring, DNS zone editing, network discovery, logins or page scripting in the HTTP check, and any agent or collector.

Related pages

• Domains - the module, and Keeping internal names inside
• Domains - Developer Guide
• A failed DNS lookup was reported as a missing record - why "could not ask" is never "missing"
• Background jobs