How to Configure SSL/TLS for Corporate Environments Using the Truststore in Spec-Kit

The Spec-Kit CLI leverages the truststore library to automatically validate HTTPS connections against the operating system's certificate authorities, enabling seamless TLS configuration in corporate environments with custom root CAs.

Configuring SSL/TLS for corporate environments using the truststore ensures that the Spec-Kit CLI can securely connect to internal services and GitHub APIs even when traffic passes through inspection proxies or private certificate authorities. According to the github/spec-kit source code, the tool uses the truststore library to build an SSLContext that respects the host operating system's native certificate store without requiring manual certificate management in Python code.

How Truststore Works in Spec-Kit

The TLS implementation relies on the third-party truststore library (declared as truststore>=0.10.4 in pyproject.toml) to bridge Python's SSL layer with platform-native certificate storage mechanisms. This approach eliminates the need to bundle corporate certificates directly with the application.

SSL Context Initialization

In src/specify_cli/__init__.py (lines 54-59), the CLI constructs a secure transport layer during initialization:

ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
client = httpx.Client(verify=ssl_context)

The truststore.SSLContext class extends the standard library's ssl.SSLContext but automatically loads certificates from:

• Windows: Certificate Store (machine and user contexts)
• macOS: Keychain (System and login keychains)
• Linux: /etc/ssl/certs/ or paths specified by OpenSSL configuration

HTTP Client Integration

The same file (lines 57-58) instantiates httpx.Client with the custom SSL context, ensuring that all subsequent HTTPS requests—including template downloads and GitHub API calls—use the same verification settings derived from the OS trust store.

The --skip-tls Escape Hatch

For environments where certificate verification must be bypassed entirely (documented at lines 1254-1259 in src/specify_cli/__init__.py), the CLI provides a dismissal flag:

specify init my-project --skip-tls

This forces httpx.Client(verify=False) under the hood, disabling all certificate checks. This option is intended solely for debugging in controlled environments.

Configuring Corporate Root Certificates

To enable TLS validation against corporate proxy certificates or internal services, administrators must ensure the root CA certificates are discoverable by the truststore library through one of two methods.

Option 1: Installing Certificates in the OS Trust Store

Add the corporate root or intermediate certificates to the operating system's native trust anchor database:

• Linux: Copy the PEM-encoded certificate to /usr/local/share/ca-certificates/ and execute update-ca-certificates
• macOS: Import the certificate into the System keychain using Keychain Access or the command security add-trusted-cert
• Windows: Import the certificate into "Trusted Root Certification Authorities" via the Certificate Manager (certmgr.msc)

Once installed, the Spec-Kit CLI automatically includes these CAs in its verification chain on the next execution.

Option 2: Using a Custom CA Bundle via Environment Variables

If modifying the OS trust store is not permitted, set the SSL_CERT_FILE environment variable to point to a PEM file containing the corporate certificate bundle:

export SSL_CERT_FILE=/path/to/corporate-ca-bundle.pem
specify init my-project --ai claude

The truststore library also recognizes REQUESTS_CA_BUNDLE as a fallback for compatibility with existing tooling conventions.

Code Examples

Using the Default OS Trust Store

When corporate certificates are properly installed in the system store, no additional configuration is required:

specify init my-project --ai opencode

The CLI automatically detects and trusts the corporate CAs via truststore.SSLContext.

Supplying a Custom PEM Bundle

For scenarios requiring explicit certificate paths without permanent OS installation:

# Set the environment variable for the current session

export SSL_CERT_FILE=/opt/certs/corporate-ca-bundle.pem

# Execute Spec-Kit commands; custom bundle applies to all HTTPS requests

specify check
specify init my-project --ai gemini

Disabling Verification Temporarily

Use this only for troubleshooting in isolated network segments:

specify init my-project --skip-tls

Warning: This disables all certificate validation and exposes connections to potential man-in-the-middle attacks.

Summary

• Automatic OS integration: Spec-Kit uses truststore.SSLContext in src/specify_cli/__init__.py to read certificates from the native OS store without code modifications.
• Environment variable support: Set SSL_CERT_FILE to specify a custom CA bundle when OS store modification is not possible.
• Secure by default: All HTTPS connections through httpx.Client validate against the configured trust anchors unless explicitly bypassed.
• Debug option: The --skip-tls flag (lines 1254-1259) provides a temporary escape hatch but should never be used in production environments.

Frequently Asked Questions

Does Spec-Kit require manual SSL configuration on corporate networks?

No. If corporate root certificates are installed in the operating system's native trust store, Spec-Kit automatically trusts them through the truststore library. Only environments using non-standard certificate deployments require the SSL_CERT_FILE environment variable.

What environment variables does the truststore library recognize?

The implementation recognizes SSL_CERT_FILE as the primary variable for custom CA bundles, with REQUESTS_CA_BUNDLE serving as a compatible alternative. Setting either to a valid PEM file path causes Spec-Kit to include those certificates in its TLS verification process.

Is --skip-tls safe to use in production?

No. This flag disables all certificate verification by passing verify=False to the HTTP client, making connections vulnerable to interception and tampering. Reserve this option strictly for temporary debugging in fully controlled, isolated network environments.

Where is the SSL logic implemented in the Spec-Kit source code?

The TLS configuration resides in src/specify_cli/__init__.py, specifically lines 54-59 where truststore.SSLContext is instantiated and injected into the httpx.Client. The --skip-tls argument handling appears at lines 1254-1259 in the same file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}