SPO Permissions Hub

🎯 Objetivo del Proyecto 01

SPO Permissions Hub es una plataforma interna que escanea, almacena y presenta informes de permisos de sitios SharePoint Online. Sustituye al uso manual de herramientas comerciales como Syskit, ofreciendo:

🏛 Arquitectura 02

La plataforma sigue una arquitectura de 4 capas, comunicadas por NDJSON streaming y SQLite (WAL mode):

📁 Estructura de Ficheros 03

🧩 Componentes Detallados 04

4.1 Scanner (Get-SPOPermissionsReport.ps1)

Script PowerShell 7 de ~1000 lineas que realiza el escaneo completo de un sitio SPO.

Modos de autenticacion:

• Desatendido (certificado): ClientId + Thumbprint/CertificatePath + Tenant
• Interactivo: ClientId + navegador (MFA compatible)
• Auto-registro: si no hay ClientId, registra una App de Entra ID automaticamente

Modos de salida:

• -OutputJson: NDJSON a stdout, logs a stderr (para el orchestrator)
• CSV + HTML (modo tradicional, ejecucion standalone)

4.2 Orchestrator (orchestrator.py)

Proceso Python que coordina los escaneos:

• Lee sitios habilitados de la tabla sites en SQLite
• Crea un registro en scans con estado running
• Lanza el PS1 via subprocess.Popen con dos threads:
  • Thread stderr: lee progreso en tiempo real y actualiza scans.last_progress
  • Thread stdout: parsea NDJSON e inserta en permissions en batches de 500
• Soporta ejecucion paralela con --max-workers N (ThreadPoolExecutor)
• Puede lanzarse manual (--triggered-by manual) o programado (run_scan.bat)

4.3 Database (SQLite)

Base de datos SQLite con WAL mode para concurrencia lectura/escritura. Ver seccion 6 para el esquema completo.

4.4 Web Application (Flask)

Aplicacion Flask con 4 blueprints:

Endpoints API:

🔄 Flujo de Datos Completo 05

Para cada sitio, el proceso sigue estas fases:

Fase 1: Enumeracion (~10 min para 400K items)

Get-PnPListItem -PageSize 500 obtiene todos los items de cada lista/biblioteca. Se filtran en PowerShell para quedarse solo con carpetas (FSObjType=1), o todos los items si se usa -IncludeFiles.

Fase 2: Pre-filtro REST $batch (~36 min para 65K carpetas)

Se envian batches de 100 peticiones GET al endpoint _api/$batch de SharePoint, consultando HasUniqueRoleAssignments para cada item. Esto devuelve un HashSet<int> con los IDs de items que realmente tienen permisos unicos.

// Ejemplo de sub-request en el batch multipart
GET {webUrl}/_api/web/lists(guid'{listId}')/items({itemId})/HasUniqueRoleAssignments HTTP/1.1
Accept: application/json;odata=nometadata

// Respuesta por item
{"value": true}   // o false

Fase 3: Extraccion de permisos CSOM (~25 min para 1591 items)

Para cada item con permisos unicos, se cargan las RoleAssignments via CSOM (PnP PowerShell) y se expanden:

• Grupos SharePoint → miembros individuales
• Grupos Entra ID → miembros via Microsoft Graph
• Sharing Links → identificados por patron en LoginName
• Usuarios → enriquecidos con Graph (departamento, cargo)

Cada permiso se emite como una linea JSON a stdout (NDJSON).

Fase 4: Ingesta y almacenamiento

El orchestrator lee stdout del PS1 linea a linea, parsea JSON, y hace INSERT en batches de 500 filas en la tabla permissions. Simultaneamente, lee stderr para mostrar progreso en logs y actualizar scans.last_progress.

🗄 Modelo de Datos 06

CREATE TABLE sites (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    url             TEXT    NOT NULL UNIQUE,
    display_name    TEXT    NOT NULL DEFAULT '',
    enabled         INTEGER NOT NULL DEFAULT 1,
    include_files   INTEGER NOT NULL DEFAULT 0,
    created_at      TEXT    NOT NULL DEFAULT (datetime('now')),
    notes           TEXT    NOT NULL DEFAULT ''
);

CREATE TABLE scans (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    site_id         INTEGER NOT NULL REFERENCES sites(id),
    started_at      TEXT    NOT NULL DEFAULT (datetime('now')),
    finished_at     TEXT,
    status          TEXT    NOT NULL DEFAULT 'running'
                    CHECK(status IN ('running','success','failed','skipped')),
    row_count       INTEGER,
    error_message   TEXT,
    ps1_duration_s  REAL,
    triggered_by    TEXT    NOT NULL DEFAULT 'scheduler',
    last_progress   TEXT    NOT NULL DEFAULT ''
);

CREATE TABLE permissions (
    id                      INTEGER PRIMARY KEY AUTOINCREMENT,
    scan_id                 INTEGER NOT NULL REFERENCES scans(id),
    site_id                 INTEGER NOT NULL REFERENCES sites(id),
    url                     TEXT,    -- URL completa del objeto SPO
    sharepoint_object       TEXT,    -- Nombre del objeto
    object_type             TEXT,    -- Site|DocumentLibrary|List|Folder|ListItem
    inherits_permissions    INTEGER, -- 0 = permisos unicos
    name                    TEXT,    -- Nombre del principal
    email                   TEXT,    -- Email del usuario
    principal_type          TEXT,    -- User|SharePointGroup|SecurityGroup|SharingLink
    given_through           TEXT,    -- Directly o nombre del grupo
    department              TEXT,    -- Desde Microsoft Graph
    job_title               TEXT,    -- Desde Microsoft Graph
    perm_full_control       INTEGER, -- Nivel de permiso
    perm_edit               INTEGER,
    perm_contribute         INTEGER,
    perm_read               INTEGER,
    -- + is_external_user, is_deleted, is_licensed, ...
);

🐛 Problema Detectado: Bug CSOM HasUniqueRoleAssignments 07

Sintoma

Al escanear el sitio "idealista" (406K+ items, 65K carpetas en la biblioteca "Documentos"), el scanner reportaba 65,243 carpetas con permisos unicos y tardaba horas en completar. La herramienta comercial Syskit, como referencia, reportaba solo 1,591 carpetas.

Causa raiz

Se identificaron dos causas superpuestas:

Causa 1: Bug CSOM en bibliotecas grandes

Tanto Get-PnPListItem -Includes "HasUniqueRoleAssignments" como el enfoque explicito con $ctx.Load($item, $lambda) + Invoke-PnPQuery devuelven $true para todos los items cuando se cargan con paginacion en bibliotecas grandes (>5000 items).

Causa 2: Flag -IncludeInherited en base de datos

El sitio "idealista" tenia include_inherited = 1 en la DB. Esto activaba el parametro -IncludeInherited en el PS1, que contenia esta linea:

if ($IncludeInherited) { $uniqueItems = $items }  # bypass TOTAL del filtro REST

🔧 Solucion Implementada 08

Fix 1: REST $batch API como pre-filtro

Se reemplazo el chequeo CSOM de HasUniqueRoleAssignments por llamadas a la REST API via el endpoint _api/$batch de SharePoint:

• Batches de 100 peticiones GET en formato multipart MIME
• Cada sub-request consulta: items({id})/HasUniqueRoleAssignments
• Token Bearer obtenido via Get-PnPAccessToken -ResourceTypeName SharePoint
• Refresh automatico del token cada 50 batches
• Reintentos con backoff para throttling (HTTP 429)
• Retorna HashSet<int> con IDs de items con permisos unicos

Fix 2: return ,$uniqueIds

PowerShell "desenrolla" colecciones al retornarlas de funciones. Un HashSet<int> se convierte en [object[]], perdiendo el metodo .Contains(). La coma unaria (,$var) previene esta enumeracion.

Fix 3: Eliminacion completa de -IncludeInherited

Se elimino la funcionalidad de incluir objetos con permisos heredados de todo el proyecto, ya que nunca se necesita un informe con las ~65K carpetas que heredan permisos:

Fix 4: Otros fixes tecnicos

📅 Cronologia de Fixes 09

📊 Resultados y Verificacion 10

Comparativa: Antes vs Despues

Validacion contra Syskit

Desglose del scan (scan_id=15)

Decision de diseno: Por que no Graph API

Se evaluo migrar a Microsoft Graph API pero se descarto porque:

• Graph no expone HasUniqueRoleAssignments
• El modelo de permisos de Graph no mapea a niveles SP (Full Control, Edit, etc.)
• Graph no tiene API para grupos SharePoint
• El script ya usa Graph de forma optima: para grupos AAD y enriquecimiento de usuarios

✨ Novedades v1.1 11

Mejoras incorporadas tras el lanzamiento inicial, basadas en uso real y feedback de operaciones.