From 985d5282d14e6f5fafabb6e2aeaba03d3c7724ed Mon Sep 17 00:00:00 2001
From: vidhu bala <vidhu@kosli.com>
Date: Wed, 6 May 2026 17:04:08 +0100
Subject: [PATCH] docs: expand HTTP proxy tutorial with auth, scope, endpoint
 reference, and k8s reporter

---
 tutorials/cli_and_http_proxy.md | 34 +++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/tutorials/cli_and_http_proxy.md b/tutorials/cli_and_http_proxy.md
index 5ce261c..4e71448 100644
--- a/tutorials/cli_and_http_proxy.md
+++ b/tutorials/cli_and_http_proxy.md
@@ -52,6 +52,12 @@ terraform-state-differ-beta  S3    2024-04-18T15:18:23+02:00  2024-04-18T15:18:2
 terraform-state-differ-prod  S3    2024-04-18T15:18:17+02:00  2024-04-18T15:18:17+02:00
 ```
 
+If your proxy requires authentication, embed the credentials in the proxy URL:
+
+```shell
+kosli list envs --org cyber-dojo --http-proxy http://username:password@proxy-host:8080 --api-token <your-token>
+```
+
 ## Persist the proxy configuration
 
 Rather than passing `--http-proxy` on every command, save it to your Kosli config:
@@ -62,6 +68,34 @@ kosli config --http-proxy=http://localhost:8888
 
 All subsequent CLI commands will now route through the proxy automatically.
 
+## Scope of `--http-proxy`
+
+The `--http-proxy` flag only applies to traffic between the CLI and the Kosli API. Commands that integrate with third-party services (GitHub, GitLab, Jira, SonarCloud/SonarQube, Azure, AWS) use separate HTTP clients that are **not** affected by this flag. To proxy that traffic, set the standard `HTTPS_PROXY` environment variable separately.
+
+The table below shows every external endpoint the CLI may contact and how to proxy each one:
+
+| Destination | Endpoint | Commands | Proxy method |
+|---|---|---|---|
+| Kosli API | `https://app.kosli.com` (configurable via `--host`) | All commands | `--http-proxy` or `HTTPS_PROXY` |
+| GitHub | `https://api.github.com` (configurable via `--github-base-url`) | PR/commit attestations | `HTTPS_PROXY` only |
+| GitLab | `https://gitlab.com` (configurable via `--gitlab-base-url`) | PR attestations | `HTTPS_PROXY` only |
+| Jira | Configured via `--jira-base-url` | Jira attestations | `HTTPS_PROXY` only |
+| SonarCloud/SonarQube | `https://sonarcloud.io` (configurable via `--sonar-server-url`) | Sonar attestations | `HTTPS_PROXY` only |
+| Azure DevOps | Configured via `--azure-org-url` | Azure PR attestations | `HTTPS_PROXY` only |
+| Azure management APIs | Azure ARM/IMDS endpoints | Azure app snapshots | `HTTPS_PROXY` only |
+| AWS APIs | Regional AWS endpoints | ECS / Lambda / S3 snapshots | `HTTPS_PROXY` only |
+| Container registries | OCI registries (ECR, GCR, DockerHub, etc.) | Artifact fingerprinting (`--artifact-type oci`) | `HTTPS_PROXY` only |
+| Kubernetes API server | In-cluster or via kubeconfig | `snapshot k8s` | kubeconfig `proxy-url` or `HTTPS_PROXY` |
+
+## Kubernetes reporter
+
+The `snapshot k8s` command makes two independent outbound connections:
+
+1. **Kubernetes API server** — uses the kubeconfig for connection and authentication. Configure the proxy via the kubeconfig `proxy-url` field or the `HTTPS_PROXY` environment variable.
+2. **Kosli API** — uses the standard Kosli HTTP client, controlled by `--http-proxy`.
+
+These two connections must be configured independently.
+
 ## What you've accomplished
 
 You have set up Tinyproxy as an HTTP proxy and configured the Kosli CLI to route all traffic through it. This pattern works with any HTTP proxy — replace `http://localhost:8888` with your organisation's proxy URL and run `kosli config --http-proxy=<your-proxy-url>` to apply it globally.