Pre-discovery phase

Release version: Zurich

Updated July 31, 2025

3 minutes to read

Summarize

Summarized using AI

Summary of Pre-discovery phase

The pre-discovery phase in ServiceNow’s certificate discovery process involves preparing and configuring parameters to ensure accurate and efficient certificate data collection. This phase sets up scanning parameters, credentials, and discovery methods to gather comprehensive certificate information from various sources before initiating the actual discovery.

Show full answer Show less

Discovery Methods

Discovery via Ports: The [tlssslcerts] port probe scans 14 default preauthorized ports typical for SSL and StartTLS protocols—such as 443, 636, 993, 25, and 587. The MID Server collects certificate chain details from these ports during the CI Discovery process and converts them into XML payloads. These payloads update the Discovered Certificate table with detailed certificate attributes, including issuer, subject, validity dates, and algorithms.
Discovery via URL: The Certificate URL table maintains target URLs for certificate discovery. Using the Discovery Schedule parameters, the [CertificateDiscoveryFromURLScan] probe retrieves certificate chains from these URLs and logs them in the Discovered Certificate table.
Discovery via Import Certificates (v1.1.7): Certificates can be imported from specified hosts and folders using the Import SSL Certificate pattern. Key parameters include host/IP, folder path, temporary MID Server folders, and a TLSkeepOriginalCertificate flag that affects payload size. Note that auto-select MID Server is unsupported for Windows/Linux combinations, requiring manual MID Server selection.
Discovery via Certificate Authority (v1.1.7): Integrating with GoDaddy, DigiCert, Entrust, or Sectigo CAs, this method uses REST API calls to retrieve certificates and store them in relevant tables. Optional parameters include API URLs and versions, with defaults provided per CA. From version 1.2.0, Sectigo and Entrust CAs are supported for scanning. Additional parameters control certificate retrieval limits, credential aliasing, and certificate status inclusion.

Key Configuration Parameters

TLSkeepOriginalCertificate: When enabled, the original certificate file is attached to the Certificate CI, which may lead to large payload sizes and potential memory issues.
Startoffset and Limit: Control the range of certificates retrieved from CAs to manage volume during discovery.
IncludeCertStatus: Allows specifying additional certificate lifecycle states beyond default ones to tailor discovery results.

Certificate Lifecycle States

Each CA returns certificates with different lifecycle states, which are normalized in the Unique Certificate table as follows:

Sectigo: Issued, Expired
DigiCert and GoDaddy: Active, Expired, Revoked, Canceled
Entrust: Active, Expired, Revoked

States like issued, valid, expired, or canceled from APIs are stored as "issued" in the Unique Certificate table to represent lifecycle status.

Next Steps

After completing the pre-discovery phase configurations and scans, proceed to the post-discovery phase for further processing and analysis of discovered certificates.

The pre-discovery phase involves preparatory steps, such as defining scanning parameters and configuring credential details, to ensure a smooth initiation of the certificate discovery process.

Discovery via Ports

The port probe [tls_ssl_certs] automatically scans 14 default preauthorized ports. The port probe [tls_ssl_certs] automatically scans 14 default preauthorized ports.

Typical ports for SSL: 443, 8443, 9443, 636 (ldaps), 993 (imaps), 995 (popssl), 989, 990
StartTLS ports: 25 (smtp), 110, 143, 389, 21, 587 (smtp)

As part of the CI Discovery process during Shazzam, the MID Server uses scanners to gather certificate chain information from the IP port number, capturing diverse attributes, including the certificate hierarchy. The MID Server then transforms these certificates into an XML payload, sharing it with the instance. The Shazzam sensor, in turn, detects the ECC queue entry and inserts a new record into the Discovered Certificate table [sn_disco_certmgmt_certificate_history].

The following fields are pulled from the XML payload and verified in java code from the Shazzam TLS port probe for discovered certificates: certificate id, revocation_status, subject, issuer, sans/, is_self_signed, is_ca, valid_from, valid_to, signature_algorithm, fingerprint_algorithm, key_size, serial_number, and version.

Discovery via URL

The Certificate URL [sn_disco_certmgmt_cert_url] table holds a list of URLs to target for certificate discovery. Each record also has an optional reference to the Unique Certificate [cmdb_ci_certificate] table, to see what certificate is related to the given URL definition. The necessary parameters from the Discovery Schedule are combined to create and initialize the Discovery status. The [CertificateDiscoveryFromURLScan] probe discovers the certificate chain for each of the URLs in the batch and outputs an XML payload that contains the certificate chain for each certificate. It also adds a new record into the Discovered Certificate [sn_disco_certmgmt_certificate_history] table.

Discovery via Import Certificates (Version 1.1.7 Certificate Inventory and Management)

The Import certificates are discovered through the Import SSL Certificate pattern, which relies on the following parameters.

Host name/IP where the certificates are hosted
Folder where certificates are located
TLS_keepOriginalCertificate: Setting this parameter to true may lead to increased payload size, potentially causing out-of-memory issues.
Mid_temp_folder: The temporary folder on the MID Server where files will be temporarily copied.

Note:

Auto-select MID Server option is NOT supported for Windows and Linux mid combinations. If the MID Server is used for storing the original certificates files, then Host name/IP should be set to blank or localhost and the particular MID Server should be selected for the Discovery schedule.

Discovery via CA authority (Version 1.1.7 Certificate Inventory and Management)

Once the Certificate Inventory and Management credential is set up with either GoDaddy, DigiCert, Entrust, or Sectigo Certificate Authority and the Discovery schedule runs, the specific CA pattern makes REST API calls to (GoDaddy, DigiCert, Entrust, or Sectigo), collects certificate information, retrieves the list of certificates, and stores it in the [cmdb_ci_certificate], [certificate_domain], and [sys_attachment] tables.

ca_api_url and ca_api_version are optional parameters. If these parameters are left empty inside pattern parameters, default values will be used. The default values include:

DigiCert - Certificate Management (ca_api_version = v2, ca_api_url = https://www.digicert.com/services/)
Entrust - Certificate Management (ca_api_version = v2, ca_api_url = https://api.entrust.net/enterprise/)
GoDaddy - Certificate Management (ca_api_version = v1, ca_api_url = https://api.godaddy.com/)
Sectigo - Certificate Management (ca_api_version = v1, ca_api_url = https://cert-manager.com/api/ssl/)

The arguments for GoDaddy, DigiCert, Entrust, and Sectigo patterns are as follows. Starting from Version 1.2.0, you have the capability to scan Sectigo and Entrust Certificate Authorities (CAs).

Start_offset: The offset position for reading certificates from CA authorities, with a default value of 0.
Limit: The number of certificates to be read from the start_offset, with a default value of 1500.
CredentialAlias: The name of the Credential Alias or Tag linked to the CA credentials, added in the serverless execution pattern configuration.
If the TLS_keepOriginalCertificate parameter is set to true, the certificate file is attached to the Certificate CI. This may increase payload size, potentially causing out-of-memory issues.

IncludeCertStatus: A parameter for specifying additional certificate states to discover, in addition to the defaults.

Table 1. Certificate states by certificate authorities
Certificate Authority	Default States Discovered
Sectigo	Issued Expired
DigiCert and GoDaddy	Active Expired Revoked Canceled
Entrust	Active Expired Revoked

You can include multiple certificate statuses by separating each with commas.

Note:

The state field in the Unique Certificate [cmdb_ci_certificate] table denotes the life cycle state of the certificate, not the raw state from the API. If the API returns states such as issued, valid, expired, or canceled, they are stored as "issued" in the Unique Certificate [cmdb_ci_certificate] table.

Once the pre-discovery phase is completed, move on to the post-discovery phase.