Advanced Configuration : PrivX Help

This chapter provides instructions for customizing PrivX components to suit the needs of your environment.

SSL/TLS Security

This section describes the configuration topics related to SSL/TLS security.

Setting Up a Trusted Server Certificate

Freshly set-up PrivX servers are equipped with self-signed server certificates. For production deployments we recommend replacing the self-signed server certificate with a server certificate issued by a trusted Certificate Authority (CA).

Note

The self-signed server certificate should only be trusted in evaluation deployments. In production environments, we strongly recommend that you acquire and use a trusted server certificate. You can obtain a trusted server certificate by enrolling the certificate-signing request with your corporate CA.

The initial setup has generated a certificate-signing request (CSR), which can be enrolled with a trusted CA for a trusted server certificate. The CSR is located at the following path on the PrivX server:
/etc/nginx/ssl/nginx.csr
Enroll this CSR with your CA. In response, the CA should provide you with the following:
- The server certificate.
- The CA-certificate chain of the CA itself.
Note
Note to certificate-signing authorities: The PrivX CSR contains subjectAltName definitions for DNS and IP addresses. These are critical to PrivX operation and must be preserved in the signed server certificate.
Copy the PEM (Base64) encoded server-certificate file to the ssl_certificate location on the PrivX instance. By default, the location is:
/etc/nginx/ssl/nginx.crt
Ensure that the server-certificate file has correct ownership, permissions, and SELinux context:
```
# chown root:nginx /etc/nginx/ssl/nginx.crt
# chmod 0640 /etc/nginx/ssl/nginx.crt
# restorecon /etc/nginx/ssl/nginx.crt
```
Update the trust anchor for PrivX microservices. To do this, run the following command (replace /path/to/ca_chain.crt with the path to the CA-certificate-chain file):
```
# /opt/privx/scripts/init_nginx.sh update-trust /path/to/ca_chain.crt
```
Note
In single-server deployments, provide the CA chain of the PrivX-server certificate. In HA deployments, provide the CA chain of the load-balancer certificate.
init_nginx.sh requires PEM-encoded certificate files to have Unix line endings. If the command fails, ensure correct line endings in the CA-certificate-chain file, then rerun the command.
Finally, restart the Nginx and PrivX services to start using the new server certificate:
```
# systemctl restart nginx
# systemctl restart privx
```

Setting Up a Trusted CA Certificate

PrivX Authorizer issues access certificates using its own CA, which is self-signed by default. For production deployments we recommend replacing the Authorizer CA with one signed by a trusted certificate authority.

Note

The following procedures use <key_id> and <cert_id> to substitute for PrivX-CA-key ID and the Authorizer-certificate ID respectively. Be careful not to mix them up.

To set up PrivX Authorizer with a trusted CA certificate:

Gain root-terminal access to a PrivX server, and display the PrivX-CA-key ID by running:
```
# /opt/privx/bin/keyvault-tool -name "PrivX CA Key" list-asymmetric
```
Generate a Certificate-Signing Request (CSR) for the CA private key (replace <key_id> with the PrivX-CA-key ID):
```
# /opt/privx/bin/cert-tool -command create -type authorizer-ca \
-subject "OU=PrivX Authorizer CA/CN=PrivX CA" \
-key <key_id> -csr -csrout privx-im-ca.csr
```
This creates the CSR to the file privx-im-ca.csr in your current working directory.
Request a trusted CA to sign the CSR with the following constraints:
- keyUsage must include: Digital Signature, Key Agreement, Certificate Sign, CRL Sign
- basicConstraints must be: CA:TRUE, pathlen:0
After the trusted CA provides you with the signed certificate, you may verify its constraints with (replace privx-im-ca.crt with the path to the signed certificate):
```
$ openssl x509 -text -noout -in privx-im-ca.crt 
```
Replace the Authorizer certificate. First, obtain the ID of the current Authorizer certificate:
```
# /opt/privx/bin/cert-tool -command list -type authorizer-ca
```
Then delete the current Authorizer certificate (replace <cert_id> with the Authorizer-certificate ID):
```
# /opt/privx/bin/cert-tool -command delete -id <cert_id>
```
Finally, import the signed certificate (replace <key_id> with the PrivX-CA-key ID, replace privx-im-ca.crt with the path to the signed certificate):
```
# /opt/privx/bin/cert-tool -command import -type authorizer-ca \
-key <key_id> -in privx-im-ca.crt
```
On all PrivX servers, restart the PrivX services to apply the changes:
```
# systemctl restart privx
```
Subsequent certificates issued by PrivX are signed using the new trusted Authorizer CA certificate.

Allowed SSL Protocols and Ciphers for GUI Connections

Connections to the PrivX GUI are secured using TLS. The allowed SSL protocols and SSL ciphers may be adjusted if some browsers cannot establish connections to the PrivX GUI, or if you want to harden the PrivX instance.

The allowed SSL protocols and SSL ciphers are defined in the Nginx configuration file /etc/nginx/conf.d/privx.conf, by the parameters ssl_protocols and ssl_ciphers respectively, similarly to the following:

...
http {
    sendfile on;
    server_tokens off;

    ssl_protocols  TLSv1.2;
    ssl_ciphers 'AESGCM+EECDH:AESGCM+EDH:AES+EECDH: ... ';

    tcp_nodelay on;
...

After any adjustments to Nginx settings, restart the Nginx web server to apply the changes:

# systemctl restart nginx

Rotating Encryption Keys

This section provides instructions for rotating PrivX cryptographic keys, which should be done regularly for improved security. You can rotate the following keys:

PrivX CA keys, which issue certificates for certificate-based access.
Authentication keys, which issue PrivX-user access and session tokens.

To rotate PrivX CA keys:

Run the rotation script from a PrivX server in the deployment:
```
# /opt/privx/scripts/rotate_privx_ca.sh
```
The old PrivX CA certificates are deleted and new ones are generated. The script will then restart PrivX.
On hosts with certificate authentication enabled, configure trust for the new PrivX CA. To do this:
- On target hosts with certificate-based SSH authentication: run the host-deployment script with the --rotate-ca option:
```
# deploy.py --rotate-ca
```
  Alternatively, manually configure the host to trust the new PrivX CA as described in the section called “Trusting PrivX Certificates”.
- If you use certificate-based RDP authentication: Set up trust for the new PrivX CA as described in the section called “Steps for RDP Certificate-Authentication-Setup”.

To rotate PrivX authentication keys:

Run the rotation command on a PrivX server in the deployment:
```
# /opt/privx/bin/keyvault-tool rotate-auth-keys
```
This generates new authentication keys.
On all PrivX servers, restart the PrivX services:
```
# systemctl restart privx
```

Note

PrivX-user logins may fail during the time between authentication-key generation and restarting PrivX services.

PrivX Log Settings

By default, regular and audit events are logged to syslog. Audit events use the namespace SSH-PRIVX-AUDIT, and other (info/debug/error) messages use the namespace SSH_PRIVX.

You can adjust the locations to which PrivX writes logs, and the log level of each microservice.

The log locations are configured by settings defined in /opt/privx/etc/shared-config.toml

# Should we send PrivX system events to logs under /var/log/privx
# send_regular_events_to_stdout = false
send_regular_events_to_stdout = false

# Should we send PrivX audit events to syslog
# send_regular_events_to_syslog = true
send_audit_events_to_syslog = true

# Should we send PrivX system events to syslog
# send_regular_events_to_syslog = true
send_regular_events_to_syslog = true

To enable debug output for a microservice:

Edit /opt/privx/scripts/<microservice_name>.sh (replace <microservice_name> with the name of the microservice) and set the SSH_TRACE parameter:
```
dir="/opt/privx/bin"
cmd="SSH_LOG_LEVEL=DEBUG SSH_TRACE=6 /opt/privx/bin/auth"
user="privx"
```
By default, the system-logging service rsyslog is configured to show INFO-level messages only, which blocks DEBUG messages. To configure rsyslog to show DEBUG-level messages, find the following line in the rsyslog configuration file, /etc/rsyslog.conf:
```
*.info;mail.none;authpriv.none;cron.none    /var/log/messages
```
And change it to, for example:
```
*.debug;mail.none;authpriv.none;cron.none    /var/log/messages
```
Restart rsyslog to apply the changes:
```
systemctl restart rsyslog
```
Restart the privx service to apply any changes to configuration files:
```
# systemctl restart privx
```

PrivX-Extender Configuration

This section describes configuration topics for PrivX Extenders.

Configuring Extender Log Location

By default PrivX Extender logs info and errors to /var/log/privx/privx-extender.log

If you want to enable logging to syslog, specify the rsyslog address and protocol in /opt/privx/etc/extender-config.toml, similar to the following:

syslog_protocol="tcp"
syslog_address="localhost:514"

Restart PrivX Extender to apply the changes. In addition make sure rsyslog is enabled on the extender host:

systemctl restart privx-extender
systemctl restart rsyslog

Proxying Native-Client Connections

To allow proxying native-client connections via PrivX Extenders:

On all your PrivX servers, enable the forwarder_enabled setting in /opt/privx/etc/ssh-proxy.toml
And restart PrivX services to apply the changes:
```
systemctl restart privx
```
Caution
The forwarder relays all the data it receives (not just the native-client connections), and should not be enabled in high-security networks.
Session recording must be disabled on hosts that are to be accessed using proxied native-client connections. For more detailed instructions about toggling session recording, see the section called “Session Recording Setup”.
(Optional) To simplify native-client commands, specify the required connection parameters in the users' client configuration (typically at /etc/ssh/ssh_config or ~/.ssh/config). You can do this using Host blocks that at least specify:
- The target HostName in extender-name/target-host-address format.
- The ProxyCommand: privx-nc -x $PRIVX_AGENT_PROXY %h %p
For example:
```
Host bilberry
    HostName example-extender/bilberry.example.com
    ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p
```

After setup, you can connect to target hosts as follows:

As the native-client user, start the PrivX agent (if not already started) and use it to log into PrivX.

If you have specified the required parameters in your SSH-client configuration, you can connect simply using the appropriate Host block. For example:

$ ssh target-user@bilberry

$ sftp target-user@bilberry

$ scp source/file/path target-user@bilberry:/target/file/path

Otherwise, you must additionally provide the ProxyCommand and the name of the PrivX Extender, similar to the following:

$ ssh -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
target-user@example-extender/bilberry.example.com

$ sftp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
target-user@example-extender/bilberry.example.com

$ scp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY example-extender/%h %p"\
source/file/pathtarget-user@bilberry.example.com:/target/file/path

Custom Load-Balancer Support

If you are using a custom load balancer, ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Extenders:

Add the name of the session-affinity cookie to the known_lb_cookies setting. The setting is located in the following configuration file on the Extender:
/opt/privx/etc/extender-config.toml
Restart the Extender with:
```
# systemctl restart privx-extender
```

Note

If your PrivX HA deployment also includes PrivX Carriers and PrivX Web Proxies, configure those to accept your session-affinity cookie as well, as per instructions in the section called “Custom Load-Balancer Support”.

PrivX-Carrier and Web Proxy Configuration

This section describes configuration topics for the PrivX Carrier and PrivX Web Proxy.

Allowing HTTP/HTTPS Targets at Unusual Ports

This section describes modifying the allowed target ports for PrivX Web Proxies. These instructions assume you to have some familiarity with Squid configuration.

By default PrivX only allows access to HTTP/HTTPS targets running on certain ports. The allowed ports are available toward the start of your Squid configuration file.

To allow access to targets at nonstandard ports:

Verify and set the allowed target ports on your Web-Proxy machines in /opt/privx/etc/squid.conf
- For HTTP and HTTPS targets, ensure the target port is included in the Safe_ports list. You can add the target port by adding a similar line immediately after other acl Safe_ports directives (replace <target_port> with the port of your HTTP/HTTPS service):
```
acl Safe_ports port <target_port>
```
- Additionally for HTTPS targets, ensure the target port is included in the SSL_ports list. You can add the target port by adding a similar line immediately after other acl SSL_ports directives (replace <target_port> with the port of your HTTPS service):
```
acl SSL_ports port <target_port>
```
For example, to allow access to HTTPS target running on port 9443, you would need to add the port to SSL_ports:
```
acl SSL_ports port 443
acl SSL_ports port 9443
acl Safe_ports port 80          # http
acl Safe_ports port 21          # ftp
acl Safe_ports port 443         # https
acl Safe_ports port 1025-65535  # unregistered ports
acl CONNECT method CONNECT
```
Port 9443 is already included in Safe_ports by default.
Restart the squid service to apply the changes:
```
# systemctl restart squid
```

Access Restrictions for Web Connections

You can control access to specific websites for specific PrivX roles. With this you can prevent users from accessing arbitrary websites by entering URLs, and via links on web targets.

Role-based access control is configured via Squid on PrivX Web Proxies. These instructions assume you have some familiarity with Squid configuration. This section provides some basic examples about access control. For more comprehensive descriptions about Squid's access-control settings, see their vendor documentation at https://wiki.squid-cache.org/SquidFaq/SquidAcl

To control access for a PrivX role, you will typically need to specify the following in the Squid configuration:

Define an acl matching the members of the PrivX role. You can determine PrivX users' roles from their User-Agent header.
Define acls for the restricted address(es).
Define rules allowing/denying matching members to access restricted address(es).

For example, to only allow privx-admin members to access while denying all other PrivX users access to www.example.com, perform the following on all your PrivX Web Proxies:

Add rules like the following to the Squid configuration at /opt/privx/etc/squid.conf

# Match all PrivX users belonging to the privx-admin role
acl is_privx_admin req_header User-Agent Role\=privx-admin

# Define restricted address(es)
acl restricted_to_certain_privx_roles ssl::server_name www.example.com

# Allow privx-admins to access restricted address(es)
http_access allow is_privx_admin restricted_to_certain_privx_roles

# Deny others access to restricted address(es)
http_access deny restricted_to_certain_privx_roles

Restart the squid service to apply the changes:
```
# systemctl restart squid
```

Trusting Sites with Self-Signed Certificates

Configure trust for any web targets that use self-signed certificates, for the following benefits:

PrivX users connecting to web targets no longer receive security warnings about insecure server certificates.
Support websocket connections from the web target.

Note

We recommend setting up web targets before configuring trust for them. For more information about setting up targets in PrivX, see the section called “Setting up Known Targets”.

To trust a web target:

On your PrivX Web Proxy, add the CA-certificate chain of the web target to the system trust anchors: Save the CA-certificate-chain file under
/etc/pki/ca-trust/source/anchors/
Then run:
```
# update-ca-trust extract
```
Restart the Squid service to apply the changes:
```
# systemctl restart squid
```
(Optional) Perform this step if you need to enable websocket connections from the web target.
On your PrivX Carrier, add the CA-certificate chain of the web target to your PrivX-Carrier configuration at:
/opt/privx/etc/carrier-config.toml
Then restart the Carrier and Docker services to apply the changes:
```
# systemctl restart privx-carrier
# systemctl restart docker
```

Changing Web Proxy Port Numbers

To change the Web Proxy ports, you need to edit the following:

Note

In the following examples, replace the port numbers 18080 and 18443 with the ports you want to use.

On the Carrier host, change the ports in the /opt/privx/etc/carrier-container.toml file:

[web_container]

# Web proxy ports for HTTP and HTTPS. The port numbers and Carrier host IP \
address should match the Squid configuration file in /opt/privx/etc/squid.conf
# Proxy server IP address is configured via PrivX UI.
http_proxy_port = 18080
https_proxy_port = 18443

After editing the file, restart the Carrier service:

# systemctl restart privx-carrier

On the Web Proxy host, edit the Squid configuration file in /opt/privx/etc/squid.conf to match the port numbers you entered previously:

http_port 18080
http_port 18443 ssl-bump cert=/opt/privx/squid_cert/squid.crt \
key=/opt/privx/squid_cert/squid.key generate-host-certificates=on \
dynamic_cert_mem_cache_size=4MB

After editing the file, restart the Web Proxy and Squid services:

# systemctl restart privx-web-proxy squid

The Web Proxy host's firewall should allow access to the ports you have specified. Run:

# firewall-cmd --permanent --add-port=18443/tcp
# firewall-cmd --permanent --add-port=18080/tcp
# firewall-cmd --reload

Custom Load-Balancer Support

If you are using a custom load balancer in a PrivX HA deployment, you will need to ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Carriers and PrivX Web-Proxies:

Add the name of the session-affinity cookie to the known_lb_cookies setting. The setting is located in the following configuration files, for Carriers and Web-Proxies respectively:
/opt/privx/etc/carrier-config.toml
/opt/privx/etc/web-proxy-config.toml
Restart the Carrier and Web-Proxy services. On your Carriers, run:
```
# systemctl restart privx-carrier
```
And on your Web-Proxies, run:
```
# systemctl restart privx-web-proxy
```

Note

If your PrivX HA deployment also includes Extenders, configure those to accept your session-affinity cookie as well, according to the instructions at the section called “Custom Load-Balancer Support”.

API-Client Integration

You can automate PrivX administrative tasks via the PrivX API.

You can use any RESTful client with OAuth2 support to access the PrivX API, such as curl. You may also use the PrivX SDK for Python available at https://github.com/SSHcom/privx-sdk-for-python

High-level setup steps include:

Providing role-based permissions for the API client.
OAuth2 authentication with the API client.

First define the permissions of the API client:

Create an API-client entry in PrivX.
In the PrivX GUI, go to Settings→Deployment→Integrate with PrivX using API clients, then click Add API Client.
Provide a Name for the API client. To provide permissions, also add some Roles for the API client.
Click Save to save your API client.
Back on the API clients page, expand Credentials of your API client. These are required later for authentication.

After creating your API-client entry, authenticate using your API client as follows:

Provide your API-client Credentials to the /auth/api/v1/oauth/token endpoint. For example, using curl (replace <privx.example.com> with your PrivX address, replace <oauth_client_id>, <oauth_client_secret>, <api_client_id>, and <api_client_secret> with the respective values from your API-client Credentials):
```
$ curl -X POST \
https://<privx.example.com>/auth/api/v1/oauth/token \
-u <oauth_client_id>:<oauth_client_secret> \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<api_client_id>' \
--data-urlencode 'password=<api_client_secret>'
```
Note
Unlike other PrivX-API endpoints, the /auth/api/v1/oauth/token endpoint only accepts content in application/x-www-form-urlencoded format (not in application/JSON format).
Upon successful authentication you will receive an access token in JSON format, similar to the following:
```
{
    "access_token": "<access_token>",
    "token_type": "bearer",
    "expires_in": 1800
```
You can now use the access token to perform PrivX actions using other endpoints. For example, to list all hosts in PrivX:
```
$ curl -X GET \
-H "Authorization: Bearer <access_token>" \
https://<privx.example.com>/host-store/api/v1/hosts   
```

Setting Custom Instance Names

You can set a custom instance name to better distinguish between multiple PrivX servers. Custom instance names are displayed in the PrivX GUI, and added to the audit events generated from the server.

Figure 5.1. Custom instance name in the GUI header and audit events

To set a custom instance name for a PrivX server:

Gain root-terminal access to the PrivX server.
Edit the shared configuration at:
/opt/privx/etc/shared-config.toml
In this file, set the custom instance name with privx_instance_name. For example:
```
# A custom PrivX instance name to be shown in the header
privx_instance_name = "PrivX Example Deployment 01"
```
Save your changes to the file.
Restart the PrivX services to apply the changes:
```
# systemctl restart privx
```

Custom Disclaimers

To show messages to PrivX users upon login, configure the privx_disclaimer setting in /opt/privx/etc/shared-config.toml

In the privx_disclaimer setting, specify the disclaimer message in JSON format, similar to the following:
privx_disclaimer = '''
[
{
title: 'Disclaimer',
text: 'Disclaimer message',
accept: 'I have read and agree to the terms and conditions',
mode: 'float', // float/local/popup
acceptable: true,
closeable: false
}
]
'''
You can customize the disclaimer content and visibility with the following parameters:
- title: Title for the disclaimer.
- text: Message shown in the disclaimer.
- accept: Text for the checkbox that allows users to accept the disclaimer.
- mode: How the disclaimer looks on the page. Choices are float, local, and popup
- acceptable: Allow users to accept and close the disclaimer. Can be true or false.
  After a user accepts the disclaimer it will not be displayed on subsequent logins, until users clear browser cookies. Unless closeable is also set to true, the user must accept the disclaimer to proceed.
- closeable: Allow users to close the disclaimer without accepting it. Can be true or false.
  Closed disclaimers are redisplayed on subsequent logins.
Restart PrivX services to apply the changes:
```
# systemctl restart privx
```

Resetting the Superuser Password

If you have forgotten the PrivX superuser's password, you can reset it as follows:

On a PrivX server, obtain an encrypted version of your new password (replace example_password with your new password):
```
# /opt/privx/bin/keyvault-tool bcrypt <example_password>
```
Access the PrivX database using psql with write permissions. Change the superuser password (Replace encrypted_password and superuser with the encrypted password and your superuser-account name respectively):
```
# UPDATE localuser SET password='encrypted_password' WHERE username='superuser'
```
You can now log into PrivX as superuser using the new password.