Audit Flow Examples

Case 0: Non-Linear API Flow (Branching & Merging)

> /audit-flow start
Name: api-auth-audit
Purpose: security-audit
Granularity: fine

> /audit-flow flow api-request
Entry: "Frontend makes authenticated API call"

Flow with Branching

[CODE]    fetch API         → apiClient.ts:45
[AUTH]    check token       → authMiddleware.ts:12
  ├─[BRANCHES: token valid]──→ [AUTH] proceed
  └─[BRANCHES: token expired]──→ [AUTH] refresh token
                                      │
[AUTH]    refresh token     → tokenService.ts:88
          │
          └─[MERGES]──→ [API] call endpoint
[API]     call endpoint     → handler.ts:156
[DATA]    return response   → serializer.ts:23

SQL for Branching

-- Create branch point
INSERT INTO tuples (flow_id, layer, action, subject) VALUES
(1, 'AUTH', 'check token', 'authMiddleware');  -- ID: 2

-- Create branch targets
INSERT INTO tuples (flow_id, layer, action, subject) VALUES
(1, 'AUTH', 'proceed', 'valid path'),          -- ID: 3
(1, 'AUTH', 'refresh token', 'tokenService');  -- ID: 4

-- Branch edges with conditions
INSERT INTO edges (from_tuple, to_tuple, relation, condition) VALUES
(2, 3, 'BRANCHES', 'token valid'),
(2, 4, 'BRANCHES', 'token expired');

-- Merge point
INSERT INTO tuples (flow_id, layer, action, subject) VALUES
(1, 'API', 'call endpoint', 'handler');        -- ID: 5

-- Merge edges
INSERT INTO edges (from_tuple, to_tuple, relation) VALUES
(3, 5, 'TRIGGERS'),
(4, 5, 'MERGES');

Mermaid Output

flowchart TD
    subgraph CODE
        T1(["1. fetch API"]):::entryPoint
    end
    subgraph AUTH
        T2["2. check token"]
        T3["3. proceed"]
        T4["4. refresh token"]
    end
    subgraph API
        T5["5. call endpoint"]
    end
    subgraph DATA
        T6["6. return response"]
    end

    T1 -->|"TRIGGERS"| T2
    T2 -->|"BRANCHES<br/>token valid"| T3
    T2 -->|"BRANCHES<br/>token expired"| T4
    T3 -->|"TRIGGERS"| T5
    T4 -->|"MERGES"| T5
    T5 -.->|"READS"| T6

    classDef entryPoint fill:#2ecc71,stroke:#27ae60,stroke-width:3px
    classDef concern fill:#ff6b6b,stroke:#c92a2a

    subgraph Legend
        L1(["Entry point"]):::entryPoint
        L2["Flow step"]
    end

---

Case 1: Auth Login Flow (Security Audit)

> /audit-flow start
Name: auth-login-security
Purpose: security-audit
Granularity: fine

> /audit-flow flow google-oauth
Entry: "User clicks Sign in with Google"

Expected Trace

[CODE]    onClick handler         → src/components/LoginButton.tsx:24
[AUTH]    OAuth redirect          → redirect to identity provider
[NETWORK] GET /oauth/authorize    → IdP authorization endpoint
[AUTH]    authz code received     → callback handler
[NETWORK] POST /oauth/token       → token exchange
[AUTH]    access_token issued     → {scopes, expiry, claims}
[DATA]    JWT decoded             → extract org_id, user_id
[CODE]    setSession()            → store token in memory/cookie
[AUTH]    token in headers        → Authorization: Bearer
[NETWORK] GET /api/me             → validate token backend
[CODE]    middleware validates    → services/auth/middleware.go:56
[DATA]    user context built      → {org, project, permissions}

Security Checks

Mark as concern and create findings for:

Check	What to look for	Severity
Token storage	localStorage (bad) vs httpOnly cookie (good) vs memory (ok)	high
Token logging	console.log, error handlers leaking tokens	critical
PKCE	code_verifier/code_challenge present?	high
Refresh flow	Refresh token rotation? Secure storage?	high
Token expiry	Short-lived access tokens? Proper refresh?	medium
CORS	Proper origin validation?	medium

Sample Findings

INSERT INTO findings (session_id, severity, category, description, tuple_refs)
VALUES
('auth-login-security', 'high', 'token-storage',
 'Access token stored in localStorage instead of httpOnly cookie - vulnerable to XSS', '[7]'),
('auth-login-security', 'medium', 'token-logging',
 'Token visible in Redux DevTools state - disable in production', '[7]');

---

Case 1b: Observations vs Flow Steps (Anti-Pattern)

Wrong: Chaining Observations as Tuples

When you discover a security concern, do NOT create observation tuples chained with VALIDATES:

-- WRONG: These are analyst notes, not system actions
INSERT INTO tuples (flow_id, layer, action, subject, status) VALUES
(1, 'CODE', 'NO cross-tab sync', 'TabManager', 'concern'),          -- T10
(1, 'AUTH', 'Replay attack possible', 'tokenService', 'concern');    -- T11

INSERT INTO edges (from_tuple, to_tuple, relation)
VALUES (10, 11, 'VALIDATES');  -- WRONG: creates unreadable concern chain

This produces diagrams where analyst notes are indistinguishable from system flow steps.

Correct: Use Findings

-- CORRECT: Observation recorded as a finding
INSERT INTO findings (session_id, flow_id, severity, category, description, tuple_refs)
VALUES (
    'my-session', 1, 'medium', 'concurrency',
    'No cross-tab synchronization: replay attack possible when multiple tabs refresh tokens simultaneously',
    '[196, 226, 227]'  -- References the ACTUAL flow tuples where the issue manifests
);

Findings appear in the Markdown export report, not cluttering the visual flow diagram.

---

Case 2: Chat Question Flow (Documentation)

> /audit-flow start
Name: chat-documentation
Purpose: documentation
Granularity: coarse

> /audit-flow flow question-to-results
Entry: "User submits question in chat UI"

Expected Trace

[CODE]    onSubmit handler        → src/components/ChatInput.tsx
[NETWORK] POST /api/chat/stream   → chat service
[AUTH]    token validated         → middleware extracts org_id, project_id
[API]     chat service receives   → services/chat/main.py
[DATA]    load project context    → knowledge-base service
[API]     agent invoked           → services/chat/agent/
[DATA]    schema lookup           → get relevant tables/columns
[CODE]    SQL generation          → agent node
[NETWORK] POST /analytics/query   → analytics service
[DATA]    query execution         → OLAP engine
[DATA]    results transform       → format for frontend
[NETWORK] SSE stream              → chunked response to frontend
[CODE]    render results          → ChatMessage component

Documentation Output

The export should produce:

• Sequence diagram of service interactions
• Data flow: question → SQL → results
• Auth context propagation across services

Mermaid Output

flowchart TD
    subgraph Frontend
        A[ChatInput.tsx]
        M[ChatMessage]
    end

    subgraph Chat Service
        B[POST /api/chat/stream]
        C[Auth Middleware]
        D[AI Agent]
        E[SQL Generator]
    end

    subgraph Knowledge Service
        F[Project Context]
        G[Schema Lookup]
    end

    subgraph Analytics Service
        H[POST /analytics/query]
        I[OLAP Engine]
    end

    A -->|TRIGGERS| B
    B -->|VALIDATES| C
    C -->|TRIGGERS| D
    D -->|READS| F
    D -->|READS| G
    D -->|TRIGGERS| E
    E -->|TRIGGERS| H
    H -->|READS| I
    I -->|TRANSFORMS| M

---

Case 3: Flow Ideation (Design New Feature)

> /audit-flow start
Name: export-feature-design
Purpose: ideation
Granularity: coarse

> /audit-flow flow csv-export
Entry: "User clicks Export to CSV on results"

Sketched Flow (no code yet)

[CODE]    export button click     → ExportButton component (to create)
[API]     POST /api/export        → new endpoint needed
[AUTH]    check export permission → new permission type?
[DATA]    fetch cached results    → from Redis? or re-query?
[CODE]    CSV formatter           → new util function
[NETWORK] stream file download    → chunked response
[CODE]    browser download trigger→ blob URL

Ideation Questions (record as notes)

Add these as notes on relevant tuples:

Tuple	Question
DATA: fetch cached results	Cache strategy: Redis TTL? Re-query for freshness?
API: POST /api/export	Rate limit exports? Per-user? Per-project?
AUTH: check export permission	New permission: project:export? Or reuse project:read?
NETWORK: stream file download	Large results: stream or paginate? Memory limits?
CODE: CSV formatter	Support other formats? xlsx, json, parquet?

Design Decisions to Document

After ideation, convert key decisions to implementation notes:

UPDATE tuples SET props = json_set(props, '$.decision', 'Use Redis with 15min TTL, re-query if expired')
WHERE id = 4;

UPDATE tuples SET props = json_set(props, '$.decision', 'Stream results, 10MB max per export')
WHERE id = 6;

---

Static Analysis Guidelines

Code reading only. No runtime instrumentation.

What to Follow

• Import statements (module dependencies)
• Function calls (especially cross-service)
• API client invocations (fetch, axios, http clients)
• Auth middleware chains (decorators, middleware arrays)
• Data transformations (serializers, formatters)

Security Patterns to Flag

Pattern	Risk	Severity
console.log(token)	Token leakage	critical
localStorage.setItem('token',...)	XSS vulnerability	high
String concatenation in SQL	SQL injection	critical
dangerouslySetInnerHTML	XSS	high
Missing auth middleware	Auth bypass	critical
Hardcoded secrets	Credential exposure	critical
eval(), new Function()	Code injection	critical