# The Rule object

A Lakewatch detection rule: a query that evaluates ingested data and generates a signal for
 each match. Each rule is a securable in a Unity Catalog schema.

## Attributes

- `name` (string, Beta, ID, Immutable)
  Resource name, in the form `rules/{rule_id}`. Assigned by the server on create; required
   on update.
  Example: `rules/550e8400-e29b-41d4-a716-446655440000`
- `rule_id` (string, Beta, Output only)
  Unity Catalog securable UUID of the rule, and the last segment of `name`. Never changes,
   including when the rule's catalog or schema is renamed.
- `catalog_name` (string, Beta, Immutable)
  Name of the Unity Catalog catalog that contains the rule. Required. Cannot be changed after
   creation. Reads return the value as supplied; the catalog's current name is reported in
   `effective_catalog_name`.
- `schema_name` (string, Beta, Immutable)
  Name of the Unity Catalog schema that contains the rule. Required. Cannot be changed after
   creation. Reads return the value as supplied; the schema's current name is reported in
   `effective_schema_name`.
- `effective_catalog_name` (string, Beta, Output only)
  Current name of the Unity Catalog catalog that contains the rule. Reflects catalog renames,
   which do not change `catalog_name`. Unset until resolved.
- `effective_schema_name` (string, Beta, Output only)
  Current name of the Unity Catalog schema that contains the rule. Reflects schema renames,
   which do not change `schema_name`. Unset until resolved.
- `rule_name` (string, Beta, Immutable)
  Name of the rule within its Unity Catalog schema. Required. Cannot be changed after
   creation. Reads return the value as supplied; the current UC name is reported in
   `effective_rule_name`.
- `effective_rule_name` (string, Beta, Output only)
  Current UC leaf name of the rule (server-owned). Tracks UC renames so callers
   can observe the live name without having to update the client-owned
   `rule_name`; unset until resolved.
- `description` (string, Beta)
  Free-form description.
- `version` (int64, Beta, Output only)
  Monotonic version, bumped on each update. Informational; use `etag` for
   optimistic concurrency.
- `create_time` (string, Beta, Output only)
  Time the rule was created.
- `update_time` (string, Beta, Output only)
  Time the rule was last updated.
- `created_by` (object, Beta, Output only)
  Principal that created the rule.
  - `id` (string, Beta)
    User / service-principal ID.
  - `principal_type` (string, Beta)
    Whether this principal is a regular user, service principal, or system principal.
    Possible values:
    - `REGULAR_USER`
    - `SERVICE_PRINCIPAL`
    - `SYSTEM_USER`
  - `email` (string, Beta)
    Email (regular users only).
  - `display_name` (string, Beta)
    Display name (user or SP name).
- `updated_by` (object, Beta, Output only)
  Principal that last updated the rule.
  - `id` (string, Beta)
    User / service-principal ID.
  - `principal_type` (string, Beta)
    Whether this principal is a regular user, service principal, or system principal.
    Possible values:
    - `REGULAR_USER`
    - `SERVICE_PRINCIPAL`
    - `SYSTEM_USER`
  - `email` (string, Beta)
    Email (regular users only).
  - `display_name` (string, Beta)
    Display name (user or SP name).
- `etag` (string, Beta, Output only)
  Opaque entity tag for optimistic concurrency. Content-version ETags change on
   user edits and remain stable across runtime status updates.
- `annotations` (object, Beta)
  Free-form client-managed key/value annotations.
- `owner` (object, Beta, Output only)
  Unity Catalog owner of the rule. Assigned by the server. Populated by `GetRule`.
  - `id` (string, Beta)
    User / service-principal ID.
  - `principal_type` (string, Beta)
    Whether this principal is a regular user, service principal, or system principal.
    Possible values:
    - `REGULAR_USER`
    - `SERVICE_PRINCIPAL`
    - `SYSTEM_USER`
  - `email` (string, Beta)
    Email (regular users only).
  - `display_name` (string, Beta)
    Display name (user or SP name).
- `run_as_principal` (string, Beta)
  The principal whose identity this rule's job runs as, given as a
   user email or service-principal application ID. When supplied on
   create/update, Lakewatch resolves the principal, records it on the rule, and
   creates the delegation to run as that principal — the requester must be
   authorized to delegate to it, or the request is rejected. When omitted on
   create, the requester's own identity is used. An update whose mask does not
   include `run_as_principal` keeps the current identity, and the requester must
   still be authorized to delegate to it; an editor who is not must supply a
   run_as_principal they can delegate to (for example, their own identity), or
   clear it, either of which reassigns the rule. An update whose mask includes
   `run_as_principal` but supplies no value clears it: the rule then runs as the
   requester, exactly as when it is omitted on create. Reads return the value as
   supplied; the identity the rule runs as is reported in
   `effective_run_as_principal`.
- `effective_run_as_principal` (string, Beta, Output only)
  The identity this rule's job runs as: the resolved `run_as_principal`, or the
   requester's identity when it was omitted on create or cleared on update. The value is a user
   email or service-principal application ID, falling back to the numeric principal ID if that
   identity can no longer be resolved. Populated on single-rule reads (get/create/update); list
   responses omit it.
- `category` (string, Beta)
  Free-form rule category.
- `severity` (string, Beta)
  Free-form severity label, such as `Informational`, `Medium`, `High`, or
   `Critical`.
- `fidelity` (string, Beta)
  Signal quality for this rule.
  Possible values:
  - `FIDELITY_DEVELOPMENT`
  - `FIDELITY_INVESTIGATIVE`
  - `FIDELITY_MEDIUM`
  - `FIDELITY_HIGH`
- `objective` (string, Beta)
  Long-form description of what this rule detects.
- `mitre` (array of object, Beta)
  Up to 64 MITRE ATT&CK mappings, producing at most 192 flattened alert tags.
  - `taxonomy` (string, Beta)
    Structured framework that organizes adversary behaviors, such as
     `mitre-attack`.
  - `tactic` (string, Beta)
    Adversary objective during this attack, such as `Command and Control`.
  - `technique_id` (string, Beta)
    MITRE technique ID, such as `T1078`.
  - `technique` (string, Beta)
    Human-readable MITRE technique name.
  - `sub_technique_id` (string, Beta)
    MITRE sub-technique ID, such as `T1078.001`.
  - `sub_technique` (string, Beta)
    Human-readable MITRE sub-technique name.
- `deduplication` (string, Beta)
  Signal deduplication mode.
  Possible values:
  - `DEDUPLICATION_DEFAULT`
  - `DEDUPLICATION_ENABLED`
  - `DEDUPLICATION_DISABLED`
- `deduplication_time_window` (string, Beta)
  Time window for deduplication, such as `1h`, `24h`, `7d`, or `automatic`.
- `schedule` (object, Beta)
  When the rule executes.
  - `at_least_every` (string, Beta)
    Defines the minimum cadence as a duration string. It may contain components
     for days, hours, minutes, and seconds (e.g. `5d`, `5d3h`, `3d2h5m12s`,
     `12m16s`).
  - `cron_expression` (string, Beta)
    Defines the schedule using a Quartz cron expression.
  - `continuous` (boolean, Beta)
    Runs the rule continuously. Detection rules do not accept it: batch rules reject it, and
     streaming rules run continuously without it.
  - `enabled` (boolean, Beta)
    Sets whether the job is scheduled to run. Defaults to true.
- `batch` (object, Beta)
  Batch SQL rule input.
  - `sql` (object, Beta)
    SQL query evaluated as the rule input.
    - `default_catalog_name` (string, Beta)
      Default catalog used to resolve unqualified identifiers in `query`. If
       unset, the rule's `catalog_name` is used.
    - `default_schema_name` (string, Beta)
      Default schema used to resolve unqualified identifiers in `query`. If
       unset, the rule's `schema_name` is used.
    - `query` (string, Beta)
      SQL query evaluated as the rule input.
  - `custom` (object, Beta)
    Custom-notebook user function. The output is used as input data for the
     rule.
    - `notebook` (string, Beta)
      Fully-qualified notebook path, or a path relative to the configured base
       notebook directory.
    - `options` (object, Beta)
      Optional arguments supplied when invoking the custom function.
  - `warehouse_id` (string, Beta)
    SQL warehouse used to run this batch rule.
- `output` (object, Beta)
  What to record in each signal.
  - `summary` (string, Beta)
    Signal summary. May contain SQL expressions in braces that the
     server substitutes from the input row.
  - `context` (object, Beta)
    Key/value context to record from the input row. Values may contain SQL
     expressions in braces.
  - `default_context` (boolean, Beta)
    If true, also record every column of the triggering input row. Custom
     context wins on key collision.
  - `event_time_column` (string, Beta)
    Column in the rule output that holds the event timestamp.
- `status` (object, Beta, Output only)
  Read-only lifecycle status.
  - `job_id` (string, Beta, Output only)
    Databricks Jobs API job ID. Unset for a pure ingestion pipeline.
  - `lifecycle_state` (string, Beta, Output only)
    Scheduling lifecycle of the resource's underlying job/pipeline: whether it
     is unscheduled, scheduled, stopped, or deleted. Distinct from `run_state`,
     which reports the outcome of the most recent run.
    Possible values:
    - `UNSCHEDULED`
    - `SCHEDULED`
    - `STOPPED`
    - `DELETED`
  - `run_state` (string, Beta, Output only)
    Possible values:
    - `RUNNING`
    - `SUCCEEDED`
    - `FAILED`
    - `CANCELED`
  - `last_error_message` (string, Beta, Output only)
    Most recent error message, if any. Pairs with `run_state = FAILED`.
  - `create_time` (string, Beta, Output only)
  - `last_start_time` (string, Beta, Output only)
    When the most recent run started. Pairs with `run_state = RUNNING`.
  - `last_complete_time` (string, Beta, Output only)
    When the most recent run completed. Pairs with `run_state = SUCCEEDED`.
  - `last_status_change_time` (string, Beta, Output only)
  - `pipeline_id` (string, Beta, Output only)
    DLT ingestion-pipeline ID. Set only when this status represents the
     datasource's ingestion pipeline (unset for job statuses).
- `suppress_until_time` (string, Beta)
  If set, this rule's signals do not open new alerts until the given time.
- `original_content_pack` (object, Beta, Output only)
  Reference to the content pack this rule was originally installed from.
  - `uuid` (string, Beta, Output only)
    UUID of the content pack.
  - `version` (string, Beta, Output only)
    Pack version the resource was installed from.
- `compute_workspace_id` (string, Beta, Output only)
  ID of the workspace whose compute runs this rule's jobs and owns its
   associated resources, such as the SQL warehouse a scheduled rule runs on.
   Server-assigned; a rule's warehouse can only be changed from this workspace.
- `content_resource_id` (string, Beta, Immutable)
  Immutable UUIDv4 identifying the authored content resource installed as this rule.
- `references` (array of string, Beta)
  Ordered reference URLs carried from the authored rule metadata. A maximum of three references
   of up to 512 characters each is supported. Requests exceeding these limits are rejected.
- `runbook` (string, Beta)
  Long-form operational guidance carried from the authored rule metadata. Supports up to 4096
   characters. Requests exceeding this limit are rejected.
- `timerange` (object, Beta)
  Time-range configuration for batch rules. If unset, the execution time range is extended by
   a fixed `15m` lookback.
  - `extend_lookback` (string, Beta)
    Extends the start of the execution time range by a compact duration with integer
     days, hours, minutes, and seconds in that order, such as `1h30m` or `15m`.
     Zero duration disables extension. Unset or empty uses a fixed `15m` at execution
     time. Only the start moves; the end is unchanged. Has no effect on batch SQL
     that does not use `IN_TIMERANGE`. Values must fit signed 64-bit microseconds.

## Example

```json
{
  "name": "rules/550e8400-e29b-41d4-a716-446655440000",
  "rule_id": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "effective_catalog_name": "string",
  "effective_schema_name": "string",
  "rule_name": "string",
  "effective_rule_name": "string",
  "description": "string",
  "version": 0,
  "create_time": "string",
  "update_time": "string",
  "created_by": {
    "id": "string",
    "principal_type": "REGULAR_USER",
    "email": "string",
    "display_name": "string"
  },
  "updated_by": {
    "id": "string",
    "principal_type": "REGULAR_USER",
    "email": "string",
    "display_name": "string"
  },
  "etag": "string",
  "annotations": {},
  "owner": {
    "id": "string",
    "principal_type": "REGULAR_USER",
    "email": "string",
    "display_name": "string"
  },
  "run_as_principal": "string",
  "effective_run_as_principal": "string",
  "category": "string",
  "severity": "string",
  "fidelity": "FIDELITY_DEVELOPMENT",
  "objective": "string",
  "mitre": [
    {
      "taxonomy": "string",
      "tactic": "string",
      "technique_id": "string",
      "technique": "string",
      "sub_technique_id": "string",
      "sub_technique": "string"
    }
  ],
  "deduplication": "DEDUPLICATION_DEFAULT",
  "deduplication_time_window": "string",
  "schedule": {
    "at_least_every": "string",
    "cron_expression": "string",
    "continuous": true,
    "enabled": true
  },
  "batch": {
    "sql": {},
    "custom": {},
    "warehouse_id": "string"
  },
  "output": {
    "summary": "string",
    "context": {},
    "default_context": true,
    "event_time_column": "string"
  },
  "status": {
    "job_id": "string",
    "lifecycle_state": "UNSCHEDULED",
    "run_state": "RUNNING",
    "last_error_message": "string",
    "create_time": "string",
    "last_start_time": "string",
    "last_complete_time": "string",
    "last_status_change_time": "string",
    "pipeline_id": "string"
  },
  "suppress_until_time": "string",
  "original_content_pack": {
    "uuid": "string",
    "version": "string"
  },
  "compute_workspace_id": "string",
  "content_resource_id": "string",
  "references": [
    "string"
  ],
  "runbook": "string",
  "timerange": {
    "extend_lookback": "string"
  }
}
```