REST Resource: projects.locations.instances.rules

Resource: Rule

The Rule resource represents a user-created rule.

JSON representation 
{
  "name": string,
  "revisionId": string,
  "displayName": string,
  "text": string,
  "author": string,
  "severity": {
    object (Severity)
  },
  "metadata": {
    string: string,
    ...
  },
  "createTime": string,
  "revisionCreateTime": string,
  "compilationState": enum (CompilationState),
  "type": enum (RuleType),
  "referenceLists": [
    string
  ],
  "allowedRunFrequencies": [
    enum (RunFrequency)
  ],
  "etag": string,
  "scope": string,
  "compilationDiagnostics": [
    {
      object (CompilationDiagnostic)
    }
  ],
  "nearRealTimeLiveRuleEligible": boolean,
  "dataTables": [
    string
  ],
  "inputsUsed": {
    object (InputsUsed)
  },
  "hasNonexistenceChecks": boolean,
  "ruleOwner": enum (RuleOwner),
  "tags": [
    string
  ],
  "ruleTextTags": [
    string
  ],
  "alertingEnabled": boolean,
  "liveModeEnabled": boolean,
  "archived": boolean,
  "runFrequency": enum (RunFrequency),
  "scheduleCustomizations": {
    object (ScheduleCustomizations)
  },
  "currentDayDetectionCount": integer,
  "executionState": enum (ExecutionState),
  "timeWindowDuration": string
}
Fields
name

string

Identifier. Full resource name for the rule. Format: projects/{project}/locations/{location}/instances/{instance}/rules/{rule}
revisionId

string

Output only. The revision ID of the rule. A new revision is created whenever the rule text is changed in any way. Format: v_{10 digits}_{9 digits} Populated in REVISION_METADATA_ONLY view and FULL view.
displayName

string

Output only. Display name of the rule. Populated in BASIC view and FULL view.
text

string

The YARA-L content of the rule. Populated in FULL view.
author

string

Output only. The author of the rule. Extracted from the meta section of text. Populated in BASIC view and FULL view.
severity

object (Severity)

Output only. The severity of the rule as specified in the meta section of text. Populated in BASIC view and FULL view.
metadata

map (key: string, value: string)

Output only. Additional metadata specified in the meta section of text. Populated in FULL view.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
createTime

string (Timestamp format)

Output only. The timestamp of when the rule was created. Populated in FULL view.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
revisionCreateTime

string (Timestamp format)

Output only. The timestamp of when the rule revision was created. Populated in FULL, REVISION_METADATA_ONLY views.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
compilationState

enum (CompilationState)

Output only. The current compilation state of the rule. Populated in FULL view.
type

enum (RuleType)

Output only. User-facing type of the rule. Extracted from the events section of rule text. Populated in BASIC view and FULL view.
referenceLists[]

string

Output only. Resource names of the reference lists used in this rule. Populated in FULL view.
allowedRunFrequencies[]

enum (RunFrequency)

Output only. The run frequencies that are allowed for the rule. Populated in BASIC view and FULL view.
etag

string

The etag for this rule. If this is provided on update, the request will succeed if and only if it matches the server-computed value, and will fail with an ABORTED error otherwise. Populated in BASIC view and FULL view.
scope

string

Resource name of the DataAccessScope bound to this rule. Populated in BASIC view and FULL view. If reference lists are used in the rule, validations will be performed against this scope to ensure that the reference lists are compatible with both the user's and the rule's scopes. The scope should be in the format: projects/{project}/locations/{location}/instances/{instance}/dataAccessScopes/{scope}.
compilationDiagnostics[]

object (CompilationDiagnostic)

Output only. A list of a rule's corresponding compilation diagnostic messages such as compilation errors and compilation warnings. Populated in FULL view.
nearRealTimeLiveRuleEligible

boolean

Output only. Indicate the rule can run in near real time live rule. If this is true, the rule uses the near real time live rule when the run frequency is set to LIVE.
dataTables[]

string

Output only. Resource names of the data tables used in this rule.
inputsUsed

object (InputsUsed)

Output only. The set of inputs used in the rule. For example, if the rule uses $e.principal.hostname, then the usesUdm field will be true.
hasNonexistenceChecks

boolean

Output only. Indicates whether the rule has non-existence checks.
ruleOwner

enum (RuleOwner)

Output only. The rule owner (i.e., whether the rule is customer or Google-authored).
tags[]

string

Output only. Resource names of the tags used in this rule. Example: [ "projects/{project}/locations/{location}/instances/{instance}/ tags/google.mitre.TA000", "projects/{project}/locations/{location}/instances/{instance}/ tags/google.CloudThreats", ]
ruleTextTags[]

string

Output only. Resource names of tags defined in the rule text. These tags are a subset of the tags field and can only be modified by updating the rule text. Example: [ "projects/{project}/locations/{location}/instances/{instance}/ tags/google.mitre.TA000", "projects/{project}/locations/{location}/instances/{instance}/ tags/google.CloudThreats", ]
alertingEnabled

boolean

Output only. Alerting status for the rule.
liveModeEnabled

boolean

Output only. Live Status for the rule.
archived

boolean

Output only. The archive state of the rule deployment. Cannot be set to true unless enabled is set to false. If set to true, alerting will automatically be set to false. If currently set to true, enabled, alerting, and runFrequency cannot be updated.
runFrequency

enum (RunFrequency)

Output only. The chosen run frequencies for the rule.
scheduleCustomizations

object (ScheduleCustomizations)

Output only. Schedule customizations for this rule. Only valid for customizable run frequencies. This field is currently in preview and may not be accessible to all users.
currentDayDetectionCount

integer

Output only. The number of matched events for the current day in UTC time.
executionState

enum (ExecutionState)

Output only. The execution state of the rule.
timeWindowDuration

string (Duration format)

Output only. The time window duration of the rule. If the rule does not have a time window, this will be zero.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

CompilationState

The current compilation state of the rule.

Enums
COMPILATION_STATE_UNSPECIFIED The compilation state is unspecified/unknown.
SUCCEEDED The Rule can successfully compile.
FAILED The Rule cannot successfully compile. This is possible if a backwards-incompatible change was made to the compiler.

RunFrequency

LINT.IfChange(run_frequency_enum) RunFrequency indicates the run frequency at which a YARA-L 2 rule will run if enabled. New run frequency values may be added as new scheduling options for rules are added.

Enums
RUN_FREQUENCY_UNSPECIFIED The run frequency is unspecified/unknown.
LIVE Executes in real time.
HOURLY Executes once per hour.
DAILY Executes once per day.
LIVE_CUSTOMIZABLE Executes in real time and is customizable. This enum value is currently in preview and may not be accessible to all users.
HOURLY_CUSTOMIZABLE Executes once per hour and is customizable. This enum value is currently in preview and may not be accessible to all users.

CompilationDiagnostic

CompilationDiagnostic represents a compilation diagnostic generated during a rule's compilation, such as a compilation error or a compilation warning.

JSON representation 
{
  "message": string,
  "position": {
    object (CompilationPosition)
  },
  "severity": enum (Severity),
  "uri": string
}
Fields
message

string

Output only. The diagnostic message.
position

object (CompilationPosition)

Output only. The approximate position in the rule text associated with the compilation diagnostic. Compilation Position may be empty.
severity

enum (Severity)

Output only. The severity of a rule's compilation diagnostic.
uri

string

Output only. Link to documentation that describes a diagnostic in more detail.

CompilationPosition

CompilationPosition represents the location of a compilation diagnostic in rule text.

JSON representation 
{
  "startLine": integer,
  "startColumn": integer,
  "endLine": integer,
  "endColumn": integer
}
Fields
startLine

integer

Output only. Start line number, beginning at 1.
startColumn

integer

Output only. Start column number, beginning at 1.
endLine

integer

Output only. End line number, beginning at 1.
endColumn

integer

Output only. End column number, beginning at 1.

Severity

The severity level of the compilation diagnostic.

Enums
SEVERITY_UNSPECIFIED An unspecified severity level.
WARNING A compilation warning.
ERROR A compilation error.

InputsUsed

InputsUsed is a convenience field that tells us which sources of events (if any) were used in the rule.

JSON representation 
{
  "usesUdm": boolean,
  "usesEntity": boolean,
  "usesDetection": boolean
}
Fields
usesUdm

boolean

Optional. Whether the rule queries UDM events.
usesEntity

boolean

Optional. Whether the rule queries entity events.
usesDetection

boolean

Optional. Whether the rule queries detections.

RuleOwner

RuleOwner indicates the owner of the rule.

Enums
RULE_OWNER_UNSPECIFIED Rule owner is unspecified.
CUSTOMER Rule is customer-authored.
GOOGLE Rule is Google-authored.

ScheduleCustomizations

ScheduleCustomizations customize schedules for rules with customizable run frequencies.

JSON representation 
{
  "ensureEnrichmentCompleteness": boolean,
  "lateArrivingDataAdjustment": string
}
Fields
ensureEnrichmentCompleteness

boolean

Optional. Indicates whether to add additional delays and runs to rules to ensure enrichment completeness, with the trade-off of higher detection latencies.
lateArrivingDataAdjustment

string (Duration format)

Optional. Adjust the first rule execution run to account for late-arriving data.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

ExecutionState

The possible execution states the rule deployment can be in. LINT.IfChange(executionState)

Enums
EXECUTION_STATE_UNSPECIFIED Unspecified or unknown execution state.
DEFAULT Default execution state.
LIMITED Rules in limited state may not have their executions guaranteed.
PAUSED Paused rules are not executed at all.

Methods

create

 Creates a new Rule.

delete

 Deletes a Rule.

get

 Gets a Rule.

getDeployment

 Gets a RuleDeployment.

list

 Lists Rules.

listRevisions

 Lists all revisions of the rule.

modifyRules

 ModifyRules allows users to modify the rule config for multiple rules at once.

patch

 Updates a Rule.

updateDeployment

 Updates a RuleDeployment.