Configuring Developer Tools with Netskope SSL Inspection

Disclaimer and Advisory

This document and the guidance contained herein are provided by Netskope for informational purposes only and are intended to assist developers and administrators in configuring third-party tools to operate with the Netskope platform.

• "As-Is" Information: The information, scripts, and configuration examples are provided on an "as-is" basis. While Netskope makes a reasonable effort to ensure the accuracy of this information at the time of publication, we make no warranties, express or implied, regarding its completeness, accuracy, or suitability for any particular purpose.

• Third-Party Systems: The software, libraries, and tools discussed in this document are not owned, controlled, or maintained by Netskope. The configuration, commands, and behavior of these third-party systems are subject to change at any time without notice by their respective owners. Netskope assumes no responsibility for errors, omissions, or outdated information related to these third-party systems.

• Use at Your Own Risk: The use of any information or scripts from this guide is done at your own discretion and risk. You are solely responsible for adequate protection and backup of your data and equipment. By following this guidance, you agree that you will be solely responsible for any damage to your computer system, loss of data, or disruption of service that may result from such activities.

• No Alteration of Agreements: This document does not modify, enlarge, or otherwise amend any of your rights or obligations under your master subscription agreement with Netskope. All entitlements regarding warranties, support, and maintenance for the Netskope service are governed solely by that agreement.

Netskope's goal is to reduce operational friction when using our platform. This document is a good-faith effort to aid in that process, but it should not be considered a substitute for the official documentation of the third-party products mentioned. Always consult the primary documentation for each tool for the most current and accurate configuration details.

1. Introduction

This guide provides comprehensive instructions for configuring common command-line (CLI) tools, programming languages, and development frameworks to work correctly with Netskope's SSL Interception. It also provides strategic guidance for deploying and managing SSL decryption for developer teams.

2. Strategic Approach to SSL Decryption for Developer Teams

A successful SSL decryption deployment requires balancing security objectives with developer productivity. A well-planned strategy can minimize disruption and build trust with your technical teams.

Proactive Strategies (During Deployment & Expansion)

• Phased Rollout: Avoid enabling decryption for all developers at once. Start with a small, tech-savvy pilot group. This allows you to identify and resolve common issues with a more forgiving audience.

   

• Pre-populate Exception Lists: Before deploying to the pilot group, proactively create SSL bypass policies for well-known developer service categories. This includes common code repositories, package managers, and API endpoints known to use certificate pinning. Use the Netskope-defined categories below to create broad but relevant exceptions:

   

  • Development Tools: This is the most critical category and covers services used for source code management, CI/CD, and other development processes.

     

  • IaaS/PaaS: Essential for developers working with public cloud providers. This category covers the APIs and service endpoints for major platforms.

     

  • Content Server: Often includes content delivery networks (CDNs) that host developer libraries and assets.

     

  • File Repositories / Cloud Storage: Catches services used to host software artifacts, binaries, and large datasets.

     

• Establish Clear Communication Channels: Announce the rollout schedule in advance. Clearly explain what SSL decryption is, why it is being implemented, and how developers can request an exception. Provide a link to this guide.

   

• Developer Onboarding: As part of onboarding new developers, provide them with this guide and the pre-generated certificate bundle file to ensure their environment is set up correctly from day one.

   

Reactive Strategies (When Issues Arise)

• Establish a Fast-Track Exception Process: When a developer's workflow is blocked, time is critical. Create a simple and rapid process for requesting an exception, such as a dedicated Slack channel or a high-priority service desk ticket queue. The goal is to unblock the developer first and analyze the root cause later.

   

• Empower the Help Desk: Equip your front-line support with this guide and the troubleshooting steps listed in the appendix. They can often diagnose if an issue is related to a missing CA bundle before escalating to the network security team.

   

• Use Temporary Exceptions: Grant temporary, time-based exceptions to unblock a developer immediately. This provides breathing room to investigate whether a permanent, more narrowly-scoped policy (e.g., for a specific hostname) is required.

   

3. First Steps: Generating Your Certificate Bundle

Before configuring any tools, you must have a PEM-formatted certificate bundle that includes the Netskope Root CA. Below are two methods to generate this file.

How to Find an Existing Bundle File

If you are unsure whether you already have a bundle file, use these commands to search for it.

macOS/Linux:

find ~ /tmp /Library -name "netskope-cert-bundle.pem" -o -name "nscacert*.pem" 2>/dev/null

Windows (PowerShell):

Get-ChildItem -Path C:\ -Recurse -Include "netskope-cert-bundle.pem", "nscacert*.pem" -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName

How to Download a Fresh Bundle from Your Tenant (Recommended)

The certificate bundle is a public, non-encrypted text file. The most reliable method is to generate it directly from your tenant.

Prerequisites:

• Organization ID (orgKey): Navigate to Settings → Security Cloud Platform → MDM Distribution → Organization ID.

• Full Tenant Name (tenantName): This is your tenant's full hostname.

   

Scripted Download (For detailed, step-by-step instructions on how to create and run these scripts, see the Appendix.)

macOS / Linux (Bash):

orgKey="REPLACE_WITH_YOUR_ORG_KEY" tenantName="REPLACE_WITH_YOUR_TENANT_NAME" certName="netskope-cert-bundle.pem" curl -k "https://addon-$tenantName/config/ca/cert?orgkey=$orgKey" > ./$certName curl -k "https://addon-$tenantName/config/org/cert?orgkey=$orgKey" >> ./$certName curl -k -L "https://curl.se/ca/cacert.pem" >> ./$certName

Windows (Command Prompt):

set orgKey=REPLACE_WITH_YOUR_ORG_KEY set tenantName=REPLACE_WITH_YOUR_TENANT_NAME set certName=netskope-cert-bundle.pem curl -k "https://addon-%tenantName%/config/ca/cert?orgkey=%orgKey%" > %certName% curl -k "https://addon-%tenantName%/config/org/cert?orgkey=%orgKey%" >> %certName% curl -k -L "https://curl.se/ca/cacert.pem" >> %certName%

4. Tool-Specific Configuration

AWS CLI / Boto3

• Instruction: export AWS_CA_BUNDLE=/path/to/bundle.pem

• Verification: aws s3 ls

• Bypass Examples: For temporary unblocking, a Netskope admin can add *.amazonaws.com to an SSL bypass list.

   

cURL

• Instruction: export CURL_CA_BUNDLE=/path/to/bundle.pem

• Verification: curl -v https://example.com

Docker

• Instruction: Certificate must be copied into the container image. See Appendix for details.

• Bypass Examples: *.docker.io, *.docker.com

Git

• Instruction (Recommended): git config --global http.sslCAInfo /path/to/bundle.pem

• Verification: git ls-remote https://github.com/git/git

• Bypass Examples: github.com, gitlab.com, dev.azure.com

Google Cloud SDK (gcloud CLI)

• Instruction: gcloud config set core/custom_ca_certs_file /path/to/bundle.pem

• Verification: gcloud auth login

• Bypass Examples: *.googleapis.com

Java / Maven / Gradle

• Instruction (Recommended): Use the $JAVA_OPTS environment variable.

  • Windows: setx JAVA_OPTS "-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT"

  • macOS: export JAVA_OPTS="-Djavax.net.ssl.trustStoreType=KeychainStore"

• Verification: mvn dependency:resolve

• Bypass Examples: repo.maven.apache.org, repo1.maven.org, plugins.gradle.org

Node.js / NPM / Yarn

• Instruction (Recommended): export NODE_EXTRA_CA_CERTS=/path/to/bundle.pem

• Verification: npm install express

• Bypass Examples: registry.npmjs.org, registry.yarnpkg.com

Python / pip

• Instruction: export REQUESTS_CA_BUNDLE=/path/to/bundle.pem

• Verification: pip install requests

• Bypass Examples: pypi.org, files.pythonhosted.org

⚠️ CRITICAL PYTHON 3.13+ CONSIDERATIONS ⚠️

Python 3.13 and newer versions enforce stricter TLS certificate validation standards. This may cause SSL errors when connecting to services through Netskope SSL Decryption, even with a CA bundle configured.

The error often looks like: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Missing Authority Key Identifier. This occurs because some older Netskope tenant CAs may not include certain modern X.509 extensions that Python 3.13+ now requires for validation.

If you cannot downgrade from Python 3.13+, here are the available options:

Option 1: Administrator Configuration (Recommended)

These are the most secure solutions as they do not require developers to alter their code. These actions must be performed by a Netskope administrator.

1. Create an SSL Decryption Bypass Policy: This is the best approach. An administrator can create a policy to exempt essential developer domains (such as package repositories, code hosting sites, and API endpoints) from SSL decryption.

    

   • Action: In the Netskope UI, navigate to Policies > SSL Decryption. Create a new policy to "Bypass" or "Do Not Decrypt" for the required application or domain category.

      

2. Regenerate Tenant Certificates (Long-Term Fix): The underlying issue is that the tenant's SSL interception certificates may be missing modern, required X.509 extensions.

   • Action: Open a ticket with Netskope Support to investigate regenerating your tenant's root and intermediate CAs to comply with stricter RFC standards. This is an involved process but is the ultimate solution.

      

Option 2: Advanced Python Configuration (Client-Side Workaround)

If a policy change is not possible, you can force Python to use a custom SSL context that is less strict. This requires code changes and knowingly reduces the security posture of the specific application.

The following example shows how to use requests with a custom SSLContext that trusts your CA bundle but does not enforce the newer, stricter checks.

import requests import ssl import certifi # Path to the CA bundle file you generated. NETSKOPE_CA_BUNDLE = '/path/to/your/netskope-cert-bundle.pem' class CustomHttpAdapter(requests.adapters.HTTPAdapter): """A custom transport adapter that uses a specific SSLContext.""" def __init__(self, ssl_context=None, **kwargs): self.ssl_context = ssl_context super().__init__(**kwargs) def init_poolmanager(self, connections, maxsize, block=False): # Dynamically import urllib3 poolmanager to avoid early init issues from urllib3.poolmanager import PoolManager self.poolmanager = PoolManager( num_pools=connections, maxsize=maxsize, block=block, ssl_context=self.ssl_context ) def get_legacy_session(ca_bundle_path): """ Creates a requests Session using a custom SSLContext to trust the specified CA bundle without enforcing the strictest checks. """ # Create a context that will trust the default CAs AND our custom one. ctx = ssl.create_default_context( purpose=ssl.Purpose.SERVER_AUTH, cafile=certifi.where() # Start with the standard list of CAs ) # Add the Netskope CA bundle to the context's trust store. ctx.load_verify_locations(cafile=ca_bundle_path) session = requests.Session() session.mount('https://', CustomHttpAdapter(ssl_context=ctx)) return session if __name__ == '__main__': # Use the custom session instead of the default requests.get legacy_session = get_legacy_session(NETSKOPE_CA_BUNDLE) try: # The 'verify' parameter is handled by the session's SSLContext response = legacy_session.get('https://some-developer-service.com') print(f"Success! Status Code: {response.status_code}") except requests.exceptions.SSLError as e: print(f"SSL Error occurred: {e}")

5. Monitoring Client SSL Errors in Advanced Analytics

The transaction log data confirms that the errors reported by Netskope (e.g., HsFailure (error:0A000412:SSL routines::ssl/tls alert bad certificate)) are standard TLS alerts, often derived from OpenSSL libraries. The hexadecimal code (0A000412) corresponds directly to a TLS alert code (TLS_AD_BAD_CERTIFICATE).

You can proactively monitor these errors in Netskope Advanced Analytics to identify problematic applications or domains before users report them.

Step-by-Step Guide to Create a Monitoring Report

1. Navigate to Advanced Analytics: Log into your Netskope tenant and select Advanced Analytics.

2. Select the Data Source: Start a new query using the Transaction Events data source.

3. Add Key Columns: Add the following fields to your query to get a clear picture of the errors:

   • Transaction Events > User

   • Transaction Events > Request Hostname

   • Transaction Events > Client SSL Error

   • Transaction Events > # Events (as the metric)

4. Filter for Relevant Errors:

   • To see all client-side SSL errors, add a filter: Transaction Events > Client SSL Error is not equal to OK.

      

   • To find specific certificate validation issues (like those affecting Python 3.13+), add a filter: Transaction Events > Client SSL Error contains any of bad certificate, certificate unknown, unknown ca.

      

5. Summarize and View Data:

   • Use the Group By function on Transaction Events > Request Hostname and Transaction Events > Client SSL Error.

   • Use Sum on the # Events column.

   • Sort the results by the event count in descending order. This will immediately show you the top domains and users generating the most SSL errors.

      

6. Save and Schedule the Report:

   • Save this query as a report (e.g., "Top Developer SSL Errors").

   • Add the report to a dashboard for ongoing visibility.

   • You can schedule this report to be emailed regularly to the network security and developer support teams, enabling them to proactively create exceptions or reach out to affected users with this guidance.

      

Appendix: Step-by-Step Execution Guide

This section provides detailed instructions for users who need specific guidance on running the scripts and configuring their environment.

Example 1: Generating the Certificate Bundle on macOS / Linux

This example walks through using the curl-based script to create your netskope-cert-bundle.pem file.

Step 1: Open the Terminal Application

• On macOS, press Cmd + Space, type Terminal, and press Enter.

• On a Linux desktop, find the "Terminal" application in your applications menu or press Ctrl + Alt + T.

Step 2: Create the Script File In your Terminal window, you will start in your home directory. We will create a script file here using a simple text editor called nano.

Type the following command and press Enter:

nano generate_bundle.sh

Step 3: Paste and Update the Script Content Copy the entire Bash script block below:

#!/bin/bash # --- UPDATE THESE TWO VALUES --- orgKey="TenantOrgKey_REPLACE_ME" tenantName="FullTenantName_REPLACE_ME.goskope.com" # ----------------------------- certDir=./ certName=netskope-cert-bundle.pem echo "Downloading Netskope certificates for tenant: $tenantName" curl -k "https://addon-$tenantName/config/ca/cert?orgkey=$orgKey" > $certDir/$certName curl -k "https://addon-$tenantName/config/org/cert?orgkey=$orgKey" >> $certDir/$certName echo "Downloading standard CA bundle..." curl -k -L "https://curl.se/ca/cacert.pem" >> $certDir/$certName echo "Bundle creation complete. File saved as: $certDir$certName"

Paste the copied text into the nano editor window.

This is the most important step: Use your arrow keys to move the cursor and replace the placeholder values TenantOrgKey_REPLACE_ME and FullTenantName_REPLACE_ME.goskope.com with your actual Organization ID and Full Tenant Name.

Step 4: Save and Exit the Editor

1. In nano, press Ctrl + O (the letter "O", not zero) to write the file.

2. Press Enter to confirm the filename generate_bundle.sh.

3. Press Ctrl + X to exit nano and return to the command prompt.

Step 5: Make the Script Executable By default, the file you created is just a text file. You need to give your system permission to run it as a program. Type the following command and press Enter:

chmod +x generate_bundle.sh

Step 6: Execute the Script Now, run the script from your current directory. Type the following command and press Enter:

./generate_bundle.sh

Step 7: Verify the Result You will see output messages like "Downloading Netskope certificates..." and "Bundle creation complete." After the script finishes, confirm the bundle file was created by listing the files in your directory. Type ls -l and press Enter. You should see netskope-cert-bundle.pem in the list. This is the file you will point your tools to.

Example 2: Setting Environment Variables on Windows (PowerShell)

This example shows how to permanently set the "master" environment variable in your PowerShell profile so it's available every time you open a new PowerShell window.

Step 1: Open PowerShell Click the Start Menu, type PowerShell, and select "Windows PowerShell". It does not need to be run as an administrator for this task.

Step 2: Check for and Create a PowerShell Profile Your profile is a script that runs every time PowerShell starts. First, check if you already have one. Type the following command and press Enter:

Test-Path $PROFILE

If this returns True, you already have a profile. If it returns False, create one with this command:

New-Item -Path $PROFILE -Type File -Force

Step 3: Open Your Profile in a Text Editor (Notepad) Now that the profile file exists, open it in Notepad. Type the following command and press Enter:

notepad $PROFILE

Step 4: Add the Environment Variable Configuration In the Notepad window, add the following lines. Be sure to replace the placeholder path with the actual path to the netskope-cert-bundle.pem file you created earlier.

# Set the master variable for the Netskope CA bundle # IMPORTANT: Update this path to where you saved your bundle file! $env:NETSKOPE_CA_BUNDLE = "C:\Users\YourUsername\netskope-cert-bundle.pem" # Configure common tools to use the master variable $env:REQUESTS_CA_BUNDLE = $env:NETSKOPE_CA_BUNDLE $env:NODE_EXTRA_CA_CERTS = $env:NETSKOPE_CA_BUNDLE $env:SSL_CERT_FILE = $env:NETSKOPE_CA_BUNDLE $env:AWS_CA_BUNDLE = $env:NETSKOPE_CA_BUNDLE

Step 5: Save and Close Notepad In Notepad, go to File → Save, then close the window.

Step 6: Apply and Verify the Changes The changes will not apply to your current PowerShell session until you "source" the profile. In your PowerShell window, type the following command and press Enter:

PowerShell

. $PROFILE

(Note: The command is a dot, a space, and then $PROFILE)

To verify that the variable is now set, type the following command and press Enter:

PowerShell

echo $env:NETSKOPE_CA_BUNDLE

It should print the path you specified (e.g., C:\Users\YourUsername\netskope-cert-bundle.pem). Now, close and reopen PowerShell. The variables will be set automatically in every new session.