Lesson A11.6
Software will fail sometimes. Secure architecture does not pretend every error can be prevented. Instead, it designs how failures are contained, communicated, recorded, investigated, and learned from.
This lesson teaches you to separate user-facing errors from operational diagnostics, security audit events, and protected debugging evidence while keeping secrets and unnecessary private data out of logs.
Lesson Progress
High School Advanced • A11: Secure Software Architecture • Lesson 6 of 10
Readiness Check
0/4 ready
Professional Hook
Imagine the fictional Northbridge portal fails while saving a privileged account change. The end user needs to know that the action did not complete. The operator needs to know which service failed. The security team needs an auditable record of the attempted privileged action. A developer may need deeper diagnostic context.
Those audiences should not all receive the same message.
Explain what the user needs to know and what safe action they can take next.
Include: Simple outcome, retry guidance, support reference, neutral error code when useful.
Avoid: Internal paths, stack traces, secrets, database details, dependency names, raw exception objects.
Understand service health, failed workflows, degraded dependencies, and operational recovery needs.
Include: Service, environment, operation, correlation ID, result, dependency status, retry state.
Avoid: Secret values, unnecessary payloads, private records, raw credentials.
Investigate important identity, authorization, privilege, configuration, and security-control events.
Include: Actor or service identity, target reference, action, result, timestamp, source, correlation ID, policy decision.
Avoid: Passwords, tokens, keys, cookies, recovery codes, full sensitive request bodies.
Analyze deeper implementation failures in a tightly controlled diagnostic context.
Include: Sanitized exception class, component, operation, stack location or trace reference when approved, correlation ID.
Avoid: Anything broader than needed for troubleshooting; secret or private values should remain redacted.
Learning Objectives
Explain how secure error handling protects users while still giving defenders and engineers enough evidence to understand what happened.
Separate user-facing messages, operational diagnostics, security telemetry, and protected debugging evidence by audience and purpose.
Design logging requirements that capture useful context without exposing secrets, unnecessary private data, or sensitive implementation details.
Evaluate fictional logging evidence for coverage, redaction, source health, retention, access, correlation, and auditability.
Build an error-handling and logging design that becomes the sixth artifact in the A11 Secure Software Design Assessment.
Why It Matters
Poor error handling can expose implementation details, private data, or secrets. Poor logging can hide important security decisions or create huge amounts of noisy data. Good design balances privacy, usability, operations, investigation, and accountability.
Give understandable guidance without exposing protected technical details.
Record important decisions and outcomes with enough context to investigate later.
Minimize what gets logged and keep secret or private values out of telemetry.
Core Framework
What condition occurred and which component recognized it?
Distinguish validation failures, authorization denials, dependency failures, internal faults, rate or capacity conditions, and expected business-rule outcomes.
What should the system do to prevent the failure from spreading?
Stop unsafe processing, preserve data integrity, use safe defaults, avoid partial privileged changes, and protect important state.
What should the user or calling service be told?
Return a useful but bounded response that does not expose internal implementation detail or sensitive information.
What context do operators and defenders need?
Record service, environment, operation, actor or workload reference where appropriate, result, timestamp, correlation identifier, and policy decision.
Which values must never appear in logs or errors?
Remove secrets, credentials, session tokens, private keys, recovery codes, unnecessary private data, and overly detailed request content.
Where should the evidence go and how long should it remain?
Send different event classes to appropriate protected destinations with defined access, retention, ownership, and review expectations.
How does the team know the logging path itself still works?
Track freshness, parsing, expected volume, missing sources, delayed delivery, schema drift, and retention health.
What recurring failures should change the design?
Use trends, incidents, support patterns, and control failures to refine requirements, resilience, validation, and architecture.
Vocabulary
The design and process used to detect, contain, communicate, record, and recover from failures.
A bounded message shown to a user or calling client that explains the outcome without revealing unnecessary internal detail.
Telemetry used to understand service health, workflows, dependencies, performance, and recovery.
A record of a security-relevant action or decision such as authorization, privileged change, account recovery, or configuration modification.
A non-secret identifier used to connect related events across services or stages of one workflow.
Removing or masking sensitive values that should not appear in logs, errors, dashboards, or reports.
Recording only the information needed for the stated operational or security purpose.
Evidence that a logging source is current, delivering expected events, parsing correctly, and meeting retention expectations.
The defined fields, types, and structure expected in an event.
The approved period for keeping logs or diagnostic evidence.
A more restricted evidence path used for deeper troubleshooting than ordinary user or operational output.
A design behavior that prefers a safer state when an important control or dependency cannot make a trustworthy decision.
Logging Domains
Examples
Successful staff sign-in, denied sign-in, disabled identity, session establishment failure.
Important context
Identity reference, result, source, timestamp, correlation ID, reason category.
Avoid
Passwords, tokens, recovery codes, full identity claims.
Examples
Allowed or denied access to assigned student record, privileged action approval.
Important context
Actor reference, target reference, action, decision, policy or role basis, correlation ID.
Avoid
Full private record content or unnecessary user attributes.
Examples
Role change, account recovery, configuration change, broad data export approval.
Important context
Actor, target reference, action, result, approval reference, timestamp, correlation ID.
Avoid
Secret values, full export data, private notes unrelated to the action.
Examples
Record creation, deletion request, approved export, retention action.
Important context
Actor or service, data category, operation, result, policy reference, target identifier.
Avoid
Full record content when metadata is sufficient.
Examples
Authorization baseline change, logging schema update, feature-flag change.
Important context
Actor, changed setting reference, environment, old/new state classification, approval reference.
Avoid
Secret configuration values.
Examples
Scheduling vendor unavailable, notification retry, dependency timeout, supplier API degradation.
Important context
Dependency ID, operation, result, duration, retry state, environment, correlation ID.
Avoid
Vendor credentials, private payloads, unnecessary response bodies.
Examples
Unexpected server exception, workflow rollback, failed persistence operation.
Important context
Sanitized exception category, service, operation, environment, correlation ID, impact class.
Avoid
Raw stack traces in user-facing output, secrets, full database statements, private data.
Examples
Missing heartbeat, delayed ingestion, parser failure, unexpected event-volume drop.
Important context
Source ID, last-seen time, ingestion status, parser status, expected/actual volume.
Avoid
Assuming no alerts means the source is healthy.
User vs. Defender
Strong error handling creates different outputs from the same underlying event depending on the audience.
User
You do not have permission to perform this action. Reference: NB-403.
Operator
Action denied by authorization policy; correlation ID links to audit event.
Security
Actor ref, target ref, action, decision=deny, policy ref, correlation ID.
User
This feature is temporarily unavailable. Your main record was not changed. Please try again later.
Operator
Scheduling dependency unavailable; retry queue active; correlation ID recorded.
Security
Only if the failure is security-relevant; otherwise operational evidence may be sufficient.
User
We could not complete the request. Reference: NB-500-7F2.
Operator
Service and operation failed; sanitized exception category and correlation ID available.
Security
Escalate if the event pattern or affected workflow meets a defined security-monitoring rule.
User
One or more fields need attention. Review the highlighted entries.
Operator
Usually low-level operational evidence only unless repeated patterns matter to service health.
Security
Do not log full private field values merely because validation failed.
Fake Dashboard
Fictional telemetry-health data
Critical audit sources
12
11 healthy, 1 degraded
Redaction compliance
98.7%
One diagnostic schema requires remediation
Events with correlation IDs
96%
Legacy reporting workflow remains incomplete
Source freshness
99.4%
Authorization source delayed for 7 minutes earlier today
Fake SOC Alert
Source: Fictional Source Health Monitor • Time: 09:19
Event Register
Fields
Actor ref, student ref, action, decision, assignment-policy ref, timestamp, correlation ID
Redaction
No counseling-note content, passwords, tokens, or unnecessary profile data
Retention
Security audit retention class
Owner
Application + Security Monitoring
Fields
Approver ref, operator ref, target account ref, action, result, approval ref, timestamp, correlation ID
Redaction
No recovery codes, secrets, session values, or private identity-proof content
Retention
Privileged audit retention class
Owner
Identity Platform + Security Monitoring
Fields
Dependency ID, operation, result, retry state, duration, environment, correlation ID
Redaction
No vendor token, student appointment payload, or private fields
Retention
Operational retention class
Owner
Integration Owner
Fields
Service, operation, sanitized exception class, environment, correlation ID, trace reference
Redaction
No stack trace to user, no database credentials, no request body, no private record content
Retention
Restricted diagnostic retention class
Owner
Application Engineering
Fields
Source ID, last-seen time, parser state, expected volume, actual volume
Redaction
No user records
Retention
Monitoring health retention class
Owner
Security Monitoring
Fields
Report job ref, component ref, result, duration, environment, correlation ID
Redaction
No generated report content
Retention
Operational retention class
Owner
Reporting Team
Fake Log Panel
[09:02] AUTHZ decision=DENY actor=usr-102 target=stu-884 policy=ASSIGNMENT correlation=NB-91A [09:08] PRIV action=ACCOUNT_RECOVERY result=APPROVED approval=APR-224 correlation=NB-92C [09:14] DEP dependency=SCHEDULING result=UNAVAILABLE retry=QUEUED correlation=NB-93F [09:19] SRC source=AUTHZ_AUDIT last_seen=09:12 parser=HEALTHY freshness=DEGRADED [09:27] ERR service=RECORD_API class=StorageOperationError correlation=NB-94B redaction=PASS [09:41] LOG legacy_report correlation_id=MISSING status=UNKNOWN [09:55] SRC source=AUTHZ_AUDIT freshness=RECOVERED backlog=0
Training note: this is fake data for defensive analysis practice only.
Review Questions
Who is the audience for this error or event?
What decision should this evidence support?
Which fields are required?
Which sensitive values are forbidden?
Does the user-facing message expose internal implementation detail?
Does the event identify service and environment?
Is actor or workload identity needed?
Is target reference needed?
Is a correlation ID present?
Is the result or policy decision explicit?
Is the event schema stable and documented?
Who owns the source?
Who can access the evidence?
How long should it be retained?
How is source health measured?
What happens if the logging destination is unavailable?
Which events should become alerts?
What change triggers require schema or privacy re-review?
Analyze the Evidence
Source Health
Security teams depend on logging pipelines. If a source stops sending events, dashboards may look quiet even while the software is active. That is why source-health evidence belongs in the architecture.
When was the last expected event or heartbeat received?
Is current event volume within an expected range?
Are events being interpreted by the expected schema?
Are events arriving at the intended destination?
Are required events still available for the approved period?
Who responds when the source becomes stale or degraded?
Common Mistakes
Why it fails: Internal component names, paths, line references, dependency details, and implementation context can leak unnecessarily.
Better approach: Give users a bounded message and correlation reference; keep deeper diagnostics in restricted channels.
Why it fails: Excess data increases privacy, access, retention, storage, and investigation burden.
Better approach: Record the minimum fields needed for the operational or security purpose.
Why it fails: Logs often have broader access and longer retention than secret stores.
Better approach: Use secret metadata or record IDs, never secret values.
Why it fails: Multi-service workflows become difficult to reconstruct without a safe way to connect related events.
Better approach: Use a non-secret correlation identifier across the workflow.
Why it fails: A silent logging pipeline can make defenders believe nothing happened when evidence is simply missing.
Better approach: Track source freshness, expected volume, parser state, and ingestion health.
Why it fails: Users, operators, defenders, and diagnostic reviewers need different levels of detail.
Better approach: Separate user messages, operational logs, security audit events, and restricted diagnostics.
Why it fails: Temporary diagnostic detail can become long-term sensitive telemetry.
Better approach: Time-bound diagnostic settings, restrict access, review retention, and return to the approved baseline.
Why it fails: Ordinary validation and dependency failures can overwhelm monitoring if they are not classified by purpose and impact.
Better approach: Define which events are operational, which are security-relevant, and which need escalation.
Scenario Decision Lab
A fictional privileged account change fails because the record service returns an unexpected internal exception. The user is waiting, operators need to troubleshoot, and the security team must preserve the audit trail.
Scenario Decision Lab
The authorization dashboard shows no events for seven minutes, but the source-health monitor reports degraded freshness while parser health remains normal.
Safe Fictional Lab
Use only fictional events and synthetic identifiers. Do not include real private records, credentials, tokens, internal production endpoints, or confidential logs.
Choose at least eight fictional error or audit events.
Identify the audience for each event.
Write a safe user-facing message where applicable.
Define the operational fields needed.
Define the security audit fields needed.
List forbidden sensitive values.
Add a correlation ID requirement for multi-service workflows.
Define event owner and source owner.
Define access and retention class.
Add source-health expectations.
Define alert or escalation conditions.
Assign status: Confirmed, Conditional, Unknown, or Blocked.
Add validation evidence.
Add change triggers for schema, privacy, or architecture changes.
Analyze the Evidence
Advanced Challenge
Create a fictional audit schema for a high-impact account-recovery workflow that is useful to defenders without exposing secrets or unnecessary private information.
Event ID
Timestamp
Environment
Actor reference
Approver reference
Target account reference
Action
Result
Policy or approval reference
Correlation ID
Service source
Reason category
Forbidden fields
Retention class
Access owner
Source-health owner
The best schema is not the one with the most fields. It is the one that captures the evidence needed for accountability and investigation while minimizing sensitive data.
Defender Habits
Skill Check
Check Your Understanding
Choose your answers first. Explanations appear only after submission.
Portfolio Prompt
Create the sixth artifact for your A11 Secure Software Design Assessment: a fictional error-handling and logging matrix with at least eight events. Include audience, safe user message, operational fields, security audit fields, forbidden fields, correlation requirement, owner, source owner, access class, retention class, source-health expectation, validation evidence, status, escalation rule, and change trigger.
Confidence / Readiness Reflection
A11.7 moves to Code Review for Security. Before continuing, make sure you can identify what secure implementation reviewers should look for in error handling, logging, and evidence.
I can separate user-facing errors, operational logs, security audit events, and protected diagnostics.
I can define useful event fields without logging secrets or unnecessary private data.
I can explain why correlation IDs improve multi-service traceability.
I can evaluate source health before drawing conclusions from missing events.
I can define access, retention, ownership, and change triggers for logging evidence.
Portfolio Build Guide
Give each important event a stable ID so requirements, code review, testing, alerts, and retention can reference it.
Show the user response, operational evidence, security evidence, and diagnostic evidence separately.
Make redaction rules explicit rather than assuming developers will know what not to log.
Use fictional actor, target, service, and correlation identifiers rather than real user data.
Document freshness, volume, parsing, ingestion, and ownership expectations.
Explain who can view the evidence and how long it should remain.
Record how the team confirms required fields are present and forbidden values are absent.
Link events back to requirements, threat-model concerns, secrets governance, and dependency workflows.
Key Takeaways
Lesson Safety Boundary
Do not collect, expose, or request real credentials, tokens, private records, confidential logs, production endpoints, or other sensitive operational data. All examples in this lesson are fictional and defensive.
Lesson Complete
You now have an error-handling and logging architecture that balances user safety, operational troubleshooting, auditability, privacy, redaction, correlation, retention, access, and source health. Next, A11.7 focuses on Code Review for Security.