This page describes how to define rules for Forseti Scanner.
You can find some sample rules in the
rules
directory. When you make changes to the rule files, upload them to your
Forseti bucket under forseti-server-xxxx/rules/
or copy them to the rules_path
listed in forseti_server_conf.yaml
.
BigQuery scanner rules can be blacklists or whitelists, for example:
rules:
- name: sample BigQuery rule to search for public datasets
mode: blacklist
resource:
- type: organization
resource_ids:
- YOUR_ORG_ID / YOUR_PROJECT_ID
dataset_ids: ['*']
bindings:
- role: '*'
members:
- special_group: 'allAuthenticatedUsers'
name
resource
type
organization
, billing_account
, folder
,
project
, bucket
or dataset
.resource_ids
*
to match for all.dataset_ids
*
to match for all.bindings
role
OWNER
, WRITER
or READER
.members
domain
group_email
user_email
special_group
special_group
*
to match for all.domain
*
to match for all.role
OWNER
, WRITER
or READER
.group_email
*
to match for all.user_email
*
to match for all.The BigQuery Scanner rules specify entities that are allowed or not allowed
(depending on mode) to access your datasets.
For blacklists, when you set a value of *
for special_group
, user_email
,
domain
, or group_email
, the Scanner checks to make sure that no entities that
have the field set can access your datasets. If you specify any other value, the
Scanner only checks to make sure that the entity you specified doesn’t have access.
For whitelists, the specified entity specifies who has access to your datasets.
Any entity that does not match a whitelist binding will be marked as a violation.
rules:
- blacklist: Emerging Threat blacklist
url: https://rules.emergingthreats.net/fwrules/emerging-Block-IPs.txt
rules:
- name: sample audit logging rule for data access logging
resource:
- type: project
resource_ids:
- '*'
service: 'storage.googleapis.com'
log_types:
- 'DATA_READ'
- 'DATA_WRITE'
allowed_exemptions:
- 'user:user1@MYDOMAIN.com'
- 'user:user2@MYDOMAIN.com'
name
resource
type
organization
, folder
or project
.resource_ids
*
to match for all.service
allServices
denotes audit logs for all services.allServices
, storage.googleapis.com
log_types
ADMIN_READ
, DATA_READ
or DATA_WRITE
.allowed_exemptions
user:user1@MYDOMAIN.com
This section describes rules for Cloud Identity and Access Management (Cloud IAM).
Forseti Scanner recognizes the following rule grammar in YAML or JSON:
rules:
- name: $rule_name
mode: $rule_mode
resource:
- type: $resource_type
applies_to: $applies_to
resource_ids:
- $resource_id1
- $resource_id2
- ...
inherit_from_parents: $inherit_from
bindings:
- role: $role_name
members:
- $member1
- $member2
...
name
mode
whitelist
, blacklist
or required
.whitelist
: Allow the members defined.blacklist
: Block the members defined.required
: Defined members with the specified roles must be found in policy.resource
type
organization
, folder
or project
.applies_to
self
, children
or self_and_children
.self
: Allow the members defined.children
: Block the members defined.self_and_children
: The rule applies to the specified resource and its child resources.resource_ids
*
to match for all.inherit_from_parents
true
or false
.bindings
role
roles/editor
, roles/viewer
members
serviceAccount:*@*gserviceaccount.com
(all service accounts) or
user:*@company.com
(anyone with an identity at company.com).This section describes rules for Cloud Identity-Aware Proxy (Cloud IAP).
rules:
# custom rules
- name: Allow direct access from debug IPs and internal monitoring hosts
resource:
- type: organization
applies_to: self_and_children
resource_ids:
- YOUR_ORG_ID
inherit_from_parents: true
allowed_direct_access_sources: '10.*,monitoring-instance-tag'
name
mode
whitelist
, blacklist
or required
.whitelist
: Allow the members defined.blacklist
: Block the members defined.required
: Defined members with the specified roles must be found in policy.resource
type
organization
, folder
or project
.applies_to
self
, children
or self_and_children
.self
: Allow the members defined.children
: Block the members defined.self_and_children
: The rule applies to the specified resource and its child resources.resource_ids
*
to match for all.inherit_from_parents
true
or false
.allowed_direct_access_sources
10.*,monitoring-instance-tag
rules:
- name: sample Cloud SQL rule to search for publicly exposed instances
instance_name: '*'
authorized_networks: '0.0.0.0/0'
ssl_enabled: 'False'
resource:
- type: organization
resource_ids:
- YOUR_ORG_ID / YOUR_PROJECT_ID
name
resource
type
organization
, folder
or project
.resource_ids
*
to match for all.instance_name
*
to match for all.authorized_networks
0.0.0.0/0
ssl_enabled
true
or false
.rules:
- name: sample bucket acls rule to search for public buckets
bucket: '*'
entity: AllUsers
email: '*'
domain: '*'
role: '*'
resource:
- resource_ids:
- YOUR_ORG_ID / YOUR_PROJECT_ID
name
resource
resource_ids
*
to match for all.bucket
*
to match for all.entity
AllUsers
email
*
to match for all.domain
*
to match for all.role
*
to match for all.For more information, refer to the BucketAccessControls documentation.
rules:
- name: sample enabled APIs whitelist rule
mode: whitelist
resource:
- type: project
resource_ids:
- '*'
services:
- 'bigquery-json.googleapis.com'
- 'compute.googleapis.com'
- 'logging.googleapis.com'
- 'monitoring.googleapis.com'
- 'pubsub.googleapis.com'
- 'storage-api.googleapis.com'
- 'storage-component.googleapis.com'
name
mode
whitelist
, blacklist
or required
.whitelist
: Allow only the APIs listed in services
.blacklist
: Block the APIs listed in services
.required
: All APIs listed in services
must be enabled.resource
type
organization
, folder
or project
.applies_to
self
, children
or self_and_children
.self
: Allow the members defined.children
: Block the members defined.self_and_children
: The rule applies to the specified resource and its child resources.resource_ids
*
to match for all.services
bigquery-json.googleapis.com
, logging.googleapis.com
rules:
- name: Only allow access to projects in my organization.
allowed_ancestors:
- organizations/{ORGANIZATION_ID}
name
allowed_ancestors
users
Firewall Scanner rules can be blacklist
, whitelist
, required
, or matches
policies.
rules:
- rule_id: 'prevent_allow_all_ingress'
description: 'Detect allow tcp and udp ingress from anywhere to all instances'
mode: 'blacklist'
match_policies:
- direction: 'ingress'
allowed: ['*']
sourceRanges: ['0.0.0.0/0']
verify_policies:
- allowed:
- IPProtocol: 'tcp'
ports:
- 'all'
- allowed:
- IPProtocol: 'udp'
ports:
- 'all'
# (...)
# You can chose to group your rules into rule_groups
# to apply them all at once on a resource
rule_groups:
- group_id: 'default_rules'
rule_ids:
- 'prevent_allow_all_ingress'
# (...)
# Bind your rules or rule_groups to resources
org_policy:
resources:
- type: organization
resource_ids:
- YOUR_ORG_ID
rules:
group_ids:
- 'default_rules'
rule_ids:
- 'prevent_allow_all_ingress'
All modes share the same first-level rule structure:
rule_id
prevent_allow_all_ingress
, no_rdp_to_linux
description
mode
blacklist
, whitelist
, required
, matches
.blacklist
: Ensure unauthorized firewall rules raise a violation.whitelist
: Only authorize the policies you define in the rule.required
: Check if firewall rules match one of the match_policies
defined in the rule.matches
: Check if firewall rules match all of the match_policies
defined in the rule.whitelist
and blacklist
rules require match and verify policies.required
and matches
rules only require match policies.match_policies
(applicable to all modes)
direction
:
ingress
, egress
.ingress
traffic, it is NOT supported to specify destinationRanges
.egress
traffic, it is NOT supported to specify sourceRanges
OR sourceTags
.allowed
:
*
to match for all.allowed
or denied
can be used at the same time.denied
:
*
to match for all.allowed
or denied
can be used at the same time.sourceRanges
:
'0.0.0.0/0'
sourceServiceAccounts
:
'PROJECT@compute.gserviceaccount.com'
.sourceTags
:
linux
.destinationRanges
:
egress
, 256 ranges max) A list of destination ranges.'0.0.0.0/0'
targetServiceAccounts
:
'PROJECT@compute.gserviceaccount.com'
.targetTags
:
linux
.direction
of the firewall rules you want to match:
ingress
rules, the target parameter specifies the destination VMs for traffic.egress
rules, the target parameter specifies the source VMs for traffic.source
parameters are only applicable to ingress
rules, ingress
rules cannot include target
parameters.ingress
rules require that you specify one of the following:
sourceRanges
sourceServiceAccounts
sourceRanges
and sourceServiceAccounts
sourceRanges
and sourceTags
target
parameters are only applicable to egress
rules, egress
rules cannot include source
parameters.destinationRanges
is required for egress
rules.verify_policies
(only for blacklist
and whitelist
modes)
allowed
:
IPProtocol
and ports
that describes a permitted connection.IPProtocol
:
TCP
, UDP
, ICMP
, ESP
, AH
, IPIP
, SCTP
, or ALL
.ports
:
TCP
and UDP
protocols.22
, 3389
or a range 0-1024
, or all
(shortcut for 0-65535
).allowed
or denied
can be used at the same time.denied
:
IPProtocol
and ports
that describes a unauthorized connection.IPProtocol
:
TCP
, UDP
, ICMP
, ESP
, AH
, IPIP
, SCTP
, or ALL
.ports
:
TCP
and UDP
protocols.22
, 3389
or a range 0-1024
, or all
(shortcut for 0-65535
).allowed
or denied
can be used at the same time.sourceRanges
:
'0.0.0.0/0'
sourceTags
:
linux
.Sample firewall rules for each mode are available at samples/scanner/scanners/firewall_rules/
.
To learn more, see the Firewalls API Reference
and the Firewall rules in GCP documentation.
rules:
- name: Rule Name Example
target: Forwarding Rule Target Example
mode: whitelist
load_balancing_scheme: EXTERNAL
ip_protocol: ESP
ip_address: "198.51.100.46"
name
target
mode
whitelist
mode.whitelist
: Ensure each forwarding rule only directs to the intended target instance.load_balancing_scheme
INTERNAL
or EXTERNAL
.ip_protocol
TCP
, UDP
, ESP
, AH
, SCTP
, or ICMP
.ip_address
198.51.100.46
To learn more, see the ForwardingRules documentation.
- name: Allow my company users and gmail users to be in my company groups.
group_email: my_customer
mode: whitelist
conditions:
- member_email: '@MYDOMAIN.com'
- member_email: '@gmail.com'
# GCP Service Accounts
# https://cloud.google.com/compute/docs/access/service-accounts
#- member_email: "gserviceaccount.com"
# Big Query Transfer Service
#- member_email: "@bqdts.google.baggins"
rules:
- name: default
mode: whitelist
only_iam_groups: True
groups_emails:
- '*'
settings:
allowExternalMembers: True
whoCanJoin: "INVITED_CAN_JOIN"
whoCanInvite: "ALL_MANAGERS_CAN_INVITE"
whoCanAdd: "ALL_MANAGERS_CAN_ADD"
allowExternalMembers: False
whoCanLeaveGroup: "ALL_MANAGERS_CAN_LEAVE"
name
mode
only_iam_groups
group_emails
*
to match all.settings
rules:
# This rule helps with:
# #1 Ensure instances with external IPs are only running
# on whitelisted networks
# #2 Ensure instances are only running on networks created in allowed
# projects (using XPN)
- name: all networks covered in whitelist
project: '*'
network: '*'
is_external_network: True
# this would be a custom list of your networks/projects.
whitelist:
project-1:
- network-1
project-2:
- network-2
- network-2-2
project-3:
- network-3
name
project
*
to match for all.network
*
to match for all.whitelist
Example values: The following values would specify that VM instances in project_01’s network_01 can have external IP addresses:
project_01:
- network_01
rules:
- name: sample rule to allow symmetric keys with this configuration
mode: whitelist
resource:
- type: organization
resource_ids:
- '*'
key:
- rotation_period: 100 #days
algorithm:
- GOOGLE_SYMMETRIC_ENCRYPTION
protection_level: SOFTWARE
purpose:
- ENCRYPT_DECRYPT
state:
- ENABLED
name
mode
blacklist
or whitelist
.whitelist
: Allow the crypto key configuration defined.blacklist
: Block the crypto key configuration defined.resource
type
organization
is supported.resource_ids
*
to match for all.key
rotation_period
algorithms
GOOGLE_SYMMETRIC_ENCRYPTION
, EC_SIGN_P256_SHA256
protection_level
SOFTWARE
or HSM
.purpose
ENCRYPT_DECRYPT
, ASYMMETRIC_SIGN
and
ASYMMETRIC_DECRYPT
.state
PENDING_GENERATION
, ENABLED
, DISABLED
,
DESTROY_SCHEDULED
and DESTROYED
.rules:
- name: logging should be enabled
resource:
- type: project
resource_ids:
- '*'
key: loggingService
mode: whitelist
values:
- logging.googleapis.com
name
resource
type
organization
, folder
or project
.resource_ids
*
to match for all.key
Description: A JMESPath expression that extracts values from the JSON representation of a GKE cluster.
Tip: to find the JSON representation of your cluster use
gcloud --format=json container clusters describe <name>
Valid values: String, must be a well-formed JMESPath expression.
mode
whitelist
or blacklist
.` values
mode
is set to whitelist
, the rule generates a violation
if the value extracted from a cluster is NOT on this list.mode
is set to blacklist
, the rule generates a violation
if the value extracted from a cluster IS on the list.Valid values: A list of any valid YAML values.
Tip: Pay attention to the data types that you enter here. If
the JMESPath expression in key
extracts an integer, you probably
want integers in this list. Similarly, if the expression extracts
a list of values, you need to provide lists.
rules:
- name: Nodepool version not patched for critical security vulnerabilities
resource:
- type: organization
resource_ids:
- '*'
check_serverconfig_valid_node_versions: false
check_serverconfig_valid_master_versions: false
allowed_nodepool_versions:
- major: '1.6'
minor: '13-gke.1'
operator: '>='
- major: '1.7'
minor: '11-gke.1'
operator: '>='
- major: '1.8'
minor: '4-gke.1'
operator: '>='
- major: '1.9'
operator: '>='
name
resource
type
organization
, folder
or project
.resource_ids
*
to match for all.check_serverconfig_valid_node_versions
true
or false
.check_serverconfig_valid_master_versions
true
or false
.allowed_nodepool_versions
major
1.6
, 1.7
, 1.8
minor
11-gke.1
, 12-gke.1
operator
>=
rules:
- name: Require project deletion liens for all projects in the organization.
mode: required
resource:
- resource_ids:
- org-1
type: organization
restrictions:
- resourcemanager.projects.delete
name
mode
required
.resource
type
organization
, folder
or project
.resource_ids
restrictions
resourcemanager.projects.delete
.rules:
- name: All buckets in organization must be in the US.
mode: whitelist
resource:
- type: organization
resource_ids:
- org-1
applies_to:
- type: 'bucket'
resource_ids: '*'
locations:
- 'us*'
- name: All buckets in organization must not be in EU.
mode: blacklist
resource:
- type: organization
resource_ids:
- org-1
applies_to:
- type: 'bucket'
resource_ids: '*'
locations:
- 'eu*'
name
mode
blacklist
or whitelist
.resource
type
organization
, folder
or project
.resource_ids
applies_to
type
bucket
, cloudsqlinstance
, dataset
,
instance
or kubernetes_cluster
.resource_ids
locations
:
rules:
- name: 'Require BigQuery Audit Log sinks in all projects.'
mode: required
resource:
- type: organization
applies_to: children
resource_ids:
- org-1
sink:
destination: 'bigquery.googleapis.com/*'
filter: 'logName:"logs/cloudaudit.googleapis.com"'
include_children: '*'
name
mode
required
, blacklist
or whitelist
.resource
type
organization
, folder
or project
.resource_ids
applies_to
self
, children
or self_and_children
.sink
destination
filter
include_children
true
, false
or *
. *
means the rule will match sinks with either true or false.rules:
- name: All buckets and bigquery tables in the organization should have a retention policy for 100 to 200 days.
applies_to:
- bucket
- bigquery_table
resource:
- type: organization
resource_ids:
- "123456789012"
minimum_retention: 100 # days
maximum_retention: 200 # days
name
applies_to
type
bucket
and bigquery_table
.resource
type
organization
, folder
, project
, bucket
,
or bigquery_table
.resource_ids
minimum_retention
maximum_retention
Valid values: Integer, number of days.
Tip: The rule must include a minimum_retention, maximum_retention or both.
rules:
# The max allowed age of user managed service account keys (in days)
- name: Service account keys not rotated
resource:
- type: organization
resource_ids:
- '*'
max_age: 100 # days
name
type
organization
, folder
or project
.resource_ids
*
to match for all.max_age