[docs] Note secret redaction behavior in aspire describe

[aspire-repo-bot]

Documents changes from microsoft/aspire#19248

@IEvangelist

Targeting release/13.6 based on the source PR milestone 13.6.

Why

microsoft/aspire#19248 fixes a bug where aspire describe --format json leaked a generated secret parameter (for example, the password created by AddPostgres) in plaintext via the owning resource's own environment variable, even though the redaction already worked correctly for dependent resources. The existing aspire describe docs did not mention secret redaction at all, so there was no place documenting the (now-fixed) guarantee that secret values are always redacted from describe/resources output.

What changed

• src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx: added a note (using the Aside component already imported on the page) explaining that generated secret values are redacted from aspire describe output, and that this applies to the owning resource's own environment variables as well as dependent resources.

Notes

• Only one page was updated; no new pages were created.
• This documents user-facing behavior (what appears in describe/resources output) rather than internal implementation details like SecretRedactionHistory or the dependency-walk mechanics, which are not part of the public docs surface.

Generated by PR Documentation Check for #19248 · auto · 66.5 AIC · ⌖ 15.8 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1499. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[David Pine (IEvangelist)]

🤖 Docs-accuracy review — secret redaction note in aspire describe

Phase A source of truth: microsoft/aspire @ main — SHA bac9a7d64f1bc7b0d1327a166da87f3709729829 (contains the fix commit 5faba087 from microsoft/aspire#19248).

⚠️ Branch note: This PR targets pre/13.6, but microsoft/aspire has no pre/13.6 or release/13.6 branch (the newest release branch there is release/13.5). The 13.6 milestone hasn't branched yet, and the source PR this doc documents — microsoft/aspire#19248 (milestone 13.6) — was merged to main. I therefore used main as the closest applicable source of truth and verified every claim against it.

Phase A — claims: 4 extracted · ✅ 4 verified · ⚠️ 0 verified‑with‑nuance · ❓ 0 unverifiable · ❌ 0 contradicted.

Phase B — doc-tester (blind user): served the PR head locally (Astro dev, http://localhost:4321/reference/cli/commands/aspire-describe/) and exercised 1 route · 🔴 0 critical · 🟡 1 warning · 📝 1 knowledge gap. The new Note callout renders correctly with 0 console errors.

Verdict: 💬 COMMENT — every factual claim matches source; the only items are one optional clarity warning and one behavioral knowledge gap from the blind-user pass.

---

Phase A — Claim verification

The PR adds a single <Aside type="note">. All four factual claims match microsoft/aspire @ main (bac9a7d6).

✅ Verified claims (4) with evidence

#	Claim	Verdict	Evidence (microsoft/aspire @ main bac9a7d6)
C1	Generated secret values are redacted from aspire describe / resources output.	✅ verified	src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs — RedactIfSecretValue (L1215‑1216) returns null when a value matches a resolved secret; applied to every env var at L1129 (Value = RedactIfSecretValue(e.Value, secretParameterValues)). XML doc L1203‑1204: "Redacts an environment variable value … so secrets don't leak through clients (e.g. aspire describe --format json)."
C2	Redaction applies to every resource referencing the secret, including the resource that owns it, so a generated password never appears in plaintext in an env var such as POSTGRES_PASSWORD.	✅ verified	This is precisely what #19248 fixed (commit 5faba087, "Redact owning resource's own secret env var in describe"). Commit message: previously the value was "emitted … in plaintext via the owning resource's own environment variable (e.g. POSTGRES_PASSWORD)." The fix mirrors ParameterProcessor's dependent‑parameter discovery (GetResourceDependenciesAsync) inside GetSecretParametersAsync (AuxiliaryBackchannelRpcTarget.cs L1267‑1355), so the redaction set now includes generated parameters referenced by any resource, including the owner. Matching is value‑based exact‑equality, so it fires regardless of which resource emits the variable.
C3	Resources like PostgreSQL, Redis, and SQL Server generate passwords.	✅ verified	Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs:57, Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs:44, and Aspire.Hosting.Redis/RedisBuilderExtensions.cs:76 each call CreateDefaultPasswordParameter(...), which calls CreateGeneratedParameter(builder, name, secret: true, generatedPassword) (Aspire.Hosting/ParameterResourceBuilderExtensions.cs). Redis XML doc: "If null a random password will be generated."
C4	The Postgres password environment variable is named POSTGRES_PASSWORD.	✅ verified	Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs:24: private const string PasswordEnvVarName = "POSTGRES_PASSWORD";, assigned at L121: context.EnvironmentVariables[PasswordEnvVarName] = postgresServer.PasswordParameter;.

No contradicted or unverifiable claims → no inline claim comments.

---

Phase B — Doc-tester results (blind-user pass)

This phase was run without consulting any source code; the local docs site was the only window into behavior.

Route exercised: /reference/cli/commands/aspire-describe/ (PR head content served from local Astro dev on port 4321).

Summary

Category	Passed	Failed	Warnings
Content accuracy	1	0	1
Rendering (MDX)	1	0	0
CLI / runtime behavior	0	0	0 (see knowledge gap)
Links	n/a — the note adds no links	0	0

Critical issues

None.

Warnings

Warning 1 — the note cites an environment variable, but the page's sample output never shows environment variables.

• Location: /reference/cli/commands/aspire-describe/, new Note callout.
• Issue: The note says secrets "are redacted from the output" and points at the environment variable POSTGRES_PASSWORD, yet the only sample output on the page (the default table under Examples) shows just Name / Type / State / Health / Endpoints — no environment variables. A new reader may not realize that environment variables (and therefore POSTGRES_PASSWORD) appear in the JSON output (--format Json), not the default table, so it isn't obvious where the redaction they're being promised would actually be visible.
• Suggestion (optional): Tie the note to JSON output, e.g. "… redacted from the output (for example, the environment variables emitted by aspire describe --format Json) …".

Passed checks

• Page loads (HTTP 200; title "aspire describe command | Aspire").
• The new <Aside type="note"> compiles and renders as a Starlight Note callout; text is intact, em‑dashes render, and POSTGRES_PASSWORD renders as inline code (screenshot captured).
• Placement is logical — immediately after the existing aspire resources alias tip and before the Arguments heading.
• 0 console errors / 0 console warnings on the page.

Knowledge gap — runtime redaction behavior was not executed

• What I needed to know: whether aspire describe --format Json actually redacts the owning resource's POSTGRES_PASSWORD at runtime.
• Source of my knowledge: not verified in Phase B — accepted at the documentation level only (Phase A independently confirmed it against source).
• User impact: a user on a released GA CLI is running a build from before this fix and could still observe the leak; the documented guarantee holds only on a build that includes the change. Executing the check requires (a) a dev/PR CLI build containing the fix (the 13.6 milestone isn't released yet) and (b) Docker to run a Postgres container — neither was exercised here.
• Recommendation: reasonable to rely on the Phase A source verification for this behavioral claim.

Recommendations

1. Optional clarity tweak connecting "the output" / POSTGRES_PASSWORD to --format Json (Warning 1).
2. No blocking issues — the note is accurate and renders correctly.

---

_{Automated docs-accuracy review · Phase A verified against microsoft/aspire@main bac9a7d6 · Phase B via local doc-tester on the PR head.}

[Adam Ratzman (adamint)]

This is broader than the implementation. Redaction only nulls environment-variable values that exactly match a resolved secret parameter; it is not a general secret scanner, so embedded values such as connection strings are not covered. Could we scope this wording to exact known secret-parameter values?

[David Pine (IEvangelist)]

It's a lot easier when you make real inline suggestions, that can be considered and then either tweaked or applied. Leaving these sorts of general talking points takes a lot longer to think through and finalize.

[David Pine (IEvangelist)]

🤖 Docs-accuracy review — secret redaction note in aspire describe (re-review of updated revision)

Phase A source of truth: microsoft/aspire @ main — SHA 1cdf7d17248ae78ee018abbc314f772ace5e624d (contains the fix commit 5faba087 from microsoft/aspire#19248).

⚠️ Branch note: This PR now targets release/13.6, but microsoft/aspire has no release/13.6 branch yet — the newest release branch there is release/13.5 (all 11 currently-open docs-from-code PRs target release/13.6, so the 13.6 line simply hasn't been branched in the product repo yet). The source PR this documents — microsoft/aspire#19248 (milestone 13.6) — merged to main, which is an allowed source of truth, so I verified every claim there and flag the branch mismatch here rather than block on it.

🔁 Since my last review (at dc233554, which used main): the PR was retargeted from pre/13.6 → release/13.6 and the note was reworded. The new text is more precise ("environment-variable values that exactly match a resolved secret parameter … redacted from every referencing resource") and adds a new caveat — "Secrets embedded within larger values, such as connection strings, are not redacted." I re-verified all claims, including the new caveat, against main.

Phase A — claims: 4 extracted · ✅ 4 verified · ⚠️ 0 verified‑with‑nuance · ❓ 0 unverifiable · ❌ 0 contradicted.

Phase B — doc-tester (blind user): exercised 1 route (/reference/cli/commands/aspire-describe/) on a running local build · 🔴 0 critical · 🟡 1 warning · 📝 1 knowledge gap.

Verdict: 💬 COMMENT — every factual claim matches source (the new connection-string caveat is essentially verbatim from the source XML doc); the only open items are one optional clarity warning and one behavioral knowledge gap carried over from the blind-user pass.

---

Phase A — Claim verification

The PR adds a single <Aside type="note">:

Environment-variable values that exactly match a resolved secret parameter—such as a generated PostgreSQL, Redis, or SQL Server password—are redacted from every referencing resource. Secrets embedded within larger values, such as connection strings, are not redacted.

All four factual claims match microsoft/aspire @ main (1cdf7d17). No contradicted or unverifiable claims → no inline claim comments.

✅ Verified claims (4) with evidence

#	Claim	Verdict	Evidence (microsoft/aspire @ main 1cdf7d17)
C1	Redaction is exact-match: an env-var value is redacted only when it equals a resolved secret parameter value.	✅ verified	src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs L1215‑1216: "a value is redacted only when it is exactly equal to a resolved secret parameter value." Implementation L1223‑1224: RedactIfSecretValue(...) => value is not null && secretParameterValues.Contains(value) ? null : value — a HashSet<string> exact-equality test.
C2	Generated PostgreSQL / Redis / SQL Server passwords are examples of resolved secret parameters.	✅ verified	ParameterResourceBuilderExtensions.cs L432 CreateDefaultPasswordParameter → CreateGeneratedParameter(builder, name, secret: true, generatedPassword). Called by Postgres (PostgresBuilderExtensions.cs L57), Redis (RedisBuilderExtensions.cs L76, special: false), SQL Server (SqlServerBuilderExtensions.cs L44). Postgres emits it as POSTGRES_PASSWORD (PostgresBuilderExtensions.cs L24, L121).
C3	The value is redacted from every referencing resource (including the resource that owns the secret).	✅ verified	GetSecretParametersAsync (L1275‑1359) builds the secret set from parameters "reachable from the application model, including parameters that are only referenced by another resource rather than registered as a top-level resource" — via a recursive dependency walk (GetDependenciesAsync), and its docstring L1280‑1283 names "the password created by AddPostgres". RedactIfSecretValue is then applied to every resource's env vars (L1136). This is exactly what #19248 (5faba087) fixed: the owning resource's own POSTGRES_PASSWORD is now redacted, not just dependents'. (Non-blocking nuance: because matching is value-based, redaction actually fires for any resource emitting that exact value — a superset of "referencing" — so the claim is true, if slightly conservative.)
C4	Secrets embedded within larger values, such as connection strings, are not redacted.	✅ verified (near-verbatim)	AuxiliaryBackchannelRpcTarget.cs L1219‑1220: "A secret embedded as a substring of a larger composed value (e.g. a connection string) is not detected, because only exact-equality matches are redacted." The note's wording mirrors the source XML doc, connection-string example and all.

---

Phase B — Doc-tester results (blind-user pass)

This phase was run without consulting any source code; the docs site was the only window into behavior.

Route exercised: /reference/cli/commands/aspire-describe/, served from a running local aspire.dev frontend (http://localhost:51482). ⚠️ That build does not contain this PR's note (it isn't the PR branch), so I verified the page + the note's rendering-compatibility and evaluated the note's prose as a blind user, but could not render the exact new callout in-context — see the knowledge gap.

Summary

Category	Passed	Failed	Warnings
Content accuracy	1	0	1
Rendering (MDX)	1	0	0
CLI / runtime behavior	0	0	0 (see knowledge gap)
Links	n/a — the note adds no links	0	0

Critical issues

None.

Warnings

Warning 1 — the note promises env-var redaction, but no example output on the page ever shows an environment variable.

• Location: /reference/cli/commands/aspire-describe/, new Note callout.
• Issue: The note guarantees that "environment-variable values … are redacted." Yet the page's only sample output (Example 1) is the default table — Name / Type / State / Health / Endpoints, no env vars — and Example 5 (aspire describe --format Json) shows the command but no sample JSON output. Environment variables (and therefore POSTGRES_PASSWORD) only appear in the JSON output, which the page never renders, so a new reader can't see where the promised redaction would actually be visible. The reworded note ("environment-variable values") is more precise than the previous "the output," but the gap between the promise and what the page shows remains.
• Suggestion (optional): Tie the note to JSON output, e.g. "… redacted from the environment variables emitted by aspire describe --format Json", and/or add a short redacted JSON snippet under Example 5.

Passed checks

• Page loads (HTTP 200; title "aspire describe command | Aspire"); 0 console errors.
• The page already renders an <Aside> (the Tip for the aspire resources alias) as a Starlight callout, so the PR's <Aside type="note"> — the same, already-imported component — will render as a Note callout.
• Placement is logical: immediately after the existing aspire resources alias tip and before the Arguments heading.
• The note introduces no links; existing internal links on the page are site-relative with trailing slashes (/reference/cli/commands/aspire-run/, …/aspire-ps/, …/aspire-wait/, …/aspire-stop/). No broken links introduced.

Knowledge gap — runtime redaction behavior was not executed

• What I needed to know: whether aspire describe --format Json actually redacts the owning resource's POSTGRES_PASSWORD at runtime, and how the exact new note renders in-context.
• Source of my knowledge: not verified in Phase B — the running local build predates the change, and exercising it would require a dev/PR CLI build that includes #19248 plus Docker to run a Postgres container. Neither was run here.
• User impact: a user on a released GA CLI is on a build from before this fix and could still observe the leak; the documented guarantee holds only on a build that includes the change (13.6 hasn't shipped).
• Recommendation: reasonable to rely on the Phase A source verification (C1–C4) for this behavioral claim.

Recommendations

1. Optional clarity tweak connecting the note to --format Json output, ideally with a short redacted JSON sample (Warning 1).
2. No blocking issues — the note is accurate and will render correctly.

---

_{Automated docs-accuracy review · Phase A verified against microsoft/aspire@main 1cdf7d17 (fix 5faba087 / #19248) · Phase B via local doc-tester on /reference/cli/commands/aspire-describe/. Target branch release/13.6 is not yet present in microsoft/aspire (newest release/13.5).}