chronicle · dandye · Mar 7, 2025 · Mar 7, 2025 · Mar 7, 2025 · Mar 7, 2025
diff --git a/.env.example b/.env.example
@@ -0,0 +1,5 @@
+# Chronicle API SDK Configuration
+CHRONICLE_CREDENTIALS_FILE=path/to/credentials.json
+CHRONICLE_PROJECT_ID=your-project-id
+CHRONICLE_INSTANCE=your-instance-id
+CHRONICLE_REGION=your-region
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,48 @@ __pycache__/
 venv/
 
 node_modules/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment Variables
+.env
+.env.*
+!.env.example
+
+# Credentials
+*credentials*.json
+*creds*.json
+
+# Logs
+*.log
diff --git a/.style.yapf b/.style.yapf
@@ -0,0 +1,4 @@
+[style]
+based_on_style = google
+indent_width = 2
+column_limit = 80
diff --git a/Makefile b/Makefile
@@ -0,0 +1,13 @@
+.PHONY: install dist clean
+
+build:
+	python -m build
+
+install:
+	python setup.py install
+
+dist:
+	python setup.py bdist_wheel
+
+clean:
+	rm -rf build/ dist/ *.egg-info/
diff --git a/README.md b/README.md
@@ -30,15 +30,7 @@ samples try to use the file `.chronicle_credentials.json` in the user's home
 directory. If this file is not found, you need to specify it explicitly by
 adding the following argument to the sample's command-line:
 
-```shell
--c <file_path>
-```
-
-or
-
-```shell
---credentials_file <file_path>
-```
+`shell -c <file_path>` or `shell --credentials_file <file_path>`
 
 ## Usage
 
@@ -60,8 +52,166 @@ python3 -m lists.<sample_name> -h
 
 ### Lists API v1alpha
 
-```
+```shell
 python -m lists.v1alpha.create_list -h
 python -m lists.v1alpha.get_list -h
 python -m lists.v1alpha.patch_list -h
 ```
+
+## Installing the Chronicle REST API CLI
+
+Install the CLI from source
+```
+python setup.py install
+```
+
+Alternatively, install the CLI from source using make
+```
+make install
+```
+
+Build the wheel file
+```
+make dist
+```
+
+## Using the Chronicle REST API CLI
+
+The CLI provides a unified command-line interface for Chronicle APIs.
+The CLI follows this pattern:
+```
+chronicle [common options] COMMAND_GROUP COMMAND [command options]
+```
+
+### Common Options
+
+Common options can be provided either via command-line arguments or environment
+variables:
+
+| CLI Option         | Environment Variable        | Description                   |
+|--------------------|----------------------------|--------------------------------|
+| --credentials-file | CHRONICLE_CREDENTIALS_FILE | Path to service account file   |
+| --project-id       | CHRONICLE_PROJECT_ID       | GCP project id or number       |
+| --project-instance | CHRONICLE_INSTANCE         | Chronicle instance ID (uuid)   |
+| --region           | CHRONICLE_REGION           | Region where project is located|
+
+You can set these options in a `.env` file in your project root:
+
+```bash
+# .env file
+CHRONICLE_CREDENTIALS_FILE=path/to/credentials.json
+CHRONICLE_PROJECT_ID=your-project-id
+CHRONICLE_INSTANCE=your-instance-id
+CHRONICLE_REGION=your-region
+```
+
+The CLI will use values from the `.env` file or a file provided with the
+`--env-file` parameter. Command-line options take precedence over environment
+variables.
+
+### Command Groups
+
+#### Detection API
+```bash
+chronicle detect <command-group> <command> [options]
+```
+
+Available command groups:
+
+- `alerts`
+  - `get <alert-id>`: Get alert by ID
+  - `update <alert-id>`: Update an alert
+  - `bulk-update`: Bulk update alerts matching a filter
+
+- `detections`
+  - `get <detection-id>`: Get detection by ID
+  - `list [--filter <filter>]`: List detections
+
+- `rules`
+  - `create`: Create a new rule
+  - `get <rule-id>`: Get rule by ID
+  - `delete <rule-id>`: Delete a rule
+  - `enable <rule-id>`: Enable a rule
+  - `list [--filter <filter>]`: List rules
+
+- `retrohunts`
+  - `create`: Create a new retrohunt
+  - `get <retrohunt-id>`: Get retrohunt by ID
+
+- `errors`
+  - `list [--filter <filter>]`: List errors
+
+- `rulesets`
+  - `batch-update`: Batch update rule set deployments
+
+#### Ingestion API
+```bash
+chronicle ingestion <command> [options]
+```
+
+Available commands:
+
+- `import-events`: Import events into Chronicle
+- `get-event <event-id>`: Get event details
+- `batch-get-events`: Batch retrieve events
+
+#### Search API
+```bash
+chronicle search <command> [options]
+```
+
+Available commands:
+
+- `find-asset-events [--filter <filter>]`: Find events for an asset
+- `find-raw-logs [--filter <filter>]`: Search raw logs
+- `find-udm-events [--filter <filter>]`: Find UDM events
+
+#### Lists API
+```bash
+chronicle lists <command> [options]
+```
+
+Available commands:
+
+- `create <name> [--description <desc>] --lines <json-array>`: Create a new list
+- `get <list-id>`: Get list by ID
+- `patch <list-id> [--description <desc>]
+  [--lines-to-add <json-array>] \
+  [--lines-to-remove <json-array>]`: Update an existing list
+
+### Examples
+
+Using environment variables (after setting up .env):
+```bash
+# Get an alert
+chronicle detect alerts get --alert-id ABC123 --env-file=.env
+
+# Create a list
+chronicle lists create --name "blocklist" --description "Blocked IPs" \
+ --lines '["1.1.1.1", "2.2.2.2"]' \
+ --env-file=.env
+
+# Search for events
+chronicle search find-raw-logs --filter "timestamp.seconds > 1600000000" \
+ --env-file=.env
+
+# Override a specific environment variable
+chronicle --region us-central1 detect alerts get --alert-id ABC123 \
+ --env-file=.env
+```
+
+## Running Individual Scripts
+
+You can also run individual API sample scripts directly.
+Each script supports the `-h` flag to show available options:
+
+```bash
+# Get help for a specific script
+python -m detect.v1alpha.get_alert -h
+python -m search.v1alpha.find_asset_events -h
+python -m lists.v1alpha.patch_list -h
+```
+
+## License
+
+Apache 2.0 - See [LICENSE](LICENSE) for more information.
diff --git a/__init__.py b/__init__.py
diff --git a/chronicle_api.egg-info/PKG-INFO b/chronicle_api.egg-info/PKG-INFO
@@ -0,0 +1,19 @@
+Metadata-Version: 2.2
+Name: chronicle-api
+Version: 0.1.3
+Summary: Chronicle API SDK and CLI
+Author: Google LLC
+Author-email: [email protected]
+License: Apache 2.0
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
diff --git a/chronicle_api.egg-info/SOURCES.txt b/chronicle_api.egg-info/SOURCES.txt
@@ -0,0 +1,66 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+chronicle_api.egg-info/PKG-INFO
+chronicle_api.egg-info/SOURCES.txt
+chronicle_api.egg-info/dependency_links.txt
+chronicle_api.egg-info/entry_points.txt
+chronicle_api.egg-info/requires.txt
+chronicle_api.egg-info/top_level.txt
+common/__init__.py
+common/chronicle_auth.py
+common/chronicle_auth_test.py
+common/datetime_converter.py
+common/datetime_converter_test.py
+common/project_id.py
+common/project_instance.py
+common/regions.py
+common/regions_test.py
+detect/v1alpha/__init__.py
+detect/v1alpha/batch_update_curated_rule_set_deployments.py
+detect/v1alpha/bulk_update_alerts.py
+detect/v1alpha/create_retrohunt.py
+detect/v1alpha/create_rule.py
+detect/v1alpha/delete_rule.py
+detect/v1alpha/enable_rule.py
+detect/v1alpha/get_alert.py
+detect/v1alpha/get_detection.py
+detect/v1alpha/get_retrohunt.py
+detect/v1alpha/get_rule.py
+detect/v1alpha/list_detections.py
+detect/v1alpha/list_errors.py
+detect/v1alpha/list_rules.py
+detect/v1alpha/update_alert.py
+detect/v1alpha/update_rule.py
+ingestion/v1alpha/__init__.py
+ingestion/v1alpha/create_udm_events.py
+ingestion/v1alpha/event_import.py
+ingestion/v1alpha/events_batch_get.py
+ingestion/v1alpha/events_get.py
+ingestion/v1alpha/get_udm_event.py
+iocs/v1alpha/__init__.py
+iocs/v1alpha/batch_get_iocs.py
+iocs/v1alpha/get_ioc.py
+iocs/v1alpha/get_ioc_state.py
+lists/v1alpha/__init__.py
+lists/v1alpha/create_list.py
+lists/v1alpha/get_list.py
+lists/v1alpha/patch_list.py
+lists/v1alpha/patch_list_test.py
+sdk/__init__.py
+sdk/cli.py
+sdk/commands/__init__.py
+sdk/commands/common.py
+sdk/commands/detect.py
+sdk/commands/ingestion.py
+sdk/commands/iocs.py
+sdk/commands/lists.py
+sdk/commands/search.py
+search/v1alpha/__init__.py
+search/v1alpha/asset_events_find.py
+search/v1alpha/client.py
+search/v1alpha/raw_logs_find.py
+search/v1alpha/search_queries_list.py
+search/v1alpha/search_query_get.py
+search/v1alpha/udm_events_find.py
diff --git a/chronicle_api.egg-info/dependency_links.txt b/chronicle_api.egg-info/dependency_links.txt
@@ -0,0 +1 @@
+
diff --git a/chronicle_api.egg-info/entry_points.txt b/chronicle_api.egg-info/entry_points.txt
@@ -0,0 +1,2 @@
+[console_scripts]
+chronicle = sdk.cli:cli
diff --git a/chronicle_api.egg-info/requires.txt b/chronicle_api.egg-info/requires.txt
@@ -0,0 +1,4 @@
+click>=8.0.0
+google-auth>=2.0.0
+requests>=2.25.0
+python-dotenv>=1.0.0
diff --git a/chronicle_api.egg-info/top_level.txt b/chronicle_api.egg-info/top_level.txt
@@ -0,0 +1,7 @@
+common
+detect
+ingestion
+iocs
+lists
+sdk
+search
diff --git a/common/__init__.py b/common/__init__.py
@@ -1,4 +1,4 @@
-# Copyright 2021 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

diff --git a/detect/__init__.py b/detect/__init__.py
diff --git a/detect/v1alpha/__init__.py b/detect/v1alpha/__init__.py
@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.