Skip to content

Verify TLS against the OS trust store in the remaining notebooks - #21

Open
frozer wants to merge 3 commits into
victorsteeb:mainfrom
frozer:tls-fix-2
Open

Verify TLS against the OS trust store in the remaining notebooks#21
frozer wants to merge 3 commits into
victorsteeb:mainfrom
frozer:tls-fix-2

Conversation

@frozer

@frozer frozer commented Jul 27, 2026

Copy link
Copy Markdown

What

Commit 8548dd2 wired truststore into day1/02_developer-platform/Developer_Platform.ipynb and added it to requirements.txt. This PR extends the same fix to the remaining four exercise notebooks:

  • day1/03_prompt-rescue/Prompt_Rescue_solo.ipynb
  • day1/04_diagnosing-ai-problems/Diagnose_Fix_Brief.ipynb
  • day2/01_evals/Building_an_Eval.ipynb
  • day2/02_inference-optimization/Inference_Optimization.ipynb

Why

anthropic/httpx verify TLS against the certifi bundle, which does not contain a corporate root CA. Behind a TLS-inspecting proxy (Zscaler and friends) every notebook fails on the first API call with CERTIFICATE_VERIFY_FAILED. truststore.inject_into_ssl() switches verification to the OS certificate store, where the corporate root is already trusted by IT.

How

Each setup cell now opens with, before the Anthropic client is constructed:

try:
    import truststore
    truststore.inject_into_ssl()
    print("✓ TLS: verifying against the OS certificate store")
except Exception as _tls_exc:  # Python < 3.10, or the install was blocked
    print("[!!] truststore unavailable (" + type(_tls_exc).__name__ + ") - falling back "
          "to certifi. If the API check below fails with a certificate error, see SETUP.md.")

The try/except keeps the notebooks working unchanged for anyone not behind a proxy, and on Python < 3.10 where truststore is unavailable.

Diff noise

Saving through Jupyter normalised these four files to canonical nbformat key order (cells / metadata / nbformat last) and split single-string source fields into line lists. That accounts for most of the +235/-153. No cell content changed apart from the TLS block. All five notebooks still parse as valid JSON.

Also in this PR

  1. truststore is now installed by the notebooks themselves. All four
    _ensure_packages([...]) calls gained ("truststore", "truststore"), in the same
    position after anthropic that Developer_Platform.ipynb uses. Without this, a Colab
    or fresh-kernel run never installed the shim and fell straight through to the certifi
    path — the exact scenario this PR targets.
  2. SETUP.md gained a CERTIFICATE_VERIFY_FAILED section, which the fallback message
    points at. It explains why TLS inspection defeats certifi, how to read the
    [!!] truststore unavailable diagnostic (ModuleNotFoundError = wrong kernel/not
    installed; anything else = Python < 3.10), and why verify=False / PYTHONHTTPSVERIFY=0
    is the wrong reflex, with SSL_CERT_FILE against an IT-supplied root CA as the
    supported alternative.

Testing

  • All five notebooks validated with json.load after each edit.
  • Not executed end-to-end against the API, and not yet validated from behind an actual
    TLS-inspecting proxy.

frozer and others added 3 commits July 27, 2026 16:22
Verify TLS against the OS trust store
8548dd2 wired truststore into Developer_Platform.ipynb and added it to
requirements.txt. Do the same for the other four exercises, so a corporate
TLS-inspecting proxy (Zscaler et al.) doesn't break them either.

Each setup cell now calls truststore.inject_into_ssl() before the Anthropic
client is constructed, wrapped in a try/except that falls back to certifi
with an explanatory message on Python < 3.10 or when the install was blocked.

Saving through Jupyter also normalised these four files to canonical nbformat
key order and split single-string `source` fields into line lists. That is the
bulk of the diff; no cell content changed apart from the TLS block.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two gaps left open by the previous commit.

The four notebooks imported truststore but never installed it: only
Developer_Platform.ipynb listed it in _ensure_packages. Anyone running them
in Colab or a fresh kernel without `pip install -r requirements.txt` landed
on the certifi fallback — exactly the corporate-proxy case the shim exists
to fix. Add ("truststore", "truststore") to each bootstrap list, keeping the
same position after anthropic that Developer_Platform.ipynb uses.

The fallback message tells readers to see SETUP.md, which said nothing about
certificates. Add a CERTIFICATE_VERIFY_FAILED section covering why TLS
inspection breaks certifi, how to read the "[!!] truststore unavailable"
diagnostic, and — since it is the first thing people reach for — why not to
disable verification, with SSL_CERT_FILE against an IT-supplied root CA as
the supported alternative.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant