# PII & Secret Scanner for Confluence — User Guide **Product:** PII & Secret Scanner for Confluence **Platform:** Confluence Cloud / Atlassian Forge **Audience:** Confluence administrators, approved security-dashboard viewers, page editors, governance teams and auditors This guide describes the behavior implemented by the current Marketplace build. It deliberately avoids claims for older prototypes or planned features. --- ## 1. What the app does PII & Secret Scanner for Confluence uses deterministic rules inside Atlassian Forge to look for sensitive-data patterns in Confluence content. The current release provides: - page-body scanning for built-in PII and secret patterns - bounded scanning of supported text-like attachments - redacted finding previews - manual page checks - automatic scanning of changed pages and attachment events - resumable administrator-requested space checks - global issue filtering and triage - finding suppression/restoration - version-bound page review attestation - fixed policy/lifecycle governance signals - audit/change history - CSV and JSON evidence exports - administrator-controlled dashboard viewer access The app does **not** use a third-party AI/scanning service and the manifest configures no external egress. --- ## 2. Supported and unsupported content ### 2.1 Page body The app scans Confluence page body text. A page scan is bounded to **1,000,000 characters**. If the page exceeds the bound, coverage is marked incomplete instead of treating the page as clean. ### 2.2 Supported attachments Attachment scanning is enabled by default and can be disabled by a Confluence administrator in **Settings**. The current release scans text-like attachments up to **256 KiB per attachment**. Recognized extensions include: - `.txt` - `.json` - `.csv` - `.tsv` - `.log` - `.env` - `.yml` / `.yaml` - `.xml` - `.md` Attachments that Confluence reports with a text, JSON or CSV media type can also be scanned when they remain within the same size bound. ### 2.3 Unsupported attachments The current release does **not** parse: - PDF - DOCX - XLSX - PPTX - image/OCR content - encrypted documents - legacy Office binary formats Unsupported, oversized, failed or skipped attachments produce **incomplete coverage**. They are never interpreted as having been scanned and found clean. ### 2.4 Finding bound A page scan stores at most **500 findings**. When detector output is truncated, coverage is treated as incomplete. --- ## 3. Product surfaces ### 3.1 Governance Check on a page Open a Confluence page and choose **Governance Check** from the page actions menu. The modal can: - show the latest stored scan - run **Check now** - show open/suppressed findings with redacted previews - identify whether a finding came from the page body or a supported attachment - show an incomplete-coverage warning - suppress or restore a finding - record **Mark as reviewed** for the current scanned page version A user must be able to view the page to read or scan it. Recording a review requires **update permission** on that page. ### 3.2 Governance status byline The app also provides a lightweight Confluence byline item. Use it as an entry point/status signal and open Governance Check for the full finding view. ### 3.3 Global security workspace The global app page uses these navigation items: 1. **Dashboard** 2. **Spaces** 3. **Findings / Issues** 4. **What to look for** 5. **Change history** 6. **Exports** 7. **Help** 8. **Settings** — administrators only There is no separate General, PII Detection, Lifecycle, Policy or Report tab in the current UI. --- ## 4. Access model ### 4.1 Dashboard access Confluence administrators can open the global dashboard. Administrators can also approve specific Confluence users as dashboard viewers in **Settings → Dashboard access**. Dashboard authorization is enforced by the backend resolver, not only by UI visibility. ### 4.2 Page visibility The app stores scan results in tenant-scoped Forge SQL. Before page-scoped dashboard results are returned, the backend projects those records through the current user's Confluence visibility. A dashboard viewer is not granted access to pages they cannot see in Confluence. ### 4.3 Administrator-only actions The following operations are administrator restricted on the server: - dashboard viewer management - detector configuration - starting/cancelling space reviews - administrative reports/operational actions --- ## 5. Getting started 1. Install the app and grant the requested Confluence scopes. 2. Open **PII & Secret Scanner for Confluence** from the Confluence Apps area. 3. In **Settings**, confirm whether automatic changed-page scanning and attachment scanning should be enabled. 4. In **What to look for**, review the built-in detectors and disable only rules that are not appropriate for your environment. 5. Optionally create narrowly scoped custom regex checks using synthetic test data. 6. Run **Governance Check → Check now** on representative test pages. 7. Use **Scan space / Check a space** to schedule a bounded space review. 8. Review Findings, Change history and Exports before using app output in a governance process. Use synthetic data for acceptance testing. Do not seed real secrets merely to test a detector. --- ## 6. Automatic and manual scanning ### 6.1 Changed-page scanning Confluence page and attachment product events enqueue the affected page. A scheduled worker drains the deduplicated queue. The worker runs frequently, while a per-tenant daily budget keeps automatic work bounded. Automatic changed-page checks are limited to **1,000 pages per tenant per UTC day**. Delayed page events are version-guarded so an older page version cannot replace a newer queued version. Attachment events use a force-rescan marker so an attachment-only change is not skipped merely because the parent page version is unchanged. ### 6.2 Manual checks Manual page and space reviews use a separate **1,000 pages per tenant per UTC day** budget. A space review is resumable. Large spaces can continue across multiple worker invocations and, when necessary, multiple days. ### 6.3 Installation discovery A new installation initializes Forge SQL and performs bounded site discovery so existing pages can be queued for an initial pass. This is not a recurring full-site sweep feature. --- ## 7. Dashboard The Dashboard summarizes current stored results and includes metrics for: - pages scanned today - open Critical findings - open High findings - open attachment findings Administrators can also see scheduled space checks and cancel queued/running reviews. The **Recent findings** table supports Suppress/Restore actions and links back to visible Confluence pages. --- ## 8. Spaces Use **Spaces** to search the Confluence space directory and inspect the saved scan state. Statuses are: - **Not scanned** — there is no saved scan for the space yet - **Up to date** — scanned pages currently have no saved risk signal - **Needs attention** — at least one saved scan has a risk signal An unscanned space is never displayed as Up to date. Administrators can schedule a space check from this view. --- ## 9. Findings / Issues The Issues view supports server-side filtering by: - text query - space - severity - detector/rule - status (`Open`, `Suppressed`, or `All`) Finding previews are redacted. Use **Suppress** for an accepted false positive and **Restore** to return a suppressed finding to the open state. Suppressing a finding changes app-owned finding state; it does not edit the Confluence page. --- ## 10. What to look for ### 10.1 Built-in rules Administrators can enable or disable built-in deterministic detectors. The current detector set includes common PII and credential/token formats such as email addresses, phone numbers, payment/account identifiers, passwords, private keys and provider-specific token formats. ### 10.2 Custom rules Administrators can create up to **50** custom regular-expression checks. Custom rules in the current UI use: - a name up to 100 characters - a validated regular expression - case-insensitive/global matching - Medium severity Unsafe or invalid regular expressions are rejected. Keep custom expressions specific and test them against representative synthetic text. --- ## 11. Reviews **Mark as reviewed** records a review only when: - the caller has update permission on the page - the page has a completed scan - the stored scan version matches the current Confluence page version The review is bound to that page version. If the page is edited later, the previous review no longer represents the current version. The current release sets the next-review date to 90 days after attestation. --- ## 12. Policy and lifecycle signals Policy and lifecycle checks use fixed release defaults. They are not configurable in the current UI. Default lifecycle thresholds are: - Needs attention: 300 days - Stale: 365 days - Archived governance classification: 730 days Default lifecycle exclusion labels include `permanent`, `reference`, and `no-archive`. The Archived lifecycle state is an **app governance classification**, not a Confluence native archive operation. The Marketplace build does not automatically: - add/remove lifecycle labels - reconcile lifecycle labels - post lifecycle comments - change page restrictions - archive/unarchive Confluence content - edit page body content Lifecycle classification is advisory. --- ## 13. Ownership and exposure ### 13.1 Ownership When Confluence REST v2 supplies a native page owner, the scan records ownership as assigned. An `owner:` metadata label can also provide ownership context. If owner metadata is unavailable, ownership is reported as unknown. The current release does **not** classify owners as active, inactive/deactivated, internal, or external. ### 13.2 Exposure The current release does **not** classify anonymous, guest, public-link, restricted, or space-wide exposure. Exposure is reported as **not assessed**. Use Confluence's own permissions and access-management tools for access review. Do not interpret this app's risk score as a permissions audit. --- ## 14. Change history The Change history view shows bounded app audit events such as scans, detector configuration, finding-state changes, dashboard-access changes and review attestations. Page-scoped events are filtered so a dashboard viewer does not receive events for pages they cannot currently see in Confluence. --- ## 15. Exports The Exports view can generate evidence in: - CSV - JSON Exports are bounded and permission-filtered. CSV output neutralizes spreadsheet-formula prefixes before download. Treat exports as evidence produced by this app, not as legal/compliance certification. --- ## 16. Settings Administrator settings currently include: ### Automatic changed-page checks Controls whether changed pages are automatically checked by the background worker. ### Attachment scanning Controls whether supported text-like attachments are included in page scans. When disabled, coverage is incomplete rather than clean. ### Dashboard access Search for Confluence users and explicitly grant or remove dashboard viewer access. Confluence administrators always retain access. The current Settings view does not expose policy thresholds, lifecycle thresholds/actions, exposure controls, attachment size limits, or scheduled full-site cadence controls. --- ## 17. Data handling and privacy - No external egress domain is configured in `manifest.yml`. - Analysis runs inside Atlassian Forge. - Scan/configuration data is stored in tenant-scoped Forge SQL. - Findings use redacted previews rather than storing the original matched value. - Raw Confluence response bodies are not copied into app-facing error messages for lifecycle/page-owner write failures. - Page-scoped dashboard and audit data is projected through current-user Confluence visibility. The app still processes Confluence customer data inside Atlassian infrastructure. Administrators should review the Marketplace privacy/security disclosures and their own organizational requirements before installation. --- ## 18. Operational limits and caveats - Automatic scan budget: 1,000 pages/tenant/UTC day. - Manual scan budget: 1,000 pages/tenant/UTC day. - Page body bound: 1,000,000 characters. - Attachment text bound: 256 KiB per attachment. - Finding bound: 500 per page scan. - Unsupported/failed/skipped attachment content produces incomplete coverage. - Forge SQL platform quotas and query timeouts also apply. - Forge SQL is not currently supported for Atlassian Government Cloud; the manifest also uses `arm64`, which is not an AGC-supported Forge architecture. Do not advertise this build as AGC compatible. --- ## Release availability Marketplace release coming soon. Contact support@ravenshift.com.