diff --git a/.github/skills/project-planning/privacy-pii-detector/SKILL.md b/.github/skills/project-planning/privacy-pii-detector/SKILL.md new file mode 100644 index 000000000..5ef613f3b --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/SKILL.md @@ -0,0 +1,155 @@ +--- +name: privacy-pii-detector +description: "Automated PII/PI detection and privacy control verification for codebases. Scans for personal information processing patterns, classifies by sensitivity tier and industry, verifies protective controls exist, and raises findings when controls are missing. Use when you need to detect PII in code without privacy expertise." +license: mixed +user-invocable: true +metadata: + authors: "Microsoft (detection taxonomy and control framework); NIST (PII definition from SP 800-122); GDPR (personal data definition from Art. 4); OAIC (Australian PI definition from Privacy Act 1988)" + spec_version: "1.0" + framework_revision: "1.0.0" + last_updated: "2026-08-10" + content_based_on: "https://doi.org/10.6028/NIST.SP.800-122; https://gdpr-info.eu/art-4-gdpr/; https://www.oaic.gov.au/privacy/your-privacy-rights/what-is-personal-information" +--- + +# Privacy PII Detector — Skill Entry + +This `SKILL.md` is the **entrypoint** for the Privacy PII Detector skill. + +The skill provides automated detection of Personal Information (PI) and Personally Identifiable Information (PII) in codebases, classifies detected data by sensitivity tier and industry context, verifies that appropriate privacy controls exist for each detected PII type, and produces structured findings when controls are missing. It requires zero privacy expertise from the user. + +> [!NOTE] +> This skill is a planning and detection aid, not legal advice. Its detection patterns identify likely PII processing; they do not constitute a formal data inventory or replace qualified privacy counsel. + +## Goal + +Automatically detect PII/PI processing in a codebase, verify protective controls exist for each detected type, and produce actionable findings with backlog-ready items for any unprotected personal data. + +## Success criteria + +- All code paths processing personal data are identified with the PII type classified. +- Each detected PII type is mapped to a sensitivity tier and applicable industry overlay. +- For each detected PII type, expected controls are checked against actual implementation. +- Missing controls produce FAIL findings with specific remediation and backlog items. +- The user does not need privacy expertise — the skill drives the entire assessment. + +## When to use this skill + +Use when you need to: + +- Scan a codebase for PII/PI processing without knowing what to look for +- Verify that detected personal data has appropriate privacy controls +- Generate a privacy control gap analysis for a project +- Produce backlog items for missing privacy protections +- Assess a PR or feature branch for new PII introduction +- Apply industry-specific PII detection (telco, healthcare, financial services) + +Do not use for: + +- Principle-level privacy assessment (use `privacy-by-design`) +- Standards mapping and DPIA thresholds (use `privacy-standards`) +- Security vulnerability detection (use OWASP skills) +- RAI assessment (use `rai-planner`) + +## Stop rules + +- Stop if the codebase contains no identifiable data processing (no models, APIs, databases, or data flows). +- Do not fabricate PII detections; only report what is evidenced by code patterns. +- Do not provide legal classification of data; frame findings as planning guidance. +- When detection confidence is LOW, report as NEEDS_REVIEW rather than FAIL. + +## Normative references + +1. [00 PII Taxonomy](references/00-pii-taxonomy.md) — core classification of PII types, sensitivity tiers, and regulatory anchors +2. [01 Detection Patterns](references/01-detection-patterns.md) — code-level patterns agents use to find PII processing +3. [02 Control Expectations](references/02-control-expectations.md) — required controls per PII tier with verification methods +4. [03 Finding Schema](references/03-finding-schema.md) — structured output format for detection results and backlog handoff +5. [04 Custom Classification](references/04-custom-classification.md) — project-level `.pii-config.yml` for custom types, tier overrides, suppressions, and catalog import + +## Industry overlays + +5. [10 Telco Overlay](references/10-industry-telco.md) — telecommunications-specific PII types and controls +6. [11 Healthcare Overlay](references/11-industry-healthcare.md) — health data PII types and controls +7. [12 Financial Services Overlay](references/12-industry-financial.md) — financial data PII types and controls + +## Skill layout + +- `SKILL.md` — this file (skill entrypoint). +- `references/` — detection taxonomy, patterns, control expectations, and industry overlays. + - `00-pii-taxonomy.md` — PII type catalog with sensitivity tiers and regulatory anchors. + - `01-detection-patterns.md` — language-agnostic and language-specific code patterns for PII detection. + - `02-control-expectations.md` — required controls per tier with verification methods. + - `03-finding-schema.md` — YAML-based structured output for findings and backlog items. + - `04-custom-classification.md` — `.pii-config.yml` schema for project-level customization. + - `10-industry-telco.md` — telecommunications industry overlay. + - `11-industry-healthcare.md` — healthcare industry overlay. + - `12-industry-financial.md` — financial services industry overlay. + +## Assessment protocol + +### Phase 1: Industry context + +1. Look for `.pii-config.yml` at the repository root. If present, load custom types, tier overrides, suppressions, and retention overrides. +2. Determine which industry overlay applies. If the config specifies `industry:`, load that overlay. If not specified, infer from: +- Package dependencies (e.g., `hl7`, `fhir` → healthcare; `stripe`, `plaid` → financial) +- Domain terminology in code comments and documentation +- API endpoint naming patterns + +If no industry context is determinable, use only the core PII taxonomy. + +### Phase 2: Detection scan + +For each file in scope: +1. Apply detection patterns from `01-detection-patterns.md`. +2. Apply industry-specific patterns from the applicable overlay. +3. Record each detection with location, PII type, confidence level, and evidence. + +### Phase 3: Control verification + +For each detected PII type: +1. Look up required controls from `02-control-expectations.md` based on sensitivity tier. +2. Search the codebase for evidence that each required control is implemented. +3. Record control status: PRESENT, ABSENT, or PARTIAL. + +### Phase 4: Finding generation + +For each ABSENT or PARTIAL control: +1. Generate a finding using the schema from `03-finding-schema.md`. +2. Include specific remediation guidance. +3. Map to a backlog item with priority based on sensitivity tier. + +## Integration with other skills + +| Skill | Relationship | +|-------|--------------| +| `privacy-by-design` | PII detector feeds into PbD assessment; detected PII informs principle evaluation | +| `privacy-standards` | Standards skill provides regulatory context for detected PII types | +| `security-planning` | Security controls overlap with PII protection; cross-reference rather than duplicate | +| `code-review` | PII detector can run as a perspective within code review workflow | + +## Extensibility + +Industry overlays follow a consistent structure. To add a new industry: +1. Create `references/1N-industry-.md` following the overlay template. +2. Define industry-specific PII types with detection patterns. +3. Map to sensitivity tiers and specify additional controls beyond core requirements. +4. Add the overlay to the Industry overlays section in this file. + +## Attribution and licensing posture + +### NIST SP 800-122 + +- **Source**: +- **License**: Public domain (US Government work) +- **Usage**: PII definition and classification framework referenced with attribution + +### GDPR Art. 4 (Personal Data Definition) + +- **Source**: +- **License**: Open legal text, paraphrased with attribution +- **Usage**: Personal data categories referenced for regulatory anchoring + +### Australian Privacy Act 1988 + +- **Source**: +- **License**: Open legal text, paraphrased with attribution +- **Usage**: PI definition referenced for cross-jurisdictional anchoring diff --git a/.github/skills/project-planning/privacy-pii-detector/references/00-pii-taxonomy.md b/.github/skills/project-planning/privacy-pii-detector/references/00-pii-taxonomy.md new file mode 100644 index 000000000..7d59f48ee --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/00-pii-taxonomy.md @@ -0,0 +1,97 @@ +--- +title: PII Taxonomy +description: Core classification of PII/PI types by sensitivity tier with regulatory anchors and detection identifiers +--- + +# PII Taxonomy + +This reference defines the core Personal Information (PI) and Personally Identifiable Information (PII) types that the detector scans for, organized by sensitivity tier. + +## Sensitivity tiers + +| Tier | Label | Risk level | Example | Regulatory trigger | +|------|-------|------------|---------|-------------------| +| T1 | Identifier | Medium | Email, phone, name | Standard GDPR/CCPA obligations | +| T2 | Sensitive | High | Financial, health, biometric | Enhanced protections; DPIA likely | +| T3 | Special Category | Critical | Racial origin, genetic, criminal | Explicit consent required; maximum restrictions | + +## Core PII catalog (all industries) + +### Tier 1: Identifiers + +| ID | PII Type | Description | Regulatory anchor | +|----|----------|-------------|-------------------| +| PII-001 | Full name | Given name, surname, or combined | GDPR Art. 4(1), CCPA §1798.140(v) | +| PII-002 | Email address | Personal or work email | GDPR Art. 4(1), APP 6 | +| PII-003 | Phone number | Mobile, landline, or VoIP | GDPR Art. 4(1) | +| PII-004 | Postal address | Street address, city, postcode | GDPR Art. 4(1) | +| PII-005 | Date of birth | Full DOB or partial (year, month-year) | GDPR Art. 4(1) | +| PII-006 | IP address | IPv4 or IPv6, static or dynamic | GDPR Recital 30, CCPA §1798.140(v) | +| PII-007 | Device identifier | Cookie ID, advertising ID, browser fingerprint | GDPR Recital 30, ePrivacy | +| PII-008 | Username | Login identifier or display name if linked to identity | Contextual | +| PII-009 | Photo/avatar | Facial image or profile photo | GDPR Art. 4(14) when biometric | +| PII-010 | Location data | GPS coordinates, geofence events | GDPR Art. 4(1), ePrivacy Art. 9 | + +### Tier 2: Sensitive + +| ID | PII Type | Description | Regulatory anchor | +|----|----------|-------------|-------------------| +| PII-020 | National ID | SSN, TFN, Aadhaar, passport number | NIST SP 800-122, APP 9 | +| PII-021 | Driver license | License number or document | Jurisdiction-specific | +| PII-022 | Financial account | Bank account, IBAN, BSB | PCI DSS, CCPA | +| PII-023 | Payment card | PAN, CVV, expiry | PCI DSS | +| PII-024 | Income/salary | Compensation data | Employment privacy laws | +| PII-025 | Health condition | Diagnosis, symptoms, treatment | HIPAA, GDPR Art. 9 | +| PII-026 | Medication | Prescriptions, drug names | HIPAA | +| PII-027 | Insurance ID | Policy number, member ID | HIPAA, jurisdiction-specific | +| PII-028 | Biometric data | Fingerprint, iris, voiceprint | GDPR Art. 9, BIPA | +| PII-029 | Authentication credential | Password hash, MFA secret, security question | NIST SP 800-63 | + +### Tier 3: Special Category + +| ID | PII Type | Description | Regulatory anchor | +|----|----------|-------------|-------------------| +| PII-040 | Racial/ethnic origin | Self-identified or inferred | GDPR Art. 9(1) | +| PII-041 | Political opinion | Party affiliation, voting record | GDPR Art. 9(1) | +| PII-042 | Religious belief | Faith, congregation membership | GDPR Art. 9(1) | +| PII-043 | Trade union membership | Union affiliation | GDPR Art. 9(1) | +| PII-044 | Genetic data | DNA sequence, genetic markers | GDPR Art. 9(1), GINA | +| PII-045 | Sexual orientation | Orientation or gender identity | GDPR Art. 9(1) | +| PII-046 | Criminal record | Convictions, charges, proceedings | GDPR Art. 10 | +| PII-047 | Child data | Data of individuals under 13/16 | COPPA, GDPR Art. 8 | + +## Derived and inferred PII + +These are not directly collected but inferred from other data: + +| ID | PII Type | Derived from | Regulatory note | +|----|----------|--------------|-----------------| +| PII-060 | Behavioral profile | Clickstream, purchase history | GDPR Art. 4(4) profiling | +| PII-061 | Location history | Repeated GPS/IP geolocation | Movement patterns = sensitive | +| PII-062 | Social graph | Contact lists, interaction patterns | Contextual sensitivity | +| PII-063 | Inferred health | Fitness data, purchase patterns | May trigger GDPR Art. 9 | +| PII-064 | Credit score | Payment history, financial behavior | Automated decision-making | + +## Classification rules + +When classifying detected data: + +1. **Direct PII** — data that directly identifies an individual (name, email, national ID). Use the catalog ID. +2. **Indirect PII** — data that identifies when combined with other data (ZIP + DOB + gender). Flag with confidence MEDIUM. +3. **Derived PII** — inferred from behavioral patterns. Flag with confidence LOW and mark as NEEDS_REVIEW. +4. **Pseudonymized data** — data with identifiers replaced by tokens. Still PII under GDPR Art. 4(5); flag but note pseudonymization as a control. +5. **Anonymized data** — data that cannot be re-identified. Not PII; do not flag. + +## Industry extension points + +The core catalog covers universal PII. Industry overlays add domain-specific types: + +- **Telco** → `10-industry-telco.md` adds IMEI, IMSI, MSISDN, CDR, cell tower data +- **Healthcare** → `11-industry-healthcare.md` adds MRN, diagnoses, medications, genetic markers +- **Financial** → `12-industry-financial.md` adds PAN, account numbers, transaction data, KYC + +Each overlay defines additional PII types using IDs in the range `PII-1xx` (telco), `PII-2xx` (healthcare), `PII-3xx` (financial). + +--- + +Taxonomy synthesized from NIST SP 800-122 (public domain), GDPR Art. 4 (paraphrased with attribution), and Australian Privacy Act 1988. Provided as a detection planning reference. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/01-detection-patterns.md b/.github/skills/project-planning/privacy-pii-detector/references/01-detection-patterns.md new file mode 100644 index 000000000..32ba1322a --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/01-detection-patterns.md @@ -0,0 +1,166 @@ +--- +title: Detection Patterns +description: Language-agnostic and language-specific code patterns for identifying PII processing in source code +--- + +# Detection Patterns + +This reference defines the patterns agents use to detect PII processing in codebases. Patterns are organized by detection method and map to PII taxonomy IDs. + +## Detection methods + +| Method | How it works | Confidence | +|--------|--------------|------------| +| Naming convention | Field/variable/column names matching PII patterns | HIGH | +| Data annotation | Decorators, attributes, or comments marking data classification | HIGH | +| Regex/format validation | Validation patterns that match PII formats | HIGH | +| API signature | Parameters or return types indicating PII | MEDIUM | +| Schema definition | Database columns, protobuf fields, GraphQL types | HIGH | +| String literal | Hardcoded PII in tests, seeds, or config | MEDIUM | +| Third-party SDK | Library calls known to process PII | MEDIUM | +| Log/telemetry output | Logging statements containing PII fields | HIGH | + +## Naming convention patterns + +### Field name indicators (case-insensitive, applies to variables, columns, JSON keys, model fields) + +| Pattern (glob/regex) | Maps to PII type | Confidence | +|---------------------|-----------------|------------| +| `*email*`, `*e_mail*`, `*emailAddress*` | PII-002 Email | HIGH | +| `*phone*`, `*mobile*`, `*telephone*`, `*phoneNumber*` | PII-003 Phone | HIGH | +| `*firstName*`, `*lastName*`, `*fullName*`, `*surname*`, `*givenName*` | PII-001 Name | HIGH | +| `*address*`, `*streetAddress*`, `*postalCode*`, `*zipCode*` | PII-004 Address | HIGH | +| `*dateOfBirth*`, `*dob*`, `*birthDate*`, `*birthday*` | PII-005 DOB | HIGH | +| `*ssn*`, `*socialSecurity*`, `*taxFileNumber*`, `*tfn*`, `*nationalId*` | PII-020 National ID | HIGH | +| `*passport*`, `*passportNumber*` | PII-020 National ID | HIGH | +| `*driverLicense*`, `*driversLicence*`, `*licenseNumber*` | PII-021 Driver License | HIGH | +| `*creditCard*`, `*cardNumber*`, `*pan*`, `*ccNumber*` | PII-023 Payment Card | HIGH | +| `*bankAccount*`, `*accountNumber*`, `*iban*`, `*bsb*` | PII-022 Financial Account | HIGH | +| `*password*`, `*passwordHash*`, `*secret*`, `*mfaSecret*` | PII-029 Credential | HIGH | +| `*ipAddress*`, `*clientIp*`, `*remoteAddr*` | PII-006 IP Address | HIGH | +| `*latitude*`, `*longitude*`, `*geoLocation*`, `*gps*` | PII-010 Location | HIGH | +| `*biometric*`, `*fingerprint*`, `*faceId*`, `*voicePrint*` | PII-028 Biometric | HIGH | +| `*diagnosis*`, `*condition*`, `*icdCode*`, `*healthRecord*` | PII-025 Health | HIGH | +| `*medication*`, `*prescription*`, `*drugName*` | PII-026 Medication | HIGH | +| `*salary*`, `*income*`, `*compensation*`, `*wage*` | PII-024 Income | MEDIUM | +| `*username*`, `*userId*`, `*loginId*` | PII-008 Username | MEDIUM | + +### Naming exclusions (reduce false positives) + +Exclude matches when the context indicates non-PII: + +- `*_template*`, `*_placeholder*`, `*_example*`, `*_mock*` +- Inside test fixtures clearly marked as synthetic data +- Generic words in unrelated contexts (e.g., `address` in memory address, `phone` in phone_type enum) + +## Format validation patterns (regex) + +When code contains regex patterns that match PII formats, this indicates PII processing: + +| Regex pattern in code | Indicates | PII Type | +|-----------------------|-----------|----------| +| `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b` | Email validation | PII-002 | +| `\b\d{3}[-.]?\d{3}[-.]?\d{4}\b` | US phone validation | PII-003 | +| `\b\d{3}-\d{2}-\d{4}\b` | SSN validation | PII-020 | +| `\b\d{9}\b` (in TFN context) | Australian TFN | PII-020 | +| `\b4[0-9]{12}(?:[0-9]{3})?\b` | Visa card number | PII-023 | +| `\b[0-9]{4}[\s-]?[0-9]{4}[\s-]?[0-9]{4}[\s-]?[0-9]{4}\b` | Credit card format | PII-023 | +| `\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b` | IPv4 address | PII-006 | +| `\b[0-9a-fA-F:]{17,39}\b` (MAC-like or IPv6) | Device/IP | PII-006/PII-007 | + +## Schema definition patterns + +### Database migrations and models + +Look for column definitions containing PII field names: + +```python +# SQLAlchemy example — detected PII fields +email = Column(String(255)) # PII-002 +phone_number = Column(String(20)) # PII-003 +date_of_birth = Column(Date) # PII-005 +ssn_encrypted = Column(LargeBinary) # PII-020 (note: encryption control present) +``` + +```typescript +// TypeORM / Prisma example +model User { + email String @unique // PII-002 + phone String? // PII-003 + dateOfBirth DateTime? // PII-005 + address String? // PII-004 +} +``` + +### API endpoint patterns + +Parameters or request/response bodies indicating PII: + +``` +POST /api/users → likely creates user with PII +GET /api/users/:id → returns user PII +PUT /api/profile → updates PII +POST /api/payments → processes financial PII +GET /api/health-records → health PII +``` + +## Third-party SDK indicators + +| Library/Package | Likely PII processing | Industry | +|-----------------|----------------------|----------| +| `stripe`, `braintree`, `adyen` | Payment card data | Financial | +| `twilio`, `sendgrid`, `mailgun` | Phone, email | Universal | +| `auth0`, `okta`, `firebase-auth` | Credentials, email, phone | Universal | +| `segment`, `mixpanel`, `amplitude` | Behavioral profile, device ID | Universal | +| `hl7-fhir`, `pydicom` | Health records | Healthcare | +| `plaid`, `yodlee` | Financial accounts | Financial | +| `google-maps`, `mapbox` | Location data | Universal | + +## Log and telemetry detection + +Detect PII leaking into logs: + +```python +# FAIL indicators — PII in logs +logger.info(f"User registered: {user.email}") # PII-002 in logs +logger.debug(f"Payment from card {card_number}") # PII-023 in logs +print(f"Processing {patient.ssn}") # PII-020 in stdout + +# PASS indicators — PII properly masked +logger.info(f"User registered: {mask(user.email)}") +logger.info(f"Payment processed for user_id={user.id}") +``` + +## Detection confidence levels + +| Confidence | Meaning | Action | +|------------|---------|--------| +| HIGH | Strong evidence of PII processing (naming + context match) | Report as confirmed detection | +| MEDIUM | Probable PII (naming match but ambiguous context) | Report with NEEDS_REVIEW flag | +| LOW | Possible PII (indirect inference or weak signal) | Report only in verbose mode | + +## Language-specific hints + +### Python +- Look in: models.py, serializers.py, schemas.py, forms.py, views.py, tasks.py +- Decorators: `@validator`, `@field_validator`, `@sensitive_data` + +### TypeScript/JavaScript +- Look in: *.model.ts, *.entity.ts, *.dto.ts, *.schema.ts, *.controller.ts +- Decorators: `@Column`, `@IsEmail()`, `@IsPhoneNumber()` + +### C# +- Look in: *Model.cs, *Entity.cs, *Dto.cs, *Controller.cs +- Attributes: `[PersonalData]`, `[EmailAddress]`, `[Phone]`, `[ProtectedPersonalData]` + +### Java +- Look in: *Entity.java, *Model.java, *Dto.java, *Repository.java +- Annotations: `@Email`, `@Column`, `@Sensitive` + +### Go +- Look in: *_model.go, *_handler.go, *_repository.go +- Struct tags: `json:"email"`, `db:"phone_number"` + +--- + +Detection patterns are original content (CC BY 4.0) synthesized from common software engineering practices for PII handling. Regex patterns are factual format descriptions, not reproductions of any licensed material. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/02-control-expectations.md b/.github/skills/project-planning/privacy-pii-detector/references/02-control-expectations.md new file mode 100644 index 000000000..67abbad0f --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/02-control-expectations.md @@ -0,0 +1,174 @@ +--- +title: Control Expectations +description: Required privacy controls per PII sensitivity tier with verification methods +--- + +# Control Expectations + +For each detected PII type, this reference defines the controls that must be present. The agent verifies each control and raises a finding when absent. + +## Control matrix by tier + +### Tier 1: Identifiers (PII-001 through PII-010) + +| Control | Required | Verification method | +|---------|----------|-------------------| +| Encryption at rest | Yes | Storage config shows AES-256, TDE, or managed encryption | +| Encryption in transit | Yes | TLS 1.2+ enforced; HTTPS-only endpoints | +| Access control | Yes | Role-based or attribute-based access on PII endpoints/tables | +| Input validation | Yes | Validation present on PII input fields (format, length) | +| Output masking in logs | Yes | Logging statements do not contain raw PII values | +| Retention policy | Yes | TTL, lifecycle rule, or documented retention period | +| Purpose documentation | Recommended | Collection point documents why PII is needed | +| Consent mechanism | Conditional | Required if lawful basis is consent (not contract/legitimate interest) | + +### Tier 2: Sensitive (PII-020 through PII-029) + +All Tier 1 controls plus: + +| Control | Required | Verification method | +|---------|----------|-------------------| +| Field-level encryption | Yes | Sensitive fields encrypted independently (not just disk encryption) | +| Audit logging | Yes | Access to sensitive data produces audit trail entries | +| Consent gate | Yes | Explicit consent collected before processing sensitive data | +| Purpose binding | Yes | Data tagged with processing purpose; secondary use restricted | +| Data minimization | Yes | Only minimum necessary fields collected | +| Pseudonymization | Recommended | Identifiers replaced with tokens in analytics/reporting | +| Breach notification | Yes | Incident response plan covers this data category | + +### Tier 3: Special Category (PII-040 through PII-047) + +All Tier 1 and Tier 2 controls plus: + +| Control | Required | Verification method | +|---------|----------|-------------------| +| Explicit consent | Yes | Granular, specific consent for this data category | +| DPIA conducted | Yes | Data Protection Impact Assessment documented | +| Access restriction | Yes | Need-to-know access beyond standard RBAC | +| Processing register | Yes | Entry in Records of Processing Activities (ROPA) | +| DPO notification | Recommended | Data Protection Officer aware of this processing | +| Cross-border restriction | Conditional | Transfer mechanisms if data crosses jurisdictions | +| Automated decision disclosure | Conditional | If used for profiling or automated decisions | + +## Control verification patterns + +### Encryption at rest + +Look for: +- Cloud storage lifecycle rules with encryption enabled +- Database configuration with TDE or column-level encryption +- Application-level encryption before storage (e.g., `encrypt()` calls on PII fields) +- Key management service references (AWS KMS, Azure Key Vault, GCP KMS) + +Evidence patterns: +```yaml +# Azure — encryption enabled +encryption: + services: + blob: + enabled: true + keyType: Account +``` + +```python +# Application-level encryption +encrypted_ssn = encrypt(ssn, key=get_key("pii-encryption")) +db.store(user_id=id, ssn_encrypted=encrypted_ssn) +``` + +### Access control + +Look for: +- Middleware or decorators restricting PII endpoints (`@authorize`, `@roles_required`) +- Database row-level security or column-level grants +- API gateway policies restricting PII routes + +Evidence patterns: +```python +@app.route("/api/users/") +@require_role("user_admin") # Access control present +def get_user(id): ... +``` + +### Output masking in logs + +Look for: +- Logging utility that masks/redacts PII fields +- Structured logging with PII exclusion rules +- No raw PII in `logger.*()`, `console.log()`, or `print()` calls + +Evidence patterns: +```python +# Control present — masked logging +logger.info("User action", extra={"user_id": user.id}) # ID only, no PII + +# Control absent — PII in logs +logger.info(f"Login: {user.email} from {request.remote_addr}") # FAIL +``` + +### Retention policy + +Look for: +- Database TTL or expiration columns +- Cloud storage lifecycle rules with deletion actions +- Scheduled cleanup jobs or retention enforcement code +- Documentation defining retention periods per data category + +Evidence patterns: +```yaml +# Storage lifecycle rule +lifecycle_rule: + condition: { age_days: 365 } + action: delete +``` + +```python +# Code-level retention +def purge_expired_users(): + cutoff = datetime.now() - timedelta(days=RETENTION_DAYS) + User.objects.filter(created_at__lt=cutoff).delete() +``` + +### Consent mechanism + +Look for: +- Consent collection UI or API (consent endpoint, checkbox, modal) +- Consent record storage (consent_given_at, consent_version, purpose) +- Consent check before processing (if not consented, block) + +Evidence patterns: +```typescript +// Consent gate before PII processing +if (!user.hasConsent("analytics")) { + throw new ConsentRequiredError("Analytics consent not given"); +} +``` + +## Control absence findings + +When a required control is not found, the finding includes: + +| Field | Value | +|-------|-------| +| `pii_type` | The detected PII taxonomy ID | +| `tier` | Sensitivity tier (T1/T2/T3) | +| `missing_control` | Which control is absent | +| `severity` | Mapped from tier: T1→MEDIUM, T2→HIGH, T3→CRITICAL | +| `remediation` | Specific action to implement the control | +| `evidence` | What was searched and not found | + +## Control sufficiency rules + +A control is considered PRESENT when: +- Code evidence confirms implementation (not just documentation) +- The control covers the specific PII type detected (not just generic security) +- The control is active (not commented out, behind a disabled feature flag, or in dead code) + +A control is PARTIAL when: +- Implementation exists but does not cover all instances of the PII type +- Documentation claims the control but code does not implement it +- The control exists in production config but not in all environments + +--- + +Control framework is original content (CC BY 4.0) synthesized from privacy engineering best practices, NIST SP 800-122, and GDPR Art. 25 technical measures guidance. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/03-finding-schema.md b/.github/skills/project-planning/privacy-pii-detector/references/03-finding-schema.md new file mode 100644 index 000000000..8dfd7e55e --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/03-finding-schema.md @@ -0,0 +1,168 @@ +--- +title: Finding Schema +description: Structured output format for PII detection results, control gap findings, and backlog handoff +--- + +# Finding Schema + +## Detection record + +Each detected PII instance produces a detection record: + +```yaml +detection: + id: "DET-" + pii_type: "PII-" + pii_name: "" + tier: "T1 | T2 | T3" + industry_overlay: "" + location: + file: "" + line: + element: "" + context: "" + confidence: "HIGH | MEDIUM | LOW" + evidence: "" +``` + +## Control gap finding + +For each missing control on a detected PII type: + +```yaml +finding: + id: "PII-GAP-" + detection_ref: "DET-" + pii_type: "PII-" + pii_name: "" + tier: "T1 | T2 | T3" + missing_control: "" + severity: "CRITICAL | HIGH | MEDIUM | LOW" + title: "" + description: "" + evidence_searched: "" + remediation: "" + regulatory_risk: "" + citations: + pii_id: "PII-" + gdpr_article: "" + ccpa_section: "<§section>" + app_principle: "" +``` + +## Severity mapping + +| Tier | Missing required control | Severity | +|------|--------------------------|----------| +| T3 (Special Category) | Any required control | CRITICAL | +| T2 (Sensitive) | Encryption, consent, audit logging | HIGH | +| T2 (Sensitive) | Other required controls | HIGH | +| T1 (Identifier) | Encryption, access control | MEDIUM | +| T1 (Identifier) | Logging masking, retention | MEDIUM | +| Any | Recommended control missing | LOW | + +## Assessment summary + +```yaml +pii_assessment: + scan_date: "" + scope: "" + industry_overlays_applied: ["", ""] + detection_summary: + total_detections: + by_tier: + t1_identifiers: + t2_sensitive: + t3_special_category: + by_confidence: + high: + medium: + low: + unique_pii_types: + control_assessment: + total_controls_checked: + controls_present: + controls_absent: + controls_partial: + findings_summary: + total_findings: + by_severity: + critical: + high: + medium: + low: + overall_verdict: "PROTECTED | GAPS_FOUND | UNPROTECTED" + top_priority_items: + - finding_id: "" + title: "" + severity: "<severity>" +``` + +## Overall verdict rules + +| Verdict | Condition | +|---------|-----------| +| PROTECTED | All detected PII has all required controls present | +| GAPS_FOUND | Some controls are missing but no CRITICAL findings | +| UNPROTECTED | One or more CRITICAL findings (T3 data without required controls) | + +## Backlog item template + +Each finding with severity MEDIUM or above maps to a backlog item: + +```yaml +backlog_item: + source_finding: "PII-GAP-<sequence>" + title: "[Privacy] <remediation title>" + description: | + **Detected PII**: <pii_name> (<pii_type>) + **Location**: <file>:<line> + **Sensitivity**: Tier <N> + **Missing control**: <control_name> + **Risk**: <regulatory_risk> + **Remediation**: <actionable fix> + priority: "<CRITICAL→P0, HIGH→P1, MEDIUM→P2, LOW→P3>" + labels: ["privacy", "pii-detection", "control-gap"] + acceptance_criteria: + - "<specific condition that resolves the finding>" + - "Verification: re-run PII detector shows control PRESENT" +``` + +## Example output + +```yaml +detection: + id: "DET-001" + pii_type: "PII-002" + pii_name: "Email address" + tier: "T1" + industry_overlay: "core" + location: + file: "src/models/user.py" + line: 15 + element: "email" + context: "User model stores email for authentication" + confidence: "HIGH" + evidence: "email = Column(String(255), unique=True)" + +finding: + id: "PII-GAP-001" + detection_ref: "DET-001" + pii_type: "PII-002" + pii_name: "Email address" + tier: "T1" + missing_control: "Output masking in logs" + severity: "MEDIUM" + title: "Email address logged in plaintext during authentication" + description: "User email is written to application logs during login events without masking" + evidence_searched: "Searched logging calls in auth.py; found logger.info(f'Login: {user.email}')" + remediation: "Replace raw email in log with masked version or user_id reference" + regulatory_risk: "GDPR Art. 5(1)(f) integrity and confidentiality; log exposure risk" + citations: + pii_id: "PII-002" + gdpr_article: "Art. 5(1)(f)" +``` + +--- + +Schema is original content (CC BY 4.0) following the finding and backlog patterns established by the security-reviewer and privacy-by-design skills within hve-core. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/04-custom-classification.md b/.github/skills/project-planning/privacy-pii-detector/references/04-custom-classification.md new file mode 100644 index 000000000..5c88230b6 --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/04-custom-classification.md @@ -0,0 +1,287 @@ +--- +title: Custom Classification +description: Project-level configuration for custom PII types, tier overrides, suppressions, and data catalog integration +--- + +# Custom Classification + +This reference defines the `.pii-config.yml` schema that projects place in their repository root to customize PII detection. The configuration allows teams to bring their own data classification without modifying the skill's core taxonomy. + +## Configuration file location + +The detector looks for `.pii-config.yml` at the repository root. If absent, the skill uses its built-in taxonomy and industry overlays without customization. + +``` +my-project/ +├── .pii-config.yml ← project-level customization +├── src/ +├── ... +``` + +## Schema + +```yaml +# .pii-config.yml +version: "1.0" + +# Industry context (activates the matching overlay) +industry: "telco" # Options: telco, healthcare, financial, or omit for core-only + +# Custom PII types specific to this organization +custom_types: + - id: "PII-C001" + name: "Employee Badge ID" + description: "Internal badge number used for physical access" + tier: "T1" + detection_patterns: + - "*badgeId*" + - "*badge_number*" + - "*accessCardId*" + required_controls: + - "encryption_at_rest" + - "access_control" + - "retention_policy" + + - id: "PII-C002" + name: "Vehicle Registration" + description: "Customer vehicle registration plate number" + tier: "T1" + detection_patterns: + - "*registration*" + - "*plateNumber*" + - "*vehicleReg*" + format_patterns: + - "[A-Z]{1,3}\\d{1,4}[A-Z]{0,3}" # AU format + required_controls: + - "encryption_at_rest" + - "output_masking" + +# Override sensitivity tiers for built-in types +tier_overrides: + - pii_type: "PII-002" # Email + new_tier: "T2" # Upgrade from T1 to T2 + justification: "Our org handles whistleblower emails requiring enhanced protection" + + - pii_type: "PII-006" # IP address + new_tier: "T2" + justification: "Regulatory requirement to treat IP as sensitive in our jurisdiction" + +# Additional controls beyond tier defaults +additional_controls: + - pii_type: "PII-002" # Email + controls: + - "audit_logging" # Add audit logging requirement for email + - "purpose_binding" + + - pii_type: "PII-023" # Payment card + controls: + - "tokenization" # Require tokenization (beyond default encryption) + +# Suppress false positives +suppressions: + - pattern: "address" + context: "memory_address" + reason: "Our 'address' fields in kernel module refer to memory addresses, not postal" + files: + - "src/kernel/**" + - "src/drivers/**" + + - pattern: "phone" + context: "phone_type_enum" + reason: "PhoneType enum values (MOBILE, LANDLINE) are not PII" + files: + - "src/models/enums.py" + + - pattern: "patient*" + context: "test_fixtures" + reason: "Test fixtures use synthetic patient data clearly marked as non-production" + files: + - "tests/**" + - "fixtures/**" + +# Data catalog integration (import existing classification) +catalog_import: + # Microsoft Purview + purview: + enabled: false + # When enabled, the detector merges Purview sensitivity labels with its taxonomy + # Requires: PURVIEW_TENANT_ID and PURVIEW_CLIENT_ID environment variables + label_mapping: + "Highly Confidential": "T3" + "Confidential": "T2" + "General": "T1" + + # Custom CSV/JSON import + file_import: + enabled: false + path: "docs/data-classification.csv" + # CSV must have columns: field_name, pii_type, tier, description + # Imported entries are treated as custom_types + +# Retention schedule overrides (per data category) +retention_overrides: + - pii_type: "PII-002" # Email + retention_days: 730 # 2 years (org policy) + justification: "Contractual requirement for 2-year email retention" + + - pii_type: "PII-106" # CDR (telco) + retention_days: 730 # 2 years (Australian metadata retention) + justification: "Telecommunications (Interception and Access) Act 1979 s 187AA" +``` + +## Schema field reference + +### `version` + +Required. Schema version. Currently `"1.0"`. + +### `industry` + +Optional. Activates the matching industry overlay. Values: `telco`, `healthcare`, `financial`. Omit to use only core taxonomy + custom types. + +### `custom_types` + +Optional. Array of organization-specific PII types not in the core taxonomy. + +| Field | Required | Description | +|-------|----------|-------------| +| `id` | Yes | Unique ID in format `PII-C<NNN>` (C prefix = custom) | +| `name` | Yes | Human-readable name | +| `description` | Yes | What this data type is | +| `tier` | Yes | Sensitivity tier: `T1`, `T2`, or `T3` | +| `detection_patterns` | Yes | Glob patterns for field/variable names (case-insensitive) | +| `format_patterns` | No | Regex patterns for format validation detection | +| `required_controls` | Yes | Controls from the control matrix that must be present | + +### `tier_overrides` + +Optional. Override the default sensitivity tier for a built-in PII type. + +| Field | Required | Description | +|-------|----------|-------------| +| `pii_type` | Yes | PII taxonomy ID to override (e.g., `PII-002`) | +| `new_tier` | Yes | New tier assignment: `T1`, `T2`, or `T3` | +| `justification` | Yes | Why this override exists (documented for audit) | + +### `additional_controls` + +Optional. Add controls beyond the tier default for specific PII types. + +| Field | Required | Description | +|-------|----------|-------------| +| `pii_type` | Yes | PII taxonomy ID | +| `controls` | Yes | Array of additional control names from the control matrix | + +### `suppressions` + +Optional. Suppress known false positive detections. + +| Field | Required | Description | +|-------|----------|-------------| +| `pattern` | Yes | The detection pattern to suppress | +| `context` | Yes | Why it's a false positive (e.g., `memory_address`, `test_fixtures`) | +| `reason` | Yes | Human-readable justification | +| `files` | No | Glob patterns limiting suppression scope. If omitted, applies globally | + +### `catalog_import` + +Optional. Import classification from external data catalogs. + +#### `purview` + +| Field | Required | Description | +|-------|----------|-------------| +| `enabled` | Yes | Whether to import from Microsoft Purview | +| `label_mapping` | Yes (if enabled) | Maps Purview sensitivity labels to PII tiers | + +#### `file_import` + +| Field | Required | Description | +|-------|----------|-------------| +| `enabled` | Yes | Whether to import from a local file | +| `path` | Yes (if enabled) | Relative path to CSV or JSON classification file | + +### `retention_overrides` + +Optional. Override retention expectations for specific PII types. + +| Field | Required | Description | +|-------|----------|-------------| +| `pii_type` | Yes | PII taxonomy ID | +| `retention_days` | Yes | Maximum retention in days | +| `justification` | Yes | Why this retention period (regulatory reference or org policy) | + +## Resolution order + +When the detector classifies a field, it resolves in this order: + +1. **Suppressions** — if the field matches a suppression, skip it. +2. **Custom types** — check project-defined types first. +3. **Tier overrides** — apply org-specific tier changes to built-in types. +4. **Industry overlay** — apply industry-specific types if configured. +5. **Core taxonomy** — fall back to the built-in classification. + +## Control resolution + +For each detected PII type, required controls are determined by: + +1. Base controls from `02-control-expectations.md` for the effective tier. +2. Plus any `additional_controls` from the config. +3. Industry overlay controls (if applicable). + +## Example: Telco company with custom classification + +```yaml +version: "1.0" +industry: "telco" + +custom_types: + - id: "PII-C001" + name: "Network Slice ID" + description: "5G network slice identifier linked to subscriber" + tier: "T2" + detection_patterns: + - "*sliceId*" + - "*networkSlice*" + - "*nssai*" + required_controls: + - "encryption_at_rest" + - "access_control" + - "audit_logging" + +tier_overrides: + - pii_type: "PII-104" # MAC address + new_tier: "T2" + justification: "Persistent device tracking via MAC requires enhanced controls per our DPO guidance" + +suppressions: + - pattern: "address" + context: "network_address" + reason: "Network address fields in routing tables are infrastructure, not postal addresses" + files: + - "src/routing/**" + - "src/network/**" + +retention_overrides: + - pii_type: "PII-106" # CDR + retention_days: 730 + justification: "Australian Telecommunications (Interception and Access) Act metadata retention" +``` + +## Validation + +The skill validates `.pii-config.yml` at the start of Phase 1 (Industry context). Invalid configurations produce a finding: + +```yaml +finding: + id: "PII-GAP-CONFIG-001" + severity: "LOW" + title: "Invalid .pii-config.yml: <specific error>" + remediation: "Fix the configuration error; detection proceeds with defaults" +``` + +The detector does not halt on invalid config — it falls back to defaults and reports the config issue as a LOW finding. + +--- + +Configuration schema is original content (CC BY 4.0). The `.pii-config.yml` pattern follows the convention established by `.adr-config.yml` in the ADR Creator skill. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/10-industry-telco.md b/.github/skills/project-planning/privacy-pii-detector/references/10-industry-telco.md new file mode 100644 index 000000000..fd1d8255e --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/10-industry-telco.md @@ -0,0 +1,105 @@ +--- +title: Telco Industry Overlay +description: Telecommunications-specific PII types, detection patterns, and control expectations +--- + +# Telco Industry Overlay + +This overlay extends the core PII taxonomy with telecommunications-specific personal information types. Apply when the codebase processes subscriber data, network identifiers, or communication metadata. + +## Industry detection triggers + +Apply this overlay when the codebase contains: +- Dependencies: `diameter`, `ss7`, `camel`, `radius`, `sip`, telecom SDKs +- Terminology: subscriber, MSISDN, CDR, provisioning, roaming, handset +- API patterns: `/api/subscribers`, `/api/cdr`, `/api/network/` +- Domain: `.telco.`, `.telecom.`, `.mobile.` in package names or configs + +## Telco-specific PII types + +| ID | PII Type | Description | Tier | Regulatory anchor | +|----|----------|-------------|------|-------------------| +| PII-100 | IMEI | International Mobile Equipment Identity (15-digit device ID) | T2 | GDPR Art. 4(1), ePrivacy | +| PII-101 | IMSI | International Mobile Subscriber Identity (SIM identity) | T2 | GDPR Art. 4(1), ePrivacy | +| PII-102 | MSISDN | Mobile subscriber number (phone number in E.164 format) | T1 | GDPR Art. 4(1) | +| PII-103 | SIM serial (ICCID) | Integrated Circuit Card ID | T2 | ePrivacy Directive | +| PII-104 | MAC address | Device network hardware identifier | T1 | GDPR Recital 30 | +| PII-105 | Cell tower ID (CGI) | Cell Global Identity — user location via network | T2 | ePrivacy Art. 9, GDPR Art. 9 (if continuous) | +| PII-106 | CDR (Call Detail Record) | Who called whom, when, duration, cell tower | T2 | Metadata Retention laws, ePrivacy | +| PII-107 | SMS/MMS content | Message body content | T3 | Interception laws, ePrivacy Art. 5 | +| PII-108 | Voicemail content | Recorded voice messages | T3 | ePrivacy Art. 5 | +| PII-109 | Network location history | Sequence of cell attachments over time | T2 | GDPR Art. 9 (movement patterns) | +| PII-110 | Subscriber profile | Plan type, usage patterns, credit status | T1 | Contextual | +| PII-111 | Device fingerprint | Handset model, OS version, IMEI + behavioral signals | T2 | ePrivacy, GDPR Recital 30 | +| PII-112 | Roaming data | Visited networks, international movement | T2 | Cross-border transfer triggers | + +## Telco detection patterns + +### Naming conventions + +| Pattern | Maps to | Confidence | +|---------|---------|------------| +| `*imei*`, `*device_imei*`, `*handsetId*` | PII-100 IMEI | HIGH | +| `*imsi*`, `*subscriberIdentity*` | PII-101 IMSI | HIGH | +| `*msisdn*`, `*subscriberNumber*`, `*mobileNumber*` | PII-102 MSISDN | HIGH | +| `*iccid*`, `*simSerial*`, `*simId*` | PII-103 SIM Serial | HIGH | +| `*macAddress*`, `*hwAddress*`, `*mac_addr*` | PII-104 MAC | HIGH | +| `*cellId*`, `*cgi*`, `*cellTower*`, `*lac*` | PII-105 Cell Tower | HIGH | +| `*cdr*`, `*callRecord*`, `*callDetail*` | PII-106 CDR | HIGH | +| `*smsBody*`, `*messageContent*`, `*mmsPayload*` | PII-107 SMS/MMS | HIGH | +| `*voicemail*`, `*vmContent*` | PII-108 Voicemail | HIGH | +| `*locationHistory*`, `*cellHistory*`, `*networkTrace*` | PII-109 Location History | HIGH | + +### Format patterns + +| Format in code | Indicates | Confidence | +|----------------|-----------|------------| +| `\b\d{15}\b` (15-digit, Luhn check) | IMEI | MEDIUM | +| `\b\d{15,16}\b` (in IMSI context) | IMSI | MEDIUM | +| `\+?\d{10,15}` (E.164 format) | MSISDN | MEDIUM | +| `\b\d{19,20}\b` (in SIM context) | ICCID | MEDIUM | +| `([0-9A-Fa-f]{2}[:-]){5}[0-9A-Fa-f]{2}` | MAC address | HIGH | + +### Schema patterns + +```protobuf +// Telco protobuf — multiple PII fields +message CallDetailRecord { + string calling_msisdn = 1; // PII-102 + string called_msisdn = 2; // PII-102 + int64 start_time = 3; + int32 duration_seconds = 4; + string cell_id_start = 5; // PII-105 + string cell_id_end = 6; // PII-105 + string imei = 7; // PII-100 + string imsi = 8; // PII-101 +} +``` + +## Telco-specific control requirements + +Beyond core tier controls, telco PII requires: + +| Control | Applies to | Rationale | +|---------|-----------|-----------| +| Lawful interception isolation | PII-107, PII-108 | Content must be accessible only via warranted legal process | +| Metadata retention compliance | PII-106, PII-109 | Retention periods mandated by national data retention laws (varies: 6mo–2yr) | +| Network-level encryption | PII-100–PII-112 | Data in transit between network elements must use IPsec or TLS | +| Subscriber consent for location | PII-105, PII-109 | Explicit opt-in for location-based services beyond network operation | +| CDR anonymization for analytics | PII-106 | Aggregated CDR for business analytics must strip subscriber identifiers | +| Cross-border roaming controls | PII-112 | Roaming partner data sharing requires transfer agreements | +| Device correlation prevention | PII-100, PII-111 | IMEI must not be correlated across services without purpose limitation | + +## Telco regulatory context + +| Regulation | Jurisdiction | Key requirement | +|-----------|--------------|-----------------| +| ePrivacy Directive (2002/58/EC) | EU | Consent for location data; confidentiality of communications | +| Telecommunications Act 1997 | Australia | Metadata retention (2 years); interception warrant requirements | +| CPNI rules (47 CFR § 64.2001) | US | Customer Proprietary Network Information protection | +| Telecommunications (Interception) Act | Australia | Lawful interception obligations | +| EU Data Retention Directive (invalidated) | EU | Historical context; replaced by national implementations | + +--- + +Telco overlay is original content (CC BY 4.0) synthesized from telecommunications privacy engineering practices. Regulatory references are paraphrased with attribution, not legal interpretations. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/11-industry-healthcare.md b/.github/skills/project-planning/privacy-pii-detector/references/11-industry-healthcare.md new file mode 100644 index 000000000..94fac6915 --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/11-industry-healthcare.md @@ -0,0 +1,98 @@ +--- +title: Healthcare Industry Overlay +description: Health data PII types, detection patterns, and control expectations for healthcare systems +--- + +# Healthcare Industry Overlay + +This overlay extends the core PII taxonomy with healthcare-specific personal information types. Apply when the codebase processes patient data, clinical records, or health-adjacent information. + +## Industry detection triggers + +Apply this overlay when the codebase contains: +- Dependencies: `hl7`, `fhir`, `pydicom`, `hapi-fhir`, `openehr`, `cda` +- Terminology: patient, diagnosis, ICD, SNOMED, encounter, admission, discharge, provider, NPI +- API patterns: `/api/patients`, `/api/encounters`, `/api/observations`, `/fhir/` +- Domain: `.health.`, `.clinical.`, `.ehr.`, `.emr.` in package names or configs + +## Healthcare-specific PII types + +| ID | PII Type | Description | Tier | Regulatory anchor | +|----|----------|-------------|------|-------------------| +| PII-200 | Medical record number (MRN) | Facility-assigned patient identifier | T2 | HIPAA §164.514, My Health Records Act | +| PII-201 | Diagnosis/condition | ICD codes, SNOMED terms, clinical descriptions | T3 | HIPAA, GDPR Art. 9 (health data) | +| PII-202 | Medication/prescription | Drug names, dosages, prescribing provider | T2 | HIPAA | +| PII-203 | Lab result | Test values, reference ranges, interpretations | T2 | HIPAA | +| PII-204 | Clinical note | Free-text clinician documentation | T3 | HIPAA (may contain any PII) | +| PII-205 | Medical image | X-ray, MRI, CT with embedded patient metadata (DICOM) | T2 | HIPAA, DICOM de-identification | +| PII-206 | Genetic/genomic data | DNA sequences, variants, pharmacogenomics | T3 | GDPR Art. 9, GINA, state genetic privacy laws | +| PII-207 | Mental health record | Psychiatric notes, therapy records | T3 | Enhanced confidentiality (42 CFR Part 2) | +| PII-208 | Substance abuse record | Addiction treatment, rehabilitation | T3 | 42 CFR Part 2 (US), enhanced protections | +| PII-209 | Insurance/payer ID | Health plan member ID, group number | T2 | HIPAA | +| PII-210 | Provider NPI | National Provider Identifier (treating clinician) | T1 | Public data but links to patient context | +| PII-211 | Consent/advance directive | Patient treatment preferences, DNR status | T2 | Varies by jurisdiction | +| PII-212 | Disability information | Functional limitations, accommodation needs | T2 | ADA, GDPR Art. 9 | + +## Healthcare detection patterns + +### Naming conventions + +| Pattern | Maps to | Confidence | +|---------|---------|------------| +| `*mrn*`, `*medicalRecordNumber*`, `*patientId*` | PII-200 MRN | HIGH | +| `*diagnosis*`, `*icdCode*`, `*icd10*`, `*snomedCode*`, `*condition*` | PII-201 Diagnosis | HIGH | +| `*medication*`, `*prescription*`, `*rxName*`, `*drugCode*`, `*ndc*` | PII-202 Medication | HIGH | +| `*labResult*`, `*testValue*`, `*observation*`, `*loincCode*` | PII-203 Lab Result | HIGH | +| `*clinicalNote*`, `*progressNote*`, `*dischargeNote*` | PII-204 Clinical Note | HIGH | +| `*dicom*`, `*medicalImage*`, `*xray*`, `*mri*` | PII-205 Medical Image | HIGH | +| `*genetic*`, `*genomic*`, `*dna*`, `*variant*`, `*snp*` | PII-206 Genetic | HIGH | +| `*mentalHealth*`, `*psychiatric*`, `*therapy*` | PII-207 Mental Health | HIGH | +| `*substanceAbuse*`, `*addiction*`, `*rehabilitation*` | PII-208 Substance Abuse | HIGH | +| `*insuranceId*`, `*memberId*`, `*payerId*`, `*healthPlan*` | PII-209 Insurance | HIGH | +| `*npi*`, `*providerNumber*`, `*practitionerId*` | PII-210 Provider NPI | MEDIUM | + +### FHIR resource detection + +When FHIR resources are present, map to PII types: + +| FHIR Resource | Contains PII types | +|---------------|-------------------| +| `Patient` | PII-001 (name), PII-002 (email), PII-003 (phone), PII-005 (DOB), PII-200 (MRN) | +| `Condition` | PII-201 (diagnosis) | +| `MedicationRequest` | PII-202 (medication) | +| `Observation` | PII-203 (lab result) | +| `DocumentReference` | PII-204 (clinical note), PII-205 (image) | +| `MolecularSequence` | PII-206 (genetic) | +| `Claim` | PII-209 (insurance) | + +## Healthcare-specific control requirements + +Beyond core tier controls: + +| Control | Applies to | Rationale | +|---------|-----------|-----------| +| Minimum necessary | All health PII | HIPAA minimum necessary standard — disclose only what is needed | +| Break-the-glass audit | PII-201–PII-208 | Emergency access override with mandatory post-access review | +| Segmentation (42 CFR Part 2) | PII-207, PII-208 | Substance abuse and mental health records require explicit consent for each disclosure | +| DICOM de-identification | PII-205 | Medical images must strip patient metadata per DICOM PS3.15 | +| Research de-identification | All | HIPAA Safe Harbor (18 identifiers removed) or Expert Determination | +| Patient portal access | PII-200–PII-204 | Patients must have electronic access to their records (21st Century Cures) | +| Genetic non-discrimination | PII-206 | GINA prohibits use in employment/insurance decisions | +| Cross-facility consent | All | Inter-organizational health information exchange requires patient consent | + +## Healthcare regulatory context + +| Regulation | Jurisdiction | Key requirement | +|-----------|--------------|-----------------| +| HIPAA Privacy Rule | US | Minimum necessary, patient rights, covered entity obligations | +| HIPAA Security Rule | US | Administrative, physical, and technical safeguards | +| 42 CFR Part 2 | US | Enhanced consent for substance abuse records | +| GINA | US | Genetic non-discrimination in employment and insurance | +| My Health Records Act 2012 | Australia | Digital health record controls, secondary use restrictions | +| Health Records Act 2001 | Australia (VIC) | State-level health privacy protections | +| GDPR Art. 9 | EU | Health data as special category requiring explicit consent | +| 21st Century Cures Act | US | Patient access, information blocking prohibition | + +--- + +Healthcare overlay is original content (CC BY 4.0) synthesized from health privacy engineering practices. Regulatory references are paraphrased with attribution, not legal interpretations. diff --git a/.github/skills/project-planning/privacy-pii-detector/references/12-industry-financial.md b/.github/skills/project-planning/privacy-pii-detector/references/12-industry-financial.md new file mode 100644 index 000000000..3fa450e39 --- /dev/null +++ b/.github/skills/project-planning/privacy-pii-detector/references/12-industry-financial.md @@ -0,0 +1,114 @@ +--- +title: Financial Services Industry Overlay +description: Financial data PII types, detection patterns, and control expectations for banking and fintech +--- + +# Financial Services Industry Overlay + +This overlay extends the core PII taxonomy with financial services-specific personal information types. Apply when the codebase processes payment data, banking information, or financial customer records. + +## Industry detection triggers + +Apply this overlay when the codebase contains: +- Dependencies: `stripe`, `braintree`, `adyen`, `plaid`, `yodlee`, `open-banking`, PCI libraries +- Terminology: account, transaction, KYC, AML, PAN, merchant, settlement, ledger +- API patterns: `/api/accounts`, `/api/transactions`, `/api/payments`, `/api/kyc` +- Domain: `.bank.`, `.finance.`, `.payments.` in package names or configs + +## Financial-specific PII types + +| ID | PII Type | Description | Tier | Regulatory anchor | +|----|----------|-------------|------|-------------------| +| PII-300 | PAN (Primary Account Number) | Full credit/debit card number | T2 | PCI DSS | +| PII-301 | CVV/CVC | Card verification value | T2 | PCI DSS (never stored) | +| PII-302 | Bank account number | Account, IBAN, BSB + account | T2 | Banking regulations | +| PII-303 | Routing/sort code | Bank routing identifier | T1 | Contextual (sensitive with account) | +| PII-304 | Transaction history | What was bought, when, where, amount | T2 | GDPR, CCPA, APRA | +| PII-305 | Account balance | Current balance, available funds | T2 | Banking secrecy laws | +| PII-306 | Credit score | Bureau score, internal risk rating | T2 | FCRA, GDPR Art. 22 | +| PII-307 | KYC documents | Identity verification documents (passport, utility bill, selfie) | T2 | AML/CTF regulations | +| PII-308 | Tax identifier | TIN, EIN, VAT number linked to individual | T2 | Tax privacy laws | +| PII-309 | Beneficiary details | Transfer recipient name, account, relationship | T2 | AML requirements | +| PII-310 | Loan/mortgage details | Amount, terms, repayment history, arrears | T2 | Consumer credit laws | +| PII-311 | Investment portfolio | Holdings, trades, positions | T2 | Securities regulations | +| PII-312 | Fraud indicators | Fraud scores, suspicious activity flags | T2 | AML/CTF, Tipping-off rules | +| PII-313 | PIN (encrypted) | Personal identification number for authentication | T2 | PCI PIN Security | + +## Financial detection patterns + +### Naming conventions + +| Pattern | Maps to | Confidence | +|---------|---------|------------| +| `*cardNumber*`, `*pan*`, `*primaryAccountNumber*`, `*ccNumber*` | PII-300 PAN | HIGH | +| `*cvv*`, `*cvc*`, `*cardVerification*`, `*securityCode*` | PII-301 CVV | HIGH | +| `*bankAccount*`, `*accountNumber*`, `*iban*`, `*bsb*` | PII-302 Account | HIGH | +| `*routingNumber*`, `*sortCode*`, `*swiftCode*` | PII-303 Routing | HIGH | +| `*transaction*`, `*txn*`, `*payment*`, `*purchase*` | PII-304 Transaction | MEDIUM | +| `*balance*`, `*availableFunds*`, `*accountBalance*` | PII-305 Balance | HIGH | +| `*creditScore*`, `*riskRating*`, `*bureauScore*`, `*fico*` | PII-306 Credit Score | HIGH | +| `*kyc*`, `*identityVerification*`, `*proofOfId*` | PII-307 KYC | HIGH | +| `*tin*`, `*taxId*`, `*einNumber*`, `*vatNumber*` | PII-308 Tax ID | HIGH | +| `*beneficiary*`, `*recipient*`, `*payee*` | PII-309 Beneficiary | MEDIUM | +| `*loan*`, `*mortgage*`, `*repayment*`, `*arrears*` | PII-310 Loan | HIGH | +| `*portfolio*`, `*holdings*`, `*positions*`, `*trades*` | PII-311 Investment | MEDIUM | +| `*fraudScore*`, `*suspiciousActivity*`, `*sar*` | PII-312 Fraud | HIGH | +| `*pin*`, `*pinBlock*`, `*encryptedPin*` | PII-313 PIN | HIGH | + +### PCI-specific patterns + +``` +# PAN detection — look for card number handling +FAIL: Storing full PAN in plaintext columns +FAIL: Logging card numbers +FAIL: CVV stored anywhere (even encrypted) +PASS: Tokenized card reference (tok_xxx) +PASS: Last-4 only storage (card_last_four) +PASS: PCI-compliant vault reference (vault_id) +``` + +### Open Banking API patterns + +``` +# Endpoints indicating financial PII +GET /api/accounts/{id}/balance → PII-305 +GET /api/accounts/{id}/transactions → PII-304 +POST /api/payments → PII-300, PII-302 +POST /api/kyc/verify → PII-307 +GET /api/credit-score → PII-306 +``` + +## Financial-specific control requirements + +Beyond core tier controls: + +| Control | Applies to | Rationale | +|---------|-----------|-----------| +| PCI DSS compliance | PII-300, PII-301, PII-313 | Card data requires PCI DSS scope; CVV must never be stored | +| Tokenization | PII-300 | Replace PAN with non-reversible token for non-payment processing | +| PCI-compliant vault | PII-300, PII-313 | Store card data only in certified cardholder data environment (CDE) | +| Transaction monitoring | PII-304, PII-312 | AML/CTF obligation to monitor for suspicious patterns | +| KYC document retention limits | PII-307 | Retain only for regulatory minimum; destroy after obligation expires | +| Tipping-off prevention | PII-312 | Fraud/SAR flags must not be disclosed to the subject | +| Strong Customer Authentication | PII-300, PII-302 | PSD2/SCA requirement for payment initiation | +| Data segregation | All financial PII | Ring-fence financial data from marketing and analytics | +| Audit trail (immutable) | PII-304, PII-305 | Financial transactions require immutable audit for regulatory reporting | +| Cross-border transfer controls | All | SWIFT, SEPA, and correspondent banking data subject to jurisdictional rules | + +## Financial regulatory context + +| Regulation | Jurisdiction | Key requirement | +|-----------|--------------|-----------------| +| PCI DSS v4.0 | Global | Cardholder data protection, network segmentation, encryption | +| PSD2/SCA | EU | Strong customer authentication, open banking consent | +| FCRA | US | Credit reporting accuracy, consumer dispute rights | +| AML/CTF Act 2006 | Australia | Customer identification, transaction monitoring, reporting | +| Bank Secrecy Act / FinCEN | US | Anti-money laundering, suspicious activity reporting | +| APRA CPS 234 | Australia | Information security for APRA-regulated entities | +| GDPR (financial) | EU | Consent for profiling, automated decision-making transparency | +| Consumer Credit Act | UK/AU | Responsible lending, credit information handling | +| SOX Section 404 | US | Financial data integrity controls for public companies | + +--- + +Financial overlay is original content (CC BY 4.0) synthesized from financial privacy and PCI engineering practices. Regulatory references are paraphrased with attribution, not legal interpretations.