Skip to content

QUA-1588: Add field masking documentation for sensitive data protection#1084

Draft
RafaelOsiro wants to merge 10 commits intomainfrom
qua-1588-field-masking-for-sensitive-data-protection
Draft

QUA-1588: Add field masking documentation for sensitive data protection#1084
RafaelOsiro wants to merge 10 commits intomainfrom
qua-1588-field-masking-for-sensitive-data-protection

Conversation

@RafaelOsiro
Copy link
Copy Markdown
Contributor

@RafaelOsiro RafaelOsiro commented Mar 26, 2026

Summary

Adds comprehensive field masking documentation covering how masking works, where masked values appear across the platform, how to reveal and unmask fields, and the masking audit log for compliance tracking.

Key Changes

  • Field Masking concepts page: New page covering masked field identification (tree view, container listing, explore view, field detail), how masking works, where masking is applied, revealing masked values, unmasking guidance and best practices, and fields that cannot be masked
  • Masking Audit Log page: New page with UI walkthrough (Data Preview and Anomaly Source Records), audit entry details, and API access instructions
  • Unmask a Field page: New page with step-by-step instructions for unmasking from container view, field view, and bulk unmask
  • Mask a Field refactor: Moved conceptual content to the new concepts page, keeping only the step-by-step masking instructions
  • Cross-reference updates: Added field masking context to Profile, Scan, and Dry Run operation pages; updated links across source records, data preview, export, materialize, glossary, and FAQ pages to point to the new concepts page
  • Scan page fix: Replaced ambiguous "remediation" term with explicit link to Materialize operation
  • Navigation: Added Masking Audit Log entry to mkdocs.yml and field status overview table
  • Spell check: Added LGPD to .typos.toml allowed words

Test plan

  • Verify new field masking concepts page renders correctly with all images
  • Confirm masking audit log page displays properly
  • Check unmask-a-field step-by-step instructions are clear
  • Validate all cross-reference links (profile, scan, dry run, source records, data preview, export, materialize, glossary, FAQ) resolve correctly
  • Ensure navigation entry for Masking Audit Log appears in the sidebar

🤖 Generated with Claude Code

@RafaelOsiro RafaelOsiro self-assigned this Mar 26, 2026
@RafaelOsiro RafaelOsiro added the documentation Improvements or additions to documentation label Mar 26, 2026
@RafaelOsiro RafaelOsiro marked this pull request as ready for review March 26, 2026 18:37
@greptile-apps
Copy link
Copy Markdown

greptile-apps bot commented Mar 26, 2026

Greptile Summary

This PR adds a comprehensive field masking documentation suite — a new concepts page, a masking audit log page, and a dedicated unmask-a-field page — while refactoring the existing mask-a-field.md to contain only procedural steps and cross-linking the conceptual material to the new page. Cross-references in Profile, Scan, Dry Run, Data Preview, Export, Materialize, Source Record, Glossary, and FAQ pages are updated consistently to point to the new concepts page.

Key changes:

  • docs/fields/field-status/concepts/field-masking.md — new comprehensive concepts page covering masked field identification, how masking works, surfaces affected, reveal behavior, unmask guidance with best practices, and field restrictions
  • docs/fields/field-status/managing-field-status/masking-audit-log.md — new page documenting the audit trail of reveal actions, including UI walkthroughs and API reference
  • docs/fields/field-status/managing-field-status/unmask-a-field.md — new step-by-step unmask page (container view, field view, bulk); images correctly moved to the unmask-a-field/ asset directory
  • mask-a-field.md — conceptual sections and unmask procedures removed; a tip block points readers to the new concepts page
  • mkdocs.yml / overview.md — three new navigation entries added in the correct positions
  • All existing cross-references updated from mask-a-field.md to concepts/field-masking.md
  • One minor concern in scan.md: the Enrichment Datastore bullet in the new "Field Masking and Scanning" section uses the undefined term "remediation" and links to the anomaly source-record page rather than the Materialize page, which is the operation that actually writes to the enrichment datastore.

Confidence Score: 4/5

Safe to merge; one minor wording issue in scan.md that could mislead readers about which operation writes to the enrichment datastore.

The PR is well-structured with consistent cross-references, valid image assets, and accurate content throughout. The only actionable issue is a single bullet in scan.md that uses 'remediation' ambiguously and points to the wrong cross-reference for enrichment-datastore masking — a targeted one-line fix resolves it. All other pages are accurate and the new concept/procedural split is a clear improvement.

docs/source-datastore/operations/scan.md — the Enrichment Datastore bullet in the 'Field Masking and Scanning' section.

Important Files Changed

Filename Overview
docs/fields/field-status/concepts/field-masking.md New comprehensive concepts page covering how masking works, where it is applied, reveal behavior, audit logging, unmask guidance, and field restrictions — well-structured with no issues found.
docs/fields/field-status/managing-field-status/mask-a-field.md Appropriately trimmed to step-by-step instructions only; conceptual content and unmask procedures correctly moved to dedicated pages; tip block added pointing to new concepts page.
docs/fields/field-status/managing-field-status/masking-audit-log.md New page documenting audit log access, entry details, and API reference; links to field-status-api.md#masking-audit-log which is a valid anchor — no issues found.
docs/fields/field-status/managing-field-status/unmask-a-field.md New step-by-step unmask page covering container view, field view, and bulk unmask; image assets correctly placed in the new unmask-a-field directory — no issues found.
docs/source-datastore/operations/scan.md New "Field Masking and Scanning" section added; the Enrichment Datastore bullet uses the ambiguous term "remediation" and cross-links to source-record.md rather than the Materialize page that covers enrichment-datastore writes.
docs/source-datastore/operations/profile.md New "Field Masking and Profiling" section correctly describes histogram obfuscation and cross-links to the Export operation page — no issues found.
mkdocs.yml Three new nav entries added (Field Masking, Unmask a Field, Audit Log) in correct positions within the field-status concepts and managing sections.
docs/fields/field-status/overview.md Field Masking, Unmask a Field, and Masking Audit Log entries added to the status tables with accurate descriptions — no issues found.
docs/datastore-checks/dry-run.md New info callout correctly notes unconditional masking in dry-run source records and links to reveal alternatives in Data Preview and Anomaly Source Records.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Field is Masked]) --> B{Surface}
    B --> C[Data Preview]
    B --> D[Anomaly Source Records]
    B --> E[Quality Check Dry Runs]
    B --> F[Field Profile Histograms]
    B --> G[Anomaly Assertion Context]
    B --> H[Export / Materialize Outputs]

    C -->|Editor+| C1[Show masked values button → Reveal\nAudit entry created]
    D -->|Editor+| D1[Per-anomaly reveal toggle\nAudit entry created]
    E --> E1[Unconditionally masked\nNo reveal available]
    F -->|API include_masked=true| F1[Histogram revealed\nAudit entry created]
    G --> G1[Unconditionally masked\nNo reveal available]
    H -->|API include_masked=true| H1[Actual values in output\nAudit entry created]

    A --> I{Unmask Field}
    I --> J([Field status → Active\nValues visible everywhere\nNo further audit entries])
Loading

Reviews (1): Last reviewed commit: "docs(masking): add field masking context..." | Re-trigger Greptile

RafaelOsiro and others added 2 commits March 27, 2026 11:14
…otection

Resolve merge conflict in .typos.toml by keeping all custom words

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@RafaelOsiro RafaelOsiro marked this pull request as draft March 30, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant