fabricgov 1.1.1

Biblioteca Python para extração 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 | 📚 Documentação completa: luhborba.github.io/fabricgov

---

🎯 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 por artefato via Scanner API — artifact_users no resultado do inventory
• 🗄️ Datasources e modelos semânticos (tabelas, colunas, medidas, DAX) extraídos automaticamente
• 🔄 Histórico de refresh e agendamentos configurados
• 🏢 Domínios, tags, capacidades e workloads do tenant
• 📋 Log de atividades do tenant — até 28 dias de histórico
• 💾 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)
• 🔁 Comparação de snapshots via fabricgov diff — diff.json com todas as dimensões
• 🔑 Integração com Azure Key Vault — credenciais sem texto plano em disco
• ⚡ CLI pronto para uso
• 🛡️ Rate limit handling automático

---

📦 Instalação

# Instalação padrão
pip install fabricgov

# Com suporte a Azure Key Vault
pip install fabricgov[keyvault]

# 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)

Azure Key Vault (produção / sem credenciais em disco)

pip install fabricgov[keyvault]
fabricgov auth keyvault --vault-url https://meu-vault.vault.azure.net/

📘 Guia completo de autenticação → | Key Vault →

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 (inclui artifact_users, datasources e semantic_models)
fabricgov collect inventory

# Coleta acessos de workspaces (com checkpoint automático)
fabricgov collect workspace-access
fabricgov collect all-access   # atalho para workspace-access

# 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 log de atividades
fabricgov collect activity               # últimos 7 dias
fabricgov collect activity --days 28     # máximo histórico (28 dias)

# Coleta completa em sessão única
fabricgov collect all
fabricgov collect all --days 28  # inclui atividades na coleta completa (28 dias)
fabricgov collect status         # status da sessão

# Comparação de snapshots
fabricgov diff                                                  # 2 runs mais recentes
fabricgov diff --from output/20260301_120000 --to output/20260309_143000

ℹ️ Os comandos report-access, dataset-access e dataflow-access foram removidos na v1.1.0. Os dados de acesso por artefato agora estão disponíveis diretamente em artifact_users após fabricgov collect inventory.

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

A classe FabricGov oferece uma API de alto nível — sem CLI, sem configuração manual de auth/exporters:

from fabricgov import FabricGov

# Autentica via .env (TENANT_ID, CLIENT_ID, CLIENT_SECRET)
fg = FabricGov.from_env()

# Coleta completa em uma pasta de sessão (equivalente ao 'collect all')
run_dir = fg.collect.all(days=28)

# Gera relatório HTML
fg.report(output_path=run_dir / "report.html", lang="pt")

# Compara os dois runs mais recentes
result = fg.diff()

# Findings de governança (sem chamadas de API)
findings = fg.analyze(source_dir=run_dir)
for f in findings:
    print(f["severity"], f["count"], f["message"])

📘 Ver documentação completa da Python API →

---

📊 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)	—
ActivityCollector	Log de atividades do tenant (até 28 dias)	—

📘 Ver exemplos detalhados → | Log de atividades →

---

💾 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/         # 12 collectors (access, refresh, infraestrutura, atividades)
├── exporters/          # JSON/CSV export
├── reporters/          # Report HTML (InsightsEngine + HtmlReporter + template)
├── diff/               # Comparação de snapshots (DiffEngine + comparators)
├── 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
    ├── activity_events.csv # Log de atividades do tenant
    ├── report.html         # Relatório de governança (PT)
    ├── report.en.html      # Governance report (EN)
    ├── findings.json       # Findings de governança (fabricgov analyze)
    └── diff.json           # Comparativo com snapshot anterior (fabricgov diff)

---

⚠️ 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

• 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 (Atual) — em desenvolvimento)

• Integração com Azure Key Vault (fabricgov auth keyvault)
• ActivityCollector — log de atividades do tenant (até 28 dias)
• CLI: fabricgov collect activity --days N
• fabricgov collect all --days N — inclui atividades na coleta completa
• fabricgov diff — comparação de dois snapshots de output (workspaces, artefatos, acesso, refresh, findings)

✅ v1.0.0

• FabricGov Python API — facade de alto nível para uso programático sem CLI
• Relatório HTML: seções Atividade e Tendências (Activity/Trends com dados do activity_events.csv e diff.json)
• MkDocs — documentação oficial PT + EN com Material theme, Guia CLI, Guia Python, Exemplos

✅ v1.0.1 — 2026-03-28

• fix(checkpoint): guard against None checkpoint on rate limit — evita crash quando checkpoint está ausente ao atingir 429
• fix(checkpoint): corrige lógica do inner_resume para retomar corretamente sub-coletores internos

✅ v1.0.2 — 2026-04-06

• feat(collect): exibe estimativa de ciclos restantes no resumo da sessão (collect all)
• fix(collect): remove checkpoint obsoleto ao pular sub-coletor já concluído — evita retomadas desnecessárias

✅ v1.0.3 — 2026-04-06

• chore: CHANGELOG, README (PT + EN) e pyproject.toml adicionados ao repositório

✅ v1.0.4 — 2026-04-06

• chore: remove referências à empresa de todos os arquivos (relatório HTML, docs PT + EN)

✅ v1.1.0 — 2026-04-15

• feat(inventory): collect() agora retorna artifact_users, datasources e semantic_models extraídos diretamente da Scanner API
• feat(inventory): constante ARTIFACT_TYPES_WITH_USERS com 22 tipos de artefatos suportados
• refactor(inventory): _list_all_workspaces() filtra por type == "Workspace", excluindo PersonalGroup
• deprecate: ReportAccessCollector, DatasetAccessCollector e DataflowAccessCollector marcados como deprecated
• breaking(cli): comandos report-access, dataset-access e dataflow-access removidos do CLI

✅ v1.1.1 — 2026-04-15

• fix(inventory): query params no scan (datasourceDetails, getArtifactUsers, etc.) — a API ignorava quando enviados no body JSON, causando datasources.csv e artifact_users.csv nunca gerados
• fix(inventory): _extract_datasources resolve datasourceInstanceId GUID via join com datasourceInstances do nível raiz do scan
• feat(report): nova seção Datasources no relatório HTML com KPIs, gráfico de tipos e tabela de conexões
• feat(report): seção de Acesso ampliada com tabela top_artifact_users e gráfico artifact_users_by_type

📘 Ver changelog completo →

---

📚 Documentação

• Documentação completa — MkDocs PT + EN
• Python API — Uso programático com a classe FabricGov
• Autenticação — Service Principal, Device Flow, Key Vault
• Key Vault — Credenciais sem texto plano em disco
• Coletores — Exemplos e casos de uso
• Atividades — Log de atividades do tenant
• Diff de Snapshots — Comparação entre dois runs de coleta
• 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!