@musashishao/agent-kit 1.6.1 → 1.6.2

package/.agent/skills/privacy-preserving-dev/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: privacy-preserving-dev
+description: PII detection & redaction patterns, data anonymization techniques, secure prompt engineering, and data retention policies for AI systems.
+allowed-tools: Read, Glob, Grep, Bash
+skills:
+  - ai-security-guardrails
+---
+
+# Privacy-Preserving Development
+
+> Protect user data in AI systems. Privacy by design, not afterthought.
+
+## 🔧 Runtime Scripts
+
+**Execute for automated validation:**
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/pii_scanner.py` | Detect PII in code and prompts | `python scripts/pii_scanner.py <project_path>` |
+
+---
+
+## 1. PII Categories & Risk Levels
+
+### High-Risk PII (Requires Protection)
+
+| Category | Examples | Risk |
+|----------|----------|------|
+| **Identifiers** | SSN, Passport, Driver License | Critical |
+| **Financial** | Credit Card, Bank Account, Tax ID | Critical |
+| **Health** | Medical Records, Diagnosis, Prescriptions | Critical |
+| **Auth** | Passwords, API Keys, Tokens | Critical |
+| **Contact** | Email, Phone, Address | High |
+| **Personal** | Full Name, DOB, Gender | High |
+| **Biometric** | Fingerprint, Face ID, Voice | Critical |
+
+### Context-Dependent
+
+| Data | Risk When Combined |
+|------|---------------------|
+| IP Address | + User ID = Tracking |
+| Location | + Timestamp = Surveillance |
+| Device ID | + Behavior = Profiling |
+
+---
+
+## 2. PII Detection Patterns
+
+### Regex Patterns
+
+```python
+PII_PATTERNS = {
+    # Critical
+    "SSN": r"\b\d{3}-\d{2}-\d{4}\b",
+    "Credit Card": r"\b(?:\d{4}[-\s]?){3}\d{4}\b",
+    "IBAN": r"\b[A-Z]{2}\d{2}[A-Z0-9]{4,30}\b",
+    
+    # High
+    "Email": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
+    "Phone (US)": r"\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b",
+    "Phone (Intl)": r"\+\d{1,3}[-.\s]?\d{4,14}",
+    
+    # Medium
+    "IP Address": r"\b(?:\d{1,3}\.){3}\d{1,3}\b",
+    "Date of Birth": r"\b(?:\d{1,2}[-/]\d{1,2}[-/]\d{2,4})|(?:\d{4}[-/]\d{1,2}[-/]\d{1,2})\b",
+    
+    # Auth (Critical)
+    "API Key": r"\b(?:sk|pk|api)[_-]?(?:live|test)?[_-]?[a-zA-Z0-9]{20,}\b",
+    "JWT": r"eyJ[A-Za-z0-9-_]+\.eyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_.+/=]+",
+    "AWS Key": r"\bAKIA[0-9A-Z]{16}\b",
+}
+```
+
+---
+
+## 3. Redaction Strategies
+
+### Strategy Selection
+
+| Context | Strategy | Example |
+|---------|----------|---------|
+| **Logs** | Full redaction | `***REDACTED***` |
+| **Analytics** | Hash + salt | `usr_a1b2c3d4` |
+| **Display** | Partial mask | `john***@email.com` |
+| **Export** | Pseudonymization | `User_12345` |
+
+### Implementation
+
+```typescript
+interface RedactionConfig {
+  strategy: 'full' | 'partial' | 'hash' | 'tokenize';
+  salt?: string;
+  preserveFormat?: boolean;
+}
+
+function redactPII(text: string, config: RedactionConfig): string {
+  const patterns = Object.entries(PII_PATTERNS);
+  let result = text;
+  
+  for (const [type, pattern] of patterns) {
+    const regex = new RegExp(pattern, 'gi');
+    
+    result = result.replace(regex, (match) => {
+      switch (config.strategy) {
+        case 'full':
+          return `[${type.toUpperCase()}_REDACTED]`;
+        
+        case 'partial':
+          // Keep first and last characters
+          if (match.length > 4) {
+            return match[0] + '*'.repeat(match.length - 2) + match.slice(-1);
+          }
+          return '****';
+        
+        case 'hash':
+          return hashWithSalt(match, config.salt || 'default');
+        
+        case 'tokenize':
+          return getOrCreateToken(match, type);
+        
+        default:
+          return '[REDACTED]';
+      }
+    });
+  }
+  
+  return result;
+}
+```
+
+---
+
+## 4. Secure Prompt Engineering
+
+### Data Minimization
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Need-to-know** | Only include data required for task |
+| **Aggregation** | Use summaries instead of raw data |
+| **Abstraction** | Reference IDs instead of full records |
+| **Time-boxing** | Remove data after processing |
+
+### Safe Prompt Template
+
+```python
+def build_private_prompt(user_query: str, context: dict) -> str:
+    """Build prompt with PII protection."""
+    
+    # 1. Redact PII from user query
+    safe_query = redact_pii(user_query)
+    
+    # 2. Use reference IDs instead of full data
+    safe_context = {
+        "user_id": context.get("user_id"),  # Just ID, not full profile
+        "account_type": context.get("account_type"),  # Category, not details
+        "request_category": classify_request(safe_query),
+    }
+    
+    # 3. Add privacy instructions
+    return f"""
+<PRIVACY_RULES>
+- Never output personal information in responses
+- Use reference IDs instead of names
+- Do not memorize or repeat user data
+</PRIVACY_RULES>
+
+<CONTEXT>
+User Type: {safe_context['account_type']}
+Request Category: {safe_context['request_category']}
+</CONTEXT>
+
+<QUERY>
+{safe_query}
+</QUERY>
+
+Respond helpfully while respecting privacy rules.
+"""
+```
+
+---
+
+## 5. Data Anonymization Techniques
+
+### Technique Selection
+
+| Technique | Use Case | Reversible? |
+|-----------|----------|-------------|
+| **Masking** | Display, logs | No |
+| **Hashing** | Analytics | No |
+| **Tokenization** | Database storage | Yes (with key) |
+| **Encryption** | Transit, storage | Yes (with key) |
+| **Generalization** | Analytics | No |
+| **Perturbation** | ML training | No |
+
+### Generalization Examples
+
+```python
+def generalize_data(data: dict) -> dict:
+    """Convert specific data to general categories."""
+    
+    result = {}
+    
+    # Age → Age range
+    if "age" in data:
+        age = data["age"]
+        if age < 18: result["age_group"] = "minor"
+        elif age < 30: result["age_group"] = "young_adult"
+        elif age < 50: result["age_group"] = "adult"
+        else: result["age_group"] = "senior"
+    
+    # Location → Region
+    if "city" in data:
+        result["region"] = get_region(data["city"])  # "San Francisco" → "West Coast"
+    
+    # Salary → Range
+    if "salary" in data:
+        salary = data["salary"]
+        result["income_bracket"] = categorize_income(salary)  # 75000 → "70-80k"
+    
+    return result
+```
+
+---
+
+## 6. Differential Privacy
+
+### Concept
+
+```
+True Answer + Calibrated Noise = Private Answer
+```
+
+### When to Use
+
+| Scenario | Apply Differential Privacy? |
+|----------|----------------------------|
+| Aggregate statistics | ✅ Yes |
+| Individual records | ❌ Use other methods |
+| Model training | ✅ Yes (DP-SGD) |
+| Analytics dashboards | ✅ Yes |
+
+### Simple Implementation
+
+```python
+import numpy as np
+
+def add_laplace_noise(value: float, sensitivity: float, epsilon: float) -> float:
+    """Add Laplace noise for differential privacy.
+    
+    Args:
+        value: True value
+        sensitivity: Maximum change one record can cause
+        epsilon: Privacy budget (lower = more private)
+    
+    Returns:
+        Noisy value
+    """
+    scale = sensitivity / epsilon
+    noise = np.random.laplace(0, scale)
+    return value + noise
+
+# Example: Private count
+def private_count(data: list, epsilon: float = 1.0) -> float:
+    true_count = len(data)
+    return add_laplace_noise(true_count, sensitivity=1, epsilon=epsilon)
+```
+
+---
+
+## 7. Data Retention Policies
+
+### Retention Matrix
+
+| Data Type | Retention Period | Action After |
+|-----------|------------------|--------------|
+| **Session data** | Until logout | Delete |
+| **Conversation logs** | 30 days | Anonymize |
+| **User profiles** | Account lifetime + 30 days | Delete |
+| **Analytics** | 1 year (aggregated) | Archive |
+| **Audit logs** | 7 years | Secure archive |
+
+### Implementation
+
+```typescript
+interface RetentionPolicy {
+  dataType: string;
+  retentionDays: number;
+  actionAfter: 'delete' | 'anonymize' | 'archive';
+}
+
+async function enforceRetention(policy: RetentionPolicy): Promise<void> {
+  const cutoffDate = new Date();
+  cutoffDate.setDate(cutoffDate.getDate() - policy.retentionDays);
+  
+  const expiredRecords = await db.findExpired(policy.dataType, cutoffDate);
+  
+  for (const record of expiredRecords) {
+    switch (policy.actionAfter) {
+      case 'delete':
+        await db.delete(record.id);
+        break;
+      
+      case 'anonymize':
+        await db.update(record.id, anonymize(record));
+        break;
+      
+      case 'archive':
+        await archiveService.store(record);
+        await db.delete(record.id);
+        break;
+    }
+  }
+  
+  log.info(`Processed ${expiredRecords.length} ${policy.dataType} records`);
+}
+```
+
+---
+
+## 8. Consent Management
+
+### Consent Types
+
+| Type | Required For | Revocable? |
+|------|--------------|------------|
+| **Essential** | Core service | No |
+| **Analytics** | Usage tracking | Yes |
+| **Marketing** | Promotions | Yes |
+| **AI Training** | Model improvement | Yes |
+
+### Implementation Pattern
+
+```typescript
+interface UserConsent {
+  userId: string;
+  consents: {
+    essential: true;  // Always true
+    analytics: boolean;
+    marketing: boolean;
+    aiTraining: boolean;
+  };
+  updatedAt: Date;
+}
+
+function canProcessForPurpose(consent: UserConsent, purpose: string): boolean {
+  if (purpose === 'essential') return true;
+  return consent.consents[purpose] === true;
+}
+
+// Before AI processing
+async function processWithConsent(userId: string, data: any): Promise<void> {
+  const consent = await getConsent(userId);
+  
+  if (!canProcessForPurpose(consent, 'aiTraining')) {
+    // Use data for this request only, don't store for training
+    return processWithoutStorage(data);
+  }
+  
+  return processAndStore(data);
+}
+```
+
+---
+
+## 9. Audit Trail
+
+### What to Log
+
+| Event | Required Fields |
+|-------|-----------------|
+| **Data access** | Who, What, When, Why |
+| **Data modification** | Before, After, Reason |
+| **Data deletion** | What, When, By whom |
+| **Consent change** | Old, New, Timestamp |
+
+### Secure Logging
+
+```python
+import hashlib
+from datetime import datetime
+
+def log_data_access(user_id: str, data_type: str, purpose: str, accessor: str):
+    """Log data access with privacy protection."""
+    
+    # Hash user ID for log privacy
+    hashed_user = hashlib.sha256(f"{user_id}:audit_salt".encode()).hexdigest()[:16]
+    
+    audit_entry = {
+        "timestamp": datetime.utcnow().isoformat(),
+        "subject_hash": hashed_user,
+        "data_type": data_type,
+        "purpose": purpose,
+        "accessor": accessor,
+        "action": "access"
+    }
+    
+    # Append-only audit log
+    audit_log.append(audit_entry)
+```
+
+---
+
+## 10. Checklist
+
+### Before Processing User Data
+
+- [ ] PII identified and classified
+- [ ] Redaction/anonymization applied
+- [ ] Consent verified for purpose
+- [ ] Data minimization applied
+- [ ] Retention policy set
+
+### For AI/LLM Processing
+
+- [ ] PII redacted from prompts
+- [ ] Output checked for PII leakage
+- [ ] No training on personal data without consent
+- [ ] Audit trail enabled
+
+### For Data Storage
+
+- [ ] Encryption at rest
+- [ ] Access controls implemented
+- [ ] Retention automation configured
+- [ ] Deletion verification
+
+---
+
+## 11. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Log full PII | Log hashed/tokenized references |
+| Store "just in case" | Apply data minimization |
+| Use PII as identifiers | Use synthetic IDs |
+| Ignore consent | Check consent before processing |
+| Hard-delete only | Verify deletion, maintain audit |
+
+---
+
+> **Remember:** Privacy is not about hiding data—it's about respecting user control over their information.