# Security Guide

This guide explains how to use the SDK's Security module to implement content moderation, prompt shielding, and PII (Personally Identifiable Information) detection for agent inputs and outputs.

## Overview

The Security module provides content safety check functionality supporting 3 cloud providers.

| Provider  | Content Moderation      | Prompt Shield      | PII Detection                                   |
| --------- | ----------------------- | ------------------ | ----------------------------------------------- |
| **Azure** | Azure AI Content Safety | Prompt Shield API  | PII Detection API                               |
| **AWS**   | Bedrock Guardrails      | Bedrock Guardrails | Bedrock Guardrails (sensitiveInformationPolicy) |
| **GCP**   | Model Armor             | Model Armor        | Cloud DLP                                       |

> **info**
>
> **About PII Detection on AWS**: PII detection uses the Bedrock Guardrails `sensitiveInformationPolicy` and supports multiple languages (including Japanese). Content Safety and PII detection share the same Guardrail and are evaluated together in a single `apply_guardrail` API call.

```text
User Input
     |
     v
+------------------------+
| SecurityClientBase     |  <- Execute all at once with check_security()
+--------+---------------+
         |
    +----+----+
    v         v
Content    PII
Moderation Detection
    |         |
    +----+----+
         |
  allowed / blocked decision
         |
         v
  Agent processing or block
```

## Provider Configuration

**Azure**

```toml
[security]
provider = "azure"
content_safety_endpoint = "https://your-content-safety.cognitiveservices.azure.com/"
content_safety_api_key = "${AZURE_CONTENT_SAFETY_KEY}"
language_endpoint = "https://your-language.cognitiveservices.azure.com/"
language_api_key = "${AZURE_LANGUAGE_KEY}"
moderation_threshold = 2
pii_confidence_threshold = 0.7
```

```python
from agenticstar_platform.security import AzureSecurityClient, AzureSecurityConfig

config = AzureSecurityConfig(
    content_safety_endpoint="https://your-content-safety.cognitiveservices.azure.com/",
    content_safety_api_key="your-api-key",
    language_endpoint="https://your-language.cognitiveservices.azure.com/",
    language_api_key="your-language-key",
)
client = AzureSecurityClient(config)
```

**AWS**

```toml
[security]
provider = "aws"
region_name = "us-east-1"
guardrail_id = "your-guardrail-id"
guardrail_version = "DRAFT"
# PII detection backend (default: "bedrock_guardrails")
#   "bedrock_guardrails": Bedrock Guardrails sensitiveInformationPolicy
#     (multi-language support including Japanese; shares guardrail_id/version)
#   "comprehend": Amazon Comprehend DetectPiiEntities (en/es only; legacy)
# pii_service = "bedrock_guardrails"
```

```python
from agenticstar_platform.security import AWSSecurityClient, AWSSecurityConfig

config = AWSSecurityConfig(
    region_name="us-east-1",
    guardrail_id="your-guardrail-id",
    # pii_service defaults to "bedrock_guardrails" (multi-language PII)
)
client = AWSSecurityClient(config)
```

> **info**
>
> The default value of `pii_service` is `"bedrock_guardrails"`. Make sure to enable `sensitiveInformationPolicy` on the Bedrock Guardrails side (register NAME / EMAIL / PHONE / ADDRESS etc. in `piiEntitiesConfig` with `action: ANONYMIZE`). You can switch to Amazon Comprehend DetectPiiEntities by explicitly setting `"comprehend"`, but this is generally not recommended since Comprehend only supports en/es.

**GCP**

```toml
[security]
provider = "gcp"
project_id = "your-project"
model_armor_template = "your-armor-template"
model_armor_region = "us-central1"
dlp_location = "global"
```

```python
from agenticstar_platform.security import GCPSecurityClient, GCPSecurityConfig

config = GCPSecurityConfig(
    project_id="your-project",
    model_armor_template="your-armor-template",
    model_armor_region="us-central1",
)
client = GCPSecurityClient(config)
```

**Vertex AI Safety Filters backend (all-region coverage for Marketplace, SDK 0.5.22+)**

Setting `content_safety_backend="vertex_ai_safety"` routes content moderation through Vertex AI Safety Filters and prompt-shield checks through a Gemini judge (LLM-as-a-judge). It avoids the Limited-Support region constraints of Model Armor in `asia-northeast1` / `asia-southeast1`, keeping multilingual content moderation working in every region. Requires `google-cloud-aiplatform>=1.60.0` (the `[security]` extra).

```python
config = GCPSecurityConfig(
    project_id="your-project",
    content_safety_backend="vertex_ai_safety",
    vertex_ai_location="global",
    vertex_judge_model="gemini-2.5-flash",  # Gemini model used for the prompt-injection/jailbreak judge
    vertex_harm_thresholds={
        "HARM_CATEGORY_HATE_SPEECH": "BLOCK_MEDIUM_AND_ABOVE",
        "HARM_CATEGORY_HARASSMENT": "BLOCK_MEDIUM_AND_ABOVE",
    },
)
client = GCPSecurityClient(config)
```

PII detection uses Cloud DLP (global endpoint, all regions) under both backends.

## Auto-Detection Factory

You can automatically detect the provider from a configuration dictionary and generate a client. `create_security_client()` determines the provider (Azure / AWS / GCP) from the dict keys (`detect_provider`).

**Azure**

```python
# base_url contains cognitiveservices.azure.com → detected as Azure
config_dict = {
    "base_url": "https://<resource>.cognitiveservices.azure.com/",
    "api_key": "<key>",
}
```

**AWS**

```python
# service is bedrock_guardrails / comprehend → detected as AWS
config_dict = {
    "service": "bedrock_guardrails",
    "region": "us-east-1",
    "guardrail_id": "your-guardrail-id",
}
```

**GCP**

```python
# service is model_armor / dlp / vertex_ai_safety → detected as GCP
config_dict = {
    "service": "model_armor",
    "project_id": "your-project",
    "template_name": "your-armor-template",
    "location": "us-central1",
}
```

```python
from agenticstar_platform.security import create_security_client

# Auto-detect provider from config dictionary
client = create_security_client(config_dict)

# Generate PII detection-only client
from agenticstar_platform.security import create_pii_client
pii_client = create_pii_client(config_dict)
```

## Content Moderation

Detect harmful content in user inputs and agent outputs.

```python
result = await client.check_content_moderation(
    text="Text to check",
    threshold=2,  # severity 0-6, blocks at or above this threshold
)

print(result.blocked)      # True (blocked) / False (allowed)
print(result.categories)   # {ContentCategory.HATE: 0, ContentCategory.VIOLENCE: 4, ...}
print(result.threshold)    # Applied threshold
```

### Detection Categories and Severity

| ContentCategory | Description                  | Severity (0-6)                  |
| --------------- | ---------------------------- | ------------------------------- |
| `HATE`          | Hate speech / discrimination | 0=safe, 2=low, 4=medium, 6=high |
| `SEXUAL`        | Sexual content               | Same as above                   |
| `SELF_HARM`     | Self-harm                    | Same as above                   |
| `VIOLENCE`      | Violent content              | Same as above                   |
| `PROFANITY`     | Inappropriate language       | Same as above                   |
| `INSULT`        | Insulting language           | Same as above                   |
| `THREAT`        | Threatening language         | Same as above                   |

## Prompt Shield

Detect prompt injection attacks.

```python
result = await client.check_prompt_shield(
    user_prompt="User input text",
    documents=["Reference document 1", "Reference document 2"],
)

print(result.attack_detected)  # True / False
print(result.attack_type)      # Attack type (when detected)
print(result.confidence)       # Confidence score
```

check\_prompt\_shield() automatically trims each document to 10,000 characters (to comply with Azure API limits).

## PII Detection

Detect personally identifiable information in text.

- **Azure**: PII Detection API (multi-language support)
- **AWS**: Bedrock Guardrails `sensitiveInformationPolicy` by default (multi-language support including Japanese). Setting `pii_service="comprehend"` explicitly switches to Amazon Comprehend DetectPiiEntities (en/es only)
- **GCP**: Cloud DLP (multi-language support)

```python
result = await client.detect_pii(
    text="Taro Tanaka's phone number is 090-1234-5678. Email is tanaka@example.com.",
    mask=True,
    language="ja",
)

print(result.success)              # True
print(result.masked_text)          # "Taro Tanaka's phone number is ***. Email is ***."
print(result.categories_detected)  # [PIICategory.PHONE_NUMBER, PIICategory.EMAIL]
for entity in result.entities:
    print(f"  {entity.category}: {entity.text} (offset={entity.offset}, len={entity.length}, confidence={entity.confidence})")
```

### Batch Detection and Quota Protection (SDK 0.5.23+)

Multiple texts can be scanned together with `detect_pii_batch()`. Azure packs up to 5 documents per request, cutting API call volume by up to 5x compared to calling `detect_pii()` per text (the Azure S0 tier allows 300 requests/min, so batching is essential when scanning large text sets such as conversation histories). Results come back in the same order and length as the input; failures are returned per text as `success=False` (no exception).

```python
results = await client.detect_pii_batch(
    texts=["I am Taro Tanaka", "Phone: 090-1234-5678", "Text without PII"],
    mask=True,
    language="ja",
)
for r in results:
    print(r.success, r.masked_text)
```

Azure 429s (rate limiting) are retried automatically honoring `Retry-After` (2 retries by default, configurable via the `AGENTICSTAR_AZURE_LANG_429_RETRIES` environment variable). If throttling persists after retries, the remaining Azure calls are aborted and unresolved texts fail closed (`masked_text=""`) with `error_code="RATE_LIMITED"`. Callers are encouraged to detect this and surface HTTP 429 + `Retry-After` to their clients (AWS / GCP inherit a sequential default implementation from the base class).

### PII Categories (Major)

| PIICategory         | Detection Examples           |
| ------------------- | ---------------------------- |
| `PERSON_NAME`       | Taro Tanaka                  |
| `PHONE_NUMBER`      | 090-1234-5678, 03-1234-5678  |
| `EMAIL`             | user\@example.com            |
| `CREDIT_CARD`       | 4111-1111-1111-1111          |
| `NATIONAL_ID`       | My Number (12 digits)        |
| `PASSPORT_NUMBER`   | TK1234567                    |
| `ADDRESS`           | Shibuya-ku, Tokyo...         |
| `IP_ADDRESS`        | 192.168.1.1                  |
| `API_KEY`           | sk-...                       |
| `CONNECTION_STRING` | DefaultEndpointsProtocol=... |

For the complete list of `PIICategory` values, see the [SDK API Reference — PIICategory](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/develop/reference/sdk-ref.md#piicategory).

## Integrated Security Check

The `check_security()` method allows you to run content moderation, prompt shield, and PII detection all at once.

```python
result = await client.check_security(
    text="Text to check",
    check_moderation=True,
    check_prompt_shield=True,
    check_pii=False,           # Default is False
    fail_on_error=True,
)

print(result.allowed)              # True (allowed) / False (blocked)
print(result.violations)           # ["harmful_content", "jailbreak_attack", "pii_detected", ...]
print(result.content_moderation)   # ContentModerationResult or None
print(result.prompt_shield)        # PromptShieldResult or None
print(result.pii_detection)        # PIIDetectionResult or None
```

## ContentSafetyValidator

`ContentSafetyValidator` is a wrapper class that validates and marks **external content** (fetched from web / browser / API / MCP) based on guardrail settings.

```python
from agenticstar_platform.security import ContentSafetyValidator, GuardrailsConfig

validator = ContentSafetyValidator(
    security_client=client,
    guardrails=guardrails_config,  # GuardrailsConfig retrieved from DB (defaults if omitted)
)

# Validate and sanitize external content (source_type is required)
result = await validator.validate_and_sanitize(
    content=external_content,
    source_type="web",                  # "web" / "browser" / "api" / "mcp"
    source_url="https://example.com",   # optional
    user_prompt=user_message,           # for Prompt Shield validation (optional)
)

if result.is_safe:
    print(result.marked_content)  # marked content (empty string when unsafe)
print(result.metadata)            # validation metadata
```

## Usage Patterns in Agents

### Input and Output Checking

```python
async def safe_agent_run(user_message: str) -> str:
    # 1. Input check
    input_result = await client.check_security(text=user_message)
    if not input_result.allowed:
        return f"Request blocked: {', '.join(input_result.violations)}"

    # 2. Agent processing
    response = await run_agent_logic(user_message)

    # 3. Output check
    output_result = await client.check_security(text=response)
    if not output_result.allowed:
        return "A content policy violation was detected during response generation."

    return response
```

## Next Steps

SDK API Reference — Security Module

Complete specifications for SecurityClient / ContentSafetyValidator

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/develop/reference/sdk-ref.md#security-module)

Memory Guide

Content validation before saving to memory

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/develop/guide/memory-guide.md)
