Missing Documentation for Design

Description

Missing Documentation for Design occurs when software lacks documentation that represents its design architecture and structure. This includes missing architectural diagrams, component specifications, interface definitions, data flow documentation, security design documents, and other artifacts that describe how the system is designed and intended to function. Without such documentation, understanding the system's security boundaries, trust relationships, and intended behavior becomes extremely difficult.

Risk

While primarily a documentation quality issue, missing design documentation has significant indirect security implications. Security reviewers cannot verify that the implementation matches security requirements without knowing the intended design. Threat modeling becomes impossible or ineffective without documented data flows and trust boundaries. New developers may introduce vulnerabilities by misunderstanding system architecture. Incident response is hampered when responders don't understand system design. Compliance audits may fail due to lack of documented security controls. Design flaws are harder to identify when there's no design to review.

Solution

Create and maintain comprehensive design documentation including: (1) System architecture diagrams showing component relationships, (2) Security architecture documents describing trust boundaries and security controls, (3) Data flow diagrams showing how sensitive data moves through the system, (4) API specifications and interface contracts, (5) Threat models documenting identified risks and mitigations, (6) Deployment architecture showing infrastructure security boundaries. Treat documentation as code - version control it, review changes, and keep it synchronized with implementation. Use automated documentation generation where possible.

Common Consequences

Impact	Details
Other	Scope: Other Reduce Maintainability - Lack of design documentation makes the system harder to understand, maintain, and securely modify.
Other	Scope: Other Quality Degradation - Without design documentation, developers may implement features that conflict with the intended architecture, potentially introducing security flaws.

Example Code

Vulnerable Code

// Vulnerable: System with no design documentation
// (This represents a common scenario, not actual code)

/*
 * PROBLEMS WITH UNDOCUMENTED SYSTEMS:
 *
 * 1. No architectural overview
 *    - How does the authentication system work?
 *    - Where are authorization checks performed?
 *    - What are the trust boundaries?
 *
 * 2. No data flow documentation
 *    - Where does sensitive data enter the system?
 *    - How is it processed and stored?
 *    - What encryption is applied and where?
 *
 * 3. No security design document
 *    - What threats were considered?
 *    - What security controls are implemented?
 *    - What are the security assumptions?
 *
 * 4. No API contracts
 *    - What authentication is required?
 *    - What authorization model is used?
 *    - What input validation is expected?
 */

// Developer joins project and sees this undocumented code:
public class PaymentProcessor {
    // No documentation on:
    // - Security requirements
    // - Required encryption
    // - PCI compliance controls
    // - Data retention policies

    public void processPayment(PaymentRequest request) {
        // Developer doesn't know:
        // - Should this validate card number format?
        // - Is the connection to payment gateway encrypted?
        // - Should we log payment details?
        // - What fraud checks are expected?

        // Without documentation, developers may:
        // - Skip security controls they don't know about
        // - Log sensitive data accidentally
        // - Use insecure communication
        // - Miss required compliance controls
    }
}

Fixed Code

# Fixed: Comprehensive Design Documentation

## 1. Architecture Overview Document

### System Architecture

┌─────────────────────────────────────────────────────────────┐
│ Internet/Users │
└──────────────────────────┬──────────────────────────────────┘
│ HTTPS (TLS 1.3)
▼
┌─────────────────────────────────────────────────────────────┐
│ Load Balancer / WAF │
│ - Rate limiting: 100 req/min per IP │
│ - OWASP ModSecurity rules enabled │
└──────────────────────────┬──────────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Web Server │ │ Web Server │ │ Web Server │
│ (Stateless) │ │ (Stateless) │ │ (Stateless) │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
└───────────────────┼───────────────────┘
│ Internal Network (mTLS)
▼
┌─────────────────────────────────────────────────────────────┐
│ API Gateway │
│ - JWT validation │
│ - Request authentication │
│ - API versioning │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Auth │ │ Payment │ │ User │
│ Service │ │ Service │ │ Service │
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Auth DB │ │ Payment │ │ User DB │
│(Encrypted)│ │ Gateway │ │(Encrypted)│
└──────────┘ │ (PCI) │ └──────────┘
└──────────┘


## 2. Security Architecture Document

### Authentication & Authorization

```yaml
authentication:
  method: JWT with RS256
  token_lifetime: 15 minutes
  refresh_token_lifetime: 7 days
  mfa:
    required_for:
      - admin_users
      - financial_operations
    methods:
      - totp
      - sms (deprecated, removed in v2.0)

authorization:
  model: RBAC with permissions
  roles:
    - admin: full system access
    - operator: read/write operational data
    - viewer: read-only access
    - api_client: programmatic access only
  enforcement_points:
    - API Gateway (coarse-grained)
    - Service layer (fine-grained)

Data Classification & Handling

data_classification:
  pii:
    - name
    - email
    - phone
    - address
    handling:
      storage: AES-256-GCM encrypted
      transmission: TLS 1.3 only
      logging: masked (show last 4 chars only)
      retention: 2 years after account closure

  payment_data:
    - card_number
    - cvv
    - expiry
    handling:
      storage: never stored (tokenized via gateway)
      transmission: direct to PCI-compliant gateway
      logging: never logged
      retention: not applicable

3. Data Flow Diagram

Payment Processing Flow

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client  │────▶│   API    │────▶│ Payment  │────▶│ Payment  │
│          │     │ Gateway  │     │ Service  │     │ Gateway  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                      │                │                │
Security Controls:    │                │                │
- TLS 1.3            ─┘                │                │
- JWT validation     ───────────────────┘               │
- Input validation   ───────────────────────────────────┘
- PCI compliance     ───────────────────────────────────┘

Data Elements:
→ card_number: masked in logs, never stored
→ amount: validated (0.01 - 10000.00)
→ merchant_id: from config, not user input
→ transaction_id: UUID, logged for audit

4. Threat Model Summary

STRIDE Analysis for Payment Service

Threat	Risk	Mitigation	Status
Spoofing - fake payment requests	High	JWT auth + mTLS between services	Implemented
Tampering - modified amounts	High	Digital signatures on transactions	Implemented
Repudiation - denied transactions	Medium	Comprehensive audit logging	Implemented
Info Disclosure - card data leak	Critical	Tokenization, no storage	Implemented
DoS - flood payment service	High	Rate limiting, circuit breaker	Implemented
Elevation - unauthorized refunds	High	Role-based access, dual approval	Implemented

5. API Contract Documentation

POST /api/v1/payments

endpoint: /api/v1/payments
method: POST
authentication: Bearer JWT
authorization: role in [admin, operator]

request:
  headers:
    Authorization: "Bearer <jwt_token>"
    Content-Type: "application/json"
    X-Request-ID: "uuid"  # For tracing
  body:
    amount:
      type: number
      required: true
      validation: 0.01 <= amount <= 10000.00
    card_token:
      type: string
      required: true
      description: "Tokenized card from gateway"
    currency:
      type: string
      default: "USD"
      enum: ["USD", "EUR", "GBP"]

response:
  success:
    status: 200
    body:
      transaction_id: string
      status: "approved" | "pending" | "declined"
      timestamp: ISO8601
  errors:
    401: "Invalid or expired authentication"
    403: "Insufficient permissions"
    400: "Invalid request parameters"
    429: "Rate limit exceeded"

security_notes:
  - Card numbers MUST be tokenized before calling this endpoint
  - All requests are logged (excluding sensitive data)
  - Failed attempts trigger fraud monitoring


```java
// Fixed: Code with documentation references
/**
 * Payment Processor Service
 *
 * ARCHITECTURE: See docs/architecture/payment-service.md
 * SECURITY: See docs/security/payment-processing.md
 * API CONTRACT: See docs/api/payments.yaml
 * THREAT MODEL: See docs/security/threat-model.md#payment-service
 *
 * Security Requirements:
 * - PCI-DSS compliant (see compliance/pci-dss-checklist.md)
 * - Card data must be tokenized before reaching this service
 * - All operations require authenticated user with 'payment' permission
 * - Failed transactions trigger fraud detection (see fraud-detection.md)
 */
public class PaymentProcessor {

    /**
     * Process a payment transaction.
     *
     * @param request The payment request (see PaymentRequest documentation)
     * @return PaymentResult with transaction ID and status
     *
     * @security Authentication required (JWT)
     * @security Authorization: 'process_payment' permission
     * @security Rate limited: 10 requests/minute per user
     *
     * @see docs/api/payments.yaml for full API specification
     * @see docs/security/payment-processing.md for security controls
     */
    public PaymentResult processPayment(PaymentRequest request) {
        // Validation per security requirements (docs/security/input-validation.md)
        validateRequest(request);

        // Fraud check per threat model (docs/security/threat-model.md)
        fraudDetection.check(request);

        // Process via PCI-compliant gateway (docs/compliance/pci-integration.md)
        return gateway.process(request);
    }
}

CVE Examples

This CWE is marked as PROHIBITED for direct CVE mapping as it represents a documentation/quality concern rather than a direct security vulnerability.

CWE-1059: Insufficient Technical Documentation (parent)
CWE-1225: Documentation Issues (category member)
CWE-1208: Cross-Cutting Problems (category member)

References

MITRE Corporation. "CWE-1053: Missing Documentation for Design." https://cwe.mitre.org/data/definitions/1053.html
OWASP. "Threat Modeling."
Microsoft. "Security Development Lifecycle."

Missing Documentation for Design

Description

Risk

Solution

Common Consequences

Example Code

Vulnerable Code

Fixed Code

Data Classification & Handling

3. Data Flow Diagram

Payment Processing Flow

4. Threat Model Summary

STRIDE Analysis for Payment Service

5. API Contract Documentation

POST /api/v1/payments

CVE Examples

References

Platform

Resources

Company

Latest Articles

Missing Documentation for Design

Description

Risk

Solution

Common Consequences

Example Code

Vulnerable Code

Fixed Code

Data Classification & Handling

3. Data Flow Diagram

Payment Processing Flow

4. Threat Model Summary

STRIDE Analysis for Payment Service

5. API Contract Documentation

POST /api/v1/payments

CVE Examples

Related CWEs

References