diff --git a/detect/v1alpha/create_rule.py b/detect/v1alpha/create_rule.py new file mode 100644 index 0000000..a832cd7 --- /dev/null +++ b/detect/v1alpha/create_rule.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 + +# Copyright 2024 Google LLC +# +# 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. +# +r"""Executable and reusable sample for creating a detection rule. + +HTTP request +POST https://chronicle.googleapis.com/v1alpha/{parent}/rules + +python3 -m detect.v1alpha.create_rule \ + --project_guid $PROJECT_GUID \ + --project_id $PROJECT_ID \ + --rule_file=./ip_in_abuseipdb_blocklist.yaral + +Requires the following IAM permission on the parent resource: +chronicle.rules.create + +API reference: +https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.rules/create +https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.rules#Rule + +""" + +import argparse +import json +from typing import Any, List, Mapping + +from common import chronicle_auth +from common import project_guid +from common import project_id +from common import regions + +from google.auth.transport import requests +from google.oauth2 import service_account + + +INGESTION_API_BASE_URL = "https://malachiteingestion-pa.googleapis.com" +AUTHORIZATION_SCOPES = ["https://www.googleapis.com/auth/malachite-ingestion"] + +SCOPES = [ + "https://www.googleapis.com/auth/cloud-platform", +] + + +def authorize( + credentials_file_path: str, scopes: List(str) +) -> requests.AuthorizedSession: + """Obtains an authorized session using the provided credentials. + + Args: + credentials_file_path: The service account credentials file path. + scopes: List of Chronicle API Scopes + + Returns: + requests.AuthorizedSession: An authorized session for making API calls. + """ + credentials = service_account.Credentials.from_service_account_file( + credentials_file_path, scopes=scopes + ) + return requests.AuthorizedSession(credentials) + + +def create_rule( + http_session: requests.AuthorizedSession, rule_file_path: str +) -> Mapping[str, Any]: + """Creates a new detection rule to find matches in logs. + + Args: + http_session: Authorized session for HTTP requests. + rule_file_path: Content of the new detection rule, used to evaluate logs. + + Returns: + New detection rule. + + Raises: + requests.exceptions.HTTPError: HTTP request resulted in an error + (response.status_code >= 400). + """ + parent = f"projects/{args.project_id}/locations/{args.region}/instances/{args.project_guid}" + url = f"https://{args.region}-chronicle.googleapis.com/v1alpha/{parent}/rules" + + body = { + "name": "ip_in_abuseipdb_blocklist", + "text": rule_file_path.read(), + } + response = http_session.request("POST", url, json=body) + if response.status_code >= 400: + print(response.text) + response.raise_for_status() + return response.json() + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + # common + chronicle_auth.add_argument_credentials_file(parser) + project_guid.add_argument_project_guid(parser) + project_id.add_argument_project_id(parser) + regions.add_argument_region(parser) + # local + parser.add_argument( + "-f", + "--rule_file", + type=argparse.FileType("r"), + required=True, + # File example: python3 create_rule.py -f + # STDIN example: cat rule.txt | python3 create_rule.py -f - + help="path of a file with the desired rule's content, or - for STDIN", + ) + args = parser.parse_args() + + auth_session = authorize(args.credentials_file, SCOPES) + new_rule = create_rule(auth_session, args.rule_file) + print(json.dumps(new_rule, indent=2)) diff --git a/ingestion/v1alpha/create_udm_events.py b/ingestion/v1alpha/create_udm_events.py new file mode 100644 index 0000000..4007790 --- /dev/null +++ b/ingestion/v1alpha/create_udm_events.py @@ -0,0 +1,150 @@ +#!/usr/bin/env python3 + +# Copyright 2024 Google LLC +# +# 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. +# +r"""Executable and reusable sample for ingesting events in UDM format. + +WARNING: This script makes use of the Ingestion API v1alpha. v1alpha is currently only in +preview for certain Chronicle customers. Please reach out to your Chronicle +representative if you wish to use this API. + +The Unified Data Model (UDM) is a way of representing events across all log +sources. See +https://cloud.google.com/chronicle/docs/unified-data-model/udm-field-list for a +description of UDM fields, and see +https://cloud.google.com/chronicle/docs/unified-data-model/format-events-as-udm +for how to describe a log as an event in UDM format. + +This command accepts a path to a file (--json_events_file) that contains an +array of JSON formatted events in UDM format. See +./example_input/sample_udm_events.json for an example. + +So, assuming you've created a credentials file at $HOME/.chronicle_credentials.json, +and you are using environment variables for your PROJECT_GUID and PROJECT_ID, +you can run this command using the sample input like so: + +$ python3 -m ingestion.v1alpha.create_udm_events \ + --project_guid $PROJECT_GUID \ + --project_id $PROJECT_ID \ + --json_events_file=./ingestion/example_input/sample_udm_events.json + +API reference: +https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.events/import +https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.events/import#EventsInlineSource +https://cloud.google.com/chronicle/docs/reference/udm-field-list +https://cloud.google.com/chronicle/docs/unified-data-model/udm-usage +""" + +import argparse +import json +from typing import List + +from common import chronicle_auth +from common import project_guid +from common import project_id +from common import regions + +from google.auth.transport import requests +from google.oauth2 import service_account + +INGESTION_API_BASE_URL = "https://malachiteingestion-pa.googleapis.com" +AUTHORIZATION_SCOPES = ["https://www.googleapis.com/auth/malachite-ingestion"] + +SCOPES = [ + "https://www.googleapis.com/auth/cloud-platform", +] + + +def authorize( + credentials_file_path: str, scopes: List(str) +) -> requests.AuthorizedSession: + """Obtains an authorized session using the provided credentials. + + Args: + credentials_file_path: The service account credentials file path. + scopes: List of Chronicle API Scopes + + Returns: + requests.AuthorizedSession: An authorized session for making API calls. + """ + credentials = service_account.Credentials.from_service_account_file( + credentials_file_path, scopes=scopes + ) + return requests.AuthorizedSession(credentials) + + +def create_udm_events( + http_session: requests.AuthorizedSession, json_events: str +) -> None: + """Sends a collection of UDM events to the Chronicle backend for ingestion. + + A Unified Data Model (UDM) event is a structured representation of an event + regardless of the log source. + + Args: + http_session: Authorized session for HTTP requests. + json_events: A collection of UDM events in (serialized) JSON format. + + Raises: + requests.exceptions.HTTPError: HTTP request resulted in an error + (response.status_code >= 400). + + Requires the following IAM permission on the parent resource: + chronicle.events.import + + POST https://chronicle.googleapis.com/v1alpha/{parent}/events:import + + https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.events/import + """ + parent = f"projects/{args.project_id}/locations/{args.region}/instances/{args.project_guid}" + url = f"https://{args.region}-chronicle.googleapis.com/v1alpha/{parent}/events:import" + + body = { + "inline_source": { + "events": [{ + "name": "foo", + "udm": json.loads(json_events)[0], + }] + } + } + + response = http_session.request("POST", url, json=body) + if response.status_code >= 400: + print(body) + print(response.text) + response.raise_for_status() + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + # common + chronicle_auth.add_argument_credentials_file(parser) + project_guid.add_argument_project_guid(parser) + project_id.add_argument_project_id(parser) + regions.add_argument_region(parser) + # local + parser.add_argument( + "--json_events_file", + type=argparse.FileType("r"), + required=True, + help=( + 'path to a file (or "-" for STDIN) containing a list of UDM ' + "events in json format" + ), + ) + args = parser.parse_args() + + auth_session = authorize(args.credentials_file, SCOPES) + create_udm_events(auth_session, args.json_events_file.read()) diff --git a/lists/v1alpha/create_list.py b/lists/v1alpha/create_list.py new file mode 100644 index 0000000..0647241 --- /dev/null +++ b/lists/v1alpha/create_list.py @@ -0,0 +1,167 @@ +#!/usr/bin/env python3 + +# Copyright 2024 Google LLC +# +# 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. +# +"""Executable and reusable sample for creating a Reference List. + +Requires the following IAM permission on the parent resource: +chronicle.referenceLists.create +https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.referenceLists/create +""" + +import argparse +from typing import List, Sequence + +from common import chronicle_auth +from common import regions +from google.auth.transport import requests +from google.oauth2 import service_account + +SCOPES = [ + "https://www.googleapis.com/auth/cloud-platform", +] + + +def authorize( + credentials_file_path: str, scopes: List(str) +) -> requests.AuthorizedSession: + """Obtains an authorized session using the provided credentials. + + Args: + credentials_file_path: The service account credentials file path. + scopes: List of Chronicle API Scopes + + Returns: + requests.AuthorizedSession: An authorized session for making API calls. + """ + credentials = service_account.Credentials.from_service_account_file( + credentials_file_path, scopes=scopes + ) + return requests.AuthorizedSession(credentials) + + +def create_list( + http_session: requests.AuthorizedSession, + name: str, + description: str, + content_lines: Sequence[str], + content_type: str, +) -> str: + """Creates a list. + + Args: + http_session: Authorized session for HTTP requests. + name: Unique name for the list. + description: Description of the list. + content_lines: Array containing each line of the list's content. + content_type: Type of list content, indicating how to interpret this list. + + Returns: + Creation timestamp of the new list. + + Raises: + requests.exceptions.HTTPError: HTTP request resulted in an error + (response.status_code >= 400). + """ + + parent = f"projects/{args.project_id}/locations/{args.region}/instances/{args.project_guid}" + url = f"https://{args.region}-chronicle.googleapis.com/v1alpha/{parent}/referenceLists" + + # Test auth with a Get List + response = http_session.request("GET", url) + if response.status_code >= 400: + print(response.text) + response.raise_for_status() + + # entries are list like [{"value": }, ...] + # https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.referenceLists#resource:-referencelist + entries = [] + for content_line in content_lines: + entries.append({"value": content_line.strip()}) + + body = { + "name": name, + "description": description, + "entries": entries, + "syntax_type": content_type, + } + url_w_query_string = f"{url}?referenceListId={name}" + response = http_session.request("POST", url_w_query_string, json=body) + # Expected server response: + # ['name', 'displayName', 'revisionCreateTime', 'description', + # 'entries', 'syntaxType']) + if response.status_code >= 400: + print(response.text) + response.raise_for_status() + return response.json()["revisionCreateTime"] + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + chronicle_auth.add_argument_credentials_file(parser) + regions.add_argument_region(parser) + parser.add_argument( + "-n", "--name", type=str, required=True, help="unique name for the list" + ) + parser.add_argument( + "-d", + "--description", + type=str, + required=True, + help="description of the list", + ) + parser.add_argument( + "-t", + "--syntax_type", + type=str, + default="REFERENCE_LIST_SYNTAX_TYPE_PLAIN_TEXT_STRING", + help="type of list lines", + ) + parser.add_argument( + "-f", + "--list_file", + type=argparse.FileType("r"), + required=True, + # File example: + # python3 -m lists.create_list -f + # STDIN example: + # cat | python3 -m lists.create_list -f - + help="path of a file containing the list content, or - for STDIN", + ) + parser.add_argument( + "-p", + "--project_id", + type=str, + required=True, + help="Your BYOP, project id", + ) + parser.add_argument( + "-g", + "--project_guid", + type=str, + required=True, + help="Your Chronicle instance's GUID", + ) + + args = parser.parse_args() + auth_session = authorize(args.credentials_file, SCOPES) + new_list_create_time = create_list( + auth_session, + args.name, + args.description, + args.list_file.read().splitlines(), + args.syntax_type, + ) + print(f"New list created successfully, at {new_list_create_time}")