clearview/README.md

Clearview

SharePoint permission deviation scanner for multiple customer tenants.

Clearview scans SharePoint sites down to folder and file level and reports only permissions that deviate from the root permissions of each site. Designed to manage and monitor multiple customer tenants from a single instance.

---

How it works

1. Add a customer tenant (name, Azure tenant ID, client ID)
2. Generate a certificate — upload the public .cer to the Azure app registration
3. Submit site URLs manually or via a Microsoft Sites CSV export
4. Clearview scans asynchronously and reports permission deviations

Only permissions that are added relative to the site root are reported (delta_type=added). No NTFS or filesystem permissions are used.

Deviations are deduplicated hierarchically: if a principal already has a deviation at a library or folder level, individual files below that level are suppressed.

---

Job Details

After a scan completes, the Selected Job Details panel provides:

• Site filter — narrow targets and deviations to a single site
• Export Excel — download a .xlsx file with Targets and Deviations sheets, sorted by Site URL → Object URL → Principal
• Resolve Sharing Links — fetch the actual recipients of sharing links post-scan (Anonymous and Flexible types resolved by default)

SharingLinks colour coding

Type	Risk	Colour
Anonymous*	Critical	Red
Flexible	High	Orange
Organization*	Low	Blue
Direct*	Low	Green

---

Deployment

Prerequisites

• Docker + Docker Compose (or Portainer)

Stack

Copy stack/.env and stack/docker-compose.yml to your deployment location and adjust .env as needed. The .env file is self-documented.

Start the stack:

docker compose -f stack/docker-compose.yml up -d

Clearview is available at http://<host>:<CLEARVIEW_PORT>.
Adminer (database inspector) is available at http://<host>:<ADMINER_PORT>.

---

Azure app setup (per tenant)

Each customer tenant requires a dedicated Azure app registration with SharePoint access.

1. Azure Portal → Entra ID → App registrations → New registration
   • Name: e.g. Clearview Scan App
   • Supported account types: Single tenant
2. Copy the Directory (tenant) ID and Application (client) ID
3. API permissions → Add → SharePoint → Application permissions → Sites.FullControl.All → Grant admin consent
4. Add the tenant in Clearview (name, tenant ID, client ID)
5. Click Certificate → download the .cer file
6. Upload the .cer in Azure Portal → App registration → Certificates & secrets → Certificates

---

Build

./build-and-push.sh t    # test build (:dev tag)
./build-and-push.sh 1    # patch release
./build-and-push.sh 2    # minor release
./build-and-push.sh 3    # major release

---

Data model

Table	Description
tenant_profiles	Customer tenant credentials and certificates
scan_jobs	Scan jobs with status and progress tracking
scan_targets	Individual sites within a job
permission_deviations	Detected permission deviations per target, including resolved sharing link members

See docs/TECHNICAL.md for full architecture documentation.