CreateRuleVersion (V2) parity mapping

Supported in:

This guide details the request and response mapping specifications and property parity analysis for migrating from the legacy Backstory Rules Engine V2 API (CreateRuleVersion) to the modern Chronicle API (CreateRule).

Protocol and mapping overview

Feature Legacy API (CreateRuleVersion V2) Modern Chronicle API (CreateRule)
HTTP method POST POST
Permissions Partner token or legacy API keys chronicle.googleapis.com/rules.create

Request payload field-by-field parity

The modern Chronicle API CreateRuleRequest scopes creation under a target parent instance path.

Legacy field (CreateRuleVersionRequest) Modern field (CreateRuleRequest / Rule) Field type Parity & migration notes
— parent (in HTTP path) string Google Cloud scoping context / new field: Scopes the rule creation under a target parent instance path in the URL: projects/{project}/locations/{location}/instances/{instance}.
rule_id — string Retired / server-assigned: In the modern API, rule identifiers are assigned by the server upon creation and cannot be predefined by the client.
rule rule Rule Parity mapped: The rule content structure (details inside nested mappings in the following table).
field_mask — — Retired: Field masks do not apply during initial resource creation.

Nested Rule request fields mapped

The fields mapping inside the Rule request is as follows:

Legacy field (Rule request) Modern field (Rule request) Field type Parity & migration notes
rule_text text string Renamed: The YARA-L rule code block content itself.
rule_id, version_id, and version_create_time — — Ignored / output-only: Identifiers and timestamps are generated by the server.
rule_name, author, and metadata — — Ignored / output-only: Display name, author, and custom metadata map keys are extracted automatically from the YARA-L text block.
compilation_state or compilation_error — — Ignored / output-only: Populated post-compilation by the backend system.
alerting_enabled — — Decoupled: Alert state is managed separately under the RuleDeployment resource post-creation.
live_rule_enabled — — Decoupled: Continuous live rule execution state is managed separately under RuleDeployment.
rule_type or inputs_used — — Ignored / output-only: Evaluated and populated automatically by the compiler.
labels — — Retired / decoupled: Event labeling rules are managed and resolved dynamically in the detection pipelines.

Response payload field-by-field parity

Both APIs return Rule objects, but the modern API decomposes deployment properties (alerts and live status) to RuleDeployment resources.

Legacy field (Rule response) Modern field (Rule response) Field type Parity & migration notes
rule_id and version_id name string Consolidated: Legacy separate identifier strings are unified into the canonical Google Cloud resource path: projects/{project}/locations/{location}/instances/{instance}/rules/{rule_id}.
version_id revision_id string Renamed: Represents the unique version checksum string.
rule_name display_name string Renamed: The user-specified title display name of the rule.
rule_text text string Renamed: YARA-L rule content.
author author string Direct map / extracted: Author name metadata extracted from YARA-L comments.
metadata metadata map<string, string> Direct map: Structured user-defined YARA-L metadata headers.
version_create_time revision_create_time Timestamp Renamed: Timestamp when the rule revision was written.
— create_time Timestamp New field: Timestamp of when the rule was originally created.
compilation_state compilation_state enum Direct map: Compilation status enum (COMPILATION_STATE_UNSPECIFIED, SUCCEEDED, FAILED).
compilation_error — (nested) string Restructured: Legacy compilation errors are mapped into structured warning lists inside compilation_diagnostics in the modern response.
— compilation_diagnostics repeated CompilationDiagnostic New field: Structured collection containing warnings and errors generated during compilation.
archived_time — Timestamp Retired: Rule archiving and deletion lifecycles are managed natively using standard delete and undelete actions and operations.
alerting_enabled — bool Decoupled: Alert enablement state is decoupled from the rule definition and managed under the RuleDeployment resource (projects/*/rules/*/deployment).
live_rule_enabled — bool Decoupled: Continuous live rule evaluation toggle is decoupled and managed under the RuleDeployment resource.
rule_type type enum RuleType Renamed and type shift: Renamed from string rule_type to RuleType enum (RULE_TYPE_UNSPECIFIED, SINGLE_EVENT, MULTI_EVENT).
last_alert_status_change_time — Timestamp Decoupled: Moved to the corresponding activation change history under RuleDeployment.
inputs_used inputs_used InputsUsed Direct map: Structured fields indicating if the rule reads UDM events, context entities, or system alerts.
labels — RuleLabels Retired / decoupled: Event labeling rules are managed and resolved dynamically in the detection pipelines.
— reference_lists repeated string New field: Extracted list of resource names for Reference Lists referenced in the YARA-L rule.
— allowed_run_frequencies repeated RunFrequency New field: Execution frequencies allowed for the rule based on YARA-L complexity (for example, LIVE, HOURLY, DAILY).
— etag string New field: Concurrency control token used in updates.
— scope string New field: Data RBAC scope resource name associated with the rule.
— near_real_time_live_rule_eligible bool New field: Read-only flag indicating whether the rule is eligible for near-real-time streaming detection.
— data_tables repeated string New field: Resource names of Data Tables referenced by this rule.
— has_nonexistence_checks bool New field: Flag indicating whether the rule implements non-existence checks.

Key differences

  • Google Cloud project scoping integration:
    • Scoped natively under parent project instance folder bindings (projects/{project}/locations/{location}/instances/{instance}).
  • Execution state separation:
    • YARA-L code syntax is updateable independently from live scheduling or alerts (which are decoupled under RuleDeployment resources).
  • Compilation reporting and syntax resolution:
    • Simple error strings are replaced by comprehensive diagnostic items (compilation_diagnostics), and modern YARA-L references to external tables (data_tables) and lookup keys (reference_lists) are automatically parsed and cataloged.
  • IAM permissions:
    • Request validation maps to standard Cloud IAM permission validation check (chronicle.googleapis.com/rules.create).