Troubleshooting

Use this section to troubleshoot issues with your Puppet Comply installation.

Reset your Comply password

If you forget your password, you can reset it in the user admin console.

  1. SSH into your Comply node and run the following commands to retrieve the admin username and password: 
    kubectl exec $(kubectl get pod -l app.kubernetes.io/name=comply-auth -o jsonpath="{.items[0].metadata.name}") -- /bin/bash -c 'env | grep KEYCLOAK_ADMIN='
    kubectl exec $(kubectl get pod -l app.kubernetes.io/name=comply-auth -o jsonpath="{.items[0].metadata.name}") -- /bin/bash -c 'env | grep KEYCLOAK_ADMIN_PASSWORD='
  2. Navigate to https://<COMPLY-HOSTNAME>/auth/admin using the FQDN of your Comply node.
  3. Login using the credentials from step 1.
  4. Select Puppet Realm from the dropdown menu.
  5. Navigate to Users.
  6. Use an asterisk(*) as a search term to show all users and select the user account you want to update.
  7. Click Edit to edit the selected user account.
  8. Select the Credentials tab and then reset the password.

Access logs

If you run into issues with Puppet Comply, you can download the relevant log files. The Comply logs are stored in Puppet Application Manager.

  1. Log into Puppet Application Manager — https://<PUPPET-APPLICATION-MANAGER-ADDRESS>:8800.
  2. Select the Troubleshoot tab, and click Analyse Comply.
  3. Download the bundle of log files.

Resolve the Comply domain

If the Puppet Comply gatekeeper is unable to resolve the Comply domain, try the following troubleshooting steps.

When you assign a hostname to Comply, it needs to be resolved by the pods in your Kubernetes cluster. A preflight check verifies the domain you specified in the configuration is resolvable. You must ensure that the nodes can resolve their own hostnames, through either local host mapping or a reachable DNS server.
  1. To verify your whether your hostname is resolvable, run the following commands: 
    kubectl exec $(kubectl get pod -l app=kotsadm -o jsonpath="{.items[0].metadata.name}") -- /bin/sh -c 'curl --SI <hostname>'
    If the hostname was resolved, the command returns an exit code 0 with no output.
    If the hostname cannot be resolved, the command returns an exit code 6. Proceed to step 2 to add DNS entries.
  2. To add DNS entries for CoreDNS, run the following command to open the CoreDNS configuration maps: 
    kubectl -n kube-system edit configmaps coredns
  3. Add a hosts entry below kubernetes. This is where you configure the DNS entry for Comply. For example: 
    kubernetes cluster.local in-addr.arpa ip6.arpa {
   pods insecure
   fallthrough in-addr.arpa ip6.arpa
   ttl 30
}
hosts {
  10.23.24.25 comply.mycompany.net comply // IP_address canonical_hostname [aliases...]
  fallthrough
}
prometheus :9153
  4. Run the command from step 1 to verify whether the DNS entry was updated: 
    kubectl exec $(kubectl get pod -l app=kotsadm -o jsonpath="{.items[0].metadata.name}") -- /bin/sh -c 'curl --SI <hostname>'
  5. Re-run the preflight checks.

Resolve a failed assessor upgrade

If an upgrade of the assessor has failed on one of your nodes, try the following troubleshooting step.

If the upgrade of an assessor on a node fails, the node is marked in red on the Inventory page. Failures may be due to network issues. If that is the case, Comply attempts to upgrade the node once connectivity returns. An hourly background task runs to check if nodes have been upgraded or not. If a node does not upgrade and remains red on the Inventory page, run the Puppet agent. If the upgrade continues to fail, see the Puppet agent logs for more information.

Resolve a failed scan

If an inappropriate version of Java Runtime Environment (JRE) is installed on the host system where the CIS-CAT Pro Assessor resides, you might see an error message about a failed scan.

The error message is similar to the following example:
Error: Scan did not complete successfully 'java _Server -b 
/opt/puppetlabs/comply/Assessor-CLI/benchmarks/CIS_Red_Hat_Enterprise_Linux_7_Benchmark_v3.1.1-xccdf.xml -D 
ciscat.license.filepath=/opt/puppetlabs/comply/Assessor-CLI/license/license.xml', 'Exception in thread "main" 
java.lang.UnsupportedClassVersionError: org/cisecurity/assessor/cli/Assessor : Unsupported major.minor version 52.0 at
 java.lang.ClassLoader.defineClass1(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:808) at 
java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142) at 
java.net.URLClassLoader.defineClass(URLClassLoader.java:443) at 
java.net.URLClassLoader.access$100(URLClassLoader.java:65) at java.net.URLClassLoader$1.run(URLClassLoader.java:355) 
at java.net.URLClassLoader$1.run(URLClassLoader.java:349) at java.security.AccessController.doPrivileged(Native Method) 
at java.net.URLClassLoader.findClass(URLClassLoader.java:348) at java.lang.ClassLoader.loadClass(ClassLoader.java:430) 
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:326) at 
java.lang.ClassLoader.loadClass(ClassLoader.java:363) at 
sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:482)

N.B. The java.lang.UnsupportedClassVersionError: org/cisecurity/assessor/cli/Assessor : Unsupported major.minor version 
52.0
To resolve the issue, ensure that JRE v1.8 or later is installed. For the latest information about JRE requirements, see the CIS-CAT Pro Assessor Configuration Guide.

Troubleshooting TLS issues in Comply

Incorrect configuration of TLS certificates when setting up Comply to work with PE can cause agents and/or scan tasks to fail.

There are two main certificate configuration errors that cause problems:

  • If the CA certificate configured for Comply in Puppet Application Manager does not match the CA certificate the Puppet Enterprise certificate is signed with, then a trust store issue is returned upon setting up PE or trying to run a scan.
  • A hostname issue can arise if a server identity check does not pass. The dnsName in the subjectAltName of the server certificate must match the hostname Comply is communicating with. The hostname configured in the Comply settings page for Puppet Enterprise must match one of the dnsName entries in the PE certificate.

Troubleshooting agent issues

Agents can fail if the certificate is configured incorrectly in two ways:

  • The hostname could be the issue - the Comply TLS certificate must have the dnsName with which the agent is trying to contact the Comply server. This is relevant only if you set up the Comply module to download the assessor from the Comply server. The hostname the Comply server is contacted with is the hostname in the configured scanner_source parameter URL.
  • The trust store may also be the problem if the Comply server TLS certificate and the client certificate are not signed by the same CA.

Troubleshooting scan task issues

Scan tasks can also fail if the certificate is configured incorrectly in two ways:

  • If the hostname is incorrectly configured - The Comply TLS certificate must have the dnsName with which the agent is trying to contact the Comply server. The hostname used is passed through by the task and can be seen in the PE UI by checking the task parameters. Verify the task parameters to ensure that the hostname is correct.
  • If the Comply server TLS certificate and the client certificate are not signed by the same CA a trust store issue occurs and this too can cause the scan task to fail.

Troubleshoot TLS from a node

You can run a simple cURL command to troubleshoot TLS issues from a node.

To troubleshoot TLS from a node:

  1. SSH into a node and change to the SSL subdirectory: 
    cd /etc/puppetlabs/puppet/ssl/
  2. Issue the following cURL command replacing values in angle brackets with values relevant to your installation: 
    curl -G --key private_keys/<local host key> --cacert certs/ca.pem --cert ../certs/<local host cert> https://<comply-fqdn>:30303/assessor --output /tmp/assessor.zip
    Note: If you are using your own ingress, issue the following command:
    curl -G --key private_keys/<local host key> --cacert certs/ca.pem --cert ../certs/<local host cert> https://<PE TLS hostname>/assessor --output /tmp/assessor.zip

    If this command fails, there is an issue with certificates. The error message can help to identify if there is a CA, client certificate or hostname issue.

    • If there is a hostname error, the output resembles the following error message:
      curl: (60) SSL: no alternative certificate subject name matches target host name '<comply-fqdn>'
    • If it is a CA issue, the output is likely to be similar to the example below:
      curl: (60) SSL certificate problem: unable to get local issuer certificate
      Important: This may be because the CA of the https://<comply-fqdn>:30303/assessor (or https://<PE TLS hostname>/assessor) does not match the CA passed to the cURL command or because there is a mismatch with the CA of the client certificate.