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

> Configure SSL/TLS for corporate environments with Spec-Kit. Seamlessly validate HTTPS connections using the truststore library and custom root CAs for enhanced security.

- Repository: [GitHub/spec-kit](https://github.com/github/spec-kit)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/github/spec-kit/blob/main/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`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) (lines 54-59), the CLI constructs a secure transport layer during initialization:

```python
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`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py)), the CLI provides a dismissal flag:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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:

```bash
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`](https://github.com/github/spec-kit/blob/main/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`](https://github.com/github/spec-kit/blob/main/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.