Using C4 Diagrams In Security Work

The worst time to discover bad architecture documentation is during an incident.

Someone asks which systems are exposed, where customer data flows, or what can talk to the affected database. The answer is a diagram nobody trusts, a wiki page from two reorganizations ago, and a Slack thread full of guesses.

The C4 model gives teams four levels of structural detail:

1. Context - what the system talks to
2. Container - the major deployable pieces
3. Component - the important parts inside a container
4. Code - implementation details, when they are actually useful

For a security review, I would start with context and containers, then add a component view where the location of a control needs explanation. C4 does not require all four levels.

Context: What Is Outside The System?

A context diagram should answer basic questions quickly:

• Who uses the system?
• Which external systems does it depend on?
• What data crosses the boundary?
• Which connections are untrusted, semi-trusted, or internal?

Example:

[Customer] --HTTPS--> [E-commerce Platform] --API--> [Payment Processor]
                              |
                              v
                       [Inventory System]

For security review, I would annotate:

• customer PII enters from the public internet
• payment data leaves to a third party
• inventory is an internal dependency
• authentication and logging are required at the platform boundary

That is enough to start a useful conversation.

Container: What Are The Big Pieces?

A C4 container is an application or data store, rather than specifically a Docker container. Show the web application, API, database, and queue at this level. Deployment infrastructure such as load balancers belongs in a deployment view, although a simplified security sketch may show it explicitly. The example below mixes those concerns to highlight transport decisions; it is a review sketch rather than strict C4 notation.

Example:

[Browser] --TLS--> [Load Balancer] --HTTP--> [Web App]
                                             |
                                             v
                                      [API Service] --SQL--> [Database]
                                             |
                                             v
                                      [Object Storage]

This version immediately raises questions:

• Why is traffic from the load balancer to the web app HTTP?
• Which component validates identity?
• Does the API have direct database access?
• What is logged before object storage reads and writes?
• Where is the trust boundary between public and private networks?

Label the answer when it is known. Leaving HTTP on the drawing without saying whether it is intentional gives the next reviewer the same unanswered question.

Component: Where Do Security Decisions Happen?

Component diagrams are useful when a container owns meaningful security logic.

Example:

[Request Handler] --> [Authentication] --> [Authorization] --> [Business Logic]
                             |                    |                    |
                             v                    v                    v
                       [User Store]          [Policy Store]       [Audit Logger]

Now the review can get specific:

• Are authentication and authorization separate?
• Is policy cached, and if so, how is it invalidated?
• Does the audit logger see denied actions or only successful ones?
• Can business logic bypass the authorization layer?

This is where architecture documentation starts helping code review.

Code: Use Sparingly

Most security teams do not need class diagrams for everything. Code-level diagrams are useful when the implementation pattern matters:

• cryptographic wrappers
• authorization decorators
• policy evaluation paths
• serialization and validation boundaries
• high-risk parsing logic

If the diagram cannot guide a review or explain a failure mode, skip it.

Security Annotations

I keep the notation simple:

• Red: external or untrusted
• Yellow: partner or semi-trusted
• Green: internal service
• Blue: security control
• Dashed line: trust boundary
• Label on flow: protocol plus data classification

For example:

[Partner API] --TLS, contract data--> [API Gateway] --mTLS, internal--> [Order Service]
                 untrusted boundary ^

Use text and line styles alongside color so the drawing remains readable without color perception. An internal service is still an authenticated subject with limited authority; green should never mean trusted without checks.

Where C4 Helps Security Teams

Threat Modeling

Start with the context diagram to find attack surfaces. Use the container diagram to find trust boundaries. Use the component diagram to identify authorization, validation, and logging paths.

That prevents threat modeling from becoming a free-form brainstorm detached from the real system.

Incident Response

During an incident, a current C4 diagram helps answer:

• what might be affected?
• what can the compromised system reach?
• where should logs exist?
• which dependency could explain the observed behavior?
• what can be isolated without breaking everything?

Compliance

C4 diagrams are not compliance artifacts by themselves, but they make compliance evidence easier to explain:

• PCI boundaries
• PHI flows
• data retention systems
• third-party processors
• audit logging paths

Common Mistakes

• drawing every database table on a container diagram
• mixing deployment detail with business context
• leaving data classification off the flows
• making one perfect diagram instead of three useful ones
• letting diagrams age without tying them to reviews or incidents

A Simple Starting Point

Pick one important system and make three diagrams:

1. context diagram with users, external dependencies, and trust boundaries
2. container diagram with deployable parts and data stores
3. component diagram for the part that makes access decisions

Review them with a developer, an operator, and a security person. If all three groups correct the diagram, it is doing its job.

Record the owner, review date, and relevant deployment or release next to the diagrams. When a new connector or background worker appears, updating its access path should be part of reviewing the change.