Thycotic

1. Introduction

Thycotic Secret Server (PAM) provides a solution that helps manage, control, and monitor the admin activities on assets.

The SAFE - Thycotic integration leverages the credentials stored in Thycotic Secret Server and eliminates the manual entry of asset username & password on the SAFE platform for assessment. With this integration, SAFE pulls the asset credentials from the Thycotic Secret Server via API, authenticates the assets using these credentials, and does the assessment. This all takes place without SAFE ever storing the assets credentials.

SAFE provides two ways to get data from Thycotic:

1. Users can use the out-of-the-box configuration and script to fetch data from Thycotic.
2. Or, users can implement their own custom script that will be responsible for getting the data from Thycotic. This method can be used if there is complex logic required to determine which credentials should be used for assessments, in the case where multiple credentials for an asset are stored in Thycotic.

2. Configure Thycotic in Site Coordinator

To configure the Thycotic in Site Coordinator:

1. Connect to the host machine where the site coordinator is installed.
2. In the command line execute:
   docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o add
3. Enter the valid configuration details as prompted:
   1. Thycotic URL: The URL of the Thycotic server, which is accessible from the site coordinator
   2. Thycotic authorization URL path: The URL path for authorization [Default: SecretServer/oauth2/token]
   3. Thycotic secrets URL path: The URL path for secrets API [Default: SecretServer/api/v1/secrets]
   4. Thycotic port: The port at which the above URL is accessible [Default: 443]
   5. Thycotic username: Thycotic login username
   6. Thycotic Password: Thycotic login password
   7. Verify SSL: Should the script verify SSL before sending a request. If the above Thycotic URL is secured by a well-known Certificate Authority, its SSL certificate should be verified, otherwise, provide the certificate signature in the next step.
   8. Certificate signature: SHA256 Fingerprint hash to verify the Thycotic server SSL certificate. Asked only when Verify SSL is No.
      
4. Enter the valid field details as prompted:
   1. Select the SAFE field name for asset identification: Select one of the given identifiers, namely Asset Name, IP Address or Hostname, and CMDB ID. The value of the selected field for a corresponding asset will be used to uniquely identify and fetch asset details from the Thycotic Secret Server. It will be passed as the value of the searchText parameter in secrets/lookup Thycotic API.
      For example: Let the selected field be CMDB ID, and the asset value for an asset in SAFE is cmdb1234. Then the searchText in Thycotic API will be passed as cmdb1234.
   2. Select the Thycotic field name for asset identification (case sensitive): Enter a valid Thycotic field name to which the SAFE field value maps in the Thycotic Secret Server. This field will be passed in the searchField parameter in secrets/lookup Thycotic API.
   3. Enter Thycotic field name for username (case sensitive): Enter a valid Thycotic field name whose value is to be treated as an asset's username. The script considers “username” as the default field name if nothing is entered.
      For example: If the asset username is stored as “user” in Thycotic Secret Server, then “user” is to be entered in this field.
   4. Enter the Thycotic field name for the password (case sensitive): Enter a valid Thycotic field name whose value is to be treated as an asset's password. The script considers “password” as the default field name if nothing is entered.
      For example: If the asset password is stored as “pass” in Thycotic Secret Server, then “pass” is to be entered in this field.
   5. Enter a valid Thycotic Field value to test script sanity: Enter a valid Thycotic field value that maps to an asset in Thycotic Secret Server. This Step is needed to validate connectivity to Thycotic Secret Server using the above-configured parameters. It uses the Thycotic field name entered in 4.b and the value provided to check if the username and password can be retrieved from Thycotic Secret Server successfully.
      For Example: If in 4.b Secret Name is entered and there is an entry in Thycotic for which Secret Name is "Secret Name Value", then in this field, "Secret Name Value" is to be entered.
      
5. At this point, if step 4.e returned a success, the integration with Thycotic is complete. Assets in SAFE configured to use this site coordinator and without a username and password saved should rely on the Thycotic Secret Server for credential retrieval. If any errors are encountered, check the FAQ below in Section 5.

3. Using Custom Script to configure Thycotic in Site Coordinator

SAFE integration with Thycotic can be configured with a customer-provided custom script instead of relying on the default SAFE script. This can be used to retrieve asset credentials where complex custom logic is required to get the appropriate asset credentials from Thycotic Secret Server.

An alternative to creating a new script from scratch is to use the default Safe provided script framework and modify the logic that acquires credentials to suit your needs. 

The default SAFE thycotic.py script can be acquired by copying it from the agentless-scanner container to the Site Coordinator /tmp directory by running the below command on the Site Coordinator.

docker cp $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}'):/usr/src/app/data/integrations/default/thycotic/thycotic.py /tmp/thycotic.py

A few points to remember when implementing a custom script:

1. The script is to be placed only under the site coordinator install root directory at: safe-security/site-coordinator/data/integrations/custom/thycotic/  and the name of the script should be thycotic.py
2. The entry point function name in the script should be get_password_from_thycotic.
3. SAFE will only provide 3 inputs, namely Asset Name, IP Address or Hostname, and CMDB ID to the entry point function.
4. The function has to return username(mandatory), password(mandatory), privilegePassword(optional) in the format given in the custom template below.

#CUSTOM TEMPLATE
#Name of this file will have to be thycotic.py
import base64

# Entry point for Thycotic
def get_password_from_thycotic(query_data):
    # query_data will have a format like:
    # query_data = {
    #     "asset_name": <asset name>,
    #     "ip_address": <ip address>,
    #     "cmdb_id": <cmdb id>
    # }
    # Any key from the above dictionary can be used to get the value that is to be matched in Thycotic
    # This default script fetches it from thycotic_mapping.json

    # Logic to fetch asset details from Thycotic

    # The dictionary returned can have username, password and privilegePassword as the keys.
    return {
        "username": <asset_username>,                                                           # Username should be in plain text
        "password": base64.encodestring(<asset_password>.encode()).decode(),                    # Required and the value needs to be base64 encoded
        "privilegePassword": base64.encodestring(<asset_privilege_password>.encode()).decode()  # Optional, if present the value needs to be base64 encoded
    }

Follow the below steps:

1. Place your script file inside the folder safe-security/site-coordinator/data/integrations/custom/thycotic/ with the name as thycotic.py. The entry point function name in the thycotic.py should be get_password_from_thycotic.
2. Integrate Thycotic with SAFE:
   1. In the case where the custom script takes care of everything like connecting with Thycotic and fetching the data from Secret Server, then in the command line execute docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o enable to enable Thycotic flag in SAFE.
   2. {In case the user still wants to leverage the way that SAFE uses to store Thycotic credentials and to map the SAFE and Thycotic fields in their custom script, then Section 2 can be followed}.
3. To check if Thycotic script returns the output in expected format, use docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o test-thycotic-script.

4. Additional configure_thycotic.py commands

The configure_thycotic script provides a set of options to show status, add, enable, disable, and test-thycotic-script. Execute the configure script along with --help flag to see all the available options docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py --help

1. To see the status of the Thycotic flag in Site Coordinator, run docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o status. This command will return if Thycotic is Enabled/Disabled/Not configured on Site coordinator.
2. To add a new Thycotic configuration in Site Coordinator, run docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o add . This is also a default option. If -o is not passed then add will be picked.
3. To enable Thycotic flag in SAFE, run  docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o enable
4. To disable Thycotic flag in SAFE, run docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o disable
5. To test default/custom Thycotic script and stored configuration, run docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o test-thycotic-script
6. To edit Thycotic configuration, the same add command can be used docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o add. It will override the existing data.

5. FAQs

1. What to do if the configure script exited with an error before saving the configuration in SC?

1. Check that the Thycotic URL is accessible at the given port.
2. If the error is related to SSL verification, retry the add Thycotic configuration with Verify SSL as false and enter a valid certificate signature.

2. What to do if the configure script exited with an error after saving the configuration but mapping details are not saved?

If the configure script exited while fetching asset details from Thycotic, verify that Thycotic field details are correct in the thycotic_mapping.json file inside the site-coordinator/data/integrations/custom/thycotic/ folder.

If the field details are not correct modify the thycotic_mapping.json and try the test-thycotic-script command.

{"safeFieldName": "asset_name", "thycoticFieldName": "Secret Name", "extendedFields": ["password", "username"]}

3. Thycotic configuration is successful but no data is returned from Thycotic Secret Server?

Check that the Thycotic field is searchable, this is case-sensitive. If the entered field value is wrong, you can edit the field details in the thycotic_mapping.json file inside the site-coordinator/data/integrations/custom/thycotic/ folder.

If you are using SAFEs default script, try executing  docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o test-thycotic-script

4. Thycotic is not working for my version as the API used is not supported?

SAFE is only tested with v1 APIs of Thycotic. If you still want to use other versions, you can follow section 3 and put a custom script in place. Theoretically, using a custom script and having a different API in that script will work.

5. What to do if enabling Thycotic request fails for one or more SAFE (Master Site Coordinator)?

If when enabling Thycotic the request fails for one or more SAFE URLs (Master Site Coordinator) the failed requests will be retried every 30 minutes. If the failures continue on subsequent attempts log the issue with Safe customer support for further investigation.

6. I have placed the custom script with no errors, it is working manually but SAFE is not implementing it up properly.

Use docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') python bin/configure_thycotic.py -o test-thycotic-script to double check that script does not return any error.

 If still, the integration is not working, the last resort can be:

• Run docker service ls
• Copy the agentless-scanner service name
• Run docker service update --force <service name copied in step 2>

7. How to make Site Coordinator trust internal CA Signed HTTPS certificates?

In case you have an internal CA signed HTTPS certificate but giving the Yes as Verify SSL option in Thycotic configuration is not working, you can use the steps below to make Site Coordinator trust the root CA: 

Step-1: Trusting a new root CA in the host machine

Ubuntu:

• Add a new CA certificate inside /usr/local/share/ca-certificates file in .pem format with .crt extension . Command: sudo cp local-ca.crt /usr/local/share/ca-certificates
• Update the ca-certificates.crt file inside /etc/ssl/certs/ca-certificates.crt . Command: sudo update-ca-certificates
• To confirm if the new root CA certificate is updated inca-certificates.crt you can check the file size before and after executing above commands. Command: ls -la /etc/ssl/certs/ca-certificates.crt
• Ref: Installing a root CA certificate in the trust store | Ubuntu

Red-Hat:

• Add a new CA certificate inside /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/ file in .pem format. Command: sudo cp local-ca.pem /usr/share/pki/ca-trust-source/anchors/
• Update the ca-bundle.crt file inside /etc/pki/tls/certs/ca-bundle.crt . Command: sudo update-ca-trust
• To confirm if the new root CA certificate is updated in ca-bundle.crt you can check the trust list before and after executing the above commands. Command: trust list and check your local root CA entry should be added
• Ref: 4.14. Using Shared System Certificates Red Hat Enterprise Linux 7 | Red Hat Customer Portal

Step-2: Restart the Docker container service so that the certificate is updated inside the container

• Command: docker service update --force site-coordinator_agentless-scanner
• Check if the ca-certificates.crt file inside the container is updated. The file size should increase after trusting one more CA. Command: docker exec -it $(docker ps --filter 'name=agentless-scanner' --format '{{.ID}}') ls -la /etc/ssl/certs/ca-certificates.crt

Step-3: Reconfigure Thycotic with Verify SSL = true