owasp/piihunterPostgreSQL 데이터베이스와 Jira 이슈에서 정규식, NER/ML, 선택적 자체 호스팅 LLM 탐지를 사용하여 PII를 스캔하며, 마스킹된 보고서와 감사 로깅을 제공합니다.
PostgreSQL 데이터베이스와 Jira 프로젝트에서 개인 식별 정보(PII)를 탐지하기 위한 내부 보안 도구
AI PII 스캐너는 애플리케이션 보안 및 개인정보 보호 팀이 PII를 탐지하고 목록화할 수 있도록 설계된 포괄적인 보안 중심 도구입니다. 두 가지 스캔 대상을 지원합니다:
탐지는 3계층 파이프라인을 사용합니다:
@mentions 및 회사 이메일 주소중요: 이 도구는 안전하고 통제된 환경 내에서 내부 사용 전용으로 설계되었습니다.
| 보안 제어 | 구현 |
|---|---|
| 데이터 유출 방지 | 서드파티 API 호출 없음; LLM 엔드포인트는 자체 호스팅이어야 함 |
| 최소 권한 접근 | 애플리케이션 데이터에 대한 쓰기 권한이 없는 읽기 전용 데이터베이스 역할 |
| PII 최소화 | 탐지 결과는 메타데이터와 철저히 마스킹된 샘플만 저장 |
| 감사 추적 | 모든 스캔을 누가/무엇을/언제/어떻게 세부 정보와 함께 기록 |
| 보안 로깅 | 자동 PII 필드 마스킹이 적용된 구조화된 로그 |
| 전송 암호화 | 모든 데이터베이스 연결에 SSL/TLS 필수 |
| 웹훅 검증 | 수신 Jira 이벤트에 대한 HMAC-SHA256 서명 검증 |
PostgreSQL 데이터베이스의 컬럼 전반에서 PII를 스캔하려는 경우 이 방법을 사용하세요.
# 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
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;
cp .env.example .env
# Fill in DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
스캔 결과가 저장되는 security_pii 스키마를 생성합니다. 한 번만 실행하세요:
python -m pii_scanner.cli init-schema
# 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
python -m pii_scanner.cli test-connection
Jira 이슈와 댓글에서 우발적인 PII 노출을 스캔하려면 이 방법을 사용하세요.
기본 설치(위의 1단계)가 먼저 필요합니다. Jira 스캔만 원한다면 데이터베이스 설정(2–4단계)은 필요하지 않습니다.
지난 N시간 동안의 활동을 요청 시 Jira에서 폴링합니다. 서버가 필요하지 않습니다.
1단계 — 기본 설치 (아직 하지 않았다면)
cd PIIHunter
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m spacy download en_core_web_lg
2단계 — Jira API 토큰 생성
https://id.atlassian.com → Security → API tokens로 이동합니다3단계 — 환경 구성
cp .env.example .env
.env를 편집하고 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
4단계 — 연결 테스트
자격 증명을 확인하고, 접근 가능한 프로젝트를 나열하며, 최근 이슈의 샘플을 가져옵니다:
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
이것이 실패하면 API 토큰을 확인하고 JIRA_EMAIL이 토큰이 생성된 계정과 일치하는지 확인하세요.
5단계 — 스캔 실행
# Scan last 24 hours
python -m pii_scanner.cli jira scan
# Custom lookback window
python -m pii_scanner.cli jira scan --hours 48
Jira 이벤트를 수신하고 도착하는 즉시 스캔하는 HTTP 서버를 시작합니다. 공개적으로 접근 가능한 엔드포인트가 필요합니다.
1단계 — 기본 설치 + REST API 설정 (하위 섹션 A의 1–4단계를 먼저 완료하세요)
2단계 — 웹훅 종속성 설치
pip install fastapi uvicorn
3단계 — .env에 webhook 설정 추가
# Secret used to verify requests genuinely come from Jira
JIRA_WEBHOOK_SECRET=your_webhook_secret
JIRA_WEBHOOK_PORT=8080
4단계 — 웹훅 서버 시작
python -m pii_scanner.cli jira webhook
# Custom port
python -m pii_scanner.cli jira webhook --port 9090
5단계 — Jira에 웹훅 등록
http://yourserver:8080/webhook로 설정합니다.Issue → createdComment → created.env의 JIRA_WEBHOOK_SECRET과 일치하도록 설정합니다.이제 Jira는 새로운 이슈와 댓글이 생성될 때마다 서버로 POST 요청을 보냅니다. 스캐너는 각 요청을 즉시 처리합니다.
사용 가능한 엔드포인트:
| 엔드포인트 | 용도 |
|---|---|
POST /webhook | Jira 이벤트를 수신합니다 |
GET /health | 서버가 실행 중인지 확인합니다 |
프로덕션 참고 사항: uvicorn을 인터넷에 직접 노출하지 마십시오. 고급 주제의 프로덕션 웹훅 설정 섹션을 참조하십시오.
모든 구성은 .env의 환경 변수를 통해 관리됩니다. 시작하려면 .env.example을 복사하십시오.
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database
DB_USER=pii_scanner_readonly
DB_PASSWORD=your_secure_password
DB_SSLMODE=require
# Schemas to scan (comma-separated)
SCHEMAS_TO_SCAN=public,app_data,customer_data
# Schemas to exclude (comma-separated)
SCHEMAS_TO_EXCLUDE=pg_catalog,information_schema,pg_toast
# Rows to sample per column
SAMPLE_SIZE=1000
# Batch size for streaming
BATCH_SIZE=500
# Minimum confidence threshold (0.0-1.0)
CONFIDENCE_THRESHOLD=0.5
# Enable/disable detection layers
ENABLE_REGEX_DETECTION=true
ENABLE_NER_DETECTION=true
ENABLE_LLM_DETECTION=false # Only with self-hosted LLM
자체 호스팅 엔드포인트에서만 사용하세요. 절대 공용 API를 가리키도록 설정하지 마세요.
LLM_ENDPOINT=http://your-internal-llm.company.local:8000/v1
LLM_API_KEY=your_private_key
LLM_MODEL=llama-2-7b
# Jira connection
JIRA_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your_jira_api_token # generate at id.atlassian.com
# Projects to watch — leave empty to scan ALL accessible projects
# JIRA_PROJECT_KEYS=ENG,OPS,SUPPORT
# Emails from these domains are NOT flagged as PII (your internal addresses)
COMPANY_EMAIL_DOMAINS=yourcompany.com,internal.yourcompany.com
# Webhook server settings (only needed for real-time mode)
# JIRA_WEBHOOK_SECRET=your_webhook_secret
JIRA_WEBHOOK_PORT=8080
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=json # json or console
security_pii 메타데이터 스키마를 생성합니다. 최초 설정 시 한 번 실행하세요:
python -m pii_scanner.cli init-schema
PII 가능성 순으로 정렬된 후보 컬럼을 미리 봅니다 — 데이터는 읽지 않습니다:
# Discover all columns
python -m pii_scanner.cli discover
# Specific schemas only
python -m pii_scanner.cli discover --schemas public,customer_data