Setup Guide for Enterprise Firewalls and MITM Proxies

If you encounter SSL errors or connectivity issues in enterprise networks, this guide explains why and how to solve them.

To enable Sema4.ai tools to work properly in enterprise networks with MITM proxies, you need to:

Provide the proxy settings to all Sema4.ai tooling
Enable access to the certificates that the proxy uses (to allow certificates not signed by public CAs)

Here's how to set up:

1. Ensure you have the latest versions:

Studio v1.2.9 or above
SDK-extension v2.12.0 or above

2. Create a network configuration file (for proxy settings)

The file needs to be located in:

~/.sema4ai/network-settings.yaml on macOS and Linux
%LOCALAPPDATA%\sema4ai\network-settings.yaml on Windows.

If the file is not present tooling behaves as if there are no proxies.

3. Configure your profile

# Network profiles for Sema4.ai Python, Go and NodeJS tooling
spec-version: 1.0.0
 
current-profile: Home
profiles:
  - name: "No Proxy"
    description: "No proxy profile"      # Setup where there is no proxy
    disable-ssl: false                   # By default traffic should always be HTTPS encrypted
    
  - name: "Work"
    description: "My proxy settings for work"
    disable-ssl: false
    proxy-settings:
      authentication: 
        auth-type: os-certificate
      no-proxy: "localhost,127.0.0.1"
      https-proxy: https://work-proxy.company.com
      http-proxy: http://work-proxy.company.com
  
  - name: "Insecure Proxy"  # Example of a profile with all SSL disable, proxy is there with no auth
    description: "Direct connection without proxy and all internal traffic is HTTP"
    disable-ssl: true
    proxy-settings:
      authentication: 
        auth-type: none
      no-proxy: ""
      https-proxy: http://no-ssl-proxy.company.com
      http-proxy: http://no-ssl-proxy.company.com

By default, our tooling accesses the system certificate store where your IT department typically installs the proxy certificates.

4. For Custom Actions

If you have custom actions, We provide HTTP helper (opens in a new tab) -library to adapt your own Python code to work with MITM proxies. For simple requests you can use the functions provided there or you can use it to get the configs that you can use with your favorite Python HTTP library.

5. Advanced: SSL Issues

If you continue to have SSL issues:

Set disable-ssl: true in your profile configuration (with IT approval only)
This should be a last resort after trying system certificate store options

Technical background

Why This Happens?

Enterprise networks use man-in-the-middle (MITM) firewalls or proxies to inspect and control outgoing and incoming traffic. These solutions:

Intercept encrypted HTTPS traffic
Decrypt it and scan it
Re-encrypt it with their own (often self-signed) certificate

This process is known as Transparent HTTPS, HTTPS Inspection, SSL/TLS Inspection, SSL Interception, SSL Forward Proxy, or SSL Decryption. MITM proxy explanation While browsers trust these certificates (installed in your system certificate store), command-line tools like those used by Sema4.ai don't automatically access this store, resulting in SSL verification errors.

Agent API Terminology