TrustView Documentation
1. Certificate Discovery¶
TrustView is able to automatically discover and start monitoring SSL endpoints
in your network - both internal and external endpoints. TrustView supports a number of mechanisms for this,
such as network scan, DNS zone transfer, domain- and AD scanning, and discovering certificates already stored
in an Azure Key Vault - see Azure Key Vault below. When configured,
all the scans are executed periodically on a daily basis and will add all new SSL endpoints found.
Each of these can also be triggered manually at any time, using the Scan now button on its edit page,
instead of waiting for the next scheduled run.
If the SSL endpoints found have any SSL certificates deployed, TrustView will automatically import them and begin to monitor them all by default.
Tip
This behavior can be changed in the Settings menu, if needed.
If a certificate can’t be found by any of these automatic methods, it can also be added manually - see Manually adding a certificate below.
1.1. Manually adding a certificate¶
If TrustView cannot reach a certificate directly - for example because the service using it sits behind a firewall, or it isn’t otherwise exposed on the network - it can be added manually for monitoring, instead of waiting for a discovery method to find it.
Click Other certificates in the left menu, then Add. Paste the PEM-encoded certificate (the -----BEGIN CERTIFICATE----- header and footer are optional) or upload the certificate file, add a name and an optional comment, then save.
Once added, TrustView monitors its expiry the same way it does for any other monitored certificate, including sending expiry notifications.
1.2. Network scan¶
TrustView can scan your network for services exposed using SSL/TLS, such as HTTPS, LDAPS and IMAPS.
To configure a network scan, click SSL network scanning in the left menu and add a new SSL network scan.
The information required is listed in the following table:
Parameter |
Description |
Examples |
|---|---|---|
Target specification
|
IP range to scan |
192.168.0.0/24
10.0-4.0.0/16
|
Port range |
TCP ports to scan for
SSL for each IP in the
IP range
|
443
1-1000
443,636,1443,8443
|
Comment |
Any comment |
When saved, the SSL network scan will execute periodically on a daily basis.
Tip
If TrustView has a large backlog of scans and network scans in particular seem to wait a long time to run, see Limit how many scan jobs run concurrently in Maintenance.
Selecting one or more network scans from the list enables bulk Scan now, bulk comment and bulk Delete.
1.2.1. Bulk add network scans¶
Go to SSL network scanning Bulk Add.
To add one or more network scans you can add one entry per line, following a syntax:
IP Range;Port Range;Scan Agent
So an example could look like this:
1192.168.0.0/24;1-1000;local
2192.168.10.10/25;443;cloudscan
3192.168.10.12/24;443,636
Important
If you don’t specify a Scan Agent it will automatically default to local.
1.2.2. Bulk-create SSL endpoints from other sources¶
In addition to bulk-adding network scans, SSL endpoints can also be bulk-created directly from two other sources, both found under SSL endpoints Bulk create.
1.2.2.1. From a network scan file¶
Upload the result of an nmap port scan (an nmap XML output file). TrustView lists the hosts and ports found in the file that aren’t already monitored, so hostnames or IPs can be selected and added as SSL endpoints in bulk.
1.2.2.2. By subdomain lookup¶
Enter a domain name and TrustView looks up its subdomains and checks each one for an SSL certificate, then lists any matches so they can be added as SSL endpoints in bulk, the same way as with an uploaded scan file.
1.2.2.3. By pasting a list of hosts¶
Paste a plain list of hosts, one per line (optionally prefixed with http:// or https://), and TrustView
checks each one for an SSL certificate on port 443, then lists any matches so they can be added as SSL endpoints
in bulk, the same way as with the other two methods above.
Tip
Creating an SSL endpoint normally adds an entry to its event log. When bulk-creating a large number of SSL
endpoints at once, setting disableEndpointCreationLogging = true in TrustView.groovy skips that log
entry, to avoid a flood of near-identical creation events. This applies to every monitored object TrustView
creates, not only SSL endpoints added this way.
1.3. DNS zone transfers¶
DNS zone transfers in the left menu and add a newParameter |
Description |
Examples |
|---|---|---|
DNS host |
Hostname or IP of
your DNS
|
192.168.0.1
dns.example.org |
Zones |
List of zones to transfer |
|
Comment |
Any comment |
When saved, the DNS zone transfer will execute periodically on a daily basis.
1.4. Domain scanning¶
Domain scans use domain registrant (Whois) information to discover the top-level private domains that you own. For each domain you own, the domain scan feature will obtain a list of hosts for this domain using a TrustView backend-service hosted by Cryptomathic. This set of SSL endpoint candidates will be scanned. If TrustView is able to detect any SSL/TLS-enabled services on the host during the scan, TrustView will start monitoring the services found.
All domains (if any) will be scanned periodically on a daily basis.
Important
This discovery method requires access to the backend of Cryptomathic to work.
Selecting one or more domains from the list enables bulk Activate, Deactivate and Delete buttons.
There are also two owner-based bulk actions, which act on every domain sharing the same Whois owner details as
a selected domain, without needing to select each one individually: Deactivate all with this owner and
Delete all with this owner.
Danger
Deactivating or deleting a domain (individually or via a bulk/owner-based action) also deletes all SSL endpoints that were discovered from it, along with its CT domain monitoring entry.
1.5. Endpoint candidate port scanning¶
Beyond the discovery methods above, TrustView also periodically re-examines the hosts behind already-monitored SSL endpoints, as well as the SSL endpoint candidates found by a domain scan, for additional open SSL/TLS ports - not only the one an SSL endpoint is already monitored on. Any newly found port is added and monitored as its own SSL endpoint.
The range of ports probed during this re-examination is controlled by endpointCandidatePortRange in
TrustView.groovy, and defaults to 1-65535 (every port).
1 endpointCandidatePortRange = "443,8443-8450"
Tip
Set endpointCandidatePortRange = "-1" to disable this re-examination entirely.
1.6. Certificate Transparency (CT) domain monitoring¶
Certificate Transparency (CT) is a public log of every certificate issued by a participating CA. TrustView can watch these logs for your domains and notify you whenever a new certificate is issued for one - a useful way to detect certificates issued without your knowledge, for example by a compromised CA account or a rogue subdomain.
Every domain added under Domain scanning above is automatically registered for CT log monitoring by default - no separate setup is required. Registration, and the CT log check itself, run on their own periodic schedule (roughly every 17 hours) independently of the domain scan’s own daily run, so a newly domain-scanned domain can take up to that long to show up here.
Important
Certificate Transparency (CT) domain monitoring also requires access to the backend of Cryptomathic, and a TrustView API key registered for the user group (see API) - without one, nothing is retrieved and no error is shown, so a missing API key can go unnoticed.
Removing or disabling a Domain Scan also disables the CT monitoring entry that was automatically created for it - a domain added directly under CT domain monitoring (not from a domain scan) is unaffected by domain scan changes.
The CT domain monitoring menu item itself can be hidden per user under My settings Disabled functionality, by checking Certificate transparency logs - see Disable functionality. This only hides the menu item for that user though - it doesn’t stop domains being registered or monitored, and doesn’t stop the notification e-mails; to stop those, disable the notification separately under My settings Additional notification settings (see Notifications).
A domain can also be added for CT monitoring directly, without setting up a domain scan for it, by clicking CT domain monitoring in the left menu, then Add.
Opening a monitored domain’s detail page shows every certificate Certificate Transparency has found for it, each of which can be downloaded individually, plus an event log for the domain.
Tip
See Notifications for details on the e-mails sent when a new certificate is logged for a monitored domain.
1.7. Active Directory SSL endpoint discovery¶
TrustView can periodically search your Active Directory for relevant entries (typically servers) and
add any SSL/TLS-enabled services found on the servers as SSL endpoints. To configure Active Directory SSL
endpoint discovery, click Active Directory SSL endpoint discovery in the left menu and add a new AD scan.
The information required is listed in the following table:
Parameter |
Description |
Examples |
|---|---|---|
AD username |
Username to bind to
your AD. No special
permissions are
required
|
|
AD user password |
Password of the AD
user used to bind
|
|
Domain controller |
Hostname of the domain
controller to bind to
|
|
LDAP port |
TCP port to connect to |
389 |
Searchbase |
Location of the part of
the AD structure to
search in
|
ou=Servers,ou=Computers,dc=example,dc=org |
Search the DNS zone
for the domain
|
TrustView will attempt
to extract DNS zone
information from your
AD if ticked
|
|
Comments |
Any comment |
When saved, the AD scan will execute periodically on a daily basis.
1.8. Azure Key Vault¶
TrustView can also discover certificates, keys and secrets that already exist in a Microsoft Azure Key Vault, once an Azure integration has been configured - the same integration also used to deploy issued certificates to a Key Vault via an Automation task. Each item found is listed and monitored for expiry the same way as other discovered certificates, provided it has an expiry date set in Azure; see the Azure Integration page for the full setup and its prerequisites.
1.9. Excluding hosts from discovery¶
A hostname, DNS name, IP address or CIDR range can be excluded from every discovery method on this page -
network scans, DNS zone transfers, domain scanning, subdomain lookup and Active Directory SSL endpoint
discovery alike - by adding it to discoveryBlacklistedHosts in TrustView.groovy. A blacklisted host
is skipped by whichever discovery method would otherwise have found it; it has no effect on an SSL endpoint
that was already added before the host was blacklisted.
1 discoveryBlacklistedHosts = ["printer.example.org", "192.168.1.100", "10.20.0.0/16"]
Tip
This takes a list, so hostnames, individual IPs and CIDR ranges can all be mixed together, separated by
commas inside the [ ] brackets.
Save the file and restart the TrustView service, or reload the configuration from the Settings menu, for
the change to take effect.
1.10. Troubleshooting¶
1.10.1. AD SSL endpoint discovery fails with an SSL error¶
If Active Directory SSL endpoint discovery fails and the TrustView log shows an entry such as:
1Caught exception of type SSL Exception during AD search
the underlying cause is usually a certificate trust failure, for example:
1javax.net.ssl.SSLHandshakeException: (certificate_unknown) PKIX path building failed:
2sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
this means TrustView doesn’t trust the SSL certificate presented by the domain controller for LDAPS. Add the domain
controller’s certificate under Manage trusted certificates - this is the recommended
fix and takes effect immediately - or to the Java keystore (cacerts file) used by TrustView, as described
here, which is an older alternative that still works but requires a Tomcat restart.
See Diagnosing certificate trust errors for commands to see exactly
which certificate is missing.
Tip
Before troubleshooting manually, try Global settings AD autodetect configuration.
Given a domain user, password, domain name and searchbase, it tests connectivity and LDAP/LDAPS binds against
every discovered domain controller and reports what the AD-login configuration should look like.
1.10.2. DNS zone transfer fails¶
If a DNS zone transfer fails, the error shown will usually point to one of two causes:
NXDOMAIN- the zone specified doesn’t exist on the DNS server queried. Double-check the zone name for typos.An unresolved address error - TrustView was unable to resolve or reach the DNS host specified. Check that the hostname or IP is correct and reachable from the TrustView server.
1.10.3. Network scan reports no results¶
If a network scan references a Scan agent that has since been deleted or deactivated, the scan fails silently with no results. Check that the Scan Agent selected for the network scan (or specified in a bulk-add entry) still exists and is active under Scan Agents.