diff --git a/content/agent/configuration/encrypt-communication.md b/content/agent/configuration/encrypt-communication.md
index a7cf75134..88a511c09 100644
--- a/content/agent/configuration/encrypt-communication.md
+++ b/content/agent/configuration/encrypt-communication.md
@@ -58,6 +58,96 @@ NGINX_AGENT_TLS_ENABLE=true
---
+## Certificate revocation checking (CRL/OCSP)
+
+### Overview
+Certificate revocation ensures that certificates that are compromised, mis-issued, or otherwise invalid are rejected. For NGINX Instance Manager (NIM) and NGINX Agent mTLS, you should:
+- Enforce revocation of Agent client certificates on the NIM side using Certificate Revocation Lists (CRLs).
+- Enable OCSP stapling on the NIM TLS endpoint so clients receive the server certificate's status with the TLS handshake.
+
+Current limitations:
+- NGINX does not verify client certificates via OCSP. Use CRLs to enforce revocation for client (Agent) certificates.
+- NGINX Agent does not perform OCSP/CRL checks of the server certificate. Rely on strict verification (tls.skip_verify: false), CA pinning, short‑lived certificates with automated rotation, and server-side OCSP stapling for better hygiene and monitoring.
+
+### Prerequisites
+- Accurate system time (NTP) on all nodes participating in TLS.
+- Access to CRL files from your issuing CA for Agent client certificates.
+- If enabling OCSP stapling on the NIM endpoint: allow egress from NIM to CA OCSP responders, have the full certificate chain available, and configure a DNS resolver.
+- Avoid skip_verify: true in production; it bypasses chain, name, and revocation checks.
+
+### NIM validates Agent client certificates (mTLS) using CRLs
+Place NIM behind NGINX to terminate TLS and validate Agent client certificates. Configure NGINX to require client certs and enforce revocation via CRLs:
+
+```nginx
+server {
+ listen 443 ssl;
+ server_name nim.example.com;
+
+ # Server cert/key for NIM endpoint
+ ssl_certificate /etc/nginx/nim/server.crt;
+ ssl_certificate_key /etc/nginx/nim/server.key;
+
+ # Verify Agent (client) certificates
+ ssl_client_certificate /etc/nginx/nim/ca/agent-issuing-ca.pem;
+ ssl_verify_client on; # require client certs
+ ssl_verify_depth 2;
+
+ # Enforce revocation of client certs via CRL
+ ssl_crl /etc/nginx/nim/ca/agent-issuing-ca.crl.pem; # PEM-encoded CRL
+
+ # Harden server-side presentation to clients (see next section)
+ ssl_stapling on;
+ ssl_stapling_verify on;
+ ssl_trusted_certificate /etc/nginx/nim/ca/fullchain.pem; # for OCSP responder trust
+ resolver 1.1.1.1 8.8.8.8 valid=300s;
+ resolver_timeout 5s;
+
+ location / {
+ proxy_pass http://nim-backend:8035; # adjust to your NIM service
+ }
+}
+```
+
+Notes:
+- Convert DER CRLs to PEM if needed: openssl crl -in ca.crl -inform DER -out ca.crl.pem -outform PEM
+- Update CRLs regularly according to your CA's publishing schedule and reload NGINX. Stale CRLs may allow revoked certs.
+- Keep CRLs small/manageable by issuing Agent certs from an intermediate CA dedicated to Agents.
+- NGINX does not perform OCSP checks for client certificates; use ssl_crl for mTLS client revocation enforcement. Ensure the CRL corresponds to the issuing CA for Agent certificates.
+
+### Agent validates the NIM server certificate (client-side)
+- Keep tls.skip_verify set to false (default) so hostname and chain validation are enforced.
+- Pin your issuing CA by setting tls.ca to a minimal bundle that includes only the CA(s) that issue the NIM server certificate. Avoid broad system bundles.
+- Prefer short-lived server certificates and automate rotation; promptly revoke compromised certs.
+- Enable OCSP stapling on the NIM TLS endpoint (as above). The Agent does not itself validate OCSP/CRL, but stapling improves overall security posture and observability.
+
+Agent configuration recap:
+
+```bash
+tls:
+ enable: true
+ cert: "/path/to/agent-cert.pem" # if mTLS
+ key: "/path/to/agent-key.pem" # if mTLS
+ ca: "/etc/pki/org-ca/issuing-ca.pem" # pin your issuing CA
+ skip_verify: false
+```
+
+### Cautions
+- Setting skip_verify: true disables hostname and chain checks and can lead to trusting revoked/forged server certificates.
+- Stale or missing CRLs mean revoked Agent client certificates may still be accepted. Automate CRL refresh and nginx reload.
+- Treat OCSP stapling failures as an operational alert; monitor error logs for ocsp errors and investigate promptly.
+
+### Verification
+- Verify OCSP stapling from the NIM endpoint:
+ openssl s_client -connect nim.example.com:443 -status -servername nim.example.com | grep -A3 "OCSP response"
+- Verify a revoked Agent client certificate is rejected (expect TLS handshake failure and a 400/495 status at the edge): attempt client auth with a revoked cert and confirm access is denied.
+
+See also:
+- Enabling mTLS (above) for how to enable TLS/mTLS on the Agent.
+- Secure Traffic with Certificates for key/cert generation and configuration guidance: https://docs.nginx.com/nginx-instance-manager/system-configuration/secure-traffic/
+- Insecure Mode (Not Recommended) (below) for the risks of disabling TLS verification.
+
+---
+
## Enabling Server-Side TLS
To enable server-side TLS you must have TLS enabled. See the following examples for how to set these values using a configuration file, CLI flags, or environment variables.
diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md
index 15009d21f..f79cd75d9 100644
--- a/content/includes/agent/installation/install-agent-api.md
+++ b/content/includes/agent/installation/install-agent-api.md
@@ -6,6 +6,14 @@ files:
{{}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{}}
+Before installing, you can validate the NGINX Instance Manager endpoint and its revocation status:
+
+```bash
+openssl s_client -connect :443 -servername -status | grep -E "Verify return code|OCSP response"
+```
+
+Note: OCSP status output appears only if the server staples OCSP. Absence of a stapled status is not itself an error, but you should address stapling and revocation checking as described in [Certificate revocation checking (CRL/OCSP)](https://docs.nginx.com/nginx-instance-manager/system-configuration/secure-traffic/#certificate-revocation-checking-crl-ocsp).
+
If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands:
{{}}
@@ -24,6 +32,8 @@ If your NGINX Instance Manager host doesn't use valid TLS certificates, you can
curl --insecure https:///install/nginx-agent | sudo sh
```
+{{}}Caution: The --insecure flag disables certificate validation and certificate revocation checks (CRL/OCSP). Do not use this in production. Instead, use trusted CA bundles and, where possible, pin the issuing CA certificate rather than relying on broad system CA stores.{{}}
+
To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag:
```shell
@@ -46,6 +56,8 @@ chmod u+x install.sh
sudo ./install.sh --skip-verify false
```
+This enforces hostname and full certificate chain validation. For guidance on enforcing certificate revocation checking (CRL/OCSP) to avoid accepting revoked certificates—and on using trusted CA bundles or pinning the issuing CA—see [Certificate revocation checking (CRL/OCSP)](https://docs.nginx.com/nginx-instance-manager/system-configuration/secure-traffic/#certificate-revocation-checking-crl-ocsp).
+
{{%/tab%}}
{{%tab name="wget"%}}
@@ -62,6 +74,8 @@ sudo ./install.sh --skip-verify false
wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh
```
+{{}}Caution: The --no-check-certificate flag disables certificate validation and certificate revocation checks (CRL/OCSP). Do not use this in production. Instead, use trusted CA bundles and, where possible, pin the issuing CA certificate rather than relying on broad system CA stores.{{}}
+
To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag:
```shell
diff --git a/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md b/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md
index 68da7ec26..2fc7b4d85 100644
--- a/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md
+++ b/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md
@@ -14,6 +14,8 @@ docs:
{{}}If you use self-signed certificates in your NGINX Instance Manager environment, follow the steps in [Configure SSL verification for usage reporting with self-signed certificates]({{< ref "nim/system-configuration/secure-traffic.md#configure-ssl-verify" >}}).{{}}
+ {{}}The `usage_report` connection is an outbound HTTPS client from NGINX to NGINX Instance Manager. Ensure the NIM endpoint presents a valid, non-revoked server certificate issued by a trusted CA. For production, avoid self-signed certificates; if you must use a private CA or self-signed certificate, import the issuing CA into the NGINX host's trust store and use short-lived server certificates with automated rotation. If your security policy requires active revocation checks, front NGINX Instance Manager with an NGINX server that staples OCSP (`ssl_stapling on;` `ssl_stapling_verify on;`) so monitoring can detect issues quickly. CRL/OCSP configuration for the `usage_report` HTTPS client is not exposed here; see [Certificate revocation checking (CRL/OCSP)]({{< ref "nim/system-configuration/secure-traffic.md#certificate-revocation-checking-crl-ocsp" >}}) for server-side hardening and operational guidance.{{}}
+
3. Reload NGINX:
``` bash