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: exceptions.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(['blacklist', 'matches', 'whitelist', 'required'])¶

__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 = 207¶

_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:	RuleDoesntExistError – Raised if a rule included in the group does not exist. GroupDoesntExistError – Raised if a group included in an org policy does not exist. InvalidOrgDefinition – Raised if org policy doesn’t have resources.

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:	DuplicateFirewallGroupError – Raised if the group id already exists. RuleDoesntExistError – Raised if a rule included in the group does not exist. InvalidGroupDefinition – Raised if a group definition is invalid.

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.

__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_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

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