# Create a rule

Launch stage: Beta

`POST /api/2.0/lakewatch/rules`

Creates a new rule.

API scopes: lakewatch

## Request body

The rule to create. Server-assigned fields (`name`, `rule_id`, timestamps,
 `etag`, …) are ignored on the request.
- `name` (string, optional, 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`
- `catalog_name` (string, required, 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, required, 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`.
- `rule_name` (string, required, 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`.
- `description` (string, optional)
  Free-form description.
- `annotations` (object, optional)
  Free-form client-managed key/value annotations.
- `run_as_principal` (string, optional)
  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`.
- `category` (string, optional)
  Free-form rule category.
- `severity` (string, required)
  Free-form severity label, such as `Informational`, `Medium`, `High`, or
   `Critical`.
- `fidelity` (string, required)
  Signal quality for this rule.
  Possible values:
  - `FIDELITY_DEVELOPMENT`
  - `FIDELITY_INVESTIGATIVE`
  - `FIDELITY_MEDIUM`
  - `FIDELITY_HIGH`
- `objective` (string, optional)
  Long-form description of what this rule detects.
- `mitre` (array of object, optional)
  Up to 64 MITRE ATT&CK mappings, producing at most 192 flattened alert tags.
  - `taxonomy` (string, optional)
    Structured framework that organizes adversary behaviors, such as
     `mitre-attack`.
  - `tactic` (string, optional)
    Adversary objective during this attack, such as `Command and Control`.
  - `technique_id` (string, optional)
    MITRE technique ID, such as `T1078`.
  - `technique` (string, optional)
    Human-readable MITRE technique name.
  - `sub_technique_id` (string, optional)
    MITRE sub-technique ID, such as `T1078.001`.
  - `sub_technique` (string, optional)
    Human-readable MITRE sub-technique name.
- `deduplication` (string, optional)
  Signal deduplication mode.
  Possible values:
  - `DEDUPLICATION_DEFAULT`
  - `DEDUPLICATION_ENABLED`
  - `DEDUPLICATION_DISABLED`
- `deduplication_time_window` (string, optional)
  Time window for deduplication, such as `1h`, `24h`, `7d`, or `automatic`.
- `schedule` (object, required)
  When the rule executes.
  - `at_least_every` (string, optional)
    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, optional)
    Defines the schedule using a Quartz cron expression.
  - `continuous` (boolean, optional)
    Runs the rule continuously. Detection rules do not accept it: batch rules reject it, and
     streaming rules run continuously without it.
  - `enabled` (boolean, optional)
    Sets whether the job is scheduled to run. Defaults to true.
- `batch` (object, optional)
  Batch SQL rule input.
  - `sql` (object, optional)
    SQL query evaluated as the rule input.
    - `default_catalog_name` (string, optional)
      Default catalog used to resolve unqualified identifiers in `query`. If
       unset, the rule's `catalog_name` is used.
    - `default_schema_name` (string, optional)
      Default schema used to resolve unqualified identifiers in `query`. If
       unset, the rule's `schema_name` is used.
    - `query` (string, required)
      SQL query evaluated as the rule input.
  - `custom` (object, optional)
    Custom-notebook user function. The output is used as input data for the
     rule.
    - `notebook` (string, required)
      Fully-qualified notebook path, or a path relative to the configured base
       notebook directory.
    - `options` (object, optional)
      Optional arguments supplied when invoking the custom function.
  - `warehouse_id` (string, optional)
    SQL warehouse used to run this batch rule.
- `output` (object, required)
  What to record in each signal.
  - `summary` (string, optional)
    Signal summary. May contain SQL expressions in braces that the
     server substitutes from the input row.
  - `context` (object, optional)
    Key/value context to record from the input row. Values may contain SQL
     expressions in braces.
  - `default_context` (boolean, optional)
    If true, also record every column of the triggering input row. Custom
     context wins on key collision.
  - `event_time_column` (string, optional)
    Column in the rule output that holds the event timestamp.
- `suppress_until_time` (string, optional)
  If set, this rule's signals do not open new alerts until the given time.
- `content_resource_id` (string, optional, Immutable)
  Immutable UUIDv4 identifying the authored content resource installed as this rule.
- `references` (array of string, optional)
  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, optional)
  Long-form operational guidance carried from the authored rule metadata. Supports up to 4096
   characters. Requests exceeding this limit are rejected.
- `timerange` (object, optional)
  Time-range configuration for batch rules. If unset, the execution time range is extended by
   a fixed `15m` lookback.
  - `extend_lookback` (string, optional)
    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.

## Returns

Returns the Rule object.

## Response

```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"
  }
}
```