Using Notes and Documentation

Using Notes and Documentation

Document your threat modeling process with rich markdown notes.

Overview

TMI supports comprehensive documentation through markdown-formatted notes with Mermaid diagram support.

Creating Notes

Adding a Note

1. Navigate to threat model
2. Click "Notes" section
3. Click "New Note" or "Add Note"
4. Enter title and content
5. Save (auto-save may be enabled)

Note Properties

• Title: Descriptive name
• Content: Markdown-formatted text
• Author: Creator
• Last Modified: Update timestamp
• Metadata: Custom properties

Markdown Formatting

Basic Syntax

# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*
`code`

- Bullet list
- Another item

1. Numbered list
2. Second item

[Link text](https://example.com)

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |
| More     | More     | More     |

Code Blocks

```python
def example():
    return "Hello, World!"
```

Blockquotes

> This is a blockquote
> Multiple lines

Mermaid Diagrams

Embedding Mermaid

```mermaid
flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
```

Flowcharts

```mermaid
flowchart TD
    A[User Request] --> B{Authenticated?}
    B -->|Yes| C[Process Request]
    B -->|No| D[Deny Access]
    C --> E[Return Response]
    D --> E
```

Sequence Diagrams

```mermaid
sequenceDiagram
    User->>+API: Login Request
    API->>+Auth: Validate Credentials
    Auth-->>-API: Token
    API-->>-User: Success + Token
```

Architecture Diagrams

```mermaid
graph TB
    subgraph "Frontend"
        A[Web App]
        B[Mobile App]
    end
    subgraph "Backend"
        C[API Gateway]
        D[Services]
    end
    A --> C
    B --> C
    C --> D
```

Note Organization

Recommended Note Types

Security Assumptions:

• Document trust assumptions
• Authentication expectations
• Data handling policies

Threat Modeling Decisions:

• Why certain approaches were chosen
• Tradeoffs considered
• Alternatives rejected

Out of Scope:

• What's not included
• Future considerations
• Deferred items

Security Controls:

• Existing protections
• Planned mitigations
• Control effectiveness

Review Notes:

• Review sessions
• Action items
• Follow-ups

Linking and References

Internal Links

Link to other parts of TMI:

• Link to specific threats
• Reference diagrams
• Cross-reference notes

External Links

• Architecture documentation
• Security policies
• Compliance requirements
• Related systems

Best Practices

Clear Structure

• Use headings for organization
• Break into logical sections
• Use lists for readability

Comprehensive Documentation

• Document all assumptions
• Explain decisions
• Record rationale
• Note limitations

Keep Updated

• Update as system evolves
• Review regularly
• Mark outdated sections
• Version important changes

Use Visual Aids

• Mermaid diagrams for clarity
• Tables for comparisons
• Code blocks for examples

Common Note Patterns

Security Assumptions Note

# Security Assumptions

## Authentication
- All users authenticate via OAuth 2.0
- MFA required for administrative access
- Session timeout: 30 minutes of inactivity

## Data Protection
- All data in transit encrypted with TLS 1.3
- All data at rest encrypted with AES-256
- PII stored in dedicated secure database

## Network
- All production systems in private VPC
- No direct internet access to databases
- All ingress through load balancer

Architecture Decision Note

# Decision: Use JWT for API Authentication

## Context
Need to authenticate API requests from multiple client types.

## Decision
Use JWT tokens issued after OAuth login.

## Rationale
- Stateless authentication
- Works across multiple services
- Industry standard
- Good library support

## Consequences
- Must protect token secret
- Need token rotation strategy
- Clock skew considerations

Collaboration on Notes

Co-Editing

• Multiple users can edit notes
• Real-time synchronization
• See collaborator cursors
• Automatic conflict resolution

Comments

• Add comments to notes
• Discuss specific sections
• @mention team members
• Track discussions

Exporting Notes

Future features may include:

• Export as PDF
• Export as Markdown file
• Include in threat model export

Next Steps

• Learn about Metadata and Extensions
• Review Collaborative Threat Modeling
• Explore API Integration for programmatic access