@mwguerra/anonymize

CLI para anonimização determinística de dados pessoais em arquivos CSV, XLS e XLSX.

Detecta colunas sensíveis automaticamente, confirma com o usuário, e substitui valores de forma consistente — o mesmo valor original sempre gera o mesmo valor fake dentro de uma execução, inclusive entre múltiplas abas.

Instalação

npm install -g @mwguerra/anonymize

Ou execute diretamente:

npx @mwguerra/anonymize run ./clientes.xlsx

Uso

anonymize <comando> [opções]

Comandos

| Comando | Descrição | |---|---| | anonymize run <caminhos...> | Anonimizar arquivo(s) ou diretório (comando principal) | | anonymize inspect <arquivo> | Mostrar colunas detectadas sem modificar nada | | anonymize config:init | Criar .anonymizerc.json no diretório atual | | anonymize config:show | Exibir configuração resolvida |

Exemplos

# Anonimizar CSV (interativo)
anonymize run ./dados.csv

# Anonimizar XLSX com saída customizada
anonymize run ./clientes.xlsx --output ./clientes-safe.xlsx

# Modo não-interativo (CI/CD)
anonymize run ./export.xlsx --yes --output ./export-safe.xlsx

# Dry run — ver plano sem modificar
anonymize run ./clientes.csv --dry-run

# Config customizada com locale inglês
anonymize run ./customers.csv --config ./my-rules.json --locale en_US

# Anonimizar múltiplos arquivos com consistência cruzada (requer --output com diretório)
anonymize run ./clientes.csv ./pedidos.xlsx --output ./safe/ --yes

# Dry run em múltiplos arquivos
anonymize run ./a.csv ./b.xlsx --output ./safe/ --dry-run

# Anonimizar diretório inteiro (requer --output)
anonymize run ./dados/ --output ./dados-safe/ --yes

# Dry run em diretório — ver plano sem modificar
anonymize run ./dados/ --output ./dados-safe/ --dry-run

# Anonimizar com agrupamento por identidade (CPF)
anonymize run ./clientes.csv --identity-column cpf --yes

# Múltiplos arquivos com identidade + consistência cruzada
anonymize run ./clientes.csv ./pedidos.xlsx --output ./safe/ --identity-column cpf --yes

# Inspecionar colunas detectadas
anonymize inspect ./clientes.csv

# Criar arquivo de configuração
anonymize config:init

# Ver configuração resolvida
anonymize config:show
anonymize config:show --config ./my-rules.json

Flags (run)

| Flag | Alias | Descrição | Default | |---|---|---|---| | --output | -o | Caminho do arquivo de saída | <input>.anonymized.<ext> | | --config | -c | Caminho do arquivo de configuração | Auto-detect | | --yes | -y | Pular confirmação interativa | false | | --dry-run | -d | Mostrar plano sem modificar | false | | --encoding | -e | Forçar encoding do CSV | Auto-detect | | --delimiter | | Forçar delimitador do CSV | Auto-detect | | --locale | -l | Override do locale do faker | pt_BR | | --identity-column | | Agrupar anonimização por coluna identidade (referencia um rule ID) | undefined | | --no-overwrite | | Falhar se arquivo de saída já existe | false | | --verbose | -v | Logs detalhados | false | | --silent | -s | Suprimir toda saída exceto erros | false |

Configuração

A ferramenta busca configuração nesta ordem:

1. Flag --config <caminho>
2. .anonymizerc.json no diretório do arquivo de entrada
3. .anonymizerc.json no diretório home do usuário
4. Configuração padrão embutida

Formato

{
  "locale": "pt_BR",
  "rules": [
    {
      "id": "name",
      "columns": ["nome", "name", "nome_completo", "full_name"],
      "generator": "faker.person.fullName()",
      "identityColumn": "cpf"
    },
    {
      "id": "cpf",
      "columns": ["cpf", "cpf_cnpj", "documento"],
      "generator": "faker.helpers.replaceSymbols('###.###.###-##')"
    }
  ],
  "columnOverrides": {
    "name": [
      { "file1.csv:Sheet1": "nome" },
      { "file2.xlsx:Clientes": "Nome do Cliente" }
    ],
    "email": "correo_electronico"
  }
}

Regras Padrão

| Regra | Colunas Detectadas | Gerador | |---|---|---| | name | nome, name, nome_completo, full_name, ... | faker.person.fullName() | | cpf | cpf, cpf_cnpj, documento, ... | faker.helpers.replaceSymbols('###.###.###-##') | | cnpj | cnpj, cnpj_empresa | faker.helpers.replaceSymbols('##.###.###/####-##') | | email | email, e-mail, email_address, ... | faker.internet.email() | | address | endereco, endereço, address, logradouro, ... | faker.location.streetAddress(...) | | zipcode | cep, zip, zipcode, ... | faker.location.zipCode('#####-###') | | phone | telefone, phone, celular, whatsapp, ... | faker.phone.number() |

Regras Customizadas

O campo generator aceita qualquer expressão válida do @faker-js/faker:

{
  "id": "birthdate",
  "columns": ["data_nascimento", "birthdate"],
  "generator": "faker.date.birthdate({ min: 18, max: 80, mode: 'age' }).toISOString().split('T')[0]"
}

Coluna de Identidade (identityColumn)

Por padrão, todos os registros com o mesmo nome (ex: "Marcelo") recebem o mesmo nome fake. Com identityColumn, a anonimização é agrupada pela identidade real da pessoa:

{
  "id": "name",
  "columns": ["nome"],
  "generator": "faker.person.fullName()",
  "identityColumn": "cpf"
}

Se houver 8 registros "Marcelo" mas 5 CPFs distintos, serão gerados 5 nomes fake diferentes. Registros com mesmo CPF + mesmo nome → mesmo nome fake.

Também disponível via CLI: --identity-column cpf (sobrescreve todas as regras).

Mapeamento de Colunas (columnOverrides)

Quando arquivos diferentes usam nomes de colunas diferentes para os mesmos dados:

{
  "columnOverrides": {
    "name": [
      { "arquivo1.csv:Sheet1": "nome" },
      { "arquivo2.xlsx:Clientes": "Nome do Cliente" }
    ],
    "email": "correo_electronico"
  }
}

• String: aplica para todos os arquivos (ex: "email": "correo_electronico")
• Array de objetos: mapeia por arquivo:aba (ex: [{ "file.csv:Sheet1": "nome" }])
• Omitido: usa o padrão (detecção por nome da coluna)

Prioridade: columnOverrides > detecção por padrão.

Como Funciona

Arquivo único

1. Lê o arquivo de entrada (CSV, XLS ou XLSX)
2. Detecta colunas sensíveis comparando nomes com as regras (case-insensitive, match parcial)
3. Exibe tabela de detecção para confirmação (pular com --yes)
4. Percorre cada célula marcada, substituindo por valores fake via @faker-js/faker
5. Mantém cache global: o mesmo valor original → mesmo valor fake (inclusive entre abas)
6. Gera arquivo de saída preservando estrutura e formatação

Múltiplos arquivos

1. Lê todos os arquivos de entrada e detecta colunas sensíveis em cada um
2. Exibe tabela unificada de detecção para confirmação (pular com --yes)
3. Cria um cache único compartilhado entre todos os arquivos
4. Processa cada arquivo sequencialmente usando o cache compartilhado
5. O mesmo valor original → mesmo valor fake em todos os arquivos (ex: "José" em a.csv e b.xlsx → mesmo nome fake)
6. --output (diretório) é obrigatório. Não é permitido misturar arquivos e diretórios.

Diretório

1. Percorre recursivamente o diretório de entrada
2. Replica a estrutura de pastas no diretório de saída
3. Arquivos suportados (.csv, .xls, .xlsx) são anonimizados individualmente
4. Arquivos não suportados (ex: .md, .txt, .pdf) são copiados sem alteração
5. Confirmação interativa é desabilitada no modo diretório (equivalente a --yes)

Segurança

• O arquivo original nunca é modificado
• O cache de mapeamento existe apenas em memória (não é persistido)
• O campo generator executa código via new Function() com escopo limitado (apenas faker disponível) — cuidado ao usar configs de terceiros
• Valores originais não são logados (apenas contadores e nomes de colunas)

Requisitos

• Node.js >= 18

Licença

MIT