Trusting the inspection CA

To inspect TLS traffic, the collector terminates each connection with a certificate it signs on the fly. For clients to accept that without warnings, they must trust the collector's CA. This is the one deployment step that touches devices — and the most common source of onboarding trouble — so it's worth doing carefully and first.

Where the CA is — and isn't — needed

The CA covers the proxy (mitm) lane: browsers, desktop apps, and hosts configured with HTTPS_PROXY (the agent-host script path). On devices running Kilasec Connect, terminal AI tools (CLIs / SDKs honoring ANTHROPIC_BASE_URL / OPENAI_BASE_URL) ride the client's CA-free AI gateway instead — no cert in any trust store, no forged TLS — so a CA-trust gap in some SDK's private bundle no longer silently breaks or bypasses inspection for those tools. The Connect installer still trusts the CA for browser coverage. See Remote devices.

Where you do this: Two surfaces.

• In the cloud dashboard — Collectors → your collector → step 2, "Trust the CA cert" — download the cert (.pem / .cer / .mobileconfig) or the fleet bundle. Requires the tenant_admin role.
• On client devices — pushed by your MDM / GPO / Jamf / Intune, or run the kilasec.com/trust-ca one-liner on headless Linux hosts as root. Per-platform recipes below.

What the CA is

Each collector holds its own CA — the private key stays on the collector (host-bound; a stolen copy is useless on another machine) and never leaves your network. The cert (the public half) is what clients trust. Because the key is local, you distribute the collector's public cert to clients; the fleet bundle rolls every collector's cert into one file, so you still distribute once no matter how many collectors you run.

In the dashboard → Collectors → your collector → step 2, "Trust the CA cert" — pick the format your fleet needs:

• .pem — Linux / generic.
• .cer — Windows (GPO / Intune) and anything wanting a binary root.
• .mobileconfig — an Apple Configuration Profile for Jamf / Intune that installs and trusts the cert in one payload.

The fleet bundle trusts every collector in a single file. Adding or rebuilding a collector means re-downloading the bundle and re-pushing it — an occasional MDM refresh, and no private key ever leaves your network.

Headless Linux clients (no browser, no MDM)

On the client host, as root. Agent hosts, servers, CI runners, and pods don't have a UI. Trust the CA with one command — it fetches the public cert and installs it into the system trust store:

curl -fsSL https://kilasec.com/trust-ca | sudo sh -s -- --collector <collector-id>

By default this trusts the whole fleet (so one install covers every collector); add --this-only to trust just the one. Works on Debian/Ubuntu (update-ca-certificates) and RHEL/Fedora (update-ca-trust). The cert it fetches is public — no secret is involved.

How the agent keeps the CA in place

On devices running Kilasec Connect, trusting the CA is not a one-time install step — the agent reconciles its OS trust store against the tenant bundle on every poll and installs whatever is missing, provided it has the rights (always on Windows, where it writes the per-user store; on macOS/Linux only when it runs elevated). That covers the three ways a one-shot install went stale:

• the device was still pending approval when the installer ran (the CA is only delivered after approval, so the install had nothing to install);
• the CA rotated, or a second collector joined the fleet and the bundle grew;
• the root was removed from the machine — a reimage, or a user clearing it.

Where the agent cannot install (an unelevated macOS/Linux daemon), it reports the state instead of failing quietly. Either way the verdict comes from the OS trust store, never from a file on disk:

kilasec-connect status    # "ca trust: trusted by this OS" / "NOT TRUSTED — …"
kilasec-connect doctor    # same check, in the pass/fail list

In the dashboard, a device that doesn't trust the CA carries a no CA badge on Devices, and the page header counts them. This matters more than it sounds: a device that can't decrypt produces no Live Traffic rows at all, which looks exactly like a device nobody is using.

Managed fleets: push it with MDM/GPO

For a domain-joined or MDM-managed estate, the CA belongs in a machine-wide policy (GPO → Trusted Root Certification Authorities, or an Intune/Jamf profile) — one push covers every user on every box, including users who have never signed in. Install the agent with -NoTrustCa there and let it verify and report rather than install. Per-device self-install is the BYOD / unmanaged path.

Do this on a pilot group first

Trust the CA on a handful of test machines and verify inspection works there before you route traffic for everyone. If you flip routing on before the CA is trusted, every AI call throws a certificate warning.

Distribution by platform

The mechanics are standard "add a trusted root CA" — the same thing you'd do for any inspection proxy. Use whatever fleet-management tool you already have.

Windows — Group Policy

On your Domain Controller (Group Policy Management Console).

1. Convert/keep the CA as .cer.
2. Your GPO → Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities.
3. Import the CA cert. On a test client, gpupdate /force, or wait for the refresh cycle.

Applications using the Windows cert store (Edge, Chrome, most .NET/native tools) will now trust it. Firefox and some tools use their own store — see below.

macOS — Jamf / Intune / MDM

In your MDM console.

• Package the CA in a Configuration Profile with a Certificate payload, and (importantly) set the trust setting so it's trusted for SSL.
• Push via Jamf (a Configuration Profile), Intune (Devices → Configuration → Trusted certificate profile), or your MDM of choice.
• On the client, the cert lands in the System keychain, trusted for SSL.

iOS / Android — MDM

In your MDM / EMM console.

• iOS: push the CA via an MDM Configuration Profile; on supervised devices trust is automatic, otherwise the end user enables it on the device under Settings → General → About → Certificate Trust Settings.
• Android: push via your EMM as a CA certificate for the managed profile. Note that Android app traffic only trusts user CAs if the app opts in; managed/system CA installation via EMM is the reliable path.

Linux hosts / servers

On the host, as root. Either use the kilasec.com/trust-ca one-liner above, or the manual steps:

# Debian/Ubuntu
sudo cp kilasec-ca.crt /usr/local/share/ca-certificates/kilasec.crt
sudo update-ca-certificates

# RHEL/Fedora
sudo cp kilasec-ca.crt /etc/pki/ca-trust/source/anchors/kilasec.crt
sudo update-ca-trust

Containers / CI

In the image build / CI runner setup. Bake the CA into the image's trust store (the same update-ca-certificates step) or mount it and set NODE_EXTRA_CA_CERTS / REQUESTS_CA_BUNDLE / SSL_CERT_FILE as appropriate for the runtime.

Applications with their own trust store

Some tools ignore the OS store and need the CA added directly:

• Firefox — Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import (or the security.enterprise_roots.enabled policy to honor the OS store).
• Node.js — NODE_EXTRA_CA_CERTS=/path/kilasec-ca.crt.
• Python requests — REQUESTS_CA_BUNDLE, or certifi bundle append.
• curl — --cacert or CURL_CA_BUNDLE.
• Java — import into the JVM's cacerts with keytool.

If a specific agent or SDK still fails after the OS trusts the CA, it almost always uses one of these private stores — check the tool's TLS/CA docs.

Certificate pinning

Tools that pin a certificate (some mobile apps, some SDKs) will refuse the intercepting cert no matter what you trust — that's pinning working as designed. For those destinations, Kilasec can be configured to pass through without interception (the traffic isn't decrypted, so it isn't inspected). Decide per-destination whether inspection or pass-through is the right call.

Verifying trust

On a client with the CA installed and routing applied:

curl -sS https://api.openai.com/v1/models -o /dev/null -w "%{http_code}\n"

A clean 200/401 (auth error is fine — it means TLS succeeded) confirms the CA is trusted and traffic is flowing through the collector. A certificate error means the CA isn't trusted in the store that curl/the app uses.

Rotating or removing

• To remove inspection from a device, pull the CA from its trust store and stop routing its traffic.
• Adding or rebuilding a collector produces a new local CA, so re-download the fleet bundle and re-push it (the CLI one-liner and the .mobileconfig both update in place). Existing collectors' certs are unchanged, so already-trusting clients keep working for those.