Using Notes and Documentation - ericfitz/tmi GitHub Wiki

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. Notes are attached to a threat model and provide a space for recording assumptions, decisions, and analysis. Each note has a name, optional description, markdown content, and metadata. Notes can optionally be included in generated PDF reports.

Creating Notes

Adding a Note

Open a threat model
Locate the Notes card in the Outputs section
Click the + button in the Notes card header
A dialog opens in create mode with fields for name, description, content, and an "Include in report" checkbox
Enter a name (required) and markdown content (required)
Click Save to save without closing, or Save and Close to save and return to the threat model

Notes are saved explicitly; there is no auto-save. If you attempt to close with unsaved changes, a confirmation prompt appears.

Editing an Existing Note

Click a note row in the Notes table to navigate to the full-page note editor. The full-page editor provides the same fields as the create dialog, plus:

Timestamps showing when the note was created and last modified
A metadata button for viewing or managing custom key-value metadata
A kebab menu with addon invocation and delete options

Note Properties

Each note has the following properties:

Name: Required. Descriptive title (max 256 characters)
Description: Optional short summary (max 2,048 characters), shown in the notes table
Content: Required. Markdown-formatted text (max 262,144 characters)
Include in report: Checkbox controlling whether the note appears in generated PDF reports (defaults to on for new notes)
Created: Timestamp set when the note is first saved
Last Modified: Timestamp updated on each save
Metadata: Custom key-value properties managed through a separate dialog

The Markdown Editor

Edit and Preview Modes

The note editor has two modes, toggled via toolbar buttons:

Edit mode: Shows a plain-text textarea where you write raw markdown
Preview mode: Renders the markdown as formatted output with Mermaid diagram support

When opening an existing note with content, the editor starts in preview mode. When creating a new note or opening a note with no content, it starts in edit mode. Read-only users always see preview mode.

Toolbar

The markdown toolbar (visible to users with edit permission) provides:

Edit and Preview toggle buttons
Cut, Copy, and Paste buttons for clipboard operations
Character count showing current length vs. maximum (262,144)
Save button (in the dialog version)

In preview mode, the Copy button copies the entire markdown source to the clipboard. Cut and Paste are disabled in preview mode.

Supported Markdown Syntax

Basic Formatting

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

**Bold text**
*Italic text*
`inline 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

Task Lists

Task lists are interactive in preview mode -- clicking a checkbox toggles its state and updates the underlying markdown content.

- [ ] Unchecked item
- [x] Checked item
- [ ] Another unchecked item

Anchor Links

Internal anchor links (e.g., [Jump to section](#section-heading)) work in preview mode and scroll smoothly to the target heading within the note.

Mermaid Diagrams

Mermaid diagrams are rendered in preview mode. Click on a rendered diagram to open an expanded viewer.

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
```

Notes in the Threat Model Page

The Notes card in the threat model page displays a sortable table with columns:

Icon: Article icon
Name: Note name (sortable, used as default sort)
Description: Note description text
Actions: Metadata button and kebab menu

The kebab menu on each note row provides:

Download: Downloads the note content as a Markdown (.md) file
Addons: Run registered addons against the note
Audit Trail: View the change history for the note
Delete: Delete the note (with confirmation dialog, requires edit permission)

The Notes card header also has a kebab menu for bulk addon operations.

Clicking a note row navigates to the full-page note editor.

When the table is empty, a message indicates that no notes exist yet.

Exporting and Reporting

Individual Note Download

Each note can be downloaded as a standalone Markdown file from the note row's kebab menu. The file is named {ThreatModelName}-{NoteName}.md.

PDF Report

Notes marked with "Include in report" are included in the generated PDF report for the threat model. The report renders note content as formatted markdown, including headings, lists, and text formatting. Generate a report from the threat model's kebab menu by selecting Report.

Threat Model Export

When exporting the full threat model as JSON, all notes are included in the export with their content and metadata.

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 is not included
Future considerations
Deferred items

Security Controls:

Existing protections
Planned mitigations
Control effectiveness

Review Notes:

Review sessions
Action items
Follow-ups

Metadata

Each note supports custom key-value metadata, managed through the metadata dialog. Access it from:

The list icon button in the note page header
The metadata button in the notes table action column

Metadata can be used to tag notes with categories, statuses, or other custom attributes.

Addons

Addons that are registered for the "note" object type can be invoked on individual notes. Access addon invocation from:

The kebab menu on the note page
The kebab menu on a note row in the notes table

Best Practices

Clear Structure

Use headings for organization
Break content into logical sections
Use lists for readability
Use task lists to track action items

Comprehensive Documentation

Document all assumptions
Explain decisions and rationale
Record limitations and constraints
Use the description field for a brief summary visible in the notes table

Keep Updated

Update notes as the system evolves
Review notes regularly
Use the "Include in report" checkbox to control what appears in generated reports
Check the audit trail to review change history

Use Visual Aids

Mermaid diagrams for architecture and flow visualization
Tables for structured comparisons
Code blocks for technical 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

Next Steps

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