google.cloud.forseti.scanner.audit.log_sink_rules_engine module

Log Sinks/Exports rules engine.

Builds the RuleBook (LogSinkRuleBook) from the rule definitions (file either stored locally or in GCS) and compares a resource’s log sinks against the RuleBook to determine whether there are violations. Log Sinks rules can be defined on organization, folder, billing_account and project.

class LogSinkRuleBook(global_configs, rule_defs=None, snapshot_timestamp=None)[source]

Bases: google.cloud.forseti.scanner.audit.base_rules_engine.BaseRuleBook

The RuleBook for Log Sink configs.

Rules from the rules definition file are parsed and placed into a map, which associates the applies_to value and GCP resource (project, folder, billing_account or organization) with the rules defined for it.

Resources are evaulated against matching rules defined with applies_to = “self”. Project resources are also evaulated against rules for ancestor resources defined with applies_to = “children”.

__eq__(other)[source]

Equals.

Parameters:other (object) – Object to compare.
Returns:True or False.
Return type:bool
__ne__(other)[source]

Not Equals.

Parameters:other (object) – Object to compare.
Returns:True or False.
Return type:bool
__repr__()[source]

Object representation.

Returns:The object representation.
Return type:str
_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 186
_abc_registry = <_weakrefset.WeakSet object>
add_rule(rule_def, rule_index)[source]

Add a rule to the rule book.

The rule supplied to this method is the dictionary parsed from the rules definition file.

For example, this rule…

# rules yaml: rules:

  • name: a rule mode: required resource:

    • type: organization applies_to: children resource_ids:

      • 11223344
    sink:
    • destination: ‘bigquery.googleapis.com/projects/my-proj/’ filter: ‘logName:”logs/cloudaudit.googleapis.com”’ include_children: ‘

… gets parsed into:

{

‘name’: ‘a rule’, ‘mode’: ‘required’, ‘resource’: [{

‘type’: ‘organization’, ‘applies_to’: ‘children’, ‘resource_ids’: [‘11223344’]

}], ‘sink’: {

‘destination’: ‘bigquery.googleapis.com/projects/my-proj/’, ‘filter’: logName:”logs/cloudaudit.googleapis.com”’, ‘include_children’: ‘

}

}

Parameters:
  • rule_def (dict) – Contains rule definition properties.
  • rule_index (int) – The index of the rule from the rule definitions. Assigned automatically when the rule book is built.
add_rules(rule_defs)[source]

Add rules to the rule book.

Parameters:rule_defs (dict) – Rules parsed from the rule definition file.
find_violations(resource, log_sinks)[source]

Find Log Sink violations in the rule book.

Parameters:
  • resource (gcp_type) – The resource that the log sinks belong to.
  • log_sinks (list) – list of LogSinks for resource.
Returns:

A generator of the rule violations.

Return type:

iterable

supported_resource_types = frozenset(['project', 'organization', 'folder', 'billing_account'])
supported_rule_applies_to = frozenset(['self', 'children'])
class LogSinkRulesEngine(rules_file_path, snapshot_timestamp=None)[source]

Bases: google.cloud.forseti.scanner.audit.base_rules_engine.BaseRulesEngine

Rules engine for Log Sinks.

add_rules(rules)[source]

Add rules to the rule book.

Parameters:rules (list) – The list of rules to add to the book.
build_rule_book(global_configs=None)[source]

Build LogSinkRuleBook from the rules definition file.

Parameters:global_configs (dict) – Global configurations.
find_violations(resource, log_sinks, force_rebuild=False)[source]

Determine whether a resources’s log sink config violates rules.

Parameters:
  • resource (gcp_type) – The resource that the log sinks belong to.
  • log_sinks (list) – list of LogSinks for resource.
  • force_rebuild (bool) – If True, rebuilds the rule book. This will reload the rules definition file and add the rules to the book.
Returns:

A generator of rule violations.

Return type:

iterable

class Rule(rule_name, rule_index, rule)[source]

Bases: object

Rule properties from the rule definition file. Also finds violations.

class RuleViolation(resource_type, resource_id, full_name, rule_name, rule_index, violation_type, sink_destination, sink_filter, sink_include_children, resource_data, resource_name)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

__repr__()

Return a nicely formatted representation string

_asdict()

Return a new OrderedDict which maps field names to their values

_fields = ('resource_type', 'resource_id', 'full_name', 'rule_name', 'rule_index', 'violation_type', 'sink_destination', 'sink_filter', 'sink_include_children', 'resource_data', 'resource_name')
classmethod _make(iterable, new=<built-in method __new__ of type object>, len=<built-in function len>)

Make a new RuleViolation object from a sequence or iterable

_replace(**kwds)

Return a new RuleViolation object replacing specified fields with new values

full_name
resource_data
resource_id
resource_name
resource_type
rule_index
rule_name
sink_destination
sink_filter
sink_include_children
violation_type
find_violations(resource, log_sinks)[source]

Find Log Sink violations in the rule book.

Parameters:
  • resource (gcp_type) – The resource that the log sinks belong to.
  • log_sinks (list) – list of log sinks for resource.
Yields:

namedtuple – Returns RuleViolation named tuple.

_find_blacklist_violations(rule_def, sinks)[source]

Returns log sinks that match the rule definition.

Parameters:
  • rule_def (dict) – sink blacklist rule definition.
  • sinks (list) – list of LogSinks to be matched against blacklist.
Returns:

All LogSinks in sinks that violate the blacklist.

Return type:

list

_find_whitelist_violations(rule_def, sinks)[source]

Returns log sinks that DON’T match the rule definition.

Parameters:
  • rule_def (dict) – sink whitelist rule definition.
  • sinks (list) – list of LogSinks to be matched against whitelist.
Returns:

All LogSinks in sinks that violate the whitelist.

Return type:

list

_parse_sink_rule_spec(sink_spec)[source]

Validates and escapes a sink from a rule config.

Parameters:sink_spec (dict) – A sink definition from a LogSink rule definition.
Returns:A sink definition with fields escaped and globified, or None if sink_spec is invalid.
Return type:dict
_required_sink_missing(rule_def, sinks)[source]

Returns True if no sink matches the rule definition.

Parameters:
  • rule_def (dict) – required sink rule definition.
  • sinks (list) – list of LogSinks to be matched against required sink.
Returns:

True if at least one log sink matches the required sink.

Return type:

bool

_sink_matches_rule(rule_def, sink)[source]

Returns true if the log sink matches the rule’s sink definition.

Parameters:
  • rule_def (dict) – sink rule definition.
  • sink (LogSink) – sink being matched to the rule definition.
Returns:

True if sink matches rule definition.

Return type:

bool