Contributing GCP plugin

Signed-off-by: ahmedameenaim <[email protected]>
falcosecurity · Jul 17, 2023 · 5096caf · 5096caf
1 parent 5bbc310
commit 5096caf
Show file tree

Hide file tree

Showing 14 changed files with 1,403 additions and 0 deletions.
diff --git a/plugins/gcp/.gitignore b/plugins/gcp/.gitignore
diff --git a/plugins/gcp/CHANGELOG.md b/plugins/gcp/CHANGELOG.md
@@ -0,0 +1,43 @@
+# Changelog
+
+## v0.6.0
+
+* [`ae6e3ed`](https://github.com/falcosecurity/plugins/commit/ae6e3ed) docs(plugins/dummy): update readme according to new plugin version
+
+* [`9563397`](https://github.com/falcosecurity/plugins/commit/9563397) update(plugins/dummy): bump plugin version to 0.6.0
+
+* [`aa9a20d`](https://github.com/falcosecurity/plugins/commit/aa9a20d) refactor(plugins/dummy): modify plugin open parameters for modern SDK approaches
+
+
+## v0.5.0
+
+* [`30f4fac`](https://github.com/falcosecurity/plugins/commit/30f4fac) update(plugins/dummy): bump version to 0.5.0
+
+
+## v0.4.0
+
+* [`41696f9`](https://github.com/falcosecurity/plugins/commit/41696f9) update(plugins/dummy): adapt plugin for plugin-sdk-go v0.4.0
+
+
+## v0.3.0
+
+* [`ab3491f`](https://github.com/falcosecurity/plugins/commit/ab3491f) refactor(plugins/dummy): create package directory
+
+
+## v0.2.1
+
+
+## v0.2.0
+
+* [`c91c2cc`](https://github.com/falcosecurity/plugins/commit/c91c2cc) update(dummy): bump plugin version to 0.2.0
+
+* [`e200fde`](https://github.com/falcosecurity/plugins/commit/e200fde) update(dummy): bump plugin version to 0.2.0
+
+* [`50526ed`](https://github.com/falcosecurity/plugins/commit/50526ed) update(dummy): support init config schema in dummy plugin
+
+
+## v0.1.0
+
+* [`e507a7f`](https://github.com/falcosecurity/plugins/commit/e507a7f) refactor(dummy): update dummy to new SDK design
+
+
diff --git a/plugins/gcp/Makefile b/plugins/gcp/Makefile
@@ -0,0 +1,35 @@
+#
+# Copyright (C) 2022 The Falco Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+SHELL=/bin/bash -o pipefail
+GO ?= go
+
+NAME := gcp_auditlog
+OUTPUT := $(NAME).so
+
+ifeq ($(DEBUG), 1)
+    GODEBUGFLAGS= GODEBUG=cgocheck=2
+else
+    GODEBUGFLAGS= GODEBUG=cgocheck=0
+endif
+
+all: $(OUTPUT)
+
+clean:
+	@rm -f $(OUTPUT)
+
+$(OUTPUT): 
+	@$(GODEBUGFLAGS) $(GO) build -buildmode=c-shared -o $(OUTPUT) ./plugin
+
+readme:
+	@$(READMETOOL) -p ./$(OUTPUT) -f README.md
diff --git a/plugins/gcp/README.md b/plugins/gcp/README.md
@@ -0,0 +1,179 @@
+# GCP audit logs Events Plugin
+
+This GCP Audit Logs Plugin is designed to ingest GCP audit logs for several GCP services, including Compute Engine, KMS, Cloud Armor WAF, IAM, Firewall, Cloud Storage, BigQuery, CloudSQL, Pub/Sub, Cloud Logging, and Cloud Functions.
+
+The GCP Audit Logs Plugin's primary purpose is to detect security threats, vulnerabilities, and compliance risks by analyzing the ingested GCP audit logs. The default security detection rules were built with the MITRE & ATT&CK framework in mind, which provides a comprehensive and industry-standard way to identify and classify different types of security threats.
+
+The GCP Audit Logs Plugin can help security teams identify and respond to security incidents quickly, improve compliance posture, and reduce overall risk to the organization. It provides a comprehensive and centralized view of security events across multiple GCP services and can help detect and prevent unauthorized access, data exfiltration, and other types of malicious activity.
+
+By leveraging GCP audit logs, the GCP Audit Logs Plugin provides deep insights into the activities of different users, services, and resources in your GCP environment. The GCP Audit Logs Plugin's advanced ebpf capabilities enable it to identify anomalous activities and raise alerts when it detects suspicious or malicious behavior.
+
+The GCP Audit Logs Plugin also offers customizable detection rules that enable you to fine-tune the detection capabilities to suit your organization's specific needs. You can customize the rules to detect specific types of security threats, monitor specific users or services, and track specific resources or data types.
+
+
+For more details about what GCP Audit logs are, see the [GCP official documentation](https://cloud.google.com/logging/docs/audit/understanding-audit-logs).
+
+### Functionality
+
+The GCP Audit Logs Plugin comes with pre-built security detection rules designed to detect security threats based on the MITRE & ATT&CK framework. These rules are constantly updated to ensure that the security agent is always detecting the latest threats and vulnerabilities.
+
+The default security detection rules cover the following areas:
+
+* Identity and Access Management (IAM)
+* Network Security
+* Data Security
+* Compliance
+* Infrastructure Security
+* Cloud Service Providers
+
+The GCP Audit Logs Plugin's detection rules can identify threats such as:
+
+* Privilege escalation
+* Unauthorized access
+* Data exfiltration
+* Denial of Service (DoS) attacks
+* Insider threats
+* Suspicious network activity
+
+- [GCP Audit Logs Plugin](#GCP Audit Logs Plugin)
+- [Event Source](#event-source)
+- [Supported Fields](#supported-fields)
+- [Development](#development)
+  - [Requirements](#requirements)
+  - [Build](#build)
+- [Settings](#settings)
+- [Configurations](#configurations)
+- [Usage](#usage)
+  - [Requirements](#requirements-1)
+  - [Results](#results)
+
+# Event Source
+
+The event source for `GCP Audit Logs Plugin` events is `GCP Audit Logs`.
+
+This GCP Audit Logs Plugin is designed to ingest GCP audit logs from several GCP services, including: 
+* Compute Engine
+* KMS 
+* Cloud Armor WAF 
+* IAM 
+* Firewall 
+* Cloud Storage
+* BigQuery
+* Cloud SQL
+* Pub/Sub
+* Cloud Logging
+* Cloud Functions
+
+The GCP Audit Logs Plugin subscribes to a Pub/Sub topic service and is backed by an optimized sink that exports the most important log entries.
+
+```sql
+log_name="projects/your-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity" AND
+(protoPayload.serviceName="cloudsql.googleapis.com" OR 
+protoPayload.serviceName="logging.googleapis.com" OR 
+protoPayload.serviceName="iam.googleapis.com" OR 
+(protoPayload.serviceName="compute.googleapis.com" AND NOT protoPayload.authenticationInfo.principalEmail=~"^service-") OR 
+protoPayload.serviceName="pubsub.googleapis.com" OR
+protoPayload.serviceName="cloudkms.googleapis.com" OR
+protoPayload.serviceName="cloudfunctions.googleapis.com" OR
+protoPayload.serviceName="storage.googleapis.com" OR
+protoPayload.serviceName="cloudresourcemanager.googleapis.com" OR
+protoPayload.serviceName="bigquery.googleapis.com")
+```
+
+You can change the log query to fit your specific needs.
+
+For more details about what Cloud logging log queries, see the [GCP official documentation](https://cloud.google.com/logging/docs/view/logging-query-language).
+
+# Supported Fields
+
+<!-- README-PLUGIN-FIELDS -->
+|              NAME               |   TYPE   |              DESCRIPTION                        |
+|---------------------------------|----------|-------------------------------------------------|
+| `gcp.user`            | `string` | GCP principal email who committed the action    |
+| `gcp.callerIP`               | `string` | GCP principal caller IP                         |
+| `gcp.userAgent `        | `string` | GCP principal caller useragent                  |
+| `gcp.authorizationInfo `       | `string` | GCP authorization information affected resource |
+| `gcp.policyDelta`        | `string` | GCP API service name                            |
+| `gcp.request`            | `string` | GCP API raw request                             |
+| `gcp.serviceName`                | `string` | GCP API service  method executed                |
+
+<!-- /README-PLUGIN-FIELDS -->
+
+# Development
+## Requirements
+
+You need:
+* `Go` >= 1.17
+
+## Build
+
+```shell
+make
+```
+
+# Settings
+
+Only `init` accepts settings:
+* `project_id`: the name of your GCP project
+* `num_goroutines`: is the number of goroutines that each datastructure along the Receive path will spawn (default: 10)
+* `maxout_stand_messages`: is the maximum number of unprocessed messages (default: 1000)
+* `sub_id`: The subscriber name for your pub/sub topic
+
+# Configurations
+
+* `falco.yaml`
+
+  ```yaml
+  plugins:
+    - name: json
+      library_path: libjson.so
+
+    - name: gcp_auditlog
+      library_path: gcp_auditlog.so
+      init_config: '{"num_goroutines": 4, "maxout_stand_messages": 100, "project_id": "your-gcp-project", "sub_id":"Your-subscription-ID"}'
+  load_plugins: [gcp_auditlog, json]
+  ```
+
+* `rules.yaml`
+
+The `source` for rules must be `gcp_auditlog`.
+
+See example:
+```yaml
+- rule: GCP Bucket configured to be public
+  desc: Detect when access on a GCP Bucket granted to the public internet.
+  condition: is_gcs_service and gcp.methodName="storage.setIamPermissions" and is_binded_delta_to_public 
+  output: > 
+    project=%json.value[/resource/labels/project_id]
+    A GCP bucket access granted to be public by user=%gcp.user userIP=%gcp.callerIP userAgent=%gcp.userAgent  bindedDelta=%gcp.policyDelta
+    authorizationInfo=%gcp.authorizationInfo
+    rawRequest=%gcp.request 
+    bucketName=%json.value[/resource/labels/bucket_name]  
+  priority: CRITICAL
+  source: auditlogs
+  tags: [GCP, buckets, compliance]
+```
+
+# Usage
+
+```shell
+falco -c falco.yaml -r auditlogs_rules.yaml
+```
+
+## Requirements
+
+* `Falco` >= 0.35
+
+## Results
+
+```shell
+{"hostname":"sherlock","output":"01:43:54.476694000: Notice project=********** A GCP WAF network policy or waf rule modified by [email protected] userIP=41.45.115.69 userAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36,gzip(gfe),gzip(gfe)  authorizationInfo=[{\"granted\":true,\"permission\":\"compute.securityPolicies.update\",\"resourceAttributes\":{\"name\":\"projects/=**********/global/securityPolicies/**********\",\"service\":\"compute\",\"type\":\"compute.securityPolicies\"}}] rawRequest={\"@type\":\"type.googleapis.com/compute.securityPolicies.addRule\",\"action\":\"deny(403)\",\"description\":\"\",\"match\":{\"config\":{\"srcIpRanges\":[\"1.1.1.1\"]},\"versionedExpr\":\"SRC_IPS_V1\"},\"preview\":false,\"priority\":\"0\"} policyName=**********","priority":"Notice","rule":"GCP WAF rule modified or deleted","source":"gcp_auditlog","tags":["CloudArmor","GCP","T1562-impair-defenses","TA0005-defense-evasion","WAF"],"time":"2023-07-06T22:43:54.476694000Z", "output_fields": {"evt.time":1688683434476694000,"gcp.authorizationInfo":"[{\"granted\":true,\"permission\":\"compute.securityPolicies.update\",\"resourceAttributes\":{\"name\":\"projects/=**********/global/securityPolicies/**********\",\"service\":\"compute\",\"type\":\"compute.securityPolicies\"}}]","gcp.callerIP":"41.45.115.69","gcp.request":"{\"@type\":\"type.googleapis.com/compute.securityPolicies.addRule\",\"action\":\"deny(403)\",\"description\":\"\",\"match\":{\"config\":{\"srcIpRanges\":[\"1.1.1.1\"]},\"versionedExpr\":\"SRC_IPS_V1\"},\"preview\":false,\"priority\":\"0\"}","gcp.user":"[email protected]","gcp.userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36,gzip(gfe),gzip(gfe)","json.value[/resource/labels/policy_name]":"**********","json.value[/resource/labels/project_id]":"****"}}
+
+{"hostname":"sherlock","output":"03:36:21.780289000: Critical project=********** A GCP bucket access granted to be public by [email protected] userIP=156.204.230.94 userAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36,gzip(gfe),gzip(gfe)  bindedDelta=[{\"action\":\"ADD\",\"member\":\"allUsers\",\"role\":\"roles/storage.objectViewer\"}] authorizationInfo=[{\"granted\":true,\"permission\":\"storage.buckets.setIamPolicy\",\"resource\":\"projects/_/buckets/amin-test\",\"resourceAttributes\":{}}]  bucketName=ahmed-test","priority":"Critical","rule":"GCP Bucket configured to be public","source":"gcp_auditlog","tags":["GCP","buckets","compliance"],"time":"2023-06-30T00:36:21.780289000Z", "output_fields": {"evt.time":1688085381780289000,"gcp.authorizationInfo":"[{\"granted\":true,\"permission\":\"storage.buckets.setIamPolicy\",\"resource\":\"projects/_/buckets/ahmed-test\",\"resourceAttributes\":{}}]","gcp.callerIP":"156.204.230.94","gcp.policyDelta":"[{\"action\":\"ADD\",\"member\":\"allUsers\",\"role\":\"roles/storage.objectViewer\"}]","gcp.user":"[email protected]","gcp.userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36,gzip(gfe),gzip(gfe)","json.value[/resource/labels/bucket_name]":"ahmed-test","json.value[/resource/labels/project_id]":"**********"}}
+
+{"hostname":"sherlock","output":"01:36:49.223570000: Notice project=-***-**-*** A GCP WAF network policy or waf rule modified by [email protected] userIP=x.x.x.x userAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36,gzip(gfe),gzip(gfe) authorizationInfo=[{\"granted\":true,\"permission\":\"compute.securityPolicies.update\",\"resourceAttributes\":{\"name\":\"projects/-***-**-***/global/securityPolicies/xxx-xxxx-xxxx\",\"service\":\"compute\",\"type\":\"compute.securityPolicies\"}}] policyName=xxx-xxxx-xxxx","priority":"Notice","rule":"GCP WAF rule modified or deleted","source":"auditlogs","tags":["CloudArmor","GCP","T1562-impair-defenses","TA0005-defense-evasion","WAF"],"time":"2023-04-22T23:36:49.223570000Z", "output_fields": {"gcp.authorizationInfo ":"[{\"granted\":true,\"permission\":\"compute.securityPolicies.update\",\"resourceAttributes\":{\"name\":\"projects/-***-**-***/global/securityPolicies/xxx-xxxx-xxxx\",\"service\":\"compute\",\"type\":\"compute.securityPolicies\"}}]","gcp.user":"[email protected]","al.principal.ip":"x.x.x.x","gcp.userAgent ":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36,gzip(gfe),gzip(gfe)","evt.time":1682206609223570000,"json.value[/resource/labels/policy_name]":"xxx-xxxx-xxxx","json.value[/resource/labels/project_id]":"-***-**-***"}}
+
+{"hostname":"sherlock-ThinkBook-15-G2-ITL","output":"02:48:23.599777000: Notice project=xxx-xxxx-xxxx A GCP serviceAccount delete by [email protected] userIP=156.204.230.94 userAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36,gzip(gfe)  authorizationInfo=[{\"granted\":true,\"permission\":\"iam.serviceAccounts.delete\",\"resource\":\"projects/-/serviceAccounts/101363364166838521279\",\"resourceAttributes\":{\"name\":\"projects/-/serviceAccounts/101363364166838521279\"}}]","priority":"Notice","rule":"GCP IAM serviceAccount deleted","source":"gcp_auditlog","tags":["GCP","IAM","abuse-elevation-control-mechanism"],"time":"2023-06-29T23:48:23.599777000Z", "output_fields": {"evt.time":1688082503599777000,"gcp.authorizationInfo":"[{\"granted\":true,\"permission\":\"iam.serviceAccounts.delete\",\"resource\":\"projects/-/serviceAccounts/101363364166838521279\",\"resourceAttributes\":{\"name\":\"projects/-/serviceAccounts/101363364166838521279\"}}]","gcp.callerIP":"156.204.230.94","gcp.user":"[email protected]","gcp.userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36,gzip(gfe)","json.value[/resource/labels/project_id]":"xxx-xxxx-xxxx"}}
+
+
+```
diff --git a/plugins/gcp/falco.yaml b/plugins/gcp/falco.yaml
@@ -0,0 +1,66 @@
+plugins:
+  - name: json
+    library_path: libjson.so
+
+  - name: gcp_auditlog
+    library_path: gcp_auditlog.so
+    init_config: '{"num_goroutines": 4, "maxout_stand_messages": 100, "project_id": "ldp-dev-2", "sub_id":"amin-security-test-sub", "path":"wait.json"}'
+    open_params: ''
+load_plugins: [gcp_auditlog, json]
+
+stdout_output:
+  enabled: true
+
+# Watch config file and rules files for modification.
+# When a file is modified, Falco will propagate new config,
+# by reloading itself.
+watch_config_files: true
+
+# If true, the times displayed in log messages and output messages
+# will be in ISO 8601. By default, times are displayed in the local
+# time zone, as governed by /etc/localtime.
+time_format_iso_8601: false
+
+# If "true", print falco alert messages and rules file
+# loading/validation results as json, which allows for easier
+# consumption by downstream programs. Default is "false".
+json_output: true
+
+# When using json output, whether or not to include the "output" property
+# itself (e.g. "File below a known binary directory opened for writing
+# (user=root ....") in the json output.
+json_include_output_property: true
+
+# When using json output, whether or not to include the "tags" property
+# itself in the json output. If set to true, outputs caused by rules
+# with no tags will have a "tags" field set to an empty array. If set to
+# false, the "tags" field will not be included in the json output at all.
+json_include_tags_property: true
+
+# Send information logs to stderr and/or syslog Note these are *not* security
+# notification logs! These are just Falco lifecycle (and possibly error) logs.
+log_stderr: true
+log_syslog: true
+
+# Minimum log level to include in logs. Note: these levels are
+# separate from the priority field of rules. This refers only to the
+# log level of falco's internal logging. Can be one of "emergency",
+# "alert", "critical", "error", "warning", "notice", "info", "debug".
+log_level: info
+
+# Falco is capable of managing the logs coming from libs. If enabled,
+# the libs logger send its log records the same outputs supported by
+# Falco (stderr and syslog). Disabled by default.
+libs_logger:
+  enabled: false
+  # Minimum log severity to include in the libs logs. Note: this value is
+  # separate from the log level of the Falco logger and does not affect it.
+  # Can be one of "fatal", "critical", "error", "warning", "notice",
+  # "info", "debug", "trace".
+  severity: debug
+
+# Minimum rule priority level to load and run. All rules having a
+# priority more severe than this level will be loaded/run.  Can be one
+# of "emergency", "alert", "critical", "error", "warning", "notice",
+# "informational", "debug".
+priority: debug
diff --git a/plugins/gcp/go.mod b/plugins/gcp/go.mod
@@ -0,0 +1,34 @@
+module falcoplugin
+
+go 1.19
+
+require (
+	cloud.google.com/go/pubsub v1.30.0
+	github.com/alecthomas/jsonschema v0.0.0-20220216202328-9eeeec9d044b
+	github.com/falcosecurity/plugin-sdk-go v0.7.1
+	github.com/valyala/fastjson v1.6.4
+	google.golang.org/api v0.114.0
+)
+
+require (
+	cloud.google.com/go v0.110.0 // indirect
+	cloud.google.com/go/compute v1.18.0 // indirect
+	cloud.google.com/go/compute/metadata v0.2.3 // indirect
+	cloud.google.com/go/iam v0.12.0 // indirect
+	github.com/golang/groupcache v0.0.0-20200121045136-8c9f03a8e57e // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/google/go-cmp v0.5.9 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.2.3 // indirect
+	github.com/googleapis/gax-go/v2 v2.7.1 // indirect
+	github.com/iancoleman/orderedmap v0.0.0-20190318233801-ac98e3ecb4b0 // indirect
+	go.opencensus.io v0.24.0 // indirect
+	golang.org/x/net v0.8.0 // indirect
+	golang.org/x/oauth2 v0.6.0 // indirect
+	golang.org/x/sync v0.1.0 // indirect
+	golang.org/x/sys v0.6.0 // indirect
+	golang.org/x/text v0.8.0 // indirect
+	google.golang.org/appengine v1.6.7 // indirect
+	google.golang.org/genproto v0.0.0-20230320184635-7606e756e683 // indirect
+	google.golang.org/grpc v1.53.0 // indirect
+	google.golang.org/protobuf v1.29.1 // indirect
+)