fix(toolkit): honor HTTPS_PROXY when installing the CLI; docs: close three documentation gaps

[DimaBir]

Addresses four open issues: one behavioral fix and three documentation gaps.

fix(toolkit): honor HTTPS_PROXY and NO_PROXY when downloading the MSDO CLI

Fixes #61.

resolveRequestOptions in msdo-nuget-client.js returned request options with no agent, and both https.request call sites — the NuGet service-index/metadata lookup and the .nupkg download — inherited that. Node's https does not read proxy environment variables on its own, so on a runner behind an egress proxy the install reached out directly and hung or failed, regardless of HTTPS_PROXY being set.

This adds resolveProxyAgent(url), which reuses @actions/http-client's getProxyUrl for env-var and NO_PROXY resolution and builds a tunnel agent, then assigns it at both call sites. Behavior is unchanged when no proxy is configured — getProxyUrl returns undefined and options['agent'] stays unset, so requests take exactly the path they take today. A proxy environment variable that is not a valid URL (HTTPS_PROXY=10.0.0.5:3128, no scheme) also falls back to a direct connection rather than failing the install.

Both @actions/http-client and tunnel are already present and committed under node_modules/, so the new requires resolve without a dependency change.

Caveat. msdo-nuget-client.js lives under node_modules/ but is committed — only five toolkit files are tracked — so this is effective at runtime. It will be lost on the next bump of @microsoft/security-devops-actions-toolkit. The same fix needs to land upstream in microsoft/security-devops-actions-toolkit, where @actions/http-client and tunnel should also be declared dependencies rather than relying on the consumer's tree. The upstream fix would also cover the equivalent Azure DevOps task reports.

docs: bundled tool versions track the MSDO CLI release

Fixes #267.

The README claimed MSDO "installs the latest versions of static analysis tools". It does not — third-party tool binaries ship as redist packages pinned to a CLI release, so a version published upstream is only picked up once a CLI release bundling it exists. The claim set an expectation the action cannot meet. Reworded, with an explicit note under the tools table.

docs: document existingFilename

Fixes #36.

existingFilename has been declared in action.yml since the input was added and maps to upload --file, but appears in zero markdown files, so the "can I publish SARIF from another tool?" question had no discoverable answer. Documents it, including that it short-circuits the analyzer run and does not set the sarifFile output.

docs: explain tool selection and the container-mapping exception

Fixes #135.

Adds a "How tools are selected" section covering the tools-set vs tools-unset paths and the container-mapping asymmetry: it is implemented by this action's pre/post steps rather than by the CLI, is filtered out of --tool in src/v1/msdo.ts, and its pre/post steps run on every use of the action regardless of tools. The content-based selection logic itself lives in the closed-source CLI, and the section says so rather than guessing at per-tool trigger conditions.

Validation

npm run buildAndTest could not be run in the authoring environment — devDependencies are not installed and the npm registry fails the TLS handshake there. No src/v1/*.ts file is touched, so the committed lib/ does not need regenerating; CI covers the build.

For the JS change:

• node --check on msdo-nuget-client.js — passes.
• Module loads and both new requires resolve from the toolkit directory.
• resolveProxyAgent exercised directly against the real vendored tunnel and @actions/http-client/lib/proxy, 11/11 cases: no proxy env (returns undefined, direct); HTTPS_PROXY over http; lowercase https_proxy; HTTPS_PROXY over https (httpsOverHttps); proxy with credentials (proxyAuth populated); NO_PROXY matching the target host (bypass); NO_PROXY not matching (proxied); HTTP_PROXY alone correctly ignored for an https target; malformed HTTPS_PROXY (direct); scheme-less HTTPS_PROXY (direct); proxy URL without an explicit port.

[Copilot]

Pull request overview

This PR fixes MSDO CLI installation behind egress proxies by explicitly honoring HTTPS_PROXY/NO_PROXY when downloading from NuGet, and updates documentation to remove an inaccurate “latest tools” claim and fill gaps around SARIF upload and tool selection behavior.

Changes:

• Add proxy-aware HTTPS agents (via @actions/http-client proxy resolution + tunnel) for NuGet metadata and package downloads in the toolkit’s NuGet client.
• Update README wording to clarify bundled tool versions track the installed MSDO CLI release.
• Document the existingFilename input and explain how tool selection works (including the container-mapping exception).

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

File	Description
README.md	Clarifies tool version pinning, documents existingFilename, and explains tool-selection behavior including container-mapping.
node_modules/@microsoft/security-devops-actions-toolkit/msdo-nuget-client.js	Ensures HTTPS downloads during CLI install can route through configured proxies by setting an appropriate agent on requests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.