Policy Reference

Policy Structure

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

- 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.

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.

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.

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`

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`

from charley_policy import FlowConfigData

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

`DlpConfigData`

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,
    ),
)

Overview

Dashboard

Policy as Code

Integrations

API Reference

Self-Hosting

Policy Structure

`scope` and `target`

`locked`

App Config (`app_config`)

Flow Config (`flow_config`)

Available Categories

DLP Config (`dlp_config`)

`targets`

`detections.builtins`

`actions.mode`

`slack_context`

Python SDK Models

`AppConfigData`

`FlowConfigData`

`DlpConfigData`

​Policy Structure

​scope and target

​locked

​App Config (app_config)

​Flow Config (flow_config)

​Available Categories

​DLP Config (dlp_config)

​targets

​detections.builtins

​actions.mode

​slack_context

​Python SDK Models

​AppConfigData

​FlowConfigData

​DlpConfigData

Policy Structure

`scope` and `target`

`locked`

App Config (`app_config`)

Flow Config (`flow_config`)

Available Categories

DLP Config (`dlp_config`)

`targets`

`detections.builtins`

`actions.mode`

`slack_context`

Python SDK Models

`AppConfigData`

`FlowConfigData`

`DlpConfigData`