google.cloud.forseti.scanner.audit.audit_logging_rules_engine module

Cloud Audit Logging rules engine for organizations, folders, and projects.

Builds the RuleBook (AuditLoggingRuleBook) from the rule definitions (file either stored locally or in GCS) and compares a resource’s enabled audit logs against the RuleBook to determine whether there are violations.

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

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

The RuleBook for Audit Logging configs.

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

A project’s merged IamAuditConfig is evaulated against rules for all ancestor resources of that project.

__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 = 214
_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 resource:

    • type: project resource_ids:

      • my-project-123

    service: allServices log_types:

    • ‘ADMIN_READ’
    • ‘DATA_WRITE’
    allowed_exemptions:
    • ‘user:user1@org.com’
    • ‘user:user2@org.com’

… gets parsed into:

{

‘name’: ‘a rule’, ‘resource’: {

‘type’: ‘project’, ‘resource_ids’: [‘my-project-id’]

}, ‘service’: ‘allServices’, ‘log_types’: [

‘ADMIN_READ’, ‘DATA_WRITE’,

], ‘allowed_exemptions’: [

‘user:user1@org.com’, ‘user:user2@org.com’,

]

}

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(project, audit_config)[source]

Find Cloud Audit Logging violations in the rule book.

Parameters:
  • project (gcp_type) – The project that has this configuation.
  • audit_config (IamAuditConfig) – The audit config for this project, merged with ancestor configs.
Returns:

A generator of the rule violations.

Return type:

iterable

supported_resource_types = frozenset({'project', 'organization', 'folder'})
class AuditLoggingRulesEngine(rules_file_path, snapshot_timestamp=None)[source]

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

Rules engine for Cloud Audit Logging.

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 AuditLoggingRuleBook from the rules definition file.

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

Determine whether a project’s audit logging config violates rules.

Parameters:
  • project (gcp_type) – The project with audit log config.
  • audit_config (IamAuditConfig) – The audit config for this project, merged with ancestor configs.
  • 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, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data)

Bases: tuple

__getnewargs__()

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

static __new__(_cls, resource_type, resource_id, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data)

Create new instance of RuleViolation(resource_type, resource_id, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data)

__repr__()

Return a nicely formatted representation string

_asdict()

Return a new OrderedDict which maps field names to their values.

_fields = ('resource_type', 'resource_id', 'resource_name', 'full_name', 'rule_name', 'rule_index', 'violation_type', 'service', 'log_type', 'unexpected_exemptions', 'resource_data')
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

_source = "from builtins import property as _property, tuple as _tuple\nfrom operator import itemgetter as _itemgetter\nfrom collections import OrderedDict\n\nclass RuleViolation(tuple):\n 'RuleViolation(resource_type, resource_id, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data)'\n\n __slots__ = ()\n\n _fields = ('resource_type', 'resource_id', 'resource_name', 'full_name', 'rule_name', 'rule_index', 'violation_type', 'service', 'log_type', 'unexpected_exemptions', 'resource_data')\n\n def __new__(_cls, resource_type, resource_id, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data):\n 'Create new instance of RuleViolation(resource_type, resource_id, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data)'\n return _tuple.__new__(_cls, (resource_type, resource_id, resource_name, full_name, rule_name, rule_index, violation_type, service, log_type, unexpected_exemptions, resource_data))\n\n @classmethod\n def _make(cls, iterable, new=tuple.__new__, len=len):\n 'Make a new RuleViolation object from a sequence or iterable'\n result = new(cls, iterable)\n if len(result) != 11:\n raise TypeError('Expected 11 arguments, got %d' % len(result))\n return result\n\n def _replace(_self, **kwds):\n 'Return a new RuleViolation object replacing specified fields with new values'\n result = _self._make(map(kwds.pop, ('resource_type', 'resource_id', 'resource_name', 'full_name', 'rule_name', 'rule_index', 'violation_type', 'service', 'log_type', 'unexpected_exemptions', 'resource_data'), _self))\n if kwds:\n raise ValueError('Got unexpected field names: %r' % list(kwds))\n return result\n\n def __repr__(self):\n 'Return a nicely formatted representation string'\n return self.__class__.__name__ + '(resource_type=%r, resource_id=%r, resource_name=%r, full_name=%r, rule_name=%r, rule_index=%r, violation_type=%r, service=%r, log_type=%r, unexpected_exemptions=%r, resource_data=%r)' % self\n\n def _asdict(self):\n 'Return a new OrderedDict which maps field names to their values.'\n return OrderedDict(zip(self._fields, self))\n\n def __getnewargs__(self):\n 'Return self as a plain tuple. Used by copy and pickle.'\n return tuple(self)\n\n resource_type = _property(_itemgetter(0), doc='Alias for field number 0')\n\n resource_id = _property(_itemgetter(1), doc='Alias for field number 1')\n\n resource_name = _property(_itemgetter(2), doc='Alias for field number 2')\n\n full_name = _property(_itemgetter(3), doc='Alias for field number 3')\n\n rule_name = _property(_itemgetter(4), doc='Alias for field number 4')\n\n rule_index = _property(_itemgetter(5), doc='Alias for field number 5')\n\n violation_type = _property(_itemgetter(6), doc='Alias for field number 6')\n\n service = _property(_itemgetter(7), doc='Alias for field number 7')\n\n log_type = _property(_itemgetter(8), doc='Alias for field number 8')\n\n unexpected_exemptions = _property(_itemgetter(9), doc='Alias for field number 9')\n\n resource_data = _property(_itemgetter(10), doc='Alias for field number 10')\n\n"
full_name
log_type
resource_data
resource_id
resource_name
resource_type
rule_index
rule_name
service
unexpected_exemptions
violation_type
find_violations(project, audit_config)[source]

Find Cloud Audit Logging violations in the rule book. :param project: The project that has this configuation. :type project: gcp_type :param audit_config: The audit config for this project,

merged with ancestor configs.
Yields:namedtuple – Returns RuleViolation named tuple.