> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charlemagnelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Reference

> Full reference for all policy types, scopes, and fields

## Policy Structure

Every policy has the same top-level shape in YAML:

```yaml theme={null}
- name: Human-readable label      # required, string
  type: app_config                # required: app_config | flow_config | dlp_config
  scope: global                   # required: global | group | device
  target: finance                 # required when scope is group or device
  locked: false                   # optional, default false
  description: "..."              # optional, ignored by the agent
  data:                           # required, type-specific (see below)
    ...
```

### `scope` and `target`

| Scope    | Target                   | Applies to                |
| -------- | ------------------------ | ------------------------- |
| `global` | omit (or `null`)         | All devices in the org    |
| `group`  | group name or group UUID | All devices in that group |
| `device` | device UUID              | That specific device only |

Group name resolution: the SDK looks up the group by name first, then by UUID. If the group does not exist, `apply` will fail with a `404`.

### `locked`

When `locked: true`, the device agent cannot override the policy locally — even if a device-level policy would normally take precedence. Use this for compliance-critical settings you never want overridden.

***

## App Config (`app_config`)

Controls the Agent Charley application's behavior on the endpoint.

```yaml theme={null}
data:
  suppress_frontend_ui: false           # Hide browser extension UI (coin, panel, badges)
  suppress_email_content_analysis: false # Skip email phishing analysis
  stealth_mode: false                   # Fully invisible mode — no tray icon, no dashboard
  flow_logs_enabled: true               # Stream activity logs for analytics
  telemetry_enabled: true               # Report threat telemetry to the Overview dashboard
  suppress_policy_locked: false         # Allow device to override locked policies (use carefully)
```

All fields are optional. Unset fields inherit from the broader scope.

| Field                             | Type | Default | Description                                         |
| --------------------------------- | ---- | ------- | --------------------------------------------------- |
| `suppress_frontend_ui`            | bool | `false` | Hides the browser extension's visible elements      |
| `suppress_email_content_analysis` | bool | `false` | Disables email content phishing scanning            |
| `stealth_mode`                    | bool | `false` | No tray icon, no local dashboard, completely silent |
| `flow_logs_enabled`               | bool | `true`  | Enables the URL activity stream to the Charley API  |
| `telemetry_enabled`               | bool | `true`  | Enables threat event reporting for analytics        |
| `suppress_policy_locked`          | bool | `false` | If `true`, device can override even locked policies |

***

## Flow Config (`flow_config`)

Controls which URL categories Agent Charley classifies and reports.

```yaml theme={null}
data:
  enabled: true
  categories:
    - SECURITY_BLOCK
    - BANKING
    - CRYPTO
    - ECOMMERCE
    - EMAIL
    - JOB_SITES
    - SOCIAL_MEDIA
    - PRODUCTIVITY
    - TRUSTED
```

| Field        | Type          | Default | Description                              |
| ------------ | ------------- | ------- | ---------------------------------------- |
| `enabled`    | bool          | `true`  | Enable or disable flow tracking entirely |
| `categories` | list\[string] | all     | URL categories to classify and report    |

### Available Categories

| Value            | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `SECURITY_BLOCK` | Known malicious, phishing, and threat domains        |
| `BANKING`        | Online banking and financial services                |
| `CRYPTO`         | Cryptocurrency exchanges and wallets                 |
| `ECOMMERCE`      | Shopping and retail sites                            |
| `EMAIL`          | Webmail services (Gmail, Outlook, etc.)              |
| `JOB_SITES`      | Job boards and recruiting platforms                  |
| `SOCIAL_MEDIA`   | Social networks                                      |
| `PRODUCTIVITY`   | Work tools (docs, project management, collaboration) |
| `TRUSTED`        | Org-allowlisted domains                              |

***

## DLP Config (`dlp_config`)

Controls data loss prevention — scanning clipboard content and blocking or warning on sensitive data patterns.

```yaml theme={null}
data:
  enabled: true

  targets:
    apply_to_all_apps: true       # Scan paste events in all applications
    apps_allowlist:               # Alternative: only scan in these apps (by display name)
      - Chrome
      - Slack
      - Terminal

  detections:
    builtins:                     # Built-in pattern detectors
      - credit_card
      - ssn_us
      - email
      - phone
    custom_regex:                 # Custom regex patterns
      - name: account_number
        pattern: '\b[0-9]{8,17}\b'
      - name: api_key
        pattern: 'sk-[A-Za-z0-9]{32,}'

  actions:
    mode: warn                    # block | warn | allow
    clear_clipboard_on_block: true
    allow_once_override: false

  ui:
    notify_on_block: true
    notify_on_warn: true
    toast_cooldown_sec: 30        # Minimum seconds between toasts (0 = always show)

  slack_context:                  # Optional: Slack-aware DLP context
    enabled: true
    categories:                   # Only trigger in these Slack channel types
      - public_channel
      - external_shared
      - dm
      - group_dm
      - private_channel
      - context_unavailable
```

### `targets`

Either `apply_to_all_apps: true` or provide `apps_allowlist` — not both. `apps_allowlist` entries are matched against the application's display name on macOS (as reported by NSWorkspace).

### `detections.builtins`

| Value         | Detects                                                           |
| ------------- | ----------------------------------------------------------------- |
| `credit_card` | Luhn-valid 13–19 digit card numbers (Visa, MC, Amex, Discover)    |
| `ssn_us`      | US Social Security Numbers in `XXX-XX-XXXX` or `XXXXXXXXX` format |
| `email`       | Email addresses                                                   |
| `phone`       | US phone numbers in common formats                                |

### `actions.mode`

| Value   | Behavior                                            |
| ------- | --------------------------------------------------- |
| `block` | Cancels the paste. Optionally clears the clipboard. |
| `warn`  | Allows the paste but shows a warning notification.  |
| `allow` | Logs the detection but takes no visible action.     |

### `slack_context`

When `slack_context.enabled` is true, DLP triggers only when the user is pasting into a Slack window that matches the specified channel types. If `slack_context` is omitted or disabled, DLP applies regardless of the target application.

***

## Python SDK Models

### `AppConfigData`

```python theme={null}
from charley_policy import AppConfigData

AppConfigData(
    suppress_frontend_ui=False,
    suppress_email_content_analysis=False,
    stealth_mode=False,
    flow_logs_enabled=True,
    telemetry_enabled=True,
    suppress_policy_locked=False,
)
```

### `FlowConfigData`

```python theme={null}
from charley_policy import FlowConfigData

FlowConfigData(
    enabled=True,
    categories=["SECURITY_BLOCK", "BANKING", "CRYPTO"],
)
```

### `DlpConfigData`

```python theme={null}
from charley_policy import DlpConfigData, DlpTargets, DlpDetections, DlpActions, DlpUi, DlpRegex

DlpConfigData(
    enabled=True,
    targets=DlpTargets(apply_to_all_apps=True),
    detections=DlpDetections(
        builtins=["credit_card", "ssn_us"],
        custom_regex=[DlpRegex(name="account_number", pattern=r"\b[0-9]{8,17}\b")],
    ),
    actions=DlpActions(
        mode="block",
        clear_clipboard_on_block=True,
        allow_once_override=False,
    ),
    ui=DlpUi(
        notify_on_block=True,
        toast_cooldown_sec=0,
    ),
)
```