Skip to content

Commit 97bfc20

Browse files
Chronicle Teamcopybara-github
Chronicle Team
authored and
copybara-github
committed
No public description
FUTURE_COPYBARA_INTEGRATE_REVIEW=#188 from dandye:events_import_v1alpha 24f6b68 PiperOrigin-RevId: 764848268
1 parent efde6b5 commit 97bfc20

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+3568
-544
lines changed

‎.env.example

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Chronicle API SDK Configuration
2+
CHRONICLE_CREDENTIALS_FILE=path/to/credentials.json
3+
CHRONICLE_PROJECT_ID=your-project-id
4+
CHRONICLE_INSTANCE=your-instance-id
5+
CHRONICLE_REGION=your-region

‎.gitignore

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,48 @@ __pycache__/
44
venv/
55

66
node_modules/
7+
8+
# Python
9+
__pycache__/
10+
*.py[cod]
11+
*$py.class
12+
*.so
13+
.Python
14+
build/
15+
develop-eggs/
16+
dist/
17+
downloads/
18+
eggs/
19+
.eggs/
20+
lib/
21+
lib64/
22+
parts/
23+
sdist/
24+
var/
25+
wheels/
26+
*.egg-info/
27+
.installed.cfg
28+
*.egg
29+
30+
# Virtual Environment
31+
venv/
32+
env/
33+
ENV/
34+
35+
# IDE
36+
.idea/
37+
.vscode/
38+
*.swp
39+
*.swo
40+
41+
# Environment Variables
42+
.env
43+
.env.*
44+
!.env.example
45+
46+
# Credentials
47+
*credentials*.json
48+
*creds*.json
49+
50+
# Logs
51+
*.log

‎.style.yapf

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[style]
2+
based_on_style = google
3+
indent_width = 2
4+
column_limit = 80

‎Makefile

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.PHONY: install dist clean
2+
3+
build:
4+
python -m build
5+
6+
install:
7+
python setup.py install
8+
9+
dist:
10+
python setup.py bdist_wheel
11+
12+
clean:
13+
rm -rf build/ dist/ *.egg-info/

‎README.md

Lines changed: 160 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,7 @@ samples try to use the file `.chronicle_credentials.json` in the user's home
3030
directory. If this file is not found, you need to specify it explicitly by
3131
adding the following argument to the sample's command-line:
3232

33-
```shell
34-
-c <file_path>
35-
```
36-
37-
or
38-
39-
```shell
40-
--credentials_file <file_path>
41-
```
33+
`shell -c <file_path>` or `shell --credentials_file <file_path>`
4234

4335
## Usage
4436

@@ -60,8 +52,166 @@ python3 -m lists.<sample_name> -h
6052

6153
### Lists API v1alpha
6254

63-
```
55+
```shell
6456
python -m lists.v1alpha.create_list -h
6557
python -m lists.v1alpha.get_list -h
6658
python -m lists.v1alpha.patch_list -h
6759
```
60+
61+
## Installing the Chronicle REST API SDK
62+
63+
Install the SDK from source
64+
```
65+
python setup.py install
66+
```
67+
68+
Alternatively, install the SDK from source using make
69+
```
70+
make install
71+
```
72+
73+
Build the wheel file
74+
```
75+
make dist
76+
```
77+
78+
## Using the Chronicle REST API SDK
79+
80+
The SDK provides a unified command-line interface for Chronicle APIs.
81+
The CLI follows this pattern:
82+
```
83+
chronicle [common options] COMMAND_GROUP COMMAND [command options]
84+
```
85+
86+
### Common Options
87+
88+
Common options can be provided either via command-line arguments or environment
89+
variables:
90+
91+
| CLI Option | Environment Variable | Description |
92+
|--------------------|----------------------------|--------------------------------|
93+
| --credentials-file | CHRONICLE_CREDENTIALS_FILE | Path to service account file |
94+
| --project-id | CHRONICLE_PROJECT_ID | GCP project id or number |
95+
| --project-instance | CHRONICLE_INSTANCE | Chronicle instance ID (uuid) |
96+
| --region | CHRONICLE_REGION | Region where project is located|
97+
98+
You can set these options in a `.env` file in your project root:
99+
100+
```bash
101+
# .env file
102+
CHRONICLE_CREDENTIALS_FILE=path/to/credentials.json
103+
CHRONICLE_PROJECT_ID=your-project-id
104+
CHRONICLE_INSTANCE=your-instance-id
105+
CHRONICLE_REGION=your-region
106+
```
107+
108+
The SDK will use values from the `.env` file or a file provided with the
109+
`--env-file` parameter. Command-line options take precedence over environment
110+
variables.
111+
112+
### Command Groups
113+
114+
#### Detection API
115+
```bash
116+
chronicle detect <command-group> <command> [options]
117+
```
118+
119+
Available command groups:
120+
121+
- `alerts`
122+
- `get <alert-id>`: Get alert by ID
123+
- `update <alert-id>`: Update an alert
124+
- `bulk-update`: Bulk update alerts matching a filter
125+
126+
- `detections`
127+
- `get <detection-id>`: Get detection by ID
128+
- `list [--filter <filter>]`: List detections
129+
130+
- `rules`
131+
- `create`: Create a new rule
132+
- `get <rule-id>`: Get rule by ID
133+
- `delete <rule-id>`: Delete a rule
134+
- `enable <rule-id>`: Enable a rule
135+
- `list [--filter <filter>]`: List rules
136+
137+
- `retrohunts`
138+
- `create`: Create a new retrohunt
139+
- `get <retrohunt-id>`: Get retrohunt by ID
140+
141+
- `errors`
142+
- `list [--filter <filter>]`: List errors
143+
144+
- `rulesets`
145+
- `batch-update`: Batch update rule set deployments
146+
147+
#### Ingestion API
148+
```bash
149+
chronicle ingestion <command> [options]
150+
```
151+
152+
Available commands:
153+
154+
- `import-events`: Import events into Chronicle
155+
- `get-event <event-id>`: Get event details
156+
- `batch-get-events`: Batch retrieve events
157+
158+
#### Search API
159+
```bash
160+
chronicle search <command> [options]
161+
```
162+
163+
Available commands:
164+
165+
- `find-asset-events [--filter <filter>]`: Find events for an asset
166+
- `find-raw-logs [--filter <filter>]`: Search raw logs
167+
- `find-udm-events [--filter <filter>]`: Find UDM events
168+
169+
#### Lists API
170+
```bash
171+
chronicle lists <command> [options]
172+
```
173+
174+
Available commands:
175+
176+
- `create <name> [--description <desc>] --lines <json-array>`: Create a new list
177+
- `get <list-id>`: Get list by ID
178+
- `patch <list-id> [--description <desc>]
179+
[--lines-to-add <json-array>] \
180+
[--lines-to-remove <json-array>]`: Update an existing list
181+
182+
### Examples
183+
184+
Using environment variables (after setting up .env):
185+
```bash
186+
# Get an alert
187+
chronicle detect alerts get --alert-id ABC123 --env-file=.env
188+
189+
# Create a list
190+
chronicle lists create --name "blocklist" --description "Blocked IPs" \
191+
--lines '["1.1.1.1", "2.2.2.2"]' \
192+
--env-file=.env
193+
194+
# Search for events
195+
chronicle search find-raw-logs --filter "timestamp.seconds > 1600000000" \
196+
--env-file=.env
197+
198+
# Override a specific environment variable
199+
chronicle --region us-central1 detect alerts get --alert-id ABC123 \
200+
--env-file=.env
201+
```
202+
203+
## Running Individual Scripts
204+
205+
You can also run individual API sample scripts directly.
206+
Each script supports the `-h` flag to show available options:
207+
208+
```bash
209+
# Get help for a specific script
210+
python -m detect.v1alpha.get_alert -h
211+
python -m search.v1alpha.find_asset_events -h
212+
python -m lists.v1alpha.patch_list -h
213+
```
214+
215+
## License
216+
217+
Apache 2.0 - See [LICENSE](LICENSE) for more information.

‎__init__.py

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
#

‎chronicle_api.egg-info/PKG-INFO

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Metadata-Version: 2.2
2+
Name: chronicle-api
3+
Version: 0.1.3
4+
Summary: Chronicle API SDK and CLI
5+
Author: Google LLC
6+
Author-email: [email protected]
7+
License: Apache 2.0
8+
Requires-Python: >=3.10
9+
License-File: LICENSE
10+
Requires-Dist: click>=8.0.0
11+
Requires-Dist: google-auth>=2.0.0
12+
Requires-Dist: requests>=2.25.0
13+
Requires-Dist: python-dotenv>=1.0.0
14+
Dynamic: author
15+
Dynamic: author-email
16+
Dynamic: license
17+
Dynamic: requires-dist
18+
Dynamic: requires-python
19+
Dynamic: summary

‎chronicle_api.egg-info/SOURCES.txt

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
LICENSE
2+
README.md
3+
pyproject.toml
4+
setup.py
5+
chronicle_api.egg-info/PKG-INFO
6+
chronicle_api.egg-info/SOURCES.txt
7+
chronicle_api.egg-info/dependency_links.txt
8+
chronicle_api.egg-info/entry_points.txt
9+
chronicle_api.egg-info/requires.txt
10+
chronicle_api.egg-info/top_level.txt
11+
common/__init__.py
12+
common/chronicle_auth.py
13+
common/chronicle_auth_test.py
14+
common/datetime_converter.py
15+
common/datetime_converter_test.py
16+
common/project_id.py
17+
common/project_instance.py
18+
common/regions.py
19+
common/regions_test.py
20+
detect/v1alpha/__init__.py
21+
detect/v1alpha/batch_update_curated_rule_set_deployments.py
22+
detect/v1alpha/bulk_update_alerts.py
23+
detect/v1alpha/create_retrohunt.py
24+
detect/v1alpha/create_rule.py
25+
detect/v1alpha/delete_rule.py
26+
detect/v1alpha/enable_rule.py
27+
detect/v1alpha/get_alert.py
28+
detect/v1alpha/get_detection.py
29+
detect/v1alpha/get_retrohunt.py
30+
detect/v1alpha/get_rule.py
31+
detect/v1alpha/list_detections.py
32+
detect/v1alpha/list_errors.py
33+
detect/v1alpha/list_rules.py
34+
detect/v1alpha/update_alert.py
35+
detect/v1alpha/update_rule.py
36+
ingestion/v1alpha/__init__.py
37+
ingestion/v1alpha/create_udm_events.py
38+
ingestion/v1alpha/event_import.py
39+
ingestion/v1alpha/events_batch_get.py
40+
ingestion/v1alpha/events_get.py
41+
ingestion/v1alpha/get_udm_event.py
42+
iocs/v1alpha/__init__.py
43+
iocs/v1alpha/batch_get_iocs.py
44+
iocs/v1alpha/get_ioc.py
45+
iocs/v1alpha/get_ioc_state.py
46+
lists/v1alpha/__init__.py
47+
lists/v1alpha/create_list.py
48+
lists/v1alpha/get_list.py
49+
lists/v1alpha/patch_list.py
50+
lists/v1alpha/patch_list_test.py
51+
sdk/__init__.py
52+
sdk/cli.py
53+
sdk/commands/__init__.py
54+
sdk/commands/common.py
55+
sdk/commands/detect.py
56+
sdk/commands/ingestion.py
57+
sdk/commands/iocs.py
58+
sdk/commands/lists.py
59+
sdk/commands/search.py
60+
search/v1alpha/__init__.py
61+
search/v1alpha/asset_events_find.py
62+
search/v1alpha/client.py
63+
search/v1alpha/raw_logs_find.py
64+
search/v1alpha/search_queries_list.py
65+
search/v1alpha/search_query_get.py
66+
search/v1alpha/udm_events_find.py

‎chronicle_api.egg-info/dependency_links.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎chronicle_api.egg-info/entry_points.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[console_scripts]
2+
chronicle = sdk.cli:cli

0 commit comments

Comments
 (0)