Skip to content

Commit 0e46609

Browse files
geraldcombsgeraldcombs
committed
update(plugins/gcpaudit_rs): Add a README for gcpaudit_rs
Copy the README.md file from gcpaudit, and note that this is a Rust version of that plugin. Signed-off-by: Gerald Combs <gerald@wireshark.org>
1 parent 563b774 commit 0e46609

1 file changed

Lines changed: 198 additions & 0 deletions

File tree

‎plugins/gcpaudit_rs/README.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# GCP audit logs Events Plugin, Rust version
2+
3+
This is a Rust version fo the GCP Audit Logs Plugin and 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.
4+
5+
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.
6+
7+
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.
8+
9+
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.
10+
11+
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.
12+
13+
14+
For more details about what GCP Audit logs are, see the [GCP official documentation](https://cloud.google.com/logging/docs/audit/understanding-audit-logs).
15+
16+
### Functionality
17+
18+
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.
19+
20+
The default security detection rules cover the following areas:
21+
22+
* Identity and Access Management (IAM)
23+
* Network Security
24+
* Data Security
25+
* Compliance
26+
* Infrastructure Security
27+
* Cloud Service Providers
28+
29+
The GCP Audit Logs Plugin's detection rules can identify threats such as:
30+
31+
* Privilege escalation
32+
* Unauthorized access
33+
* Data exfiltration
34+
* Denial of Service (DoS) attacks
35+
* Insider threats
36+
* Suspicious network activity
37+
38+
- [GCP Audit Logs Plugin](#GCP Audit Logs Plugin)
39+
- [Event Source](#event-source)
40+
- [Supported Fields](#supported-fields)
41+
- [Development](#development)
42+
- [Requirements](#requirements)
43+
- [Build](#build)
44+
- [Settings](#settings)
45+
- [Configurations](#configurations)
46+
- [Usage](#usage)
47+
- [Requirements](#requirements-1)
48+
- [Results](#results)
49+
50+
# Event Source
51+
52+
The event source for `GCP Audit Logs Plugin` events is `GCP Audit Logs`.
53+
54+
This GCP Audit Logs Plugin is designed to ingest GCP audit logs from several GCP services, including:
55+
* Compute Engine
56+
* KMS
57+
* Cloud Armor WAF
58+
* IAM
59+
* Firewall
60+
* Cloud Storage
61+
* BigQuery
62+
* Cloud SQL
63+
* Pub/Sub
64+
* Cloud Logging
65+
* Cloud Functions
66+
67+
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.
68+
69+
```sql
70+
log_name="projects/your-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity" AND
71+
(protoPayload.serviceName="cloudsql.googleapis.com" OR
72+
protoPayload.serviceName="logging.googleapis.com" OR
73+
protoPayload.serviceName="iam.googleapis.com" OR
74+
(protoPayload.serviceName="compute.googleapis.com" AND NOT protoPayload.authenticationInfo.principalEmail=~"^service-") OR
75+
protoPayload.serviceName="pubsub.googleapis.com" OR
76+
protoPayload.serviceName="cloudkms.googleapis.com" OR
77+
protoPayload.serviceName="cloudfunctions.googleapis.com" OR
78+
protoPayload.serviceName="storage.googleapis.com" OR
79+
protoPayload.serviceName="cloudresourcemanager.googleapis.com" OR
80+
protoPayload.serviceName="bigquery.googleapis.com")
81+
```
82+
83+
You can change the log query to fit your specific needs.
84+
85+
For more details about what Cloud logging log queries, see the [GCP official documentation](https://cloud.google.com/logging/docs/view/logging-query-language).
86+
87+
# Supported Fields
88+
89+
<!-- README-PLUGIN-FIELDS -->
90+
| NAME | TYPE | ARG | DESCRIPTION |
91+
|-------------------------------|----------|------|------------------------------------------|
92+
| `gcp.user` | `string` | None | GCP principal, actor of the action |
93+
| `gcp.callerIP` | `string` | None | Actor's IP |
94+
| `gcp.userAgent` | `string` | None | Actor's User Agent |
95+
| `gcp.authorizationInfo` | `string` | None | GCP authorization (JSON) |
96+
| `gcp.serviceName` | `string` | None | GCP API service name |
97+
| `gcp.policyDelta` | `string` | None | GCP service resource access policy delta |
98+
| `gcp.request` | `string` | None | GCP API raw request (JSON) |
99+
| `gcp.methodName` | `string` | None | GCP API service method executed |
100+
| `gcp.cloudfunctions.function` | `string` | None | GCF name |
101+
| `gcp.cloudsql.databaseId` | `string` | None | GCP SQL database ID |
102+
| `gcp.compute.instanceId` | `string` | None | GCE instance ID |
103+
| `gcp.compute.networkId` | `string` | None | GCP network ID |
104+
| `gcp.compute.subnetwork` | `string` | None | GCP subnetwork name |
105+
| `gcp.compute.subnetworkId` | `string` | None | GCP subnetwork ID |
106+
| `gcp.dns.zone` | `string` | None | GCP DNS zone |
107+
| `gcp.iam.serviceAccount` | `string` | None | GCP service account |
108+
| `gcp.iam.serviceAccountId` | `string` | None | GCP IAM unique ID |
109+
| `gcp.location` | `string` | None | GCP region |
110+
| `gcp.logging.sink` | `string` | None | GCP logging sink |
111+
| `gcp.projectId` | `string` | None | GCP project ID |
112+
| `gcp.resourceName` | `string` | None | GCP resource name |
113+
| `gcp.resourceType` | `string` | None | GCP resource type |
114+
| `gcp.resourceLabels` | `string` | None | GCP resource labels (JSON) |
115+
| `gcp.storage.bucket` | `string` | None | GCP bucket name |
116+
| `gcp.time` | `string` | None | Timestamp of the event in RFC3339 format |
117+
<!-- /README-PLUGIN-FIELDS -->
118+
119+
# Development
120+
## Requirements
121+
122+
You need:
123+
* `Go` >= 1.17
124+
125+
## Build
126+
127+
```shell
128+
make
129+
```
130+
131+
# Settings
132+
133+
Only `init` accepts settings:
134+
* `project_id`: the name of your GCP project
135+
* `num_goroutines`: is the number of goroutines that each datastructure along the Receive path will spawn (default: 10)
136+
* `maxout_stand_messages`: is the maximum number of unprocessed messages (default: 1000)
137+
* `sub_id`: The subscriber name for your pub/sub topic
138+
139+
# Configurations
140+
141+
* `falco.yaml`
142+
143+
```yaml
144+
plugins:
145+
- name: json
146+
library_path: libjson.so
147+
148+
- name: gcpaudit
149+
library_path: libgcpaudit.so
150+
open_params: "your-subscription-ID"
151+
init_config:
152+
project_id: "your-gcp-project-ID"
153+
load_plugins: [gcpaudit, json]
154+
```
155+
156+
* `rules.yaml`
157+
158+
The `source` for rules must be `gcp_auditlog`.
159+
160+
See example:
161+
```yaml
162+
- rule: GCP Bucket configured to be public
163+
desc: Detect when access on a GCP Bucket granted to the public internet.
164+
condition: is_gcs_service and gcp.methodName="storage.setIamPermissions" and is_binded_delta_to_public
165+
output: >
166+
project=%gcp.projectId
167+
A GCP bucket access granted to be public by user=%gcp.user userIP=%gcp.callerIP userAgent=%gcp.userAgent bindedDelta=%gcp.policyDelta
168+
authorizationInfo=%gcp.authorizationInfo
169+
rawRequest=%gcp.request
170+
bucketName=%gcp.storage.bucket
171+
priority: CRITICAL
172+
source: auditlogs
173+
tags: [GCP, buckets, compliance]
174+
```
175+
176+
# Usage
177+
178+
```shell
179+
falco -c falco.yaml -r auditlogs_rules.yaml
180+
```
181+
182+
## Requirements
183+
184+
* `Falco` >= 0.35
185+
186+
## Results
187+
188+
```shell
189+
{"hostname":"sherlock","output":"01:43:54.476694000: Notice project=********** A GCP WAF network policy or waf rule modified by user=ahmed.amin@test.com 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":"ahmed.amin@test.com","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]":"**********","gcp.projectId":"****"}}
190+
191+
{"hostname":"sherlock","output":"03:36:21.780289000: Critical project=********** A GCP bucket access granted to be public by user=ahmed.amin@test.com 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":"ahmed.amin@test.com","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)","gcp.storage.bucket":"ahmed-test","gcp.projectId":"**********"}}
192+
193+
{"hostname":"sherlock","output":"01:36:49.223570000: Notice project=-***-**-*** A GCP WAF network policy or waf rule modified by user=ahmed.amin@test.com 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":"ahmed.amin@test.com","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","gcp.projectId":"-***-**-***"}}
194+
195+
{"hostname":"sherlock-ThinkBook-15-G2-ITL","output":"02:48:23.599777000: Notice project=xxx-xxxx-xxxx A GCP serviceAccount delete by user=ahmed.amin@test.com 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":"ahmed.amin@test.com","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)","gcp.projectId":"xxx-xxxx-xxxx"}}
196+
197+
198+
```

0 commit comments

Comments
 (0)