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 RSA-4096 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. Ensure your Mac and phone are on the same Wi-Fi network. Scan the QR code in CertMon to open the local LAN address directly in Safari.

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

Unlike Safari and Chrome, Firefox does not check the macOS Keychain by default; it uses its own bundled Mozilla trust store. To allow Firefox to trust your macOS Keychain root certificates:

1. Open Firefox and type about:config in the address bar.
2. Search for security.enterprise_roots.enabled.
3. Double-click to set it to true.

Firefox will immediately trust CertMon's certificates with no restart required.

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 Keychain 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. Support

Have questions or feedback? Email [email protected].