azure-spec-audit

Files (2)

• SKILL.md
• extract.py

SKILL.md (first lines)

# Skill — Auditoria da Analytics on Microsoft Azure Specialization (Módulo B)

> **Uso:** leia este playbook na primeira chamada da sessão. Ele define COMO extrair conteúdo
> dos documentos com rastreabilidade e COMO mapear cada trecho aos controles do Módulo B.
> A fonte normativa dos controles é a KB `kb/analytics-azure-spec/` — este skill é o "como fazer".

## Princípio fundamental: grounding com localização

Toda afirmação de "evidência encontrada" precisa apontar `arquivo › localização › trecho`. Para isso
a extração precisa preservar **número de página / aba / slide / linha**. Nunca audite a partir de
memória ou suposição — sempre extraia e cite.

## Passo 0 — Inventário do input

Liste os arquivos do diretório de input do usuário e classifique por extensão. Trate como auditáveis:
`.pdf .docx .xlsx .xls .pptx .csv .txt .md` **e imagens `.png .jpg .jpeg .bmp .tiff` (via OCR — ver Passo 1b)**.
Ignore lixo de sistema (`.DS_Store`, `Thumbs.db`). Para extensões realmente não suportadas (ex: `.msg`),
registre como ⚠️ Needs Review e siga.

```bash
find "<INPUT_DIR>" -type f \( -iname '*.pdf' -o -iname '*.docx' -o -iname '*.xlsx' \
  -o -iname '*.xls' -o -iname '*.pptx' -o -iname '*.csv' -o -iname '*.txt' -o -iname '*.md' \
  -o -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.bmp' -o -iname '*.tiff' \) \
  -not -name '.DS_Store' | sort
```

## Passo 1 — Extração por formato (com localização)

> ⚠️ **Buffer-safe (crítico):** NUNCA use a tool `Read` em documento-fonte (PDF/PPTX/DOCX/XLSX/imagem)
> nem em qualquer arquivo > 512 KB — uma mensagem de tool > ~10 MB derruba o SDK
> (`max_buffer_size`). Extraia **sempre via Bash/Python**, escrevendo o resultado em `_work/` e
> imprimindo só resumos curtos no stdout (`{arquivo, chars, status}`). Trunque o texto por unidade
> (~3.000 chars) no índice. PDFs grandes: processe **página a página** (dpi 120–150), gravando
> incremental. Se algo falhar, PARE e reporte (não entre em loop). Veja R17/R18 do agente.

### Forma PADRÃO: use o extrator versionado (NÃO reescreva script de extração)

Há um extrator pronto, testado e rápido — **use-o sempre** em vez de gerar um script novo a cada run
(reinventar o script foi o que travou execuções anteriores):

```bash
pip install pdfplumber python-docx openpyxl python-pptx pymupdf pytesseract pillow --break-system-packages -q
python skills/analytics-azure-spec/azure-spec-audit/extract.py "<INPUT_DIR>" "<OUTPUT_DIR>/_work" --workers 8
#   opcional: --lang por+eng (mais fiel ao PT, ~2x mais lento) | --max-pages 60
```

O extrator faz tudo de forma robusta: **dedup por hash** (pula arquivos idênticos), **OCR em paralelo
por arquivo** (abre cada PDF uma vez), **escrita incremental** em `<OUTPUT_DIR>/_work/parts/` +
`flat_index.json` (pequeno) + `manifest.json`, **dpi adaptativo** e **buffer-safe** (nada grande no
stdout). Acompanhe o progresso pelo stdout (`OCR k/N :: arquivo`).

Depois: trabalhe sobre `<OUTPUT_DIR>/_work/flat_index.json` (costuma ser dezenas de KB — pode `Read`),
ou faça `grep`/Bash nele. Veja `manifest.json` para status por arquivo (ok/duplicado/erro).

> O detalhe por formato abaixo é **referência/fallback** caso precise extrair um arquivo isolado — a
> rota normal é o `extract.py`.

Instalação manual de deps (fallback): `pip install pdfplumber python-docx openpyxl python-pptx pymupdf rapidocr-onnxruntime pillow --break-system-packages -q`

**PDF (texto por página):**
```python
import pdfplumber
with pdfplumber.open(path) as pdf:
    for i, page in enumerate(pdf.pages, 1):
        text = page.extract_text() or ""
        # guarde (page=i, text) para rastrear "p. i"
```

**DOCX (parágrafos + headings + tabelas):**
```python
from docx import Document
doc = Document(path)
for p in doc.paragraphs:
    # p.style.name identifica Heading 1/2... → use como "seção"
    ...
for t in doc.tables:
    for row in t.rows:
        ...  # texto de células
```

**XLSX (por aba + célula):**
```python
import openpyxl
wb = openpyxl.load_workbook(path, data_only=True, read_only=True)
for ws in wb.worksheets:
    for row in ws.iter_rows():
        for cell in row:
            if cell.value is not None:
                ... # rastrear ws.title + cell.coordinate
```

**PPTX (por slide + shape):**
```python
from pptx import Presentation
prs = Presentation(path)
for i, slide in enumerate(prs.slides, 1):
    for shape in slide.shapes:
        if shape.has_text_frame:
            ... # rastrear "slide i"
```

**CSV/TXT/MD:** leitura direta; rastrear por número de linha.

> Dica de eficiência: gere um índice JSON intermediário `{arquivo: [{loc, texto}]}` e faça a busca
> por palavras-chave dos controles em cima dele — evita reprocessar e mantém a citação exata.

## Passo 1b — Imagens e PDFs escaneados (OCR é PADRÃO, não opcional)

Em auditorias reais, **a maior parte da evidência é visual**: screenshots do Azure Portal (Key Vault,
Data Lake, Databricks, Data Factory, grupos de acesso, DevOps, gráficos de custo) e PDFs exportados
como imagem. Tratar `.png .jpg .jpeg .bmp .tiff` e **PDFs sem texto extraível** com OCR é parte do
trabalho — **faça por padrão**, não pergunte se pode.

**Detecção de PDF-imagem:** se `extract_text()` somar ~0 caractere mas houver imagens embutidas,
o PDF é escaneado → rasterize e rode OCR.

**Stack resiliente (preferir pip puro — não exige `brew`):**

```bash

From ThomazRossito/ai-data-agents, MIT.

More from ThomazRossito/ai-data-agents