google.cloud.forseti.scanner.audit.iam_rules_engine module

Rules engine for organizations, folders, and projects.

Builds the RuleBook (IamRuleBook) from the rule definitions (file either stored locally or in GCS) and compares a policy against the RuleBook to determine whether there are violations.

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

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

The RuleBook for organization resources.

Rules from the rules definition file are parsed and placed into a map, which associates the GCP resource with the particular rules defined for it.

Sample rules (simplified):

mode: whitelist Org 1234, bindings: roles/*, members: user:*@company.com Project p-a, bindings: roles/owner, members: user:pa-owner@company.com Project p-b, bindings: roles/owner, members: user:pb-owner@company.com

Sample org structure:

org 1234

/ f-1 p-c

/ p-a p-b

The rule book will be structured as:

{
Resource(org-1234): ResourceRule(org-1234, [ rules … ]), Resource(p-a): ResourceRule(p-a, [ rules … ]), Resource(p-a): ResourceRule(p-a, [ rules … ])

}

__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 = 207
_abc_registry = <_weakrefset.WeakSet object>
_get_resource_rules(resource)[source]

Get all the resource rules for (resource, RuleAppliesTo.*).

Parameters:resource (Resource) – The resource to find in the ResourceRules map.
Returns:A list of ResourceRules.
Return type:list
static _rule_applies_to_resource(resource, curr_resource, resource_rule)[source]

Check whether rules match if the applies_to condition is met.

SELF: check rules if the starting resource == current resource CHILDREN: check rules if starting resource != current resource SELF_AND_CHILDREN: always check rules

Parameters:
  • resource (Resource) – The main resource we’re checking the rule against.
  • curr_resource (Resource) – A resource that is in the main resource’s ancestry.
  • resource_rule (ResourceRule) – The rule associated with the resource.
Returns:

True if rule applies to the resource, otherwise false.

Return type:

bool

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: whitelist resource:

    • type: project applies_to: self resource_ids:

      • my-project-123

    inherit_from_parents: true bindings:

    • role: roles/editor members:

      • users:a@b.com

… gets parsed into:

{

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

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

}, ‘inherit_from_parents’: true, ‘bindings’: [

{
‘role’: ‘roles/editor’, ‘members’: [‘users:a@b.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(resource, policy, policy_bindings)[source]

Find policy binding violations in the rule book.

Parameters:
  • resource (gcp_type) – The GCP resource associated with the policy binding. This is where we start looking for rule violations and we move up the resource hierarchy (if permitted by the resource’s “inherit_from_parents” property).
  • policy (forseti_data_model_resource) – The policy to compare against the rules. See https://cloud.google.com/iam/reference/rest/v1/Policy.
  • policy_bindings (list) – A list of IamPolicyBindings.
Returns:

A generator of the rule violations.

Return type:

iterable

class IamRulesEngine(rules_file_path, snapshot_timestamp=None)[source]

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

Rules engine for org resources.

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)[source]

Build IamRuleBook from the rules definition file.

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

Determine whether policy violates rules.

Parameters:
  • resource (gcp_type) – The resource that the policy belongs to.
  • policy (resource) – The policy to compare against the rules. See https://cloud.google.com/iam/reference/rest/v1/Policy.
  • policy_bindings (list) – list of bindings found in policy.data
  • 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 ResourceRules(resource=None, rules=None, applies_to='self', inherit_from_parents=False)[source]

Bases: object

An association of a resource to rules.

__eq__(other)[source]

Equals

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

Not Equals

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

Object representation.

Returns:The object representation.
Return type:str
_check_required_rules(resource, rule, policy_bindings)[source]

Check required rule.

Parameters:
  • resource (Resource) – The resource that the policy belongs to.
  • policy_bindings (list) – The list of IamPolicyBindings.
  • rule (Rule) – The rule to check.
Yields:

iterable – A generator of RuleViolations.

_check_whitelistblacklist_rules(resource, rule, policy_bindings)[source]

Check whitelist and blacklist rules.

Parameters:
  • resource (Resource) – The resource that the policy belongs to.
  • rule (Rule) – The rule to check.
  • policy_bindings (list) – The list of IamPolicyBindings.
Yields:

iterable – A generator of RuleViolations.

_dispatch_rule_mode_check(mode, rule_members=None, policy_members=None)[source]

Determine which rule mode method to execute for rule audit.

Parameters:
  • mode (str) – The rule mode.
  • rule_members (list) – The rule binding members.
  • policy_members (list) – The policy binding members.
Returns:

The result of calling the dispatched method.

Return type:

list

find_mismatches(resource, policy_bindings)[source]

Determine if the policy binding matches this rule’s criteria.

How the member matching operates:

  1. Whitelist: policy members match at least one rule member
  2. Blacklist: policy members must not match any rule members
  3. Require: rule members must all be found in policy members
Parameters:
  • resource (Resource) – The resource that the policy belongs to.
  • policy_bindings (list) – The list of IamPolicyBindings to compare to this rule’s bindings.
Returns:

The violations generator

Return type:

iterable

_check_blacklist_members(rule_members=None, policy_members=None)[source]

Blacklist: Check that policy members ARE NOT in rule members.

If a policy member is found in the rule members, add it to the violating members.

Parameters:
  • rule_members (list) – IamPolicyMembers allowed in the rule.
  • policy_members (list) – IamPolicyMembers in the policy.
Returns:

Policy members found in the blacklist (rule members).

Return type:

list

_check_required_members(rule_members=None, policy_members=None)[source]

Required: Check that rule members are in policy members.

If a required rule member is NOT found in the policy members, add it to the violating members. Note that the check is different: it’s reversed from the whitelist/blacklist (policy as a subset of rules vs rules as subset of policy).

Parameters:
  • rule_members (list) – IamPolicyMembers allowed in the rule.
  • policy_members (list) – IamPolicyMembers in the policy.
Returns:

Rule members not found in the policy (required-whitelist).

Return type:

list

_check_whitelist_members(rule_members=None, policy_members=None)[source]

Whitelist: Check that policy members ARE in rule members.

If a policy member is NOT found in the rule members, add it to the violating members.

Parameters:
  • rule_members (list) – IamPolicyMembers allowed in the rule.
  • policy_members (list) – IamPolicyMembers in the policy.
Returns:

Policy members NOT found in the whitelist (rule members).

Return type:

list