Ivo Oskamp
b8446c0665
Full application including FastAPI backend, PostgreSQL data model, background scan worker, multi-tenant support, certificate authentication, SharePoint REST scanner with hierarchical deduplication, SharingLinks classification and post-scan resolve, Excel export, site filter in job details, role name normalisation, and updated documentation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./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.
|