privgraph

# PrivGraph: Mermaid Security & Privacy Annotation

PrivGraph annotates Mermaid diagrams with privacy and security metadata using comment-based directives, then evaluates configurable rules to surface control gaps.

## Core Workflow

When a user presents a Mermaid diagram for privacy/security review:

1. **Parse** the diagram — identify nodes, edges, subgraphs, and any existing `@pg:` annotations
2. **Classify** — determine what data flows where (direct identifiers, health data, credentials, etc.)
3. **Annotate** — add `@pg:` directives as Mermaid comments for data classes, controls, boundaries, compliance
4. **Evaluate** — check the annotated diagram against the rule set (see `references/rules.yaml`)
5. **Report** — surface findings with severity, description, and remediation guidance

When a user asks to create a new annotated diagram from scratch, follow steps 2–5 after helping them build the diagram.

## Annotation Syntax

All annotations are Mermaid comments and do not affect rendering:

```
%% @pg:<directive> <target> <parameters>
```

### Directives

**`@pg:data-class`** — classify data on a flow
```
%% @pg:data-class A-->B DIRECT_ID, LOCATION
```

**`@pg:control`** — declare present or missing (`!`) controls on a node or flow
```
%% @pg:control UserDB encrypted-at-rest, access-controlled
%% @pg:control UserDB !retention-policy
%% @pg:control A-->B encrypted-in-transit
```

**`@pg:boundary`** — declare trust boundary crossing on a flow
```
%% @pg:boundary A-->B third-party
```

**`@pg:compliance`** — declare applicable compliance frameworks
```
%% @pg:compliance UserDB GDPR, CCPA
```

**`@pg:risk-accept`** — suppress a rule finding with justification
```
%% @pg:risk-accept Cache PG-003 "24hr TTL enforced at Redis level. Approved 2024-01-10"
```

**`@pg:meta`** — diagram-level metadata
```
%% @pg:meta owner "platform-team"
%% @pg:meta system "checkout-service"
%% @pg:meta reviewed "2024-01-15"
```

### Data Classifications

| Classification | Description | Examples |
|---------------|-------------|----------|
| `DIRECT_ID` | Direct identifiers | Names, emails, SSNs, phone numbers |
| `INDIRECT_ID` | Indirect/pseudonymous identifiers | Opaque IDs, UUIDs, session tokens, pseudonyms |
| `PHI` | Protected health information | EHR, Diagnoses, prescriptions, lab results |
| `PCI` | Payment card data | Card numbers, CVVs |
| `CREDENTIALS` | Authentication secrets | Passwords, API keys, tokens |
| `BIOMETRIC` | Biometric data | Fingerprints, face data, voice prints |
| `LOCATION` | Location data | GPS coordinates, IP-derived location |
| `FINANCIAL` | Financial data | Bank accounts, transactions |
| `SENSITIVE` | Other sensitive data | Catch-all for sensitive categories |
| `PUBLIC` | Non-sensitive data | Public content, marketing copy |

### Controls

`encrypted-at-rest`, `encrypted-in-transit`, `access-controlled`, `audit-logged`, `retention-policy`, `anonymized`, `minimized`, `consent-managed`, `dpa-in-place`

Prefix with `!` to mark a control as explicitly missing.

### Boundaries

`internal`, `third-party`, `cross-region`, `cross-cloud`, `public-internet`, `user-device`

### Compliance Frameworks

`GDPR`, `CCPA`, `HIPAA`, `PCI-DSS`, `SOC2`, `FERPA`

## Rule Evaluation

After annotating, evaluate the diagram against the rule set. Load `references/rules.yaml` for the full rule definitions. Here is the summary:

| Rule | Sev | Trigger |
|------|-----|---------|
| PG-001 | HIGH | DIRECT_ID/INDIRECT_ID/PHI flow missing `encrypted-in-transit` |
| PG-002 | HIGH | DIRECT_ID/INDIRECT_ID/PHI node missing `encrypted-at-rest` |
| PG-003 | MED | Sensitive data node missing `retention-policy` |
| PG-004 | HIGH | CREDENTIALS flow missing encryption |
| PG-005 | CRIT | DIRECT_ID to `third-party` missing `dpa-in-place` |
| PG-006 | HIGH | PHI to `third-party` boundary |
| PG-007 | MED | `cross-region` flow missing compliance annotation |
| PG-008 | HIGH | HIPAA-scoped flow missing `audit-logged` |
| PG-009 | MED | GDPR-scoped node missing `retention-policy` |
| PG-010 | LOW | Flow crosses boundary with no controls documented |
| PG-011 | INFO | Node has zero controls documented |

For each violation, check if a `@pg:risk-accept` suppresses it (matching target + rule ID). Suppressed findings should be noted but not reported as active violations.

## Reporting Format

Present findings grouped by severity. Use this structure:

```
## PrivGraph Review: [system name or file]

### Findings

🔴 **CRITICAL — PG-005: Direct Identifiers to Third Party Without DPA**
Flow: UserSvc → Analytics
DIRECT_ID is transferred to a third party without a documented DPA.
→ Add: `%% @pg:control Analytics dpa-in-place`

🟡 **HIGH — PG-001: Unencrypted Identifier Transfer**
Flow: Mobile → API
DIRECT_ID transferred without encryption in transit.
→ Add: `%% @pg:control Mobile-->API encrypted-in-transit`

### Summary
X critical, Y high, Z medium | N findings suppressed by @pg:risk-accept
```

Always output the **complete annotated diagram** (original diagram with all `@pg:` annotations added) so the user can copy-paste it directly.

## Handling Ambiguity

When data classifications are unclear from the diagram alone:
- Ask the user what data flows through ambiguous edges
- Default to the more sensitive classification when context suggests it
- Flag uncertain classifications with a comment: `%% TODO: Confirm data classification for A-->B`

When a diagram has no annotations yet, annotate it fully rather than just listing what's missing. Show the user what a complete annotation looks like.

## Supported Diagram Types

- **Flowcharts**: `flowchart LR/TB/etc.` — nodes, edges, subgraphs all supported
- **Sequence diagrams**: `sequenceDiagram` — participants map to nodes, messages map to edges, boxes map to subgraphs

For annotation target syntax in sequence diagrams, use participant names: `%% @pg:data-class Client->>Server DIRECT_ID`

## Examples

See `examples/flowchart-annotated.md` and `examples/sequence-annotated.md` for complete worked examples with annotations and findings.