Using Mermaid Diagrams in PCI DSS Documentation

This guide demonstrates how to use Mermaid diagrams in your PCI DSS documentation to visually represent processes, workflows, and relationships.

What is Mermaid?

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. It's perfect for technical documentation because:

1. Diagrams are defined using text, making them version-control friendly
2. No need for external drawing tools
3. Diagrams stay up-to-date with your documentation
4. Multiple diagram types are supported

Flowchart Example

Flowcharts are useful for documenting processes like incident response procedures:

graph TD
    A[Security Incident Detected] --> B{Is it a confirmed incident?}
    B -->|Yes| C[Activate Incident Response Plan]
    B -->|No| D[Document False Positive]
    C --> E[Contain the Incident]
    E --> F[Eradicate the Threat]
    F --> G[Recover Systems]
    G --> H[Post-Incident Analysis]
    H --> I[Update Security Controls]
    D --> J[Update Detection Rules]

Sequence Diagram Example

Sequence diagrams are excellent for showing interactions between different systems or roles:

sequenceDiagram
    participant User
    participant POS
    participant PaymentProcessor
    participant Bank
    
    User->>POS: Present Payment Card
    POS->>PaymentProcessor: Send Encrypted Transaction
    PaymentProcessor->>Bank: Request Authorization
    Bank-->>PaymentProcessor: Authorization Response
    PaymentProcessor-->>POS: Transaction Status
    POS-->>User: Receipt

Class Diagram Example

Class diagrams can help document data structures and relationships:

classDiagram
    class CardholderData {
        +PAN
        +Cardholder Name
        +Expiration Date
        +Service Code
    }
    
    class SensitiveAuthData {
        +Full Track Data
        +CAV2/CVC2/CVV2/CID
        +PINs/PIN Blocks
    }
    
    class SystemComponent {
        +ID
        +Type
        +Location
        +Owner
        +PCI DSS Scope
    }
    
    SystemComponent "1" --> "*" CardholderData: may store
    SystemComponent "1" --> "0" SensitiveAuthData: must not store

State Diagram Example

State diagrams are useful for showing the different states a system can be in:

stateDiagram-v2
    [*] --> Compliant
    Compliant --> NonCompliant: Security Control Failure
    NonCompliant --> Remediation: Issue Detected
    Remediation --> Compliant: Issue Fixed
    NonCompliant --> Breach: Security Incident
    Breach --> Investigation
    Investigation --> Remediation
    Remediation --> Reporting
    Reporting --> Compliant

Entity Relationship Diagram

ERDs can help document database structures:

erDiagram
    CARDHOLDER ||--o{ TRANSACTION : makes
    MERCHANT ||--|{ TRANSACTION : processes
    TRANSACTION {
        int transaction_id
        string date
        decimal amount
        string status
    }
    CARDHOLDER {
        int id
        string name
        string masked_pan
    }
    MERCHANT {
        int id
        string name
        string location
    }

Gantt Chart Example

Gantt charts are perfect for project planning, such as PCI DSS implementation:

gantt
    title PCI DSS Implementation Plan
    dateFormat  YYYY-MM-DD
    
    section Preparation
    Gap Analysis           :a1, 2023-01-01, 30d
    Scope Definition       :a2, after a1, 15d
    
    section Implementation
    Network Security       :a3, after a2, 45d
    System Hardening       :a4, after a2, 45d
    Access Controls        :a5, after a4, 30d
    Encryption             :a6, after a4, 30d
    
    section Testing
    Vulnerability Scanning :a7, after a5, 15d
    Penetration Testing    :a8, after a6, 20d
    
    section Documentation
    Policy Development     :a9, 2023-01-15, 90d
    Procedure Documentation:a10, 2023-02-15, 75d

Pie Chart Example

Pie charts can be used to show distribution of vulnerabilities or other metrics:

pie title Vulnerability Distribution by Risk Level
    "Critical" : 15
    "High" : 30
    "Medium" : 40
    "Low" : 15

Journey Diagram Example

Journey diagrams can illustrate user experiences or processes:

journey
    title PCI DSS Compliance Journey
    section Assessment
      Determine Scope: 5: Team
      Gap Analysis: 3: Team, QSA
      Create Remediation Plan: 4: Team
    section Implementation
      Network Security Controls: 5: Security Team
      System Hardening: 4: IT Team
      Access Controls: 3: Security Team
      Encryption: 4: Security Team
    section Validation
      Internal Scanning: 5: Security Team
      Penetration Testing: 3: External Firm
      Documentation Review: 4: QSA
      Final Assessment: 3: QSA

Tips for Using Mermaid in PCI DSS Documentation

1. Keep diagrams simple and focused on one concept
2. Use consistent styling across diagrams
3. Include diagrams in relevant policies and procedures
4. Update diagrams when processes change
5. Use diagrams in training materials to improve understanding

By incorporating visual diagrams into your PCI DSS documentation, you can make complex security concepts more accessible and improve overall understanding of your security program.