Pre-discovery phase

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Pre-discovery phase

    The pre-discovery phase involves essential preparatory steps to facilitate the certificate discovery process. Key activities include defining scanning parameters and configuring credential details to ensure a seamless initiation.

    Show full answer Show less

    Key Features

    • Discovery via Ports: The tlssslcerts probe automatically scans 14 default ports for SSL certificates, such as 443 and 636. The MID Server collects certificate chain information and sends it as an XML payload to the instance, updating the Discovered Certificate table.
    • Discovery via URL: The Certificate URL table manages URLs for certificate discovery. The CertificateDiscoveryFromURLScan probe gathers certificate chain data, creating records in the Discovered Certificate table.
    • Discovery via Import Certificates: This method uses parameters like the host name/IP and folder location to discover certificates. Configuration settings can impact payload size and memory usage.
    • Discovery via CA Authority: Credential setup with certificate authorities (e.g., GoDaddy, DigiCert) enables the retrieval of certificate information through REST API calls, storing results in specified tables. Optional parameters allow customization of the API calls.

    Key Outcomes

    By completing the pre-discovery phase, customers can effectively set up their ServiceNow environment for certificate discovery. This ensures accurate tracking of certificates, streamlines the management process, and prepares for the subsequent post-discovery phase.

    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.