Escáner de PII con IA

Una herramienta de seguridad interna para descubrir Información de Identificación Personal (PII) en bases de datos PostgreSQL y proyectos de Jira

Descripción general

El Escáner de PII con IA es una herramienta integral enfocada en seguridad, diseñada para equipos de Seguridad de Aplicaciones y Privacidad con el fin de descubrir y catalogar PII. Admite dos objetivos de escaneo:

• Bases de datos PostgreSQL — descubrimiento de PII a nivel de columna en los esquemas de su aplicación
• Jira — escaneo en tiempo real o programado de incidencias y comentarios para detectar exposición accidental de PII

La detección utiliza una canalización de tres capas:

• Detección basada en regex — Patrones deterministas para correo electrónico, teléfono, SSN, tarjetas de crédito, etc.
• Detección NER/ML — Microsoft Presidio o spaCy para reconocimiento de entidades (nombres, ubicaciones, fechas)
• Clasificación LLM opcional — Modelos autoalojados para el análisis de texto libre ambiguo

Características clave

• Detección de PII multicapa — Combina regex, ML y LLM opcional para una cobertura integral
• Integración con Jira — Escanea nuevas incidencias y comentarios mediante sondeo o webhooks en tiempo real
• Filtros de excepciones inteligentes — Suprime contenido esperado: @mentions y direcciones de correo corporativas
• Informes con marca de tiempo — Los resultados del escaneo de Jira se guardan automáticamente en un archivo JSON o CSV con fecha en cada ejecución
• Diseño centrado en la seguridad — Acceso de solo lectura a la base de datos, sin llamadas a API externas, retención mínima de PII
• Muestreo inteligente — Analiza muestras de datos representativas para minimizar el impacto en el rendimiento
• Registro de auditoría integral — Cada escaneo se registra con configuración, marcas de tiempo y versiones de modelos
• Registro seguro para la privacidad — Redacción automática de PII en todos los registros y muestras almacenadas

Seguridad y privacidad

CRÍTICO: Esta herramienta está diseñada para uso interno únicamente dentro de un entorno seguro y controlado.

Control de seguridad	Implementación
Prevención de exfiltración de datos	Sin llamadas a API de terceros; los endpoints de LLM deben ser autoalojados
Acceso con privilegios mínimos	Rol de base de datos de solo lectura sin acceso de escritura a los datos de la aplicación
Minimización de PII	Los hallazgos almacenan solo metadatos y muestras fuertemente redactadas
Registro de auditoría	Todos los escaneos se registran con detalles de quién/qué/cuándo/cómo
Registro seguro	Registros estructurados con redacción automática de campos de PII
Tránsito cifrado	SSL/TLS requerido para todas las conexiones a la base de datos
Verificación de webhooks	Validación de firma HMAC-SHA256 para eventos entrantes de Jira

Tabla de contenidos

• Instalación — Escaneo de esquema de base de datos
• Instalación — Escaneo de Jira
• Configuración
• Uso — Escaneo de base de datos
• Uso — Integración con Jira
• Arquitectura
• Métodos de detección
• Esquema de base de datos
• Ejemplos
• Solución de problemas
• Temas avanzados
• Contribuir

---

Instalación — Escaneo de esquema de base de datos

Use esto si desea escanear una base de datos PostgreSQL en busca de PII en las columnas.

Paso 1 — Instalación 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

Paso 2 — Crear un rol de base de datos de solo lectura

Ejecuta esto como un superusuario de 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;

Paso 3 — Configurar el entorno

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

Paso 4 — Inicializar el esquema de metadatos

Crea el esquema security_pii donde se almacenan los resultados del escaneo. Ejecutar una vez:

python -m pii_scanner.cli init-schema

Paso 5 — Ejecuta tu primer escaneo

# 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 la conectividad en cualquier momento

python -m pii_scanner.cli test-connection

---

Instalación — Escaneo de Jira

Use esto si desea escanear incidencias y comentarios de Jira en busca de exposición accidental de PII.

La instalación base (Paso 1 anterior) es necesaria primero. La configuración de la base de datos (Pasos 2–4) no es necesaria si solo desea el escaneo de Jira.

Subsección A — API REST (Polling)

Consulta Jira bajo demanda para obtener actividad de las últimas N horas. No se necesita servidor.

Paso 1 — Instalación base (si aún no se ha realizado)

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

Paso 2 — Generar un token de API de Jira

1. Ve a https://id.atlassian.com → Security → API tokens
2. Haz clic en Create API token, asígnale un nombre y copia el token

Paso 3 — Configurar el entorno

cp .env.example .env

Edita .env y completa tus datos de 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

Paso 4 — Probar la conexión

Verifica tus credenciales, lista los proyectos accesibles y obtiene una muestra de incidencias recientes:

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

Si esto falla, verifica tu token de API y que JIRA_EMAIL coincida con la cuenta para la que se generó el token.

Paso 5 — Ejecutar un escaneo

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

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

---

Subsección B — Webhook (Tiempo real)

Inicia un servidor HTTP que recibe eventos de Jira y los escanea al instante a medida que llegan. Requiere un endpoint accesible públicamente.

Paso 1 — Instalación base + configuración de la API REST (complete primero los pasos 1–4 de la Subsección A)

Paso 2 — Instalar las dependencias del webhook

pip install fastapi uvicorn

Paso 3 — Añadir la configuración del webhook a .env