120 lines
7.2 KiB
Markdown
120 lines
7.2 KiB
Markdown
# Plan — Mailbox Permission Scanning
|
|
|
|
Voorstel voor het uitbreiden van Clearview met mailbox-rechten scanning naast de bestaande SharePoint-scan. Status: **voorstel, nog niet geïmplementeerd**.
|
|
|
|
## 1. Scope & aanpak
|
|
|
|
In Exchange Online zijn dit de relevante permissie-categorieën:
|
|
|
|
| Permissie | Bron | Waarop |
|
|
|---|---|---|
|
|
| **Full Access / Read** | `Get-MailboxPermission` | hele mailbox |
|
|
| **Send As** | `Get-RecipientPermission` | identiteit |
|
|
| **Send on Behalf** | mailbox-property `GrantSendOnBehalfTo` | identiteit |
|
|
| **Folder delegaties** (Calendar, Inbox) | `Get-MailboxFolderPermission` | per folder |
|
|
|
|
Microsoft Graph dekt dit slechts gedeeltelijk (vooral folder-permissies). De volledige set vereist **Exchange Online PowerShell met certificaat-auth** (`Connect-ExchangeOnline -CertificateThumbprint ... -AppId ... -Organization ...`). Dat sluit goed aan op het bestaande cert-model van Clearview — dezelfde Azure-app kan zowel `Sites.FullControl.All` (SharePoint) als `Exchange.ManageAsApp` (Exchange) krijgen.
|
|
|
|
**Voorgestelde aanpak:** EXO PowerShell aanroepen vanuit Python via `pwsh` subprocess, JSON-output retour. Alternatief is pure Graph, maar dan mist Send As / Send on Behalf grotendeels.
|
|
|
|
**Deviation-baseline voor mailboxen:** anders dan SharePoint heeft een mailbox geen "root vs. child" hiërarchie waar een baseline uit volgt. Voorstel: rapporteer **alle non-default permissies** (filter standaard-entries als `NT AUTHORITY\SELF`, `S-1-5-10`, default folder-permissies "Default"/"Anonymous=None") als deviation. Dus géén delta-vergelijk, maar wel dezelfde dedup-logica per (principal, role).
|
|
|
|
## 2. Layout-wijzigingen frontend
|
|
|
|
Huidige website is volledig op SharePoint gemodelleerd (één scanflow, één resultaattabel). Voorstel:
|
|
|
|
**a. Scan-type keuze in "Start New Scan"**
|
|
- Tabs of segmented control bovenaan: **SharePoint Sites** / **Mailboxes**
|
|
- Bij Mailboxes verandert het invoerveld: één UPN/email per regel (geen "skip default sites")
|
|
- CSV-import: extra accept-formaat (kolom `UserPrincipalName` / `Email` / `Mailbox`)
|
|
|
|
**b. Jobs-tabel**
|
|
- Nieuwe kolom **Type** (SharePoint / Mailbox)
|
|
- Tenant-filter blijft, extra filter op type
|
|
|
|
**c. Job Details panel**
|
|
- Sectie heading wordt dynamisch: "Targets" blijft, maar URL-kolom wordt "Mailbox" voor mailbox-jobs
|
|
- Permission Deviations tabel krijgt voor mailbox-jobs andere kolommen:
|
|
- Mailbox · Folder (leeg voor mailbox-level) · Permission Type (FullAccess/SendAs/SendOnBehalf/Folder) · Principal · Access Rights
|
|
- SharingLinks-blok wordt verborgen voor mailbox-jobs
|
|
- Site-filter wordt mailbox-filter
|
|
|
|
**d. Tenants-panel**
|
|
- In de onboarding-instructies een extra stap erbij: API permission `Office 365 Exchange Online → Exchange.ManageAsApp` + role `Exchange Administrator` toekennen aan de service principal. Voor de geautomatiseerde flow betekent dit een extra Graph-call (rol-toekenning kan niet altijd, dus mogelijk handmatige stap).
|
|
- Statuskolom `Auth` toont al cert/secret; voorstel: extra capability-badge per tenant (`SP`, `EXO`) zodat zichtbaar is welke scans mogelijk zijn.
|
|
|
|
## 3. Backend-optimalisatie / herstructurering
|
|
|
|
`scanner.py` is nu één bestand met SharePoint-specifieke logica én generieke helpers (auth, HTTP, dedup, role-name normalization). Voorstel:
|
|
|
|
```
|
|
src/clearview_app/scanners/
|
|
__init__.py # dispatcher: scan(target_type, ...)
|
|
common.py # AuthConfig, DeviationRecord, ScanResult, ProbeResult,
|
|
# MSAL token cache, _request_json, _iter_paged,
|
|
# _deduplicate_hierarchical, role-name normalization
|
|
sharepoint.py # huidige scan_site_for_deviations + probe_site + resolve_sharing_link_members
|
|
mailbox.py # nieuw: scan_mailbox_for_deviations + probe_mailbox
|
|
# roept pwsh aan met EXO-script en parseert JSON
|
|
exo_scripts/
|
|
get-permissions.ps1 # connect + get mailbox/recipient/folder permissions, output JSON
|
|
probe.ps1 # lichtgewicht: Get-EXOMailbox -Identity x | select Identity
|
|
```
|
|
|
|
Voordelen:
|
|
- `scanner.py` was richting 540 regels en mengt concerns; opsplitsen maakt testen makkelijker
|
|
- `worker.py` krijgt één dispatcher-call: `scan(target_type, target, auth, progress)` ipv. directe import van SharePoint-specifieke functies
|
|
- Toekomstige scan-types (OneDrive, Teams) passen in hetzelfde patroon
|
|
|
|
**Worker.py** moet leren: per target weten welke scanner aan te roepen op basis van `scan_targets.target_type` (of `scan_jobs.scan_type`).
|
|
|
|
## 4. Datamodel
|
|
|
|
Minimale, niet-brekende wijzigingen — toegepast via bestaand `_ensure_schema_columns()`:
|
|
|
|
| Tabel | Nieuwe kolom | Default |
|
|
|---|---|---|
|
|
| `scan_jobs` | `scan_type` VARCHAR(32) | `'sharepoint'` |
|
|
| `scan_targets` | (geen — `site_url` blijft, bevat UPN voor mailbox-jobs; of hernoem naar `target` met DB-view voor compat) | — |
|
|
| `permission_deviations` | `permission_type` VARCHAR(32) NULL | NULL (voor SP-rows) |
|
|
| `permission_deviations` | `object_type` krijgt nieuwe waarden: `Mailbox`, `MailboxFolder` | — |
|
|
|
|
**Vraag:** liever `site_url` houden als generieke "target identifier" (compacter, geen migratie), of nu hernoemen? Eerste optie is mijn voorstel.
|
|
|
|
## 5. API-endpoints
|
|
|
|
Bestaand blijft werken. Toevoegingen:
|
|
|
|
```
|
|
POST /api/scan-jobs payload krijgt optioneel "scan_type": "sharepoint"|"mailbox"
|
|
en "mailboxes": [...] naast/ipv "site_urls"
|
|
POST /api/scan-jobs/import-csv extra "scan_type" form-field
|
|
GET /api/scan-jobs?scan_type=mailbox filter
|
|
```
|
|
|
|
Nieuwe response-velden in `ScanJobDetail`: `scan_type`, en deviations krijgen `permission_type`.
|
|
|
|
## 6. Onboarding & runtime-vereisten
|
|
|
|
- **Container**: PowerShell 7 (`pwsh`) en de `ExchangeOnlineManagement` PS-module installeren in de Docker image. Dit voegt ~150MB toe. Acceptabel?
|
|
- **Azure-app**: extra permission `Office 365 Exchange Online → Exchange.ManageAsApp` + Entra-rol "Exchange Administrator" voor de service principal. In Mode A (automated) kan het permission-deel via Graph, het rol-deel meestal niet — handmatige bevestigingsstap nodig.
|
|
- **Probe**: voor mailboxen één kleine call (`Get-EXOMailbox -Identity <upn> -Properties Identity` via een korter PS-script) om vroeg te falen op auth/rol.
|
|
|
|
## 7. Implementatiestappen (volgorde)
|
|
|
|
1. Backend refactor: scanner-module opsplitsen, geen functionele wijziging (groen test)
|
|
2. Datamodel: `scan_type` + `permission_type` toevoegen, default `'sharepoint'`
|
|
3. Mailbox-scanner: PS-scripts + Python-wrapper + dispatcher; alleen via API testbaar
|
|
4. API: scan-job creatie uitbreiden met `scan_type`/`mailboxes`
|
|
5. Frontend: scan-type segment in formulier + dynamische kolommen in details
|
|
6. Onboarding-tekst en build (Dockerfile voor `pwsh`)
|
|
7. Documentatie: TECHNICAL.md + changelog-develop.md
|
|
|
|
## Open vragen
|
|
|
|
1. **PowerShell-route akkoord**, of liever Graph-only (incompleter, maar pure Python)?
|
|
2. **Eén scan-type per job** (voorstel), of mengbare jobs (SharePoint + mailboxen door elkaar)?
|
|
3. **Baseline voor mailbox**: alle non-default rechten als deviation rapporteren (voorstel), of moet er een "expected baseline" per mailbox/tenant configureerbaar worden?
|
|
4. **Image-grootte**: is +150 MB voor `pwsh` + EXO-module aanvaardbaar?
|
|
5. **`site_url` kolom hergebruiken** als generieke target-identifier, of nu hernoemen naar `target`?
|