diff --git a/docs/docs.json b/docs/docs.json index d9e5762a1..b086300ff 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -61,7 +61,9 @@ "groups": [ { "group": "Welcome", - "pages": ["index"] + "pages": [ + "index" + ] } ] }, @@ -71,7 +73,11 @@ "groups": [ { "group": "Get Started", - "pages": ["en/introduction", "en/installation", "en/quickstart"] + "pages": [ + "en/introduction", + "en/installation", + "en/quickstart" + ] }, { "group": "Guides", @@ -79,17 +85,23 @@ { "group": "Strategy", "icon": "compass", - "pages": ["en/guides/concepts/evaluating-use-cases"] + "pages": [ + "en/guides/concepts/evaluating-use-cases" + ] }, { "group": "Agents", "icon": "user", - "pages": ["en/guides/agents/crafting-effective-agents"] + "pages": [ + "en/guides/agents/crafting-effective-agents" + ] }, { "group": "Crews", "icon": "users", - "pages": ["en/guides/crews/first-crew"] + "pages": [ + "en/guides/crews/first-crew" + ] }, { "group": "Flows", @@ -324,7 +336,9 @@ }, { "group": "Telemetry", - "pages": ["en/telemetry"] + "pages": [ + "en/telemetry" + ] } ] }, @@ -334,7 +348,9 @@ "groups": [ { "group": "Getting Started", - "pages": ["en/enterprise/introduction"] + "pages": [ + "en/enterprise/introduction" + ] }, { "group": "Build", @@ -343,7 +359,8 @@ "en/enterprise/features/crew-studio", "en/enterprise/features/marketplace", "en/enterprise/features/agent-repositories", - "en/enterprise/features/tools-and-integrations" + "en/enterprise/features/tools-and-integrations", + "en/enterprise/features/pii-trace-redactions" ] }, { @@ -426,7 +443,9 @@ }, { "group": "Resources", - "pages": ["en/enterprise/resources/frequently-asked-questions"] + "pages": [ + "en/enterprise/resources/frequently-asked-questions" + ] } ] }, @@ -452,7 +471,10 @@ "groups": [ { "group": "Examples", - "pages": ["en/examples/example", "en/examples/cookbooks"] + "pages": [ + "en/examples/example", + "en/examples/cookbooks" + ] } ] }, @@ -462,7 +484,9 @@ "groups": [ { "group": "Release Notes", - "pages": ["en/changelog"] + "pages": [ + "en/changelog" + ] } ] } @@ -501,7 +525,9 @@ "groups": [ { "group": "Bem-vindo", - "pages": ["pt-BR/index"] + "pages": [ + "pt-BR/index" + ] } ] }, @@ -523,17 +549,23 @@ { "group": "Estratégia", "icon": "compass", - "pages": ["pt-BR/guides/concepts/evaluating-use-cases"] + "pages": [ + "pt-BR/guides/concepts/evaluating-use-cases" + ] }, { "group": "Agentes", "icon": "user", - "pages": ["pt-BR/guides/agents/crafting-effective-agents"] + "pages": [ + "pt-BR/guides/agents/crafting-effective-agents" + ] }, { "group": "Crews", "icon": "users", - "pages": ["pt-BR/guides/crews/first-crew"] + "pages": [ + "pt-BR/guides/crews/first-crew" + ] }, { "group": "Flows", @@ -754,7 +786,9 @@ }, { "group": "Telemetria", - "pages": ["pt-BR/telemetry"] + "pages": [ + "pt-BR/telemetry" + ] } ] }, @@ -764,7 +798,9 @@ "groups": [ { "group": "Começando", - "pages": ["pt-BR/enterprise/introduction"] + "pages": [ + "pt-BR/enterprise/introduction" + ] }, { "group": "Construir", @@ -773,7 +809,8 @@ "pt-BR/enterprise/features/crew-studio", "pt-BR/enterprise/features/marketplace", "pt-BR/enterprise/features/agent-repositories", - "pt-BR/enterprise/features/tools-and-integrations" + "pt-BR/enterprise/features/tools-and-integrations", + "pt-BR/enterprise/features/pii-trace-redactions" ] }, { @@ -883,7 +920,10 @@ "groups": [ { "group": "Exemplos", - "pages": ["pt-BR/examples/example", "pt-BR/examples/cookbooks"] + "pages": [ + "pt-BR/examples/example", + "pt-BR/examples/cookbooks" + ] } ] }, @@ -893,7 +933,9 @@ "groups": [ { "group": "Notas de Versão", - "pages": ["pt-BR/changelog"] + "pages": [ + "pt-BR/changelog" + ] } ] } @@ -932,7 +974,9 @@ "groups": [ { "group": "환영합니다", - "pages": ["ko/index"] + "pages": [ + "ko/index" + ] } ] }, @@ -942,7 +986,11 @@ "groups": [ { "group": "시작 안내", - "pages": ["ko/introduction", "ko/installation", "ko/quickstart"] + "pages": [ + "ko/introduction", + "ko/installation", + "ko/quickstart" + ] }, { "group": "가이드", @@ -950,17 +998,23 @@ { "group": "전략", "icon": "compass", - "pages": ["ko/guides/concepts/evaluating-use-cases"] + "pages": [ + "ko/guides/concepts/evaluating-use-cases" + ] }, { "group": "에이전트 (Agents)", "icon": "user", - "pages": ["ko/guides/agents/crafting-effective-agents"] + "pages": [ + "ko/guides/agents/crafting-effective-agents" + ] }, { "group": "크루 (Crews)", "icon": "users", - "pages": ["ko/guides/crews/first-crew"] + "pages": [ + "ko/guides/crews/first-crew" + ] }, { "group": "플로우 (Flows)", @@ -1193,7 +1247,9 @@ }, { "group": "Telemetry", - "pages": ["ko/telemetry"] + "pages": [ + "ko/telemetry" + ] } ] }, @@ -1203,7 +1259,9 @@ "groups": [ { "group": "시작 안내", - "pages": ["ko/enterprise/introduction"] + "pages": [ + "ko/enterprise/introduction" + ] }, { "group": "빌드", @@ -1212,7 +1270,8 @@ "ko/enterprise/features/crew-studio", "ko/enterprise/features/marketplace", "ko/enterprise/features/agent-repositories", - "ko/enterprise/features/tools-and-integrations" + "ko/enterprise/features/tools-and-integrations", + "ko/enterprise/features/pii-trace-redactions" ] }, { @@ -1294,7 +1353,9 @@ }, { "group": "학습 자원", - "pages": ["ko/enterprise/resources/frequently-asked-questions"] + "pages": [ + "ko/enterprise/resources/frequently-asked-questions" + ] } ] }, @@ -1320,7 +1381,10 @@ "groups": [ { "group": "예시", - "pages": ["ko/examples/example", "ko/examples/cookbooks"] + "pages": [ + "ko/examples/example", + "ko/examples/cookbooks" + ] } ] }, @@ -1330,7 +1394,9 @@ "groups": [ { "group": "릴리스 노트", - "pages": ["ko/changelog"] + "pages": [ + "ko/changelog" + ] } ] } diff --git a/docs/en/enterprise/features/pii-trace-redactions.mdx b/docs/en/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..75b6073aa --- /dev/null +++ b/docs/en/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: PII Redaction for Traces +description: "Automatically redact sensitive data from crew and flow execution traces" +icon: "lock" +mode: "wide" +--- + +## Overview + +PII Redaction is a CrewAI AMP feature that automatically detects and masks Personally Identifiable Information (PII) in your crew and flow execution traces. This ensures sensitive data like credit card numbers, social security numbers, email addresses, and names are not exposed in your CrewAI AMP traces. You can also create custom recognizers to protect organization-specific data. + + + + PII Redaction is available on the Enterprise plan. + Deployment must be version 1.8.0 or higher. + + + + + ![PII Redaction Overview](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## Why PII Redaction Matters + +When running AI agents in production, sensitive information often flows through your crews: + +- Customer data from CRM integrations +- Financial information from payment processors +- Personal details from form submissions +- Internal employee data + +Without proper redaction, this data appears in traces, making compliance with regulations like GDPR, HIPAA, and PCI-DSS challenging. PII Redaction solves this by automatically masking sensitive data before it's stored in traces. + +## How It Works + +1. **Detect** - Scan trace event data for known PII patterns +2. **Classify** - Identify the type of sensitive data (credit card, SSN, email, etc.) +3. **Mask/Redact** - Replace the sensitive data with masked values based on your configuration + +``` +Original: "Contact john.doe@company.com or call 555-123-4567" +Redacted: "Contact or call " +``` + +## Enabling PII Redaction + + + You must be on the Enterprise plan and your deployment must be version 1.8.0 or higher to use this feature. + + + + + In the CrewAI AMP dashboard, select your deployed crew and go to one of your deployments/automations, then navigate to **Settings** → **PII Protection**. + + + + Toggle on **PII Redaction for Traces**. This will enable automatic scanning and redaction of trace data. + + + You need to manually enable PII Redaction for each deployment. + + + + ![Enable PII Redaction](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + Select which types of PII to detect and redact. Each entity can be individually enabled or disabled. + + + ![Configure Entities](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + Save your configuration. PII redaction will be active on all subsequent crew executions, no redeployment is needed. + + + +## Supported Entity Types + +CrewAI supports the following PII entity types, organized by category. + +### Global Entities + +| Entity | Description | Example | +|--------|-------------|---------| +| `CREDIT_CARD` | Credit/debit card numbers | "4111-1111-1111-1111" | +| `CRYPTO` | Cryptocurrency wallet addresses | "bc1qxy2kgd..." | +| `DATE_TIME` | Dates and times | "January 15, 2024" | +| `EMAIL_ADDRESS` | Email addresses | "john@example.com" | +| `IBAN_CODE` | International bank account numbers | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | IPv4 and IPv6 addresses | "192.168.1.1" | +| `LOCATION` | Geographic locations | "New York City" | +| `MEDICAL_LICENSE` | Medical license numbers | "MD12345" | +| `NRP` | Nationalities, religious, or political groups | - | +| `PERSON` | Personal names | "John Doe" | +| `PHONE_NUMBER` | Phone numbers in various formats | "+1 (555) 123-4567" | +| `URL` | Web URLs | "https://example.com" | + +### US-Specific Entities + +| Entity | Description | Example | +|--------|-------------|---------| +| `US_BANK_NUMBER` | US Bank account numbers | "1234567890" | +| `US_DRIVER_LICENSE` | US Driver's license numbers | "D1234567" | +| `US_ITIN` | Individual Taxpayer ID | "900-70-0000" | +| `US_PASSPORT` | US Passport numbers | "123456789" | +| `US_SSN` | Social Security Numbers | "123-45-6789" | + +## Redaction Actions + +For each enabled entity, you can configure how the data is redacted: + +| Action | Description | Example Output | +|--------|-------------|----------------| +| `mask` | Replace with the entity type label | `` | +| `redact` | Completely remove the text | *(empty)* | + +## Custom Recognizers + +In addition to built-in entities, you can create **custom recognizers** to detect organization-specific PII patterns. + + + ![Custom Recognizers](/images/enterprise/pii_mask_recognizer.png) + + +### Recognizer Types + +You have two options for custom recognizers: + +| Type | Best For | Example Use Case | +|------|----------|------------------| +| **Pattern-based (Regex)** | Structured data with predictable formats | Salary amounts, employee IDs, project codes | +| **Deny-list** | Exact string matches | Company names, internal codenames, specific terms | + +### Creating a Custom Recognizer + + + + Go to your Organization **Settings** → **Organization** → **Add Recognizer**. + + + + + ![Configure Recognizer](/images/enterprise/pii_mask_recognizer_create.png) + + + Configure the following fields: + - **Name**: A descriptive name for the recognizer + - **Entity Type**: The entity label that will appear in redacted output (e.g., `EMPLOYEE_ID`, `SALARY`) + - **Type**: Choose between Regex Pattern or Deny List + - **Pattern/Values**: Regex pattern or list of strings to match + - **Confidence Threshold**: Minimum score (0.0-1.0) required for a match to trigger redaction. Higher values (e.g., 0.8) reduce false positives but may miss some matches. Lower values (e.g., 0.5) catch more matches but may over-redact. Default is 0.8. + - **Context Words** (optional): Words that increase detection confidence when found nearby + + + + Save the recognizer. It will be available to enable on your deployments. + + + +### Understanding Entity Types + +The **Entity Type** determines how matched content appears in redacted traces: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +Input: "Employee salary: $50,000" +Output: "Employee " +``` + +### Using Context Words + +Context words improve accuracy by increasing confidence when specific terms appear near the matched pattern: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +When "project" or "code" appears near "PRJ-1234", the recognizer has higher confidence it's a true match, reducing false positives. + + +## Viewing Redacted Traces + +Once PII redaction is enabled, your traces will show redacted values in place of sensitive data: + +``` +Task Output: "Customer placed order #12345. +Contact email: , phone: . +Payment processed for card ending in ." +``` + +Redacted values are clearly marked with angle brackets and the entity type label (e.g., ``), making it easy to understand what data was protected while still allowing you to debug and monitor crew behavior. + + + +## Best Practices + +### Performance Considerations + + + + Each enabled entity adds processing overhead. Only enable entities relevant to your data. + + + + For custom recognizers, use specific patterns to reduce false positives and improve performance. Regex patterns are best when identifying specific patterns in the traces such as salary, employee id, project code, etc. Deny-list recognizers are best when identifying exact strings in the traces such as company names, internal codenames, etc. + + + + Context words improve accuracy by only triggering detection when surrounding text matches. + + + +## Troubleshooting + + + **Possible Causes:** + - Entity type not enabled in configuration + - Pattern doesn't match the data format + - Custom recognizer has syntax errors + + **Solutions:** + - Verify entity is enabled in Settings → Security + - Test regex patterns with sample data + - Check logs for configuration errors + + + + **Possible Causes:** + - Overly broad entity types enabled (e.g., `DATE_TIME` catches dates everywhere) + - Custom recognizer patterns are too general + + **Solutions:** + - Disable entities that cause false positives + - Make custom patterns more specific + - Add context words to improve accuracy + + + + **Possible Causes:** + - Too many entities enabled + - NLP-based entities (`PERSON`, `LOCATION`, `NRP`) are computationally expensive as they use machine learning models + + **Solutions:** + - Only enable entities you actually need + - Consider using pattern-based alternatives where possible + - Monitor trace processing times in the dashboard + + +--- + +## Practical Example: Salary Pattern Matching + +This example demonstrates how to create a custom recognizer to detect and mask salary information in your traces. + +### Use Case + +Your crew processes employee or financial data that includes salary information in formats like: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +You want to automatically mask these values to protect sensitive compensation data. + +### Configuration + + + ![Salary Recognizer Configuration](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| Field | Value | +|-------|-------| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### Regex Pattern Breakdown + +| Pattern Component | Meaning | +|-------------------|---------| +| `salary:` | Matches the literal text "salary:" | +| `\s*` | Matches zero or more whitespace characters | +| `\$` | Matches the dollar sign (escaped) | +| `\s*` | Matches zero or more whitespace characters after $ | +| `\d{1,3}` | Matches 1-3 digits (e.g., "1", "50", "125") | +| `(,\d{3})*` | Matches comma-separated thousands (e.g., ",000", ",500,000") | +| `(\.\d{2})?` | Optionally matches cents (e.g., ".00", ".50") | + +### Example Results + +``` +Original: "Employee record shows salary: $125,000.00 annually" +Redacted: "Employee record shows annually" + +Original: "Base salary:$50,000 with bonus potential" +Redacted: "Base with bonus potential" +``` + + + Adding context words like "salary", "compensation", "pay", "wage", and "income" helps increase detection confidence when these terms appear near the matched pattern, reducing false positives. + + +### Enable the Recognizer for Your Deployments + + + Creating a custom recognizer at the organization level does not automatically enable it for your deployments. You must manually enable each recognizer for every deployment where you want it applied. + + +After creating your custom recognizer, enable it for each deployment: + + + + Go to your deployment/automation and open **Settings** → **PII Protection**. + + + + Under **Mask Recognizers**, you'll see your organization-defined recognizers. Check the box next to the recognizers you want to enable. + + + ![Enable Custom Recognizer](/images/enterprise/pii_mask_recognizers_options.png) + + + + + Save your changes. The recognizer will be active on all subsequent executions for this deployment. + + + + + Repeat this process for each deployment where you need the custom recognizer. This gives you granular control over which recognizers are active in different environments (e.g., development vs. production). + diff --git a/docs/images/enterprise/pii_mask_custom_recognizer_salary.png b/docs/images/enterprise/pii_mask_custom_recognizer_salary.png new file mode 100644 index 000000000..ca23dc2ae Binary files /dev/null and b/docs/images/enterprise/pii_mask_custom_recognizer_salary.png differ diff --git a/docs/images/enterprise/pii_mask_recognizer.png b/docs/images/enterprise/pii_mask_recognizer.png new file mode 100644 index 000000000..e225a5a11 Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizer.png differ diff --git a/docs/images/enterprise/pii_mask_recognizer_create.png b/docs/images/enterprise/pii_mask_recognizer_create.png new file mode 100644 index 000000000..4b9e9e957 Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizer_create.png differ diff --git a/docs/images/enterprise/pii_mask_recognizer_deployment_tab.png b/docs/images/enterprise/pii_mask_recognizer_deployment_tab.png new file mode 100644 index 000000000..0fd4ecbdf Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizer_deployment_tab.png differ diff --git a/docs/images/enterprise/pii_mask_recognizer_enable.png b/docs/images/enterprise/pii_mask_recognizer_enable.png new file mode 100644 index 000000000..ae869520a Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizer_enable.png differ diff --git a/docs/images/enterprise/pii_mask_recognizer_supported_entities.png b/docs/images/enterprise/pii_mask_recognizer_supported_entities.png new file mode 100644 index 000000000..9ac11a541 Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizer_supported_entities.png differ diff --git a/docs/images/enterprise/pii_mask_recognizer_trace_example.png b/docs/images/enterprise/pii_mask_recognizer_trace_example.png new file mode 100644 index 000000000..f348907aa Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizer_trace_example.png differ diff --git a/docs/images/enterprise/pii_mask_recognizers_options.png b/docs/images/enterprise/pii_mask_recognizers_options.png new file mode 100644 index 000000000..ebf3ebf67 Binary files /dev/null and b/docs/images/enterprise/pii_mask_recognizers_options.png differ diff --git a/docs/ko/enterprise/features/pii-trace-redactions.mdx b/docs/ko/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..a29c8f2b1 --- /dev/null +++ b/docs/ko/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: 트레이스용 PII 삭제 +description: "크루 및 플로우 실행 트레이스에서 민감한 데이터를 자동으로 삭제합니다" +icon: "lock" +mode: "wide" +--- + +## 개요 + +PII 삭제는 크루 및 플로우 실행 트레이스에서 개인 식별 정보(PII)를 자동으로 감지하고 마스킹하는 CrewAI AMP 기능입니다. 이를 통해 신용카드 번호, 주민등록번호, 이메일 주소, 이름과 같은 민감한 데이터가 CrewAI AMP 트레이스에 노출되지 않도록 보장합니다. 또한 조직별 데이터를 보호하기 위해 커스텀 인식기를 생성할 수 있습니다. + + + + PII 삭제는 Enterprise 플랜에서 사용 가능합니다. + 배포 버전은 1.8.0 이상이어야 합니다. + + + + + ![PII 삭제 개요](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## PII 삭제가 중요한 이유 + +프로덕션 환경에서 AI 에이전트를 실행할 때, 민감한 정보가 종종 크루를 통해 흐릅니다: + +- CRM 통합의 고객 데이터 +- 결제 처리업체의 금융 정보 +- 양식 제출의 개인 정보 +- 내부 직원 데이터 + +적절한 삭제 없이는 이 데이터가 트레이스에 나타나, GDPR, HIPAA, PCI-DSS와 같은 규정 준수가 어려워집니다. PII 삭제는 트레이스에 저장되기 전에 민감한 데이터를 자동으로 마스킹하여 이 문제를 해결합니다. + +## 작동 방식 + +1. **감지** - 알려진 PII 패턴에 대해 트레이스 이벤트 데이터를 스캔 +2. **분류** - 민감한 데이터 유형 식별 (신용카드, SSN, 이메일 등) +3. **마스킹/삭제** - 구성에 따라 민감한 데이터를 마스킹된 값으로 대체 + +``` +원본: "john.doe@company.com으로 연락하거나 555-123-4567로 전화하세요" +삭제됨: "로 연락하거나 로 전화하세요" +``` + +## PII 삭제 활성화 + + + 이 기능을 사용하려면 Enterprise 플랜이어야 하며 배포 버전이 1.8.0 이상이어야 합니다. + + + + + CrewAI AMP 대시보드에서 배포된 크루를 선택하고 배포/자동화 중 하나로 이동한 다음 **Settings** → **PII Protection**으로 이동합니다. + + + + **PII Redaction for Traces**를 토글하여 활성화합니다. 이렇게 하면 트레이스 데이터의 자동 스캔 및 삭제가 활성화됩니다. + + + 각 배포에 대해 PII 삭제를 수동으로 활성화해야 합니다. + + + + ![PII 삭제 활성화](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + 감지하고 삭제할 PII 유형을 선택합니다. 각 엔티티는 개별적으로 활성화하거나 비활성화할 수 있습니다. + + + ![엔티티 구성](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + 구성을 저장합니다. PII 삭제는 이후 모든 크루 실행에서 활성화되며, 재배포가 필요하지 않습니다. + + + +## 지원되는 엔티티 유형 + +CrewAI는 카테고리별로 구성된 다음 PII 엔티티 유형을 지원합니다. + +### 글로벌 엔티티 + +| 엔티티 | 설명 | 예시 | +|--------|------|------| +| `CREDIT_CARD` | 신용/직불 카드 번호 | "4111-1111-1111-1111" | +| `CRYPTO` | 암호화폐 지갑 주소 | "bc1qxy2kgd..." | +| `DATE_TIME` | 날짜 및 시간 | "2024년 1월 15일" | +| `EMAIL_ADDRESS` | 이메일 주소 | "john@example.com" | +| `IBAN_CODE` | 국제 은행 계좌 번호 | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | IPv4 및 IPv6 주소 | "192.168.1.1" | +| `LOCATION` | 지리적 위치 | "뉴욕시" | +| `MEDICAL_LICENSE` | 의료 면허 번호 | "MD12345" | +| `NRP` | 국적, 종교 또는 정치 그룹 | - | +| `PERSON` | 개인 이름 | "홍길동" | +| `PHONE_NUMBER` | 다양한 형식의 전화번호 | "+82 (10) 1234-5678" | +| `URL` | 웹 URL | "https://example.com" | + +### 미국 특정 엔티티 + +| 엔티티 | 설명 | 예시 | +|--------|------|------| +| `US_BANK_NUMBER` | 미국 은행 계좌 번호 | "1234567890" | +| `US_DRIVER_LICENSE` | 미국 운전면허 번호 | "D1234567" | +| `US_ITIN` | 개인 납세자 번호 | "900-70-0000" | +| `US_PASSPORT` | 미국 여권 번호 | "123456789" | +| `US_SSN` | 사회보장번호 | "123-45-6789" | + +## 삭제 작업 + +활성화된 각 엔티티에 대해 데이터가 삭제되는 방식을 구성할 수 있습니다: + +| 작업 | 설명 | 출력 예시 | +|------|------|----------| +| `mask` | 엔티티 유형 레이블로 대체 | `` | +| `redact` | 텍스트를 완전히 제거 | *(비어있음)* | + +## 커스텀 인식기 + +기본 제공 엔티티 외에도 조직별 PII 패턴을 감지하기 위한 **커스텀 인식기**를 생성할 수 있습니다. + + + ![커스텀 인식기](/images/enterprise/pii_mask_recognizer.png) + + +### 인식기 유형 + +커스텀 인식기에는 두 가지 옵션이 있습니다: + +| 유형 | 적합한 용도 | 사용 사례 예시 | +|------|------------|---------------| +| **패턴 기반 (Regex)** | 예측 가능한 형식의 구조화된 데이터 | 급여 금액, 직원 ID, 프로젝트 코드 | +| **거부 목록** | 정확한 문자열 매칭 | 회사명, 내부 코드명, 특정 용어 | + +### 커스텀 인식기 생성 + + + + 조직 **Settings** → **Organization** → **Add Recognizer**로 이동합니다. + + + + + ![인식기 구성](/images/enterprise/pii_mask_recognizer_create.png) + + + 다음 필드를 구성합니다: + - **Name**: 인식기의 설명적 이름 + - **Entity Type**: 삭제된 출력에 나타날 엔티티 레이블 (예: `EMPLOYEE_ID`, `SALARY`) + - **Type**: Regex 패턴 또는 거부 목록 중 선택 + - **Pattern/Values**: 매칭할 Regex 패턴 또는 문자열 목록 + - **Confidence Threshold**: 삭제를 트리거하는 데 필요한 최소 점수 (0.0-1.0). 높은 값 (예: 0.8)은 거짓 양성을 줄이지만 일부 매치를 놓칠 수 있습니다. 낮은 값 (예: 0.5)은 더 많은 매치를 잡지만 과도하게 삭제할 수 있습니다. 기본값은 0.8입니다. + - **Context Words** (선택사항): 근처에서 발견될 때 감지 신뢰도를 높이는 단어 + + + + 인식기를 저장합니다. 배포에서 활성화할 수 있게 됩니다. + + + +### 엔티티 유형 이해하기 + +**Entity Type**은 매칭된 콘텐츠가 삭제된 트레이스에 어떻게 나타나는지 결정합니다: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +입력: "직원 급여: $50,000" +출력: "직원 " +``` + +### 컨텍스트 단어 사용 + +컨텍스트 단어는 매칭된 패턴 근처에 특정 용어가 나타날 때 신뢰도를 높여 정확도를 향상시킵니다: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +"project" 또는 "code"가 "PRJ-1234" 근처에 나타나면, 인식기는 그것이 진정한 매치라는 확신이 높아져 거짓 양성을 줄입니다. + + +## 삭제된 트레이스 보기 + +PII 삭제가 활성화되면, 트레이스에서 민감한 데이터 대신 삭제된 값이 표시됩니다: + +``` +Task Output: "고객 이 주문 #12345를 했습니다. +연락처 이메일: , 전화: . +로 끝나는 카드로 결제가 처리되었습니다." +``` + +삭제된 값은 꺾쇠 괄호와 엔티티 유형 레이블 (예: ``)로 명확하게 표시되어, 어떤 데이터가 보호되었는지 쉽게 이해할 수 있으면서도 크루 동작을 디버그하고 모니터링할 수 있습니다. + + + +## 모범 사례 + +### 성능 고려사항 + + + + 활성화된 각 엔티티는 처리 오버헤드를 추가합니다. 데이터와 관련된 엔티티만 활성화하세요. + + + + 커스텀 인식기의 경우 거짓 양성을 줄이고 성능을 향상시키기 위해 구체적인 패턴을 사용하세요. Regex 패턴은 급여, 직원 ID, 프로젝트 코드 등 특정 패턴을 식별할 때 가장 적합합니다. 거부 목록 인식기는 회사명, 내부 코드명 등 정확한 문자열을 식별할 때 가장 적합합니다. + + + + 컨텍스트 단어는 주변 텍스트가 매칭될 때만 감지를 트리거하여 정확도를 향상시킵니다. + + + +## 문제 해결 + + + **가능한 원인:** + - 구성에서 엔티티 유형이 활성화되지 않음 + - 패턴이 데이터 형식과 매치되지 않음 + - 커스텀 인식기에 구문 오류가 있음 + + **해결책:** + - Settings → Security에서 엔티티가 활성화되어 있는지 확인 + - 샘플 데이터로 regex 패턴 테스트 + - 구성 오류에 대한 로그 확인 + + + + **가능한 원인:** + - 너무 광범위한 엔티티 유형이 활성화됨 (예: `DATE_TIME`이 모든 곳의 날짜를 잡음) + - 커스텀 인식기 패턴이 너무 일반적임 + + **해결책:** + - 거짓 양성을 유발하는 엔티티 비활성화 + - 커스텀 패턴을 더 구체적으로 만들기 + - 정확도 향상을 위해 컨텍스트 단어 추가 + + + + **가능한 원인:** + - 너무 많은 엔티티가 활성화됨 + - NLP 기반 엔티티 (`PERSON`, `LOCATION`, `NRP`)는 머신러닝 모델을 사용하므로 계산 비용이 높음 + + **해결책:** + - 실제로 필요한 엔티티만 활성화 + - 가능한 경우 패턴 기반 대안 고려 + - 대시보드에서 트레이스 처리 시간 모니터링 + + +--- + +## 실제 예시: 급여 패턴 매칭 + +이 예시는 트레이스에서 급여 정보를 감지하고 마스킹하는 커스텀 인식기를 생성하는 방법을 보여줍니다. + +### 사용 사례 + +크루가 다음과 같은 형식의 급여 정보가 포함된 직원 또는 재무 데이터를 처리합니다: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +민감한 보상 데이터를 보호하기 위해 이러한 값을 자동으로 마스킹하려고 합니다. + +### 구성 + + + ![급여 인식기 구성](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| 필드 | 값 | +|------|-----| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### Regex 패턴 분석 + +| 패턴 구성요소 | 의미 | +|--------------|------| +| `salary:` | 리터럴 텍스트 "salary:" 매치 | +| `\s*` | 0개 이상의 공백 문자 매치 | +| `\$` | 달러 기호 매치 (이스케이프) | +| `\s*` | $ 뒤의 0개 이상의 공백 문자 매치 | +| `\d{1,3}` | 1-3자리 숫자 매치 (예: "1", "50", "125") | +| `(,\d{3})*` | 쉼표로 구분된 천 단위 매치 (예: ",000", ",500,000") | +| `(\.\d{2})?` | 선택적으로 센트 매치 (예: ".00", ".50") | + +### 결과 예시 + +``` +원본: "직원 기록에 salary: $125,000.00 연봉이 표시됩니다" +삭제됨: "직원 기록에 연봉이 표시됩니다" + +원본: "기본 salary:$50,000에 보너스 가능성" +삭제됨: "기본 에 보너스 가능성" +``` + + + "salary", "compensation", "pay", "wage", "income"과 같은 컨텍스트 단어를 추가하면 이러한 용어가 매칭된 패턴 근처에 나타날 때 감지 신뢰도가 높아져 거짓 양성을 줄입니다. + + +### 배포에서 인식기 활성화 + + + 조직 수준에서 커스텀 인식기를 생성해도 배포에 자동으로 활성화되지 않습니다. 적용하려는 모든 배포에 대해 각 인식기를 수동으로 활성화해야 합니다. + + +커스텀 인식기를 생성한 후, 각 배포에서 활성화합니다: + + + + 배포/자동화로 이동하여 **Settings** → **PII Protection**을 엽니다. + + + + **Mask Recognizers** 아래에서 조직에서 정의한 인식기를 볼 수 있습니다. 활성화하려는 인식기 옆의 체크박스를 선택합니다. + + + ![커스텀 인식기 활성화](/images/enterprise/pii_mask_recognizers_options.png) + + + + + 변경 사항을 저장합니다. 인식기는 이 배포의 모든 후속 실행에서 활성화됩니다. + + + + + 커스텀 인식기가 필요한 각 배포에서 이 프로세스를 반복합니다. 이를 통해 다양한 환경 (예: 개발 vs. 프로덕션)에서 어떤 인식기가 활성화되는지 세밀하게 제어할 수 있습니다. + diff --git a/docs/pt-BR/enterprise/features/pii-trace-redactions.mdx b/docs/pt-BR/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..d52cc7b9f --- /dev/null +++ b/docs/pt-BR/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: Redação de PII para Traces +description: "Redija automaticamente dados sensíveis de traces de execução de crews e flows" +icon: "lock" +mode: "wide" +--- + +## Visão Geral + +A Redação de PII é um recurso do CrewAI AMP que detecta e mascara automaticamente Informações de Identificação Pessoal (PII) nos traces de execução de crews e flows. Isso garante que dados sensíveis como números de cartão de crédito, CPF, endereços de e-mail e nomes não sejam expostos nos traces do CrewAI AMP. Você também pode criar reconhecedores personalizados para proteger dados específicos da sua organização. + + + + A Redação de PII está disponível no plano Enterprise. + A implantação deve ser versão 1.8.0 ou superior. + + + + + ![Visão Geral da Redação de PII](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## Por Que a Redação de PII é Importante + +Ao executar agentes de IA em produção, informações sensíveis frequentemente fluem através das suas crews: + +- Dados de clientes de integrações CRM +- Informações financeiras de processadores de pagamento +- Detalhes pessoais de envios de formulários +- Dados internos de funcionários + +Sem a redação adequada, esses dados aparecem nos traces, tornando a conformidade com regulamentações como LGPD, HIPAA e PCI-DSS desafiadora. A Redação de PII resolve isso mascarando automaticamente dados sensíveis antes de serem armazenados nos traces. + +## Como Funciona + +1. **Detectar** - Escanear dados de eventos de trace para padrões de PII conhecidos +2. **Classificar** - Identificar o tipo de dado sensível (cartão de crédito, CPF, e-mail, etc.) +3. **Mascarar/Redigir** - Substituir os dados sensíveis por valores mascarados com base na sua configuração + +``` +Original: "Entre em contato com john.doe@company.com ou ligue para 555-123-4567" +Redigido: "Entre em contato com ou ligue para " +``` + +## Habilitando a Redação de PII + + + Você deve estar no plano Enterprise e sua implantação deve ser versão 1.8.0 ou superior para usar este recurso. + + + + + No painel do CrewAI AMP, selecione sua crew implantada e vá para uma de suas implantações/automações, depois navegue até **Settings** → **PII Protection**. + + + + Ative **PII Redaction for Traces**. Isso habilitará a varredura automática e redação de dados de trace. + + + Você precisa habilitar manualmente a Redação de PII para cada implantação. + + + + ![Habilitar Redação de PII](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + Selecione quais tipos de PII detectar e redigir. Cada entidade pode ser habilitada ou desabilitada individualmente. + + + ![Configurar Entidades](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + Salve sua configuração. A redação de PII estará ativa em todas as execuções subsequentes da crew, sem necessidade de reimplantação. + + + +## Tipos de Entidade Suportados + +O CrewAI suporta os seguintes tipos de entidade PII, organizados por categoria. + +### Entidades Globais + +| Entidade | Descrição | Exemplo | +|----------|-----------|---------| +| `CREDIT_CARD` | Números de cartão de crédito/débito | "4111-1111-1111-1111" | +| `CRYPTO` | Endereços de carteira de criptomoedas | "bc1qxy2kgd..." | +| `DATE_TIME` | Datas e horários | "15 de janeiro de 2024" | +| `EMAIL_ADDRESS` | Endereços de e-mail | "john@example.com" | +| `IBAN_CODE` | Números de conta bancária internacional | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | Endereços IPv4 e IPv6 | "192.168.1.1" | +| `LOCATION` | Localizações geográficas | "São Paulo" | +| `MEDICAL_LICENSE` | Números de licença médica | "CRM12345" | +| `NRP` | Nacionalidades, grupos religiosos ou políticos | - | +| `PERSON` | Nomes pessoais | "João Silva" | +| `PHONE_NUMBER` | Números de telefone em vários formatos | "+55 (11) 98765-4321" | +| `URL` | URLs da web | "https://example.com" | + +### Entidades Específicas dos EUA + +| Entidade | Descrição | Exemplo | +|----------|-----------|---------| +| `US_BANK_NUMBER` | Números de conta bancária dos EUA | "1234567890" | +| `US_DRIVER_LICENSE` | Números de carteira de motorista dos EUA | "D1234567" | +| `US_ITIN` | Número de Identificação de Contribuinte Individual | "900-70-0000" | +| `US_PASSPORT` | Números de passaporte dos EUA | "123456789" | +| `US_SSN` | Números de Seguro Social | "123-45-6789" | + +## Ações de Redação + +Para cada entidade habilitada, você pode configurar como os dados são redigidos: + +| Ação | Descrição | Exemplo de Saída | +|------|-----------|------------------| +| `mask` | Substituir pelo rótulo do tipo de entidade | `` | +| `redact` | Remover completamente o texto | *(vazio)* | + +## Reconhecedores Personalizados + +Além das entidades integradas, você pode criar **reconhecedores personalizados** para detectar padrões de PII específicos da sua organização. + + + ![Reconhecedores Personalizados](/images/enterprise/pii_mask_recognizer.png) + + +### Tipos de Reconhecedores + +Você tem duas opções para reconhecedores personalizados: + +| Tipo | Melhor Para | Exemplo de Caso de Uso | +|------|-------------|------------------------| +| **Baseado em Padrão (Regex)** | Dados estruturados com formatos previsíveis | Valores de salário, IDs de funcionários, códigos de projeto | +| **Lista de Negação** | Correspondências exatas de strings | Nomes de empresas, codinomes internos, termos específicos | + +### Criando um Reconhecedor Personalizado + + + + Vá para **Settings** da Organização → **Organization** → **Add Recognizer**. + + + + + ![Configurar Reconhecedor](/images/enterprise/pii_mask_recognizer_create.png) + + + Configure os seguintes campos: + - **Name**: Um nome descritivo para o reconhecedor + - **Entity Type**: O rótulo da entidade que aparecerá na saída redigida (ex.: `EMPLOYEE_ID`, `SALARY`) + - **Type**: Escolha entre Padrão Regex ou Lista de Negação + - **Pattern/Values**: Padrão regex ou lista de strings para corresponder + - **Confidence Threshold**: Pontuação mínima (0.0-1.0) necessária para uma correspondência acionar a redação. Valores mais altos (ex.: 0.8) reduzem falsos positivos, mas podem perder algumas correspondências. Valores mais baixos (ex.: 0.5) capturam mais correspondências, mas podem redigir em excesso. O padrão é 0.8. + - **Context Words** (opcional): Palavras que aumentam a confiança de detecção quando encontradas próximas + + + + Salve o reconhecedor. Ele estará disponível para habilitar em suas implantações. + + + +### Entendendo os Tipos de Entidade + +O **Entity Type** determina como o conteúdo correspondido aparece nos traces redigidos: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +Entrada: "Salário do funcionário: $50,000" +Saída: "Salário do funcionário " +``` + +### Usando Palavras de Contexto + +Palavras de contexto melhoram a precisão aumentando a confiança quando termos específicos aparecem próximos ao padrão correspondido: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +Quando "project" ou "code" aparece próximo a "PRJ-1234", o reconhecedor tem maior confiança de que é uma correspondência verdadeira, reduzindo falsos positivos. + + +## Visualizando Traces Redigidos + +Uma vez que a redação de PII está habilitada, seus traces mostrarão valores redigidos no lugar de dados sensíveis: + +``` +Task Output: "Cliente fez o pedido #12345. +E-mail de contato: , telefone: . +Pagamento processado para cartão terminando em ." +``` + +Os valores redigidos são claramente marcados com colchetes angulares e o rótulo do tipo de entidade (ex.: ``), facilitando entender quais dados foram protegidos enquanto ainda permite depurar e monitorar o comportamento da crew. + + + +## Melhores Práticas + +### Considerações de Desempenho + + + + Cada entidade habilitada adiciona sobrecarga de processamento. Habilite apenas entidades relevantes para seus dados. + + + + Para reconhecedores personalizados, use padrões específicos para reduzir falsos positivos e melhorar o desempenho. Padrões regex são melhores para identificar padrões específicos nos traces como salário, ID de funcionário, código de projeto, etc. Reconhecedores de lista de negação são melhores para identificar strings exatas nos traces como nomes de empresas, codinomes internos, etc. + + + + Palavras de contexto melhoram a precisão acionando a detecção apenas quando o texto circundante corresponde. + + + +## Solução de Problemas + + + **Possíveis Causas:** + - Tipo de entidade não habilitado na configuração + - Padrão não corresponde ao formato dos dados + - Reconhecedor personalizado tem erros de sintaxe + + **Soluções:** + - Verifique se a entidade está habilitada em Settings → Security + - Teste padrões regex com dados de amostra + - Verifique logs para erros de configuração + + + + **Possíveis Causas:** + - Tipos de entidade muito amplos habilitados (ex.: `DATE_TIME` captura datas em todos os lugares) + - Padrões de reconhecedor personalizado são muito gerais + + **Soluções:** + - Desabilite entidades que causam falsos positivos + - Torne padrões personalizados mais específicos + - Adicione palavras de contexto para melhorar a precisão + + + + **Possíveis Causas:** + - Muitas entidades habilitadas + - Entidades baseadas em NLP (`PERSON`, `LOCATION`, `NRP`) são computacionalmente caras pois usam modelos de machine learning + + **Soluções:** + - Habilite apenas entidades que você realmente precisa + - Considere usar alternativas baseadas em padrão quando possível + - Monitore tempos de processamento de trace no painel + + +--- + +## Exemplo Prático: Correspondência de Padrão de Salário + +Este exemplo demonstra como criar um reconhecedor personalizado para detectar e mascarar informações de salário em seus traces. + +### Caso de Uso + +Sua crew processa dados de funcionários ou financeiros que incluem informações de salário em formatos como: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +Você deseja mascarar automaticamente esses valores para proteger dados sensíveis de remuneração. + +### Configuração + + + ![Configuração do Reconhecedor de Salário](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| Campo | Valor | +|-------|-------| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### Análise do Padrão Regex + +| Componente do Padrão | Significado | +|----------------------|-------------| +| `salary:` | Corresponde ao texto literal "salary:" | +| `\s*` | Corresponde a zero ou mais caracteres de espaço em branco | +| `\$` | Corresponde ao sinal de dólar (escapado) | +| `\s*` | Corresponde a zero ou mais caracteres de espaço em branco após $ | +| `\d{1,3}` | Corresponde a 1-3 dígitos (ex.: "1", "50", "125") | +| `(,\d{3})*` | Corresponde a milhares separados por vírgula (ex.: ",000", ",500,000") | +| `(\.\d{2})?` | Opcionalmente corresponde a centavos (ex.: ".00", ".50") | + +### Resultados de Exemplo + +``` +Original: "Registro do funcionário mostra salary: $125,000.00 anualmente" +Redigido: "Registro do funcionário mostra anualmente" + +Original: "Salário base salary:$50,000 com potencial de bônus" +Redigido: "Salário base com potencial de bônus" +``` + + + Adicionar palavras de contexto como "salary", "compensation", "pay", "wage" e "income" ajuda a aumentar a confiança de detecção quando esses termos aparecem próximos ao padrão correspondido, reduzindo falsos positivos. + + +### Habilite o Reconhecedor para Suas Implantações + + + Criar um reconhecedor personalizado no nível da organização não o habilita automaticamente para suas implantações. Você deve habilitar manualmente cada reconhecedor para cada implantação onde deseja aplicá-lo. + + +Após criar seu reconhecedor personalizado, habilite-o para cada implantação: + + + + Vá para sua implantação/automação e abra **Settings** → **PII Protection**. + + + + Em **Mask Recognizers**, você verá os reconhecedores definidos pela sua organização. Marque a caixa ao lado dos reconhecedores que deseja habilitar. + + + ![Habilitar Reconhecedor Personalizado](/images/enterprise/pii_mask_recognizers_options.png) + + + + + Salve suas alterações. O reconhecedor estará ativo em todas as execuções subsequentes para esta implantação. + + + + + Repita este processo para cada implantação onde você precisa do reconhecedor personalizado. Isso oferece controle granular sobre quais reconhecedores estão ativos em diferentes ambientes (ex.: desenvolvimento vs. produção). +