Project 23: “The Corporate Proxy Navigator” — Enterprise Networking

Attribute Value
File KIRO_CLI_LEARNING_PROJECTS.md
Main Programming Language Env Vars / Certs
Coolness Level Level 2: Practical
Difficulty Level 3: Advanced
Knowledge Area Enterprise Networking

What you’ll build: Configure Kiro to use HTTPS_PROXY and trust a custom root CA.

Why it teaches Enterprise Readiness: Most enterprise failures happen here.

Success criteria:

  • Kiro can reach LLM endpoints through the proxy.

Real World Outcome

You’ll configure Kiro to work in a corporate environment with an HTTPS proxy and custom SSL certificates. When you run Kiro, it will successfully connect to Anthropic’s API through the corporate proxy without certificate errors.

Example Configuration:

# Set proxy environment variables
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.local

# Trust custom root CA (macOS)
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  /path/to/company-root-ca.crt

# Trust custom root CA (Linux)
sudo cp /path/to/company-root-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Verify proxy connectivity
curl -I https://api.anthropic.com/v1/messages
# HTTP/1.1 200 OK (via proxy)

# Run Kiro (should work without certificate errors)
kiro "list files in current directory"

Output you’ll see:

$ kiro "analyze the recent commits"

✓ Connected to Anthropic API via proxy.company.com:8080
✓ SSL certificate verified (CN=proxy.company.com, Issuer=CompanyRootCA)

Analyzing commits...
[Output shows Kiro successfully working through the proxy]

Troubleshooting verification:

# Verify certificate chain
openssl s_client -connect api.anthropic.com:443 -proxy proxy.company.com:8080 \
  -showcerts 2>&1 | grep -A 2 "Verify return code"
# Verify return code: 0 (ok)

# Test proxy authentication (if required)
export HTTPS_PROXY=http://username:password@proxy.company.com:8080

# Debug SSL handshake
SSL_DEBUG=true kiro "test command"

You’re configuring the same environment that 80% of enterprise developers face daily.

The Core Question You’re Answering

“Why does my LLM tool work at home but fail at the office, and how do I make it work behind a corporate proxy with SSL inspection?”

Before you configure anything, understand this: Corporate networks intercept HTTPS traffic for security monitoring. Your computer sees a certificate signed by “CompanyRootCA” instead of the real website’s certificate. Without trusting that CA, every HTTPS connection fails with “certificate validation error.”

The proxy configuration and CA trust setup are not optional workarounds—they’re the standard way enterprise tools connect to the internet.

Concepts You Must Understand First

Stop and research these before configuring:

  1. HTTPS Proxies and CONNECT Method
    • How does an HTTPS proxy tunnel encrypted traffic?
    • What is the HTTP CONNECT method and why is it used for HTTPS?
    • How does the client maintain end-to-end encryption through the proxy?
    • Book Reference: “Computer Networks” by Andrew S. Tanenbaum - Ch. 7 (Application Layer)
  2. SSL/TLS Certificate Chains and Trust
    • What is a certificate chain (root CA → intermediate CA → leaf certificate)?
    • How does the OS certificate store work (System.keychain on macOS, /etc/ssl/certs on Linux)?
    • What happens during SSL inspection (man-in-the-middle by the proxy)?
    • Book Reference: “Serious Cryptography” by Jean-Philippe Aumasson - Ch. 13 (TLS)
  3. Environment Variables and Tool Configuration
    • What is the precedence order (HTTPS_PROXY vs https_proxy vs tool-specific config)?
    • How does NO_PROXY prevent proxy usage for internal domains?
    • Why do some tools ignore environment variables (and how to configure them)?
    • Book Reference: “The Linux Programming Interface” by Michael Kerrisk - Ch. 6 (Environment)
  4. Proxy Authentication (Basic, NTLM, Kerberos)
    • How does Basic Auth work (username:password in URL)?
    • What is NTLM authentication and why is it used in Windows environments?
    • How does Kerberos Single Sign-On (SSO) work with proxies?
    • Book Reference: “TCP/IP Illustrated, Volume 1” by W. Richard Stevens - Ch. 18 (HTTP)
  5. Debugging Network Connectivity
    • How do you trace SSL handshake failures (openssl s_client)?
    • How do you verify proxy connectivity (curl -I -x)?
    • How do you capture and analyze HTTPS traffic (mitmproxy, Wireshark)?
    • Book Reference: “Practical Packet Analysis” by Chris Sanders - Ch. 5 (HTTP/HTTPS)
  6. Certificate Pinning and Bypass Strategies
    • What is certificate pinning and why do some tools use it?
    • How do you disable pinning for enterprise proxies (NODE_TLS_REJECT_UNAUTHORIZED)?
    • What are the security risks of disabling certificate validation?
    • Book Reference: “Security Engineering” by Ross Anderson - Ch. 21 (Network Attacks)

Questions to Guide Your Design

Before configuring, think through these:

  1. Proxy Discovery and Configuration
    • How do you automatically detect the corporate proxy (PAC file, WPAD)?
    • Should you use environment variables or tool-specific config files?
    • How do you handle proxy authentication without exposing credentials?
    • What happens when you VPN into the network vs. are physically on-site?
  2. Certificate Trust Strategy
    • Should you trust the root CA system-wide or per-application?
    • How do you export the root CA from the browser (Chrome, Firefox)?
    • What format does the certificate need to be (PEM, DER, PKCS#12)?
    • How do you update the certificate when it rotates annually?
  3. Handling Proxy Failures
    • How do you detect when the proxy is unreachable (timeout vs. connection refused)?
    • Should you fall back to direct connection, or fail fast?
    • How do you handle 407 Proxy Authentication Required errors?
    • What logging helps diagnose proxy issues quickly?
  4. NO_PROXY Configuration
    • Which domains should bypass the proxy (.company.local, localhost, 127.0.0.1)?
    • How do you handle wildcard domains (*.internal.company.com)?
    • Should you bypass the proxy for local development servers?
    • How do you test that NO_PROXY is working correctly?
  5. Cross-Platform Compatibility
    • How do you make the same config work on macOS, Linux, and Windows?
    • Where does each OS store trusted root certificates?
    • How do you handle case sensitivity (HTTPS_PROXY vs https_proxy on Windows)?
    • What about containerized environments (Docker, Kubernetes)?

Thinking Exercise

Trace an HTTPS Request Through a Corporate Proxy

Before configuring anything, manually trace how an HTTPS request flows through a corporate proxy with SSL inspection:

Client                 Proxy                Destination
  |                      |                       |
  |-- HTTP CONNECT api.anthropic.com:443 ------>|
  |                      |                       |
  |<-------- 200 Connection Established --------|
  |                      |                       |
  |-- TLS ClientHello -->|                       |
  |    (SNI: api.anthropic.com)                  |
  |                      |                       |
  |<-- TLS ServerHello --|                       |
  |    (Cert: CN=api.anthropic.com,             |
  |     Issuer=CompanyRootCA)                    |
  |                      |                       |
  |-- TLS Finished ----->|                       |
  |                      |-- TLS ClientHello --->|
  |                      |    (SNI: api.anthropic.com)
  |                      |                       |
  |                      |<-- TLS ServerHello ---|
  |                      |    (Cert: CN=api.anthropic.com,
  |                      |     Issuer=Let's Encrypt)
  |                      |                       |
  |-- HTTP Request ----->|-- HTTP Request ------>|
  |    (encrypted by     |    (re-encrypted by   |
  |     client-proxy TLS)|     proxy-server TLS) |
  |                      |                       |

Questions while tracing:

  • At what point does the client see the fake certificate signed by CompanyRootCA?
  • Why does the proxy need to decrypt and re-encrypt the traffic (SSL inspection)?
  • What would happen if CompanyRootCA is not trusted by the client?
  • How does the client verify the hostname matches (SNI vs. certificate CN)?
  • Why doesn’t the client see the real Let’s Encrypt certificate?

Manual test:

# 1. Try without trusting the CA (should fail)
curl https://api.anthropic.com/v1/messages -I
# curl: (60) SSL certificate problem: unable to get local issuer certificate

# 2. Export the proxy's CA certificate from Chrome
#    Settings → Privacy and security → Security → Manage certificates
#    → Authorities → Export "CompanyRootCA"

# 3. Trust the CA and retry
export SSL_CERT_FILE=/path/to/company-root-ca.crt
curl https://api.anthropic.com/v1/messages -I
# HTTP/1.1 200 OK (via proxy)

The Interview Questions They’ll Ask

Prepare to answer these:

  1. “Why do HTTPS connections fail with ‘certificate validation error’ behind a corporate proxy, even though the proxy is configured correctly?”

  2. “What is the difference between HTTP_PROXY and HTTPS_PROXY environment variables, and when is each used?”

  3. “A user reports that some tools work through the proxy but others don’t. How would you diagnose this?”

  4. “How do you securely configure proxy authentication without hardcoding credentials in environment variables?”

  5. “What is a PAC (Proxy Auto-Config) file, and how does it differ from manually setting HTTPS_PROXY?”

  6. “Why should you never set NODE_TLS_REJECT_UNAUTHORIZED=0 in production, even if it ‘fixes’ the certificate error?”

Hints in Layers

Hint 1: Start with Proxy Discovery Use the browser’s network settings to find the proxy configuration. On Windows, check “Internet Options → Connections → LAN Settings.” On macOS, check “System Preferences → Network → Advanced → Proxies.”

Hint 2: Test Connectivity Before Configuring Kiro First verify that curl works through the proxy. If curl fails with certificate errors, no amount of Kiro configuration will help—you need to fix the CA trust issue first.

Hint 3: Export and Inspect the Certificate Use openssl s_client to see the actual certificate chain:

openssl s_client -connect api.anthropic.com:443 -proxy proxy.company.com:8080 -showcerts

Look for “Issuer: CN=CompanyRootCA” (not “Issuer: Let’s Encrypt”). That certificate needs to be trusted.

Hint 4: Platform-Specific CA Trust Commands Each OS has a different way to trust certificates:

  • macOS: security add-trusted-cert
  • Linux (Debian/Ubuntu): Copy to /usr/local/share/ca-certificates/ and run update-ca-certificates
  • Linux (RHEL/CentOS): Copy to /etc/pki/ca-trust/source/anchors/ and run update-ca-trust
  • Node.js/Python tools: May need NODE_EXTRA_CA_CERTS or REQUESTS_CA_BUNDLE

Books That Will Help

Topic Book Chapter
HTTPS Proxies “Computer Networks” by Tanenbaum Ch. 7 (Application Layer)
SSL/TLS Internals “Serious Cryptography” by Aumasson Ch. 13 (TLS)
Certificate Chains “Bulletproof SSL and TLS” by Ivan Ristić Ch. 4 (PKI)
Environment Variables “The Linux Programming Interface” by Kerrisk Ch. 6 (Environment)
Debugging HTTPS “TCP/IP Illustrated, Vol. 1” by Stevens Ch. 18 (HTTP)
Network Troubleshooting “Practical Packet Analysis” by Sanders Ch. 5 (HTTP/HTTPS)

Common Pitfalls & Debugging

Problem 1: “curl: (60) SSL certificate problem: unable to get local issuer certificate”

  • Why: The corporate proxy is presenting a certificate signed by an untrusted root CA.
  • Fix: Export the root CA from your browser and add it to the system trust store.
  • Quick test: openssl s_client -connect api.anthropic.com:443 -proxy proxy.company.com:8080 -showcerts | grep Issuer

Problem 2: “Proxy authentication required (407)”

  • Why: The proxy requires username/password, but none was provided.
  • Fix: Add credentials to the proxy URL: export HTTPS_PROXY=http://username:password@proxy.company.com:8080
  • Quick test: curl -I -x http://username:password@proxy.company.com:8080 https://api.anthropic.com

Problem 3: “Connection timeout when accessing internal domains”

  • Why: Internal domains should bypass the proxy, but NO_PROXY is not configured.
  • Fix: export NO_PROXY=localhost,127.0.0.1,.company.local,*.internal.company.com
  • Quick test: curl -I http://internal.company.local (should connect directly, not via proxy)

Problem 4: “Works in browser but not in terminal”

  • Why: The browser uses the OS proxy settings, but terminal tools use environment variables.
  • Fix: Set HTTPS_PROXY in your shell profile (~/.bashrc, ~/.zshrc).
  • Quick test: echo $HTTPS_PROXY (should show the proxy URL)

Problem 5: “Certificate works for curl but not for Node.js tools”

  • Why: Node.js uses its own certificate store, separate from the OS.
  • Fix: export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.crt
  • Quick test: node -e "require('https').get('https://api.anthropic.com', r => console.log(r.statusCode))"

Problem 6: “Proxy works on-site but fails when VPNed from home”

  • Why: VPN routing may bypass the proxy, or the proxy may only be accessible on the internal network.
  • Fix: Check if the VPN provides split-tunnel (some traffic via VPN, some direct) or full-tunnel routing.
  • Quick test: curl -I https://api.anthropic.com (compare response headers on-site vs. VPN)

Definition of Done

  • Kiro successfully connects to Anthropic API through the corporate proxy
  • No SSL certificate validation errors appear
  • Internal company domains bypass the proxy (via NO_PROXY)
  • Proxy authentication (if required) works without exposing credentials in shell history
  • Configuration persists across terminal sessions (added to shell profile)
  • Works consistently on macOS, Linux, and Windows (if multi-platform team)
  • Fallback mechanism exists if proxy is unreachable (manual switch or direct connection)
  • Documentation includes troubleshooting steps for common certificate errors
  • Tested with both Kiro and curl to ensure system-wide proxy configuration
  • No hardcoded credentials in config files (use keychain or environment variables)