DOCUMENTATION

Getting Started with CertMon

CertMon eliminates the friction of local HTTPS by automating the CA, Keychain trust, DNS resolution, and reverse proxying into a single native macOS app.

1. First Launch & Setup

When you launch CertMon for the first time, it performs a 3-step initialization:

1. Generates a Local Root CA: Creates a dedicated P-256 (ECDSA) Root Certificate Authority. The private key is placed securely in your macOS Login Keychain (com.suresk.certmon.ca.key) with strict access controls. It is never stored on disk in plaintext.
2. Installs Keychain Trust: macOS presents a one-time dialog asking for your login password to trust the Root CA in your user domain (SecTrustSettingsSetTrustSettings). No system-wide root certificate modifications are needed.
3. Installs the Privileged Helper: CertMon prompts to install a minimal launchd daemon (com.suresk.certmon.helper) in /Library/PrivilegedHelperTools/. This daemon allows forwarding incoming port 443 traffic to CertMon and writes the macOS resolver configuration at /etc/resolver/test.

2. How .test Domain Resolution Works

macOS supports per-domain DNS resolvers through the /etc/resolver/ directory. CertMon creates a file at /etc/resolver/test containing:

nameserver 127.0.0.1
port 2053

CertMon runs a lightweight, non-blocking UDP DNS responder on 127.0.0.1:2053. When any application or browser requests anyhost.test, macOS forwards the query to CertMon, which answers with 127.0.0.1.

If /etc/resolver is unavailable on your system, CertMon automatically maintains a managed block in /etc/hosts as an automatic fallback:

# BEGIN CERTMON MANAGED SITES
127.0.0.1 api.shop.test
127.0.0.1 web.shop.test
# END CERTMON MANAGED SITES

3. Adding Sites & Path-Based Routing

To expose a dev server over HTTPS:

1. Click the CertMon menu bar icon and select Open Dashboard (or press ⌘O).
2. Click + Add Site.
3. Enter a hostname (e.g. api.myapp.test) and target port (e.g. 8080).
4. Click Save Site. CertMon instantly issues an X.509 certificate signed by your local CA and activates reverse proxy routing.

Path-Based Routing

You can route specific paths on the same domain to different local ports. For example:

• myapp.test/ → localhost:3000 (Next.js frontend)
• myapp.test/api → localhost:8080 (Go / Rails API backend)
• myapp.test/ws → localhost:4000 (WebSocket real-time server)

4. Auto-Discovery

CertMon uses low-overhead kernel socket inspection via libproc to scan for listening TCP sockets on your Mac. When a new local development server starts (such as Vite on 5173, Next.js on 3000, Rails on 3000, or FastAPI on 8000), CertMon identifies the process name, working directory, and Git repository branch.

A notification appears in the menu bar popover offering a 1-click + Add Site button pre-filled with the project directory name (e.g. https://myproject.test).

5. Testing on Real iOS & Android Devices

To test local HTTPS sites on a real physical iPhone or iPad over Wi-Fi:

1. In CertMon, navigate to the Trust & Devices tab.
2. Click Export iOS Profile (.mobileconfig) and AirDrop or email the file to your device.
3. On your iOS device, open Settings → Profile Downloaded and tap Install.
4. Open Settings → General → About → Certificate Trust Settings.
5. Under "Enable full trust for root certificates", toggle on CertMon Local Root CA.
6. Turn on LAN Mode in CertMon's settings so devices on your network can reach your Mac, and turn it off when you are done: while it is on, anyone on that network can reach every site listed in CertMon.
7. The device also has to resolve your .test name to your Mac's address. CertMon sets that up on your Mac only; on the device it is up to your network or a DNS override for now.

Android

In CertMon, click Export CA Certificate (.crt), transfer it to your Android device, and install it via Settings → Security → Encryption & Credentials → Install a certificate → CA certificate.

6. Firefox Configuration

Firefox keeps its own certificate store, but since Firefox 120 it also trusts root certificates you have added to macOS by default. That includes roots trusted only for your account in the login keychain, which is how CertMon trusts its root. The setting is "Allow Firefox to automatically trust third-party root certificates you install" under Settings → Privacy & Security → Certificates (security.enterprise_roots.enabled in about:config). If Firefox still shows a certificate error:

1. Check that the setting is on. On a managed Mac, a policy can switch it off.
2. Quit Firefox with Command-Q and open it again. It reads the Mac's roots when it starts.
3. Or import the root directly: click Export CA Certificate (.crt) in CertMon, then in Firefox open Settings → Privacy & Security → Certificates → View Certificates → Authorities, click Import, and tick "Trust this CA to identify websites".

7. Exporting Certificates & Snippets

Some tools (like custom Docker containers or standalone Node.js servers) require certificate and private key files directly. In the Export Config tab, you can export PEM files:

• site.crt: Leaf certificate with full chain.
• site.key: Decrypted PKCS#8 private key.

CertMon also generates ready-to-paste configuration snippets for Vite, Next.js, Rails Puma, Express, FastAPI, Caddy, and Nginx.

8. Troubleshooting & Repair

Keychain Trust Shows Warning

If a macOS major update or Keychain rebuild clears trust settings, open the Trust & Devices tab in CertMon and click Repair Trust. CertMon will re-invoke SecTrustSettingsSetTrustSettings to restore trusted status.

Port 443 Conflict

If another application (like an old Apache or Nginx daemon) is already listening on port 443, CertMon's helper cannot bind the port. Run this in Terminal to find the conflicting PID:

sudo lsof -nP -iTCP:443 -sTCP:LISTEN

Stop or disable the conflicting service and restart CertMon.

Uninstalling the Privileged Helper

To completely remove the background helper daemon, click Uninstall Helper in CertMon's Settings tab, or run:

sudo launchctl bootout system /Library/LaunchDaemons/com.suresk.certmon.helper.plist
sudo rm -f /Library/PrivilegedHelperTools/com.suresk.certmon.helper
sudo rm -f /Library/LaunchDaemons/com.suresk.certmon.helper.plist
sudo rm -f /etc/resolver/test

9. Trial & License

The 14-day trial is unrestricted. After it ends, sites you already set up keep being served, and you can still view everything, switch sites off, delete them and repair trust. Adding or changing sites, switching a site on, turning on LAN Mode and exporting device certificates need a license.

10. Support

Have questions or feedback? Email [email protected].