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

# Snapshot Rules

> Define organization-level snapshot guardrails and configure snapshot anonymization

Snapshot rules let you enforce organization-level guardrails for every snapshot
job, including required transformations and always excluded tables.

## Organization Snapshot Rules (Team & Enterprise)

Use **Settings -> Snapshot Rules** in the app to define org-wide rules that are
enforced on every snapshot.

When rules are enabled, Basecut applies them at snapshot-job creation time:

* Missing required transformations are added automatically.
* Conflicting transformations fail fast before extraction starts.
* Always excluded tables are merged into the job config.

### Snapshot Rule Shape (`rules`)

Most users configure rules in **Settings -> Snapshot Rules**. For API/CLI
integrations, the `rules` object supports this shape:

```json theme={null}
{
  "required_strategies": {
    "*.email": "fake_email",
    "users.ssn": {
      "strategy": "fake_ssn"
    },
    "users.created_at": {
      "strategy": "date_shift",
      "params": { "days": 30 }
    }
  },
  "required_excludes": ["audit_logs", "payment_events"]
}
```

### API Payload Shape

When writing rules through the API, send `enabled` and `rules`:

```json theme={null}
{
  "enabled": true,
  "rules": {
    "required_strategies": {
      "*.email": "fake_email",
      "users.ssn": "fake_ssn"
    },
    "required_excludes": ["audit_logs", "payment_events"]
  }
}
```

### Rule Behavior

| Rule                  | Behavior                                                                      |
| :-------------------- | :---------------------------------------------------------------------------- |
| `required_strategies` | Ensures a transformation is used for matching fields (for example `*.email`). |
| `required_excludes`   | Forces tables into `tables.exclude` for every snapshot.                       |

<Info>
  For rule keys like `users.email`, unqualified tables are normalized to
  `public.users`.
</Info>

### Conflict Example

If your org snapshot rules require `*.email: fake_email` and a job config sets
`users.email: none`, Basecut returns a validation error and does not create the
job.

### Precedence and Conflict Behavior

1. Organization snapshot rules are evaluated first at snapshot-job creation.
2. Required transformations are merged into the job config.
3. Always excluded tables are merged into `tables.exclude`.

## Snapshot-Level Anonymization Configuration

Use YAML anonymization rules for snapshot-specific behavior. Organization
snapshot rules are the governance layer above these settings.

## Configuration Shape

```yaml theme={null}
anonymize: auto
# or
anonymize:
  mode: manual # auto | manual | off
  rules:
    users:
      email: fake_email
      phone: fake_phone
    '*.password_hash': redact
```

### Modes

| Mode     | Behavior                                                |
| :------- | :------------------------------------------------------ |
| `auto`   | Enable built-in PII detection and apply explicit rules. |
| `manual` | Apply only explicit rules.                              |
| `off`    | Disable anonymization entirely.                         |

## Rules

You can define rules in two forms:

1. **Table-grouped rules**

```yaml theme={null}
anonymize:
  mode: manual
  rules:
    users:
      full_name: fake_name
      date_of_birth:
        strategy: date_shift
        params:
          days: 90
```

2. **Wildcard / flat rules**

```yaml theme={null}
anonymize:
  mode: manual
  rules:
    '*.email': fake_email
    '*.credit_card': redact
```

<Info>
  Unqualified table keys (for example `users`) are resolved as `public.users`.
</Info>

## Example: Balanced Auto + Overrides

```yaml theme={null}
anonymize:
  mode: auto
  rules:
    users:
      email: fake_email
      phone: fake_phone
      ssn: fake_ssn
    payments:
      card_number:
        strategy: partial_mask
        params:
          visible: 4
    '*.password_hash': redact
```

## Strategies

### Basic

| Strategy | Description                               |
| :------- | :---------------------------------------- |
| `none`   | No transformation                         |
| `redact` | Replace with `[REDACTED]`                 |
| `null`   | Replace with `null`                       |
| `fixed`  | Replace with fixed value (`params.value`) |
| `hash`   | Deterministic hash                        |

### Person Data

| Strategy                | Description                  |
| :---------------------- | :--------------------------- |
| `fake_name`             | Realistic person name        |
| `fake_first_name`       | First name                   |
| `fake_last_name`        | Last name                    |
| `fake_email`            | Realistic email              |
| `email_preserve_domain` | Fake local part, keep domain |
| `fake_phone`            | Phone number                 |
| `fake_date_of_birth`    | Realistic DOB                |
| `fake_username`         | Username/handle              |

### Financial & Identity

| Strategy            | Description             |
| :------------------ | :---------------------- |
| `fake_credit_card`  | Luhn-valid card number  |
| `fake_ssn`          | SSN-like value          |
| `fake_passport`     | Passport-like value     |
| `fake_iban`         | IBAN-like value         |
| `fake_bank_account` | Bank account-like value |
| `fake_company`      | Company name            |

### Location & Networking

| Strategy       | Description    |
| :------------- | :------------- |
| `fake_address` | Street address |
| `fake_city`    | City           |
| `fake_state`   | State          |
| `fake_zip`     | Postal code    |
| `fake_country` | Country        |
| `fake_ip`      | IP address     |
| `fake_mac`     | MAC address    |

### Utility

| Strategy         | Description                   | Params    |
| :--------------- | :---------------------------- | :-------- |
| `partial_mask`   | Keep N trailing chars visible | `visible` |
| `date_shift`     | Shift date ±N days            | `days`    |
| `numeric_noise`  | Add ±N% variance              | `percent` |
| `fake_uuid`      | Generate UUID                 | -         |
| `fake_url`       | Generate URL                  | -         |
| `fake_paragraph` | Generate text                 | -         |