Secure Software Development / Intermediate: implementation boundaries and verification / Lesson 11

Keep secrets out of code and diagnostics

Review secret purpose, scope, retrieval, rotation, revocation, and accidental disclosure without using credentials.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish public configuration, secret references, and secret values.
Design diagnostic allowlists and lifecycle evidence without exposing sensitive data.

Classify a value by the authority it grants

A secret is sensitive because possession can grant authority or reveal protected information, not because a field happens to contain the word token. Public configuration, an identifier for a secret, and the secret value itself need different handling. In the workshop service, a report format is public configuration while a service credential would grant a capability. This lesson uses explicit public classroom markers and metadata only. Do not paste a real key into a test, ticket, chat, or diagnostic record to make the example realistic. A reference may also reveal internal structure, so review its disclosure context.

Plan the entire authority lifecycle

A secret design needs an owner, narrowly scoped use, approved retrieval boundary, rotation, revocation, and failure behavior. Merely moving a value from source code to an environment variable does not solve access, logging, inheritance, or lifecycle questions. Prefer the platform’s reviewed secret mechanism and avoid building a custom vault in application code. The first record is deliberately non-runnable lifecycle metadata. It contains no value to retrieve and performs no administrative operation. A real rotation plan must consider consumers, overlap where justified, rollback implications, and evidence that old authority is actually removed.

json A fictional secret-lifecycle plan with no secret value

{"capability":"workshop-report-delivery","valueIncluded":false,"ownerRole":"delivery-maintainer","scope":"approved-report-operation","retrieval":"reviewed-platform-boundary","rotationEvidence":"consumer-acceptance-and-old-authority-revocation","missingValueBehavior":"no-delivery-with-diagnostic-category"}

The record is non-runnable design data. It neither reads environment variables nor configures a secret manager. Its role and capability names are invented, and it makes no claim that rotation or revocation was tested.

Prefer a deliberate diagnostic projection

Failure reports need enough context to explain a boundary without copying all inputs. Use a reviewed allowlist of operation, outcome category, fixture id, and nonsecret correlation data. The second program excludes a public classroom credential marker from a synthetic event. The marker is intentionally not a real credential; the exercise tests field selection. A denylist that removes only password may miss authorization headers, connection strings, cookies, reset links, or nested values. Even allowlisted identifiers need privacy and trust review, and log access and retention remain separate controls.

python Check exclusion using a public inert marker

event = {"operation":"deliver-report", "category":"dependency-unavailable", "fixture":"lab-4", "credentialMarker":"PUBLIC-CLASSROOM-MARKER"}
allowed = {"operation", "category", "fixture"}
record = {key: value for key, value in event.items() if key in allowed}
assert set(record) == allowed
assert "credentialMarker" not in record
assert "PUBLIC-CLASSROOM-MARKER" not in str(record)
print("diagnostic field exclusion checked")

Expected output

diagnostic field exclusion checked

The complete program works only with an invented dictionary and produces no log file. It verifies the listed projection, not every logging path or nested structure. No real secret is created, read, transmitted, or revoked.

Treat accidental exposure as an authority problem

If a real credential is exposed, deleting one visible copy does not remove the authority it granted or every retained copy. Follow the organization’s approved incident and revocation process with the accountable owner. Do not test the exposed credential to see whether it still works, and do not paste it into another diagnostic system. Review source history, artifacts, logs, and downstream copies through authorized processes. This course performs none of those operations; it teaches why containment, replacement, evidence preservation, and prevention are distinct responsibilities rather than a single text deletion.

Verify behavior without gathering secret values

Use public markers and injected retrieval outcomes to test missing-value behavior, safe diagnostics, and consumer error handling locally. In a separately approved platform exercise, verify actual retrieval, scope, rotation, and revocation with owned disposable resources and a plan that avoids exposing values. Record only the necessary nonsecret evidence. Do not claim that a redaction helper proves the whole secret lifecycle works. A precise report identifies which local field projection passed and which platform authority boundaries remain unexecuted, preserving useful uncertainty for the next accountable decision.

Common errors and fixes

A secret is moved to the environment and declared solved

Why it happens: Storage location is confused with lifecycle control.
How to fix it: Review scope, retrieval, inheritance, diagnostics, rotation, and revocation.
Prevent it next time: Keep a complete capability lifecycle record.

Only password is removed from logs

Why it happens: A narrow denylist misses other authority-bearing values.
How to fix it: Use a reviewed field projection and test relevant nested paths.
Prevent it next time: Review diagnostics whenever input shapes change.

Deleting an exposed string is called revocation

Why it happens: Copies and granted authority remain unaddressed.
How to fix it: Follow the approved authority-revocation and response workflow.
Prevent it next time: Assign incident ownership and preserve nonsecret evidence.

Check your understanding

1. Can the public classroom marker prove that production logs contain no credentials?

Show worked solution

No. It proves only that the selected local projection excludes that marker field. Review all logging paths and data shapes, then verify the approved integration without collecting real secret values. Keep the local evidence and platform limitations explicit.

2. A delivery credential is unavailable. What should the design record specify?