google.cloud.forseti.scanner.audit.firewall_rules_engine module

Rules engine for firewall rules.

exception DuplicateFirewallGroupError[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if group id is reused in the group definitions, must be unique.

exception DuplicateFirewallRuleError[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if a rule id is reused in the rule definitions, must be unique.

exception Error[source]

Bases: Exception

Base error class for the module.

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

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

Rules engine for firewall resources.

build_rule_book(global_configs)[source]

Build RuleBook from the rule definition file.

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

Determine whether policy violates rules.

Parameters:
  • resource (Resource) – The resource that the policy belongs to.
  • policy (dict) – The policy to compare against the rules.
  • 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 list of the rule violations.

Return type:

list

exception GroupDoesntExistError[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if an org policy tries to add a group that doesn’t exist.

exception InvalidGroupDefinition[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if a group definition is invalid.

exception InvalidOrgDefinition[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if a org definition is invalid.

exception InvalidRuleDefinition[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if a rule definition is invalid.

class Rule(rule_id=None, match_policies=None, verify_policies=None, mode='whitelist', exact_match=True)[source]

Bases: object

Rule properties from the firewall rules definitions file. Also finds violations.

VALID_RULE_MODES = frozenset({'required', 'blacklist', 'whitelist', 'matches'})
__hash__()[source]

Makes a hash of the rule id.

Returns:The hash of the rule id.
Return type:int
_create_violation(policies, violation_type, recommended_actions=None)[source]

Creates a RuleViolation.

Parameters:
  • policies (list) – A list of FirewallRule that violate the policy.
  • violation_type (str) – The type of violation.
  • recommended_actions (list) – The list of actions to take.
Returns:

A RuleViolation for the given policies.

Return type:

RuleViolation

Raises:

ValueError – If no policies are passed in.

_yield_blacklist_violations(firewall_policies)[source]

Finds blacklisted policies.

Parameters:firewall_policies (list) – A list of FirewallRules to check.
Yields:iterable – A generator of RuleViolations.
_yield_match_violations(firewall_policies)[source]

Finds policies that don’t match the required policy.

Parameters:firewall_policies (list) – A list of FirewallRules to check.
Yields:iterable – A generator of RuleViolations.
_yield_required_violations(firewall_policies)[source]

Finds missing policies that are required.

Parameters:firewall_policies (list) – A list of FirewallRules to check.
Yields:iterable – A generator of RuleViolations.
_yield_whitelist_violations(firewall_policies)[source]

Finds policies that aren’t whitelisted.

Parameters:firewall_policies (list) – A list of FirewallRules to check.
Yields:iterable – A generator of RuleViolations.
static create_rules(policies, validate=False)[source]

Creates FirewallRules from policies.

Parameters:
  • policies (list) – A list of policy dictionaries.
  • validate (bool) – Whether to validate that this is a valid firewall rule (one that can be passed to the API).
Returns:

A list of FirewallRule.

Return type:

list

find_violations(firewall_policies)[source]

Finds policy violations in a list of firewall policies.

Parameters:firewall_policies (list) – A list of FirewallRule.
Returns:A generator of RuleViolations.
Return type:iterable
classmethod from_config(rule_def)[source]

Creates a Rule from a config file.

Parameters:rule_def (dict) – A dictionary rule definition parsed from YAML config.
Returns:A rule created from the rule definition.
Return type:Rule
Raises:InvalidRuleDefinition – If rule is missing required fields.
match_rules

The FirewallRules used to filter policies.

Returns:A list of FirewallRule.
Return type:list
verify_rules

The FirewallRules used to check policies.

Returns:A list of FirewallRule.
Return type:list
class RuleBook(rule_defs=None, snapshot_timestamp=None, group_defs=None, org_policy=None)[source]

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

The RuleBook for firewall auditing.

Rules from the rules definition file are parsed and then the hierarchy and enforcement points are parsed. Rules then are assessed at the first applicable point in the ancestory tree that has rules.

Sample org structure:

org 1234

/ f-1 p-c

/ p-a p-b

Rules can be applied at any node above. When a policy is being audited, it the rulebook will start at the lowest level (the project) and will walk up the hierarchy until it reaches the first instance with rules and these are the only rules that are checked.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 214
_abc_registry = <_weakrefset.WeakSet object>
add_org_policy(org_def)[source]

Creates org policy and rule mapping.

Sample org structure:

org 1234

/ f-1 p-c

/ p-a p-b

Rules can be applied at any node above. When a policy is being audited, it the rulebook will start at the lowest level (the project) and will walk up the hierarchy until it reaches the first instance with rules and these are the only rules that are checked.

Parameters:

org_def (dict) – A dictionary of resource ids and enforced rules.

Raises:
add_rule(rule_def, rule_index)[source]

Adds a rule to the rule book.

Parameters:
  • rule_def (Rule) – A Rule used to check for violations.
  • rule_index (int) – Used for logs.
Raises:

DuplicateFirewallRuleError – When the rule by the same name exists.

add_rule_groups(group_defs)[source]

Creates group to rule matching.

Parameters:

group_defs (dict) – A dictionary with a group id and a list of rule ids that will be included by including this group in a policy.

Raises:
add_rules(rule_defs)[source]

Adds rules to rule book.

Parameters:rule_defs (list) – Rule definition dictionaries from yaml config file.
Raises:InvalidRuleDefinition – If the rule is missing required fields or the fields have invalid values.
find_violations(resource, policies)[source]

Find policy binding violations in the rule book.

Parameters:
  • resource (Resource) – 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).
  • policies (list) – A list of FirewallRule policies.
Returns:

A generator of the rule violations.

Return type:

iterable

exception RuleDoesntExistError[source]

Bases: google.cloud.forseti.scanner.audit.firewall_rules_engine.Error

Raised if a rule group tries to add a rule that doesn’t exist.

class RuleViolation(resource_type, resource_id, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name)

Bases: tuple

__getnewargs__()

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

static __new__(_cls, resource_type, resource_id, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name)

Create new instance of RuleViolation(resource_type, resource_id, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name)

__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_id', 'violation_type', 'policy_names', 'recommended_actions', '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

_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, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name)'\n\n __slots__ = ()\n\n _fields = ('resource_type', 'resource_id', 'full_name', 'rule_id', 'violation_type', 'policy_names', 'recommended_actions', 'resource_data', 'resource_name')\n\n def __new__(_cls, resource_type, resource_id, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name):\n 'Create new instance of RuleViolation(resource_type, resource_id, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name)'\n return _tuple.__new__(_cls, (resource_type, resource_id, full_name, rule_id, violation_type, policy_names, recommended_actions, resource_data, resource_name))\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) != 9:\n raise TypeError('Expected 9 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', 'full_name', 'rule_id', 'violation_type', 'policy_names', 'recommended_actions', 'resource_data', 'resource_name'), _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, full_name=%r, rule_id=%r, violation_type=%r, policy_names=%r, recommended_actions=%r, resource_data=%r, resource_name=%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 full_name = _property(_itemgetter(2), doc='Alias for field number 2')\n\n rule_id = _property(_itemgetter(3), doc='Alias for field number 3')\n\n violation_type = _property(_itemgetter(4), doc='Alias for field number 4')\n\n policy_names = _property(_itemgetter(5), doc='Alias for field number 5')\n\n recommended_actions = _property(_itemgetter(6), doc='Alias for field number 6')\n\n resource_data = _property(_itemgetter(7), doc='Alias for field number 7')\n\n resource_name = _property(_itemgetter(8), doc='Alias for field number 8')\n\n"
full_name
policy_names
recommended_actions
resource_data
resource_id
resource_name
resource_type
rule_id
violation_type
is_blacklist_violation(rules, policy)[source]

Checks if the policy is a superset of any not allowed by the rules.

Parameters:
  • rules (list) – A list of FirewallRule that the policy must be a subset of.
  • policy (FirweallRule) – A FirewallRule.
Returns:

If the policy is a superset of one of the blacklisted rules or not.

Return type:

bool

is_rule_exists_violation(rule, policies, exact_match=True)[source]

Checks if the rule is the same as one of the policies.

Parameters:
  • rule (FirweallRule) – A FirewallRule.
  • policies (list) – A list of FirewallRule that must have the rule.
  • exact_match (bool) – Whether to match the rule exactly.
Returns:

If the required rule is in the policies.

Return type:

bool

is_whitelist_violation(rules, policy)[source]

Checks if the policy is not a subset of those allowed by the rules.

Parameters:
  • rules (list) – A list of FirewallRule that the policy must be a subset of.
  • policy (FirweallRule) – A FirewallRule.
Returns:

If the policy is a subset of one of the allowed rules or not.

Return type:

bool