Scanner de PII com IA

Uma ferramenta de segurança interna para descobrir Informações de Identificação Pessoal (PII) em bancos de dados PostgreSQL e projetos Jira

Visão Geral

O Scanner de PII com IA é uma ferramenta abrangente, focada em segurança, projetada para equipes de Segurança de Aplicações e Privacidade descobrirem e catalogarem PII. Ele suporta dois alvos de varredura:

• Bancos de dados PostgreSQL — descoberta de PII em nível de coluna nos esquemas da sua aplicação
• Jira — varredura em tempo real ou agendada de issues e comentários para exposição acidental de PII

A detecção usa um pipeline de três camadas:

• Detecção baseada em Regex — Padrões determinísticos para email, telefone, SSN, cartões de crédito, etc.
• Detecção NER/ML — Microsoft Presidio ou spaCy para reconhecimento de entidades (nomes, localizações, datas)
• Classificação LLM opcional — Modelos auto-hospedados para análise de texto livre ambíguo

Principais Recursos

• Detecção de PII em Múltiplas Camadas — Combina regex, ML e LLM opcional para cobertura abrangente
• Integração com Jira — Varre novas issues e comentários via polling ou webhooks em tempo real
• Filtros de Exceção Inteligentes — Suprime conteúdo esperado: @mentions e endereços de email da empresa
• Relatórios com Timestamp — Resultados de varredura do Jira salvos automaticamente em um arquivo JSON ou CSV datado a cada execução
• Design Focado em Segurança — Acesso somente leitura ao banco de dados, sem chamadas a APIs externas, retenção mínima de PII
• Amostragem Inteligente — Analisa amostras representativas de dados para minimizar o impacto no desempenho
• Trilha de Auditoria Abrangente — Cada varredura registrada com configuração, timestamps e versões de modelo
• Logging Seguro para Privacidade — Redação automática de PII em todos os logs e amostras armazenadas

Segurança e Privacidade

CRÍTICO: Esta ferramenta é projetada para uso interno apenas dentro de um ambiente seguro e controlado.

Controle de Segurança	Implementação
Prevenção de Exfiltração de Dados	Sem chamadas a APIs de terceiros; endpoints LLM devem ser auto-hospedados
Acesso com Privilégio Mínimo	Função de banco de dados somente leitura sem acesso de escrita aos dados da aplicação
Minimização de PII	Descobertas armazenam apenas metadados e amostras fortemente redigidas
Trilha de Auditoria	Todas as varreduras registradas com detalhes de quem/o quê/quando/como
Logging Seguro	Logs estruturados com redação automática de campos de PII
Trânsito Criptografado	SSL/TLS obrigatório para todas as conexões de banco de dados
Verificação de Webhook	Validação de assinatura HMAC-SHA256 para eventos Jira recebidos

Índice

• Instalação — Varredura de Esquema de Banco de Dados
• Instalação — Varredura do Jira
• Configuração
• Uso — Varredura de Banco de Dados
• Uso — Integração com Jira
• Arquitetura
• Métodos de Detecção
• Esquema do Banco de Dados
• Exemplos
• Solução de Problemas
• Tópicos Avançados
• Contribuindo

---

Instalação — Varredura de Esquema de Banco de Dados

Use isto se você quiser escanear um banco de dados PostgreSQL em busca de PII nas colunas.

Passo 1 — Instalação base

# Clone the repository
cd PIIHunter

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download spaCy NER model (~800MB)
python -m spacy download en_core_web_lg

Passo 2 — Criar uma função de banco de dados somente leitura

Execute isto como um superusuário do PostgreSQL:

CREATE ROLE pii_scanner_readonly WITH LOGIN PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE your_database TO pii_scanner_readonly;
GRANT USAGE ON SCHEMA public, app_data TO pii_scanner_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public, app_data TO pii_scanner_readonly;

Passo 3 — Configurar o ambiente

cp .env.example .env
# Fill in DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

Passo 4 — Inicializar o esquema de metadados

Cria o esquema security_pii onde os resultados da varredura são armazenados. Execute uma vez:

python -m pii_scanner.cli init-schema

Etapa 5 — Execute sua primeira varredura

# Preview candidate columns (no data read)
python -m pii_scanner.cli discover

# Run PII detection
python -m pii_scanner.cli scan --sample-size 1000

# View results
python -m pii_scanner.cli report

Verificar a conectividade a qualquer momento

python -m pii_scanner.cli test-connection

---

Instalação — Jira Scan

Use isto se você quiser escanear issues e comentários do Jira em busca de exposição acidental de PII.

A instalação base (Etapa 1 acima) é necessária primeiro. A configuração do banco de dados (Etapas 2–4) não é necessária se você quiser apenas o escaneamento do Jira.

Subseção A — REST API (Polling)

Consulta o Jira sob demanda para atividade nas últimas N horas. Nenhum servidor é necessário.

Etapa 1 — Instalação base (se ainda não foi feita)

cd PIIHunter
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m spacy download en_core_web_lg

Passo 2 — Gerar um token de API do Jira

1. Acesse https://id.atlassian.com → Security → API tokens
2. Clique em Create API token, dê um nome a ele, copie o token

Passo 3 — Configurar o ambiente

cp .env.example .env

Edite o .env e preencha os seus detalhes do Jira:

JIRA_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token_here

# Optional — leave empty to scan all projects
# JIRA_PROJECT_KEYS=ENG,OPS,SUPPORT

# Emails from these domains will NOT be flagged as PII
COMPANY_EMAIL_DOMAINS=yourcompany.com

Passo 4 — Testar a conexão

Verifica suas credenciais, lista os projetos acessíveis e busca uma amostra de issues recentes:

python -m pii_scanner.cli jira test

Expected output:

Testing connection to https://yourcompany.atlassian.net...

  Auth          ✓  logged in as Jane Smith ([email protected])
  Projects      ✓  3 accessible: ENG, OPS, SUPPORT
  Project ENG   ✓  accessible

  Recent issues (no time filter):
    ENG-101  Fix login timeout on mobile
    ENG-100  Update password policy

Se isso falhar, verifique o seu token de API e se JIRA_EMAIL corresponde à conta para a qual o token foi gerado.

Passo 5 — Executar uma verificação

# Scan last 24 hours
python -m pii_scanner.cli jira scan

# Custom lookback window
python -m pii_scanner.cli jira scan --hours 48

Subseção B — Webhook (Tempo Real)

Inicia um servidor HTTP que recebe eventos do Jira e os verifica instantaneamente à medida que chegam. Requer um endpoint publicamente acessível.

Passo 1 — Instalação base + configuração da API REST (complete primeiro os passos 1–4 da Subseção A)

Passo 2 — Instalar dependências do webhook

pip install fastapi uvicorn

Passo 3 — Adicionar configuração de webhook ao .env

# Secret used to verify requests genuinely come from Jira
JIRA_WEBHOOK_SECRET=your_webhook_secret
JIRA_WEBHOOK_PORT=8080

Passo 4 — Iniciar o servidor de webhook

python -m pii_scanner.cli jira webhook

# Custom port
python -m pii_scanner.cli jira webhook --port 9090