libre-devops-helpers 0.4.1__tar.gz → 0.5.0__tar.gz

libre_devops_helpers-0.5.0/.github/copilot-instructions.md

@@ -0,0 +1,14 @@
+# Instructions for GitHub Copilot
+
+This repository's instructions for AI coding assistants are in [`AI.md`](../AI.md) at the
+root (and, word for word, in `AGENTS.md`, which the Copilot coding agent also reads). Read
+`AI.md` before suggesting or making any change here.
+
+The rules that matter most:
+
+- Every command reads; nothing changes a tenant or an instance unless asked.
+- Runtime dependencies are `requests` and `typer` only; the rest is the standard library.
+- Tests never touch the network: use the fakes in `tests/fakes`. Run `just check`.
+- Never hard-code `ldo` or `LDO_`: take names from `core/brand.py`.
+- UK English, and no em or en dashes anywhere.
+- No AI attribution in commits, and nothing is committed until the person asks.

libre_devops_helpers-0.5.0/AGENTS.md

@@ -0,0 +1,118 @@
+<!-- Generated from AI.md by 'just ai'. Edit AI.md, not this file. -->
+
+# Instructions for AI coding assistants
+
+This file is for Claude Code, GitHub Copilot, OpenAI Codex and any other assistant working
+in this repository. It is the one to edit: `AGENTS.md` is generated from it (`just ai`),
+`CLAUDE.md` imports it, and `.github/copilot-instructions.md` points here.
+
+## What this is
+
+`ldo` (distribution `libre-devops-helpers`, import `libre_devops_helpers`): a fast, read-only
+CLI and library for Microsoft (Entra ID, Defender XDR, Intune, Azure, Graph, PIM, Logic Apps,
+Automation) and ServiceNow. Its users are people signing in as themselves, usually through
+the Azure CLI; automation is second. Everything reads, apart from `ldo az use`, which switches
+the Azure CLI's account. Never add a command that changes a tenant or an instance without
+being asked.
+
+## Working here
+
+- Run everything through `just` (or `uv run`): `just check` before calling anything done,
+  `just ci` for all of CI's checks, `just fmt` to format, `just run <args>` to try the CLI.
+- Python 3.11 or later: nothing newer than 3.11 in the code (`just test-311` proves it).
+- ruff, line length 100. Match the surrounding code's naming, comment density and idiom.
+- Runtime dependencies are `requests` and `typer` only. Everything else is the standard
+  library. Do not add a runtime dependency without asking; test-only ones go in the `dev`
+  group.
+
+## Layout and layering
+
+```text
+src/libre_devops_helpers/
+  core/                 vendor-neutral: errors, config, brand, HTTP client, token store,
+                        polling, inputs (CSV and Excel), logging, YAML writer
+  microsoft/            the shared Microsoft layer: clouds, credentials, tokens, profiles
+  microsoft/<feature>/  one package per API: entra, xdr, graph, azure, pim, automation ...
+  microsoft/devices/    the one composite, using entra, xdr and intune
+  servicenow/           the ServiceNow vendor, same shape
+  cli/                  the ldo command: parses, calls a client, renders. No logic here.
+```
+
+`tests/project/test_package_surface.py` enforces the layering: `core` imports nothing of
+ours, a feature imports only `core` and its vendor layer, `cli` sits on top. Cross-cutting
+code (auth, HTTP, input parsing) goes in `core` or the vendor layer, never in a feature. A new
+feature package needs its entry in that test, a `REQUIREMENTS` tuple, and a test folder.
+
+## Tests
+
+- Tests mirror `src` (`tests/core`, `tests/microsoft/<feature>`, `tests/cli/commands`), one
+  test module per module, and `tests/project/test_layout.py` checks it.
+- Nothing touches the network, a real `az` or a real clock. HTTP goes through
+  `tests/fakes/http.py` (`routes`, `fake_session`), `az` through `fakes/azcli.py`, time
+  through `fakes/clock.py`. Shared fakes live in `tests/fakes`, one module per concern.
+- Coverage is gated at 93% (`fail_under` in `pyproject.toml`). Keep new code covered.
+- CI runs with `GITHUB_ACTIONS` set, which makes Typer colour and wrap errors: compare error
+  text with `usage_error(result)`, never a raw substring of `result.output`.
+- Windows caps an environment variable at 32,767 characters and pytest puts each test id in
+  one: give big parametrised values short `ids`.
+- `tests/project/test_rebrand.py` renames a copy of the repository and runs its whole suite.
+
+## Names and branding
+
+The project can be renamed (`just rebrand`). Never hard-code `ldo`, `LDO_` or the package
+name in code: use `core/brand.py` (`brand.COMMAND`, `brand.env_var("X")`,
+`brand.command("config init")`, `brand.docs("page")` for a link to a docs page).
+
+## Writing code
+
+- Library code raises `LdoError` subclasses (`InputError`, `NotFoundError`,
+  `AmbiguousError`, `ApiError`, ...) with a `hint` saying what to do, and never exits. Only
+  the CLI turns errors into messages and exit codes (0 fine, 1 error, 2 usage, 3 needs
+  attention, 130 interrupted).
+- Data goes to stdout; notes, warnings and progress to stderr, through `cli/render.py`
+  (`note`, `warn`, `error`, `emit`). In the `json` and `otlp` log formats those become log
+  records, so never write to stderr directly.
+- Every data command takes `-o table|json|csv` and `-p PROFILE`; lists of names take
+  arguments, `-` for stdin and `-f FILE` with `--column` and `--sheet`.
+- All HTTP goes through `core.http.ApiClient`, which applies `core/network.py` (the proxy
+  and `no_proxy`) and `core/trust.py` (the public roots, the OS store and `ca_bundle`), and
+  `az` runs with the same through `network.subprocess_env()`. Never call `requests` directly.
+- Anything a person types that goes into a URL path or a query is validated first (names,
+  ids, KQL values). A token or secret is never printed (only with an explicit `--raw`), never
+  logged, and never accepted on the command line.
+- Help text is rendered as markdown: no `<`, no `*`, and paragraphs reflow. A test checks.
+- Do not hide findings from a scanner or linter by renaming things; fix the code, or say it
+  is a false positive and why.
+
+## Docs
+
+- `README.md` is a short front page: the command table, install, quickstart and links.
+  Detail goes in `docs/`, one page per area. `CHANGELOG.md` gets an `Unreleased` entry for
+  every change a user would notice.
+- `tests/project/test_docs.py` runs every `ldo` example in the README, `docs/` and this file
+  with `--help`, checks every `just` example is a recipe, and follows every link. Keep
+  examples real.
+- UK English (colour, organisation, licence as a noun). Never use em or en dashes, in any
+  file: use commas, colons, brackets or a plain hyphen.
+
+## Commits and releases
+
+- Do not commit, push, tag or release until the person asks. Use their own git identity.
+- No AI attribution in commits or pull requests: no `Co-Authored-By` or "Generated with"
+  lines.
+- A release is `just release` after the version is set in `pyproject.toml` and
+  `src/libre_devops_helpers/__init__.py` and `CHANGELOG.md` has its section; see
+  `docs/development.md`. Never move or reuse a released tag, and remember a PyPI version can
+  never be replaced.
+
+## Pitfalls already met
+
+- `.gitignore` rules match anywhere unless anchored with `/`; ruff and hatchling honour
+  `.gitignore`, so an ignored folder is silently left out of linting and the wheel.
+- The arm64 image is built under emulation: keep heavy work (such as compiling bytecode) in
+  a `FROM --platform=$BUILDPLATFORM` stage.
+- The Azure CLI pins some dependencies exactly. A fix it holds back is forced in
+  `container/azure-cli/pyproject.toml` (see the comment there), then signed in with.
+- Microsoft APIs return stale duplicates (devices share names), paginate with `nextLink`
+  or `@odata.nextLink`, and answer 403 for a missing scope and a suspended tenant alike: say
+  which in the hint.

libre_devops_helpers-0.5.0/AI.md

@@ -0,0 +1,116 @@
+# Instructions for AI coding assistants
+
+This file is for Claude Code, GitHub Copilot, OpenAI Codex and any other assistant working
+in this repository. It is the one to edit: `AGENTS.md` is generated from it (`just ai`),
+`CLAUDE.md` imports it, and `.github/copilot-instructions.md` points here.
+
+## What this is
+
+`ldo` (distribution `libre-devops-helpers`, import `libre_devops_helpers`): a fast, read-only
+CLI and library for Microsoft (Entra ID, Defender XDR, Intune, Azure, Graph, PIM, Logic Apps,
+Automation) and ServiceNow. Its users are people signing in as themselves, usually through
+the Azure CLI; automation is second. Everything reads, apart from `ldo az use`, which switches
+the Azure CLI's account. Never add a command that changes a tenant or an instance without
+being asked.
+
+## Working here
+
+- Run everything through `just` (or `uv run`): `just check` before calling anything done,
+  `just ci` for all of CI's checks, `just fmt` to format, `just run <args>` to try the CLI.
+- Python 3.11 or later: nothing newer than 3.11 in the code (`just test-311` proves it).
+- ruff, line length 100. Match the surrounding code's naming, comment density and idiom.
+- Runtime dependencies are `requests` and `typer` only. Everything else is the standard
+  library. Do not add a runtime dependency without asking; test-only ones go in the `dev`
+  group.
+
+## Layout and layering
+
+```text
+src/libre_devops_helpers/
+  core/                 vendor-neutral: errors, config, brand, HTTP client, token store,
+                        polling, inputs (CSV and Excel), logging, YAML writer
+  microsoft/            the shared Microsoft layer: clouds, credentials, tokens, profiles
+  microsoft/<feature>/  one package per API: entra, xdr, graph, azure, pim, automation ...
+  microsoft/devices/    the one composite, using entra, xdr and intune
+  servicenow/           the ServiceNow vendor, same shape
+  cli/                  the ldo command: parses, calls a client, renders. No logic here.
+```
+
+`tests/project/test_package_surface.py` enforces the layering: `core` imports nothing of
+ours, a feature imports only `core` and its vendor layer, `cli` sits on top. Cross-cutting
+code (auth, HTTP, input parsing) goes in `core` or the vendor layer, never in a feature. A new
+feature package needs its entry in that test, a `REQUIREMENTS` tuple, and a test folder.
+
+## Tests
+
+- Tests mirror `src` (`tests/core`, `tests/microsoft/<feature>`, `tests/cli/commands`), one
+  test module per module, and `tests/project/test_layout.py` checks it.
+- Nothing touches the network, a real `az` or a real clock. HTTP goes through
+  `tests/fakes/http.py` (`routes`, `fake_session`), `az` through `fakes/azcli.py`, time
+  through `fakes/clock.py`. Shared fakes live in `tests/fakes`, one module per concern.
+- Coverage is gated at 93% (`fail_under` in `pyproject.toml`). Keep new code covered.
+- CI runs with `GITHUB_ACTIONS` set, which makes Typer colour and wrap errors: compare error
+  text with `usage_error(result)`, never a raw substring of `result.output`.
+- Windows caps an environment variable at 32,767 characters and pytest puts each test id in
+  one: give big parametrised values short `ids`.
+- `tests/project/test_rebrand.py` renames a copy of the repository and runs its whole suite.
+
+## Names and branding
+
+The project can be renamed (`just rebrand`). Never hard-code `ldo`, `LDO_` or the package
+name in code: use `core/brand.py` (`brand.COMMAND`, `brand.env_var("X")`,
+`brand.command("config init")`, `brand.docs("page")` for a link to a docs page).
+
+## Writing code
+
+- Library code raises `LdoError` subclasses (`InputError`, `NotFoundError`,
+  `AmbiguousError`, `ApiError`, ...) with a `hint` saying what to do, and never exits. Only
+  the CLI turns errors into messages and exit codes (0 fine, 1 error, 2 usage, 3 needs
+  attention, 130 interrupted).
+- Data goes to stdout; notes, warnings and progress to stderr, through `cli/render.py`
+  (`note`, `warn`, `error`, `emit`). In the `json` and `otlp` log formats those become log
+  records, so never write to stderr directly.
+- Every data command takes `-o table|json|csv` and `-p PROFILE`; lists of names take
+  arguments, `-` for stdin and `-f FILE` with `--column` and `--sheet`.
+- All HTTP goes through `core.http.ApiClient`, which applies `core/network.py` (the proxy
+  and `no_proxy`) and `core/trust.py` (the public roots, the OS store and `ca_bundle`), and
+  `az` runs with the same through `network.subprocess_env()`. Never call `requests` directly.
+- Anything a person types that goes into a URL path or a query is validated first (names,
+  ids, KQL values). A token or secret is never printed (only with an explicit `--raw`), never
+  logged, and never accepted on the command line.
+- Help text is rendered as markdown: no `<`, no `*`, and paragraphs reflow. A test checks.
+- Do not hide findings from a scanner or linter by renaming things; fix the code, or say it
+  is a false positive and why.
+
+## Docs
+
+- `README.md` is a short front page: the command table, install, quickstart and links.
+  Detail goes in `docs/`, one page per area. `CHANGELOG.md` gets an `Unreleased` entry for
+  every change a user would notice.
+- `tests/project/test_docs.py` runs every `ldo` example in the README, `docs/` and this file
+  with `--help`, checks every `just` example is a recipe, and follows every link. Keep
+  examples real.
+- UK English (colour, organisation, licence as a noun). Never use em or en dashes, in any
+  file: use commas, colons, brackets or a plain hyphen.
+
+## Commits and releases
+
+- Do not commit, push, tag or release until the person asks. Use their own git identity.
+- No AI attribution in commits or pull requests: no `Co-Authored-By` or "Generated with"
+  lines.
+- A release is `just release` after the version is set in `pyproject.toml` and
+  `src/libre_devops_helpers/__init__.py` and `CHANGELOG.md` has its section; see
+  `docs/development.md`. Never move or reuse a released tag, and remember a PyPI version can
+  never be replaced.
+
+## Pitfalls already met
+
+- `.gitignore` rules match anywhere unless anchored with `/`; ruff and hatchling honour
+  `.gitignore`, so an ignored folder is silently left out of linting and the wheel.
+- The arm64 image is built under emulation: keep heavy work (such as compiling bytecode) in
+  a `FROM --platform=$BUILDPLATFORM` stage.
+- The Azure CLI pins some dependencies exactly. A fix it holds back is forced in
+  `container/azure-cli/pyproject.toml` (see the comment there), then signed in with.
+- Microsoft APIs return stale duplicates (devices share names), paginate with `nextLink`
+  or `@odata.nextLink`, and answer 403 for a missing scope and a suspended tenant alike: say
+  which in the hint.

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to libre-devops-helpers are recorded here. The project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.5.0
+
+### Added
+
+- Corporate proxy support. Every HTTPS call, and every `az` `ldo` runs, follow one set of
+  rules: loopback and the metadata endpoint always direct, then `no_proxy` and `NO_PROXY`,
+  then `LDO_PROXY_ADDRESS`, the config file's `proxy`, `HTTPS_PROXY` / `HTTP_PROXY` /
+  `ALL_PROXY`, and the operating system's setting. An address without a scheme means
+  `http://`, as for cntlm and Px, which sign in to an NTLM or Kerberos proxy for you.
+- The operating system's certificate store is trusted by default, with the public roots
+  and the config file's `ca_bundle`, in one bundle the Azure CLI is handed as
+  `REQUESTS_CA_BUNDLE` too, so both work behind a TLS-inspecting proxy whose root IT has
+  installed. `LDO_CA_BUNDLE`, `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE` names a bundle to use
+  exactly instead. No new dependency.
+- `ldo network test`: asks Entra ID, Graph, Azure Resource Manager, Defender and each
+  ServiceNow instance (and any `--url`) for an unsigned answer, and says which proxy each
+  call used, which certificates are trusted, and what to try when one fails: a proxy's
+  NTLM sign-in (cntlm or Px), a proxy that is not running, a TLS-inspecting proxy's
+  certificate (with its issuer named), or a local proxy listening on 3128 or 3129.
+- `AI.md`: instructions for AI coding assistants, read by Claude Code (through `CLAUDE.md`),
+  GitHub Copilot (`.github/copilot-instructions.md`, and `AGENTS.md` for its coding agent)
+  and Codex (`AGENTS.md`). `AGENTS.md` is written from it by `just ai`, and a test fails
+  when it falls behind.
+
+### Changed
+
+- The README installs from PyPI (`uv tool install`, `pipx`, `uv pip` or `pip`), with a
+  PyPI badge; installing a tag from GitHub is still shown.
+
+### Fixed
+
+- `ca_bundle` replaced the public roots rather than adding to them, so a host a proxy does
+  not inspect (sign-in often is not) failed to verify, and it never reached the Azure CLI.
+  It now adds to the public roots and the OS store, for both.
+
+
 ## 0.4.1
 
 ### Added

libre_devops_helpers-0.5.0/CLAUDE.md

@@ -0,0 +1 @@
+@AI.md

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/CONTRIBUTING.md

@@ -5,6 +5,10 @@ command or improving the documentation.
 
 ## Workflow
 
+Working with an AI coding assistant? Its instructions are in [AI.md](AI.md), which Claude
+Code, GitHub Copilot and Codex all read (through `CLAUDE.md`, `.github/copilot-instructions.md`
+and `AGENTS.md`). Edit `AI.md` and run `just ai`; a test fails when `AGENTS.md` lags behind.
+
 1. Fork the repository and branch from `main`.
 2. Run `just sync` (or `uv sync`) to create the environment.
 3. Make your change, with tests.

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: libre-devops-helpers
-Version: 0.4.1
+Version: 0.5.0
 Summary: Libre DevOps Helpers: a fast, read-only CLI and importable helpers for Entra ID, Defender XDR, Intune, Azure, Graph, PIM, Logic Apps and ServiceNow, also shipped as a container image.
 Project-URL: Homepage, https://github.com/libre-devops/python-helpers
 Project-URL: Documentation, https://github.com/libre-devops/python-helpers/tree/main/docs
@@ -49,6 +49,7 @@ Description-Content-Type: text/markdown
 [![Container](https://github.com/libre-devops/python-helpers/actions/workflows/container.yml/badge.svg)](https://github.com/libre-devops/python-helpers/actions/workflows/container.yml)
 
 [![Release](https://img.shields.io/github/v/release/libre-devops/python-helpers?label=release&color=1793D1)](https://github.com/libre-devops/python-helpers/releases)
+[![PyPI](https://img.shields.io/pypi/v/libre-devops-helpers?label=pypi&logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/libre-devops-helpers/)
 [![Container images](https://img.shields.io/badge/ghcr.io-python--helpers-2496ED?logo=docker&logoColor=white)](https://github.com/libre-devops/python-helpers/pkgs/container/python-helpers)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&logoColor=white)](https://github.com/libre-devops/python-helpers/blob/main/pyproject.toml)
 [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](https://github.com/libre-devops/python-helpers/blob/main/LICENSE)
@@ -83,6 +84,7 @@ PowerShell module, and importable as a library too.
 | `ldo logicapp` | offline checks, export and validation for Consumption Logic Apps and Sentinel playbooks | [logic apps](https://github.com/libre-devops/python-helpers/blob/main/docs/logic-apps.md) |
 | `ldo snow` | ServiceNow: sign in, whoami, the instance, applications, a token | [servicenow](https://github.com/libre-devops/python-helpers/blob/main/docs/servicenow.md) |
 | `ldo az` | switch the Azure CLI between profiles | [signing in](https://github.com/libre-devops/python-helpers/blob/main/docs/authentication.md) |
+| `ldo network test` | test the way out through a corporate proxy: the proxy, the certificates, each service | [network](https://github.com/libre-devops/python-helpers/blob/main/docs/network.md) |
 | `ldo json` | pretty-print any JSON (`az rest ... \| ldo json`) in colour, or as YAML | [configuration](https://github.com/libre-devops/python-helpers/blob/main/docs/configuration.md#json-yaml-and-logs) |
 | `ldo profiles`, `ldo config` | your profiles, and the config file | [configuration](https://github.com/libre-devops/python-helpers/blob/main/docs/configuration.md) |
 
@@ -93,10 +95,20 @@ arguments, stdin, a text file, or a column of a CSV or Excel workbook.
 
 ## Install
 
+From [PyPI](https://pypi.org/project/libre-devops-helpers/):
+
 ```bash
-uv tool install git+https://github.com/libre-devops/python-helpers@v0.4.1
+uv tool install libre-devops-helpers     # the ldo command, in an environment of its own
+pipx install libre-devops-helpers        # the same, with pipx
+uv pip install libre-devops-helpers      # into the current environment, to use it as a library
+pip install libre-devops-helpers         # the same, with pip
+uv tool upgrade libre-devops-helpers     # later, to the newest release
 ```
 
+Add the `keychain` extra (`"libre-devops-helpers[keychain]"`) to keep sign-ins in the macOS
+Keychain or the Linux Secret Service. A tagged release installs straight from GitHub too:
+`uv tool install git+https://github.com/libre-devops/python-helpers@v0.5.0`.
+
 Or run the container image, which has the Azure CLI inside:
 `podman run --rm -it ghcr.io/libre-devops/python-helpers:latest --help`
 (see [Container images](https://github.com/libre-devops/python-helpers/blob/main/docs/containers.md)).
@@ -135,10 +147,12 @@ for those. [Permissions](https://github.com/libre-devops/python-helpers/blob/mai
 ## Documentation
 
 - [Configuration](https://github.com/libre-devops/python-helpers/blob/main/docs/configuration.md): profiles, common options, environment variables, exit codes
+- [Proxies and certificates](https://github.com/libre-devops/python-helpers/blob/main/docs/network.md): corporate proxies, cntlm, TLS inspection
 - [Signing in](https://github.com/libre-devops/python-helpers/blob/main/docs/authentication.md) and [Permissions](https://github.com/libre-devops/python-helpers/blob/main/docs/permissions.md)
 - [Container images](https://github.com/libre-devops/python-helpers/blob/main/docs/containers.md)
 - [Using it as a library](https://github.com/libre-devops/python-helpers/blob/main/docs/library.md) and [Rebranding](https://github.com/libre-devops/python-helpers/blob/main/docs/rebranding.md) for your organisation
 - [Development](https://github.com/libre-devops/python-helpers/blob/main/docs/development.md): `just` recipes, tests, CI and releasing
+- [AI.md](https://github.com/libre-devops/python-helpers/blob/main/AI.md): the instructions for AI coding assistants (Claude Code, Copilot, Codex)
 
 Contributions are welcome: see [CONTRIBUTING.md](https://github.com/libre-devops/python-helpers/blob/main/CONTRIBUTING.md), and
 [SECURITY.md](https://github.com/libre-devops/python-helpers/blob/main/SECURITY.md) to report a vulnerability. Licensed under [MIT](https://github.com/libre-devops/python-helpers/blob/main/LICENSE).

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/README.md

@@ -17,6 +17,7 @@
 [![Container](https://github.com/libre-devops/python-helpers/actions/workflows/container.yml/badge.svg)](https://github.com/libre-devops/python-helpers/actions/workflows/container.yml)
 
 [![Release](https://img.shields.io/github/v/release/libre-devops/python-helpers?label=release&color=1793D1)](https://github.com/libre-devops/python-helpers/releases)
+[![PyPI](https://img.shields.io/pypi/v/libre-devops-helpers?label=pypi&logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/libre-devops-helpers/)
 [![Container images](https://img.shields.io/badge/ghcr.io-python--helpers-2496ED?logo=docker&logoColor=white)](https://github.com/libre-devops/python-helpers/pkgs/container/python-helpers)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&logoColor=white)](pyproject.toml)
 [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
@@ -51,6 +52,7 @@ PowerShell module, and importable as a library too.
 | `ldo logicapp` | offline checks, export and validation for Consumption Logic Apps and Sentinel playbooks | [logic apps](docs/logic-apps.md) |
 | `ldo snow` | ServiceNow: sign in, whoami, the instance, applications, a token | [servicenow](docs/servicenow.md) |
 | `ldo az` | switch the Azure CLI between profiles | [signing in](docs/authentication.md) |
+| `ldo network test` | test the way out through a corporate proxy: the proxy, the certificates, each service | [network](docs/network.md) |
 | `ldo json` | pretty-print any JSON (`az rest ... \| ldo json`) in colour, or as YAML | [configuration](docs/configuration.md#json-yaml-and-logs) |
 | `ldo profiles`, `ldo config` | your profiles, and the config file | [configuration](docs/configuration.md) |
 
@@ -61,10 +63,20 @@ arguments, stdin, a text file, or a column of a CSV or Excel workbook.
 
 ## Install
 
+From [PyPI](https://pypi.org/project/libre-devops-helpers/):
+
 ```bash
-uv tool install git+https://github.com/libre-devops/python-helpers@v0.4.1
+uv tool install libre-devops-helpers     # the ldo command, in an environment of its own
+pipx install libre-devops-helpers        # the same, with pipx
+uv pip install libre-devops-helpers      # into the current environment, to use it as a library
+pip install libre-devops-helpers         # the same, with pip
+uv tool upgrade libre-devops-helpers     # later, to the newest release
 ```
 
+Add the `keychain` extra (`"libre-devops-helpers[keychain]"`) to keep sign-ins in the macOS
+Keychain or the Linux Secret Service. A tagged release installs straight from GitHub too:
+`uv tool install git+https://github.com/libre-devops/python-helpers@v0.5.0`.
+
 Or run the container image, which has the Azure CLI inside:
 `podman run --rm -it ghcr.io/libre-devops/python-helpers:latest --help`
 (see [Container images](docs/containers.md)).
@@ -103,10 +115,12 @@ for those. [Permissions](docs/permissions.md) lists what each command needs.
 ## Documentation
 
 - [Configuration](docs/configuration.md): profiles, common options, environment variables, exit codes
+- [Proxies and certificates](docs/network.md): corporate proxies, cntlm, TLS inspection
 - [Signing in](docs/authentication.md) and [Permissions](docs/permissions.md)
 - [Container images](docs/containers.md)
 - [Using it as a library](docs/library.md) and [Rebranding](docs/rebranding.md) for your organisation
 - [Development](docs/development.md): `just` recipes, tests, CI and releasing
+- [AI.md](AI.md): the instructions for AI coding assistants (Claude Code, Copilot, Codex)
 
 Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md), and
 [SECURITY.md](SECURITY.md) to report a vulnerability. Licensed under [MIT](LICENSE).

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/docs/README.md

@@ -9,6 +9,7 @@
 | [Configuration](configuration.md) | the config file, profiles, options every command takes, environment variables, exit codes |
 | [Signing in](authentication.md) | the ways to sign in, automation, when a sign-in lapses, keeping a sign-in, your own app registration |
 | [Permissions](permissions.md) | what each command needs, and what the Azure CLI's token covers |
+| [Proxies and certificates](network.md) | corporate proxies, cntlm and Px, TLS inspection, `network test` |
 | [Container images](containers.md) | the images, their tags, running and building them |
 
 ## Commands

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/docs/authentication.md

@@ -41,7 +41,7 @@ permissions:
   id-token: write
   contents: read
 steps:
-  - run: uv tool install git+https://github.com/libre-devops/python-helpers@v0.4.1
+  - run: uv tool install libre-devops-helpers==0.5.0
   - run: ldo --config .github/ldo.toml entra app-credentials -p ci --expiring 30d
 ```
 
@@ -87,7 +87,7 @@ other accounts can read is refused, as ssh refuses a readable key. `keychain` on
 Linux needs the `keychain` extra:
 
 ```bash
-uv tool install "libre-devops-helpers[keychain] @ git+https://github.com/libre-devops/python-helpers@v0.4.1"
+uv tool install "libre-devops-helpers[keychain]"
 ```
 
 ## Your own app registration

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/docs/configuration.md

@@ -15,7 +15,8 @@ or `LDO_CONFIG` points. It is created readable only by you, has a section per ve
 never holds a secret. Unknown keys are rejected, so a typo fails loudly.
 
 ```toml
-# ca_bundle = "~/certs/proxy-ca.pem"   # a CA for every HTTPS call, behind a TLS-inspecting proxy
+# proxy = "127.0.0.1:3128"             # behind a corporate proxy, e.g. cntlm (see network.md)
+# ca_bundle = "~/certs/proxy-ca.pem"   # a TLS-inspecting proxy's root, when not in the OS store
 
 [microsoft]
 default_profile = "prod-tenant"
@@ -49,7 +50,9 @@ A profile is a tenant, optionally pinned to a subscription, with one way of gett
 | `workspace_id` | The Log Analytics workspace for `logs query` without `--workspace`. |
 | `mde_url` | A regional Defender for Endpoint endpoint, e.g. `https://api-eu.securitycenter.microsoft.com`. |
 
-ServiceNow profiles are described in [ServiceNow](servicenow.md#configuration).
+ServiceNow profiles are described in [ServiceNow](servicenow.md#configuration). The
+top-level `proxy`, `no_proxy` and `ca_bundle` apply to every call, and to the Azure CLI; see
+[Proxies and certificates](network.md).
 
 ## Options every command takes
 
@@ -165,6 +168,9 @@ service:
 | `LDO_SERVICE_NAME`, `LDO_TRACE_ID` and the rest | What OTLP logs say about themselves; see [OpenTelemetry logs](#opentelemetry-logs). |
 | `LDO_REAUTH` | When the Azure CLI's sign-in lapses on a terminal: unset asks to sign in again in a browser, `device-code` asks and uses a device code, `off` never asks. |
 | `LDO_TOKEN_CACHE` | Another file for kept sign-ins, e.g. a container volume. |
+| `LDO_PROXY_ADDRESS` | The proxy for `ldo` (and the Azure CLI it runs), winning over `proxy` and `HTTPS_PROXY`, e.g. `127.0.0.1:3129` for cntlm. |
+| `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY` | As every tool reads them. See [Proxies and certificates](network.md). |
+| `LDO_CA_BUNDLE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE` | A CA bundle to use exactly as it is, in place of the public roots with the OS store. |
 | `LDO_NO_BANNER`, `NO_COLOR` | No banner; no colour. The banner only ever shows on a terminal. |
 | `AZURE_CLIENT_SECRET`, `AZURE_FEDERATED_TOKEN_FILE` | For `client-secret` and `workload-identity` profiles, as the Azure SDKs use them. |
 | `SNOW_INSTANCE_URL`, `SNOW_CLIENT_ID`, `SNOW_CLIENT_SECRET`, `SNOW_INSTANCE_USERNAME`, `SNOW_INSTANCE_PASSWORD` | ServiceNow, with or without a config file. |

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/docs/containers.md

@@ -15,12 +15,12 @@ locked in `container/azure-cli`, and no pip, so `az extension add` does not work
 
 | Tag (`-slim` for slim) | Moves? | Meaning |
 | --- | --- | --- |
-| `0.4.1` | to patched rebuilds | that release |
-| `0.4` | yes | the newest 0.4.x |
+| `0.5.0` | to patched rebuilds | that release |
+| `0.5` | yes | the newest 0.5.x |
 | `latest`, `slim` | yes | the newest release |
-| `0.4.1-20260928.57` | never | one build: its date and workflow run |
+| `0.5.0-20260928.57` | never | one build: its date and workflow run |
 
-Pin a stamped tag or a digest for a build that never changes, or `0.4` to take patches as
+Pin a stamped tag or a digest for a build that never changes, or `0.5` to take patches as
 they land. Each image carries a build provenance attestation and an SBOM:
 
 ```bash
@@ -47,6 +47,9 @@ ldo devices check -f plan.xlsx --column FQDN
 With docker, use `--user "$(id -u):$(id -g)"` in place of `--userns`. The `z` option relabels
 mounts for SELinux and does nothing elsewhere.
 
+Behind a corporate proxy, pass it in with `-e LDO_PROXY_ADDRESS=...` (a cntlm on the host is
+at `host.containers.internal`); see [Proxies and certificates](network.md#in-a-container).
+
 `slim` has no Azure CLI. Use it with a `device-code` profile (and a volume at
 `/home/ldo/.local/state/ldo` to keep the sign-in), or for automation with a
 `workload-identity` profile and the job's federated token passed through.

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/docs/development.md

@@ -15,6 +15,7 @@ just run devices check web01   # run ldo from the working tree
 just install               # put the working tree's ldo on PATH
 just lock                  # relock the tool and the image's Azure CLI
 just secrets               # the secret scan, uncommitted changes included (needs gitleaks)
+just ai                    # write AGENTS.md from AI.md, after editing AI.md
 ```
 
 Run `just` for the full list. See [CONTRIBUTING.md](../CONTRIBUTING.md) before opening a pull
@@ -44,8 +45,9 @@ tab; the full scan is kept with each run.
 ## Releasing
 
 1. Set the version in `pyproject.toml` and `src/libre_devops_helpers/__init__.py` (a test
-   keeps them equal), run `just lock`, and turn `## Unreleased` in `CHANGELOG.md` into
-   `## <version>`.
+   keeps them equal), run `just lock`, turn `## Unreleased` in `CHANGELOG.md` into
+   `## <version>`, and move the pinned install lines in the docs to it (a test names any
+   left behind).
 2. Merge to `main` and let CI pass.
 3. `just release`: it checks the tree is clean and in step with `origin/main`, that the
    changelog has the version and the tag is new, then tags and pushes.

libre_devops_helpers-0.5.0/docs/network.md

@@ -0,0 +1,106 @@
+# Proxies and certificates
+
+[Back to the docs](README.md)
+
+Behind a corporate proxy, `ldo` works with the usual settings, and every HTTPS call it makes
+goes the same way as the Azure CLI it runs, so both behave alike.
+
+```bash
+ldo network test                                  # the proxy, the certificates, each service
+ldo network test --url https://intranet.corp.example/health
+LDO_PROXY_ADDRESS=127.0.0.1:3129 ldo network test  # try a proxy before setting it anywhere
+```
+
+`network test` asks Entra ID, Graph, Azure Resource Manager and Defender (in the profile's
+cloud), and each ServiceNow instance configured, for something they answer without a
+sign-in, and expects a 2xx (Defender, which has nothing to show without a token, answers
+401). It shows the proxy each call went through, which certificates are trusted, and when a
+call fails, what to try. It exits 3 when any fails.
+
+## The proxy
+
+Each call takes the first of these that applies:
+
+| | Setting | For |
+| --- | --- | --- |
+| 1 | this machine, and `169.254.169.254` | never a proxy: sign-in redirects to localhost, managed identity |
+| 2 | `no_proxy` in the config file, and `NO_PROXY` | hosts that go direct, e.g. `.corp.example,10.0.0.0/8` |
+| 3 | `LDO_PROXY_ADDRESS` | `ldo` alone, without changing `HTTPS_PROXY` for everything else |
+| 4 | `proxy` in the config file | the same, kept in the file |
+| 5 | `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` | the usual variables, which most tools read |
+| 6 | the operating system's proxy setting | Windows and macOS |
+
+An address without a scheme, such as `127.0.0.1:3128`, means `http://`. Whichever proxy
+applies, the Azure CLI gets it too, as `HTTPS_PROXY` and `NO_PROXY`.
+
+```toml
+proxy = "127.0.0.1:3128"
+no_proxy = ".corp.example, 10.0.0.0/8"
+```
+
+### A proxy that wants NTLM or Kerberos
+
+Corporate proxies often want a sign-in of their own, which a 407 from `network test` shows.
+Neither `ldo` nor the Azure CLI speaks NTLM, so run a small local proxy that does, and point
+`ldo` at it:
+
+- [cntlm](https://cntlm.sourceforge.net/): set `Username`, `Domain` and `Proxy` in
+  `cntlm.conf`, then `cntlm -H` for the password hashes and `cntlm -I -M
+  https://graph.microsoft.com` to test them. It listens on `127.0.0.1:3128` unless its
+  `Listen` line says otherwise.
+- [Px](https://github.com/genotrance/px): the same on Windows, signing in as you with no
+  password stored.
+
+```bash
+export LDO_PROXY_ADDRESS=127.0.0.1:3129    # wherever cntlm or Px listens
+ldo network test
+```
+
+When nothing is set and a call cannot get out, `network test` looks for something listening
+on 3128 or 3129 and suggests it. A 407 from a local proxy means it could not sign in
+upstream: check its credentials.
+
+Automatic proxy scripts (PAC and WPAD files) are not read: name the proxy instead.
+
+## Certificates
+
+A TLS-inspecting proxy re-signs every site with its own certificate. By default `ldo` trusts
+three sets together, so it works where IT has installed that certificate on the machine:
+
+- the public roots,
+- the operating system's store: the Windows certificate store, the macOS system keychains,
+  or the Linux system bundle,
+- and any the config file's `ca_bundle` adds.
+
+They are combined into one file in your cache folder (`~/.cache/ldo`, or
+`%LOCALAPPDATA%\ldo\cache`), which the Azure CLI is handed as `REQUESTS_CA_BUNDLE`, so both
+trust the same. The OS store only ever adds trust: public certificates still verify.
+
+```toml
+ca_bundle = "~/certs/corp-root.pem"   # the proxy's root, when it is not in the OS store
+```
+
+To use one bundle exactly as it is instead, nothing added, name it with `LDO_CA_BUNDLE`
+(or the standard `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE`):
+
+```bash
+export LDO_CA_BUNDLE=/etc/corp/ca-bundle.pem
+```
+
+When a certificate does not verify, `network test` names who issued it: a proxy's own name
+(Zscaler, Netskope, a company CA) shows it is inspecting traffic.
+
+## In a container
+
+The container's `127.0.0.1` is the container itself, so reach a cntlm on the host through
+the host's name, and make cntlm listen where the container can reach it (`Listen 0.0.0.0:3129`,
+with `Allow` set to the container network):
+
+```bash
+podman run --rm -it -e LDO_PROXY_ADDRESS=host.containers.internal:3129 \
+  ghcr.io/libre-devops/python-helpers:latest network test
+```
+
+With docker, use `host.docker.internal` (on Linux, add `--add-host
+host.docker.internal:host-gateway`). The image's own store is Debian's: mount a corporate
+root and set `LDO_CA_BUNDLE`, or `ca_bundle` in a mounted config, when the proxy inspects TLS.

{libre_devops_helpers-0.4.1 → libre_devops_helpers-0.5.0}/justfile

@@ -24,6 +24,11 @@ lock:
     uv lock
     uv lock --project container/azure-cli
 
+# Write AGENTS.md from AI.md, the instructions every AI coding assistant reads
+[group('setup')]
+ai:
+    uv run --no-sync python scripts/ai_instructions.py
+
 # Run ldo from the working tree, e.g. just run devices check web01
 [group('run')]
 run *args: