fabricgov 0.8.1

Biblioteca Python para extralçao automatizada de dados para governança em Microsoft Fabric

fabricgov

Biblioteca Python para assessment automatizado de governança em ambientes Microsoft Fabric

🇺🇸 English documentation: README.en.md

---

🎯 O que é?

fabricgov automatiza coleta de dados de governança em Microsoft Fabric via CLI ou Python.

Principais features:

• 🔍 Inventário completo de workspaces e 27+ tipos de artefatos
• 🔐 Coleta de acessos (workspaces, reports, datasets, dataflows)
• 🔄 Histórico de refresh e agendamentos configurados
• 🏢 Domínios, tags, capacidades e workloads do tenant
• 💾 Sistema de checkpoint para tenants grandes (retoma de onde parou)
• 📊 Export em JSON ou CSV
• 📄 Relatório HTML automático com gráficos e findings de governança (PT + EN)
• 🔍 Análise de governança no terminal via fabricgov analyze (sem chamadas de API)
• ⚡ CLI pronto para uso
• 🛡️ Rate limit handling automático

---

📦 Instalação

# Via pip (recomendado)
pip install fabricgov

# Ou via Poetry
poetry add fabricgov

# CLI fica disponível
fabricgov --help

---

🚀 Quick Start

1. Autenticação

Escolha o método conforme seu cenário:

Service Principal (automação / CI-CD)

# Copie o template e preencha com suas credenciais
cp .env-example .env
# FABRICGOV_TENANT_ID=seu-tenant-id
# FABRICGOV_CLIENT_ID=seu-client-id
# FABRICGOV_CLIENT_SECRET=seu-client-secret

fabricgov auth sp       # valida as credenciais

Device Flow (uso manual / desenvolvimento local)

fabricgov auth device   # abre fluxo interativo no browser (sem .env necessário)

📘 Guia completo de autenticação →

Permissões necessárias

Autenticação	Permissão obrigatória	Onde configurar
Service Principal	Tenant.Read.All + Workspace.ReadWrite.All (Application)	Azure AD → App Registrations → API Permissions
Service Principal	Habilitado nas APIs Admin do Fabric	Portal Admin do Fabric → Configurações do tenant
Device Flow	Role Fabric Administrator no tenant	Portal Admin do Fabric → Usuários

⚠️ Sem essas permissões, as coletas retornam 403 Forbidden.

---

2. Use o CLI

# Coleta inventário
fabricgov collect inventory

# Coleta acessos (com checkpoint automático)
fabricgov collect workspace-access
fabricgov collect report-access
fabricgov collect dataset-access
fabricgov collect dataflow-access
fabricgov collect all-access   # todos os acessos de uma vez

# Coleta refresh
fabricgov collect refresh-history
fabricgov collect refresh-schedules
fabricgov collect all-refresh   # histórico + agendamentos

# Coleta infraestrutura
fabricgov collect domains
fabricgov collect tags
fabricgov collect capacities
fabricgov collect workloads

# Coleta completa em sessão única
fabricgov collect all
fabricgov collect status          # status da sessão

Flags disponíveis:

• --format json|csv (padrão: csv)
• --output DIR (padrão: output)
• --resume/--no-resume (padrão: resume habilitado)

---

4. Analise os findings de governança (terminal)

fabricgov analyze                                         # pasta mais recente em output/
fabricgov analyze --from output/20260227_143000/          # pasta específica
fabricgov analyze --from output/20260227_143000/ --lang en  # mensagens em inglês

Exibe findings diretamente no terminal (sem abrir o HTML) e salva findings.json na pasta de origem.

---

3. Gere o relatório de governança

fabricgov report                                      # pasta mais recente em output/
fabricgov report --from output/20260227_143000/       # pasta específica
fabricgov report --from output/20260227_143000/ --open  # gera e abre no browser

Gera automaticamente dois arquivos HTML standalone:

• report.html — Português
• report.en.html — English

📘 Guia completo do relatório → — seções, fontes de dados e regras aplicadas

---

5. Ou use como biblioteca Python

from fabricgov.auth import ServicePrincipalAuth
from fabricgov.collectors import WorkspaceInventoryCollector
from fabricgov.exporters import FileExporter

# Autentica
auth = ServicePrincipalAuth.from_env()

# Coleta inventário
collector = WorkspaceInventoryCollector(auth=auth)
result = collector.collect()

# Exporta
exporter = FileExporter(format="csv", output_dir="output")
exporter.export(result, [])

---

📊 Coletores Disponíveis

Coletor	O que coleta	Checkpoint
WorkspaceInventoryCollector	Inventário completo (workspaces + 27 tipos de artefatos)	✅
WorkspaceAccessCollector	Roles (Admin, Member, Contributor, Viewer)	✅
ReportAccessCollector	Permissões em reports	✅
DatasetAccessCollector	Permissões em datasets	✅
DataflowAccessCollector	Permissões em dataflows	✅
RefreshHistoryCollector	Histórico de execuções de datasets e dataflows	—
RefreshScheduleCollector	Agendamentos configurados (sem chamadas de API)	—
DomainCollector	Domínios do tenant (hierarquia, sensitivity labels)	—
TagCollector	Tags do tenant (escopo tenant ou domínio)	—
CapacityCollector	Capacidades Premium/Fabric (SKU, região, admins)	—
WorkloadCollector	Workloads de capacidades Gen1 (P-SKU, A-SKU)	—

📘 Ver exemplos detalhados →

---

💾 Sistema de Checkpoint

Para tenants grandes, o checkpoint salva progresso automaticamente:

# Execução 1: processa 200 itens, salva checkpoint
fabricgov collect report-access
# ⏹️ Rate limit atingido (429)

# Aguarda ~1h30min

# Execução 2: retoma de onde parou (automático)
fabricgov collect report-access
# ✓ Processa mais 200 itens...

Como funciona:

1. Detecta rate limit (429)
2. Salva checkpoint automaticamente
3. Encerra script (terminal liberado)
4. Na próxima execução, retoma de onde parou

📘 Entenda limitações de rate limit →

---

🏗️ Arquitetura

fabricgov/
├── cli/                # CLI via Click
├── auth/               # ServicePrincipalAuth + DeviceFlowAuth
├── collectors/         # 11 collectors (access, refresh, infraestrutura)
├── exporters/          # JSON/CSV export
├── reporters/          # Report HTML (InsightsEngine + HtmlReporter + template)
├── checkpoint.py       # Sistema de checkpoint
└── exceptions.py       # Exceções customizadas

---

📊 Exemplo de Output

output/
├── inventory_result.json           # Reutilizável entre collectors
├── checkpoint_report_access.json   # Checkpoint (auto-removido ao completar)
└── 20260226_143000/                # Timestamped folder
    ├── summary.json
    ├── workspaces.csv
    ├── reports.csv
    ├── workspace_access.csv
    ├── report_access.csv
    ├── dataset_access.csv
    ├── dataflow_access.csv
    ├── refresh_history.csv
    ├── refresh_schedules.csv
    ├── domains.csv
    ├── tags.csv
    ├── capacities.csv
    ├── workloads.csv
    ├── workloads_errors.csv
    ├── report.html         # Relatório de governança (PT)
    ├── report.en.html      # Governance report (EN)
    └── findings.json       # Findings de governança (fabricgov analyze)

---

⚠️ Limitações Conhecidas

Rate Limiting

• APIs Admin: ~200 requests/hora (não documentado)
• Tenants grandes: múltiplas execuções com pausas de ~1h30min
• Checkpoint permite retomar sem perder progresso

Personal Workspaces

• Não suportam APIs de usuários (retornam 404)
• Filtrados automaticamente (30-60% dos workspaces em tenants típicos)

Performance

• 200 workspaces: ~10 min
• 663 reports: ~5h (4 execuções com pausas)
• 2000+ itens: requer coleta agendada

📘 Lista completa de limitações →

---

🗺️ Roadmap

✅ v0.3.0 - 2026-02-23

• CLI completo (fabricgov command)
• DatasetAccessCollector
• DataflowAccessCollector
• 5 collectors com checkpoint
• Primeira Versão no Pypi

✅ v0.4.0 - 2026-02-24

• RefreshHistoryCollector (histórico de execuções)
• RefreshScheduleCollector (agendamentos configurados)
• CLI: fabricgov collect refresh-history
• CLI: fabricgov collect refresh-schedules
• CLI: fabricgov collect all-refresh
• CLI: fabricgov auth sp (renomeado de auth test)

✅ v0.5.0

• DomainCollector (domínios do tenant)
• TagCollector (tags do tenant)
• CapacityCollector (capacidades Premium/Fabric)
• WorkloadCollector (workloads de capacidades Gen1)
• CLI: fabricgov collect domains/tags/capacities/workloads
• 11 collectors no total
• CLI: Orquestradores all-infrastructure, all-access, all-refresh, all
• CLI: fabricgov collect all — coleta completa em sessão única com checkpoint
• CLI: fabricgov collect status — status da sessão e checkpoints pendentes
• Progress bars visuais nos coletores de acesso e refresh

✅ v0.6.0

• Atualização de Documentação interna (pt-BR)

✅ v0.6.1

• Documentação em inglês (docs/en/)
• README em inglês

✅ v0.6.2

• Quick Start com Device Flow e tabela de permissões

✅ v0.7.0 — 2026-02-27

• Report HTML standalone gerado via fabricgov report
• Duas versões automáticas: PT (report.html) + EN (report.en.html)
• 10 gráficos Plotly interativos + KPI cards + findings de governança
• Seção dedicada de Workspaces com tabela completa de artefatos

✅ v0.8.0

• Identificar datasets sem dono
• Usuários externos com acesso a workspaces
• Workspaces sem refresh há mais de 30 dias
• CLI: fabricgov analyze — findings no terminal + findings.json

✅ v0.8.1 (Atual)

• Correção de erro no relatório HTML (conflito dict.items no Jinja2)
• Cards de artefatos colapsáveis com nome, dono, workspace e última modificação
• Tabela "Top Usuários por Artefatos Próprios"
• Layout de gráficos otimizado na seção Inventário
• Arquivo .env-example com variáveis documentadas

🎯 v0.9.0

• Integração com Azure Key Vault
• Comparação de Snapshots — fabricgov diff

🎯 v1.0.0

• Atualizar Report HTML
• MkDocs para documentação

📘 Ver changelog completo →

---

📚 Documentação

• Autenticação — Service Principal setup
• Coletores — Exemplos e casos de uso
• Relatório HTML — Seções, fontes de dados e regras de governança
• Exportadores — Integração com Power BI, Pandas
• Limitações — Rate limits, performance
• Contribuindo — Como contribuir

---

📄 Licença

MIT License - veja LICENSE

---

👤 Autor

Luciano Borba — Consultor Data Engineering

---

⭐ Se este projeto foi útil, considere dar uma estrela no GitHub!