gdocs-audit-report

# Google Docs Security Audit Report ## Overview This skill provides patterns, constants, and gotcha-avoidance for building and maintaining security audit reports in Google Docs using the Docs API (service account auth). It encodes hard-won lessons around index drift, code styling multi-pass, paragraph vs text backgrounds, heading anchor URLs, and cross-reference linking. Always read `references/api-patterns.md` and `references/formatting-standards.md` before writing any script. ## Workflow ``` 1. Auth → make_token() from scripts/gdocs_auth.py 2. get_doc() → fresh snapshot before EVERY batch of edits 3. Build ops → sort ALL ops highest-index-first 4. do_batch() → send in chunks of ≤50 5. Verify → get_doc() again and spot-check changed ranges ``` ## Critical Gotchas (read these first) ### 1. Index drift Any insert/delete shifts every index above it. **Always sort ops high→low. Always get_doc() fresh.** ### 2. Text bg ≠ paragraph bg `updateTextStyle.backgroundColor` only covers character width - leaves white gaps between lines in code blocks. Use `updateParagraphStyle.shading.backgroundColor` + `spaceAbove/Below: 0` for full-width code block backgrounds. ### 3. headingId already has `h.` prefix Anchor URL = `#heading={headingId}` - **not** `#heading=h.{headingId}`. ### 4. Code styling needs multiple passes After `updateTextStyle` splits a run, new unstyled sub-runs appear. Always do a second full-doc re-scan after the first styling pass. ### 5. Sort code terms longest-first Prevents `maxRelayFeeBPS` matching before `assetConfig.maxRelayFeeBPS` and leaving a partial un-styled prefix. ### 6. Backtick removal order (per segment, high→low) Delete closing backtick → style inner → delete opening backtick - all in one batch. ### 7. Bullet conversion `createParagraphBullets` does not change indices. Then `deleteContentRange` the `- ` prefix high→low in a second batch. ### 8. Cross-reference links: skip only already-linked runs Scan ALL runs for `X-NN` regex - **only skip** runs where `textStyle.link` is already set. Do NOT also filter by font (Courier runs can contain xrefs too). ### 9. Table cell content replace Delete to `elements[-1].endIndex - 1` (keep the required trailing `\n`), then insert. Sort delete (higher) before insert (lower) in same batch. ### 10. replaceAllText for bulk renames Use `replaceAllText` for ID renames (e.g. renumbering findings). Same-length replacements are index-safe. Do in one batch, longest/most-specific strings first. ## Formatting Standards See `references/formatting-standards.md` for: - Severity RGB colors (Critical, High, Medium, Low, Unmitigated) - Heading purple, code purple, code bg gray - Finding structure template - Summary table column definitions - Finding ID scheme (`C-01`, `H-01`, etc.) ## API Patterns See `references/api-patterns.md` for: - Auth boilerplate - All common op templates (style, delete, insert, hyperlink, bullets, paragraph shading) - Heading anchor URL construction - Cross-reference linking pattern - Inline code multi-pass approach ## Resources - `scripts/gdocs_auth.py` - reusable auth + get_doc + do_batch helpers - `references/api-patterns.md` - op templates and patterns - `references/formatting-standards.md` - colors, typography, structure constants - `references/how-to-create-google-service-account.md` - one-time setup: instruct the user to create a service account, advise the user to restrict it to the AI-only Drive folder/file (via google share feature), and provide the JSON key path