DNS configuration#

As explained in Documenting, PyAnsys projects publish their documentation online under the following canonical name (CNAME) convention:

https://<product>.docs.pyansys.com

To request a CNAME for the pyansys.com domain, contact Maxime Rey, Roberto Pastor Muela or Alex Kaszynski. Any of these members can handle the creation of the requested PyAnsys subdomain.

Once the CNAME is created, repository administrators can configure their published documentation in GitHub pages to be exposed through it. To configure the CNAME for your documentation, refer to Managing a custom domain for your GitHub Pages site.

DNS TXT verification#

Once a CNAME is registered under the pyansys.com domain, the next step is to perform a DNS TXT verification. All PyAnsys subdomains are required by Ansys’ IT department to provide a DNS TXT verification. To verify a new CNAME for an organization, refer to Verifying a domain for your organization site. This guide shows how to create DNS TXT verification elements for GitHub Pages sites.

Warning

Only users with privilege access to the pyansys.com DNS zone can perform this operation. Contact Maxime Rey, Roberto Pastor Muela or Alex Kaszynski if needed.

PyAnsys verified domains#

In the PyAnsys GitHub organization, these domains have been verified:

  • pyansys.com

  • docs.pyansys.com

Warning

Only CNAME requests with one subdomain before the previous verified domains are allowed. The reasons behind this measure are explained in DNS protection measures.

DNS protection measures#

The rationale behind choosing the previous CNAME convention is due to cybersecurity reasons. As explained in Verifying a domain for your organization site, GitHub provides for verifying domains for users and organizations.

Having a verified domain prevents users external to the organization from taking over existing direct subdomains. However, GitHub does not verify deeper subdomains.

This is better explained with the following examples:

Case scenario - protected subdomain#

  • Consider that the domain pyansys.com has been verified for the PyAnsys GitHub organization.

  • This CNAME is requested: subdomain.pyansys.com.

This CNAME can only be used by repositories inside the PyAnsys GitHub organization. Any attempt by an external user to take over this CNAME is identified and rejected by GitHub.

Case scenario - vulnerable subdomain#

  • The domain pyansys.com has been verified for the PyAnsys GitHub organization.

  • This CNAME is requested: subsubdomain.subdomain.pyansys.com.

This CNAME can be used by external users for their repositories. For this reason, you must avoid creating CNAME requests that are not verified by the organization.

Preventing CNAME takeover#

CNAME values have been taken over in the past by external users, typically due to these reasons:

  • Ansys GitHub organizations had no domain verification set up.

  • A CNAME created did not follow the recommended CNAME guidelines.

  • More than one level of subdomain depth under the verified domain had been requested.

  • Long time lapses occurred between CNAME creation and assignment to GitHub pages.

Thus, it is important that you follow these guidelines:

  • Ensure that your GitHub organization has verified domains for hosting GitHub pages.

  • Check that the CNAME that you request does not have a subdomain depth larger than 1 with respect to the verified domains.

  • Request a CNAME only when needed, which is just prior to publishing the site.

  • Request deletion of the CNAME once it is no longer used to prevent others from hosting their sites on it.