chronicle / detection-rules

Collection of YARA-L 2.0 sample rules for the Chronicle Detection API

Chronicle API Samples in Python

Python samples and guidelines for using Chronicle APIs.

Setup

Follow these instructions: https://cloud.google.com/python/setup

You may skip installing the Cloud Client Libraries and the Cloud SDK, they are unnecessary for interacting with Chronicle.

After creating and activating a virtual environment, install Python library dependencies by running this command:

pip install -r requirements.txt

It is assumed that you're using Python 3.7 or above. If you're using an older Python 3 version, you need to install this backported library as well:

pip install dataclasses

Credentials

Running the samples requires a JSON credentials file. By default, all the 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:

-c <file_path>

or

--credentials_file <file_path>

Usage

You can run samples on the command-line, assuming the current working directory is the root directory of this repository (i.e. the directory which contains this README.md file):

Detect API

python3 -m detect.v2.<sample_name> -h

Lists API

python3 -m lists.<sample_name> -h

Lists API v1alpha

python -m lists.v1alpha.create_list -h
python -m lists.v1alpha.get_list -h
python -m lists.v1alpha.patch_list -h

detection-rules's Issues

Rule_manager - Unable to rename remote rules

@threat-punter Is renaming a remote rule not possible via the rule_cli? I tried to rename a rule in our system (changed from "office365_LogTypes" to "Office365_LogTypes") and got the below error. I updated the yaral rule_name, the file name and the rule config entry.

13-Mar-24 07:09:41 UTC | INFO | load_rules | Loaded 7 rules from /opt/actions-runner/_work/chronicle-siem-detection-rules-dev
13-Mar-24 07:09:41 UTC | INFO | update_remote_rules | Attempting to retrieve latest version of all rules from Chronicle
13-Mar-24 07:09:41 UTC | INFO | get_remote_rules | Attempting to retrieve all rules from Chronicle
13-Mar-24 07:09:42 UTC | INFO | get_remote_rules | Retrieved 57 rules
13-Mar-24 07:09:42 UTC | INFO | get_remote_rules | Retrieved a total of 57 rules
13-Mar-24 07:09:42 UTC | INFO | get_remote_rules | Attempting to retrieve rule deployment state for 57 rules
13-Mar-24 07:10:21 UTC | INFO | update_remote_rules | Checking if any rule updates are required
13-Mar-24 07:10:21 UTC | INFO | update_remote_rules | Local rule name Office365_LogTypes not found in remote rules
Traceback (most recent call last):
File "/opt/actions-runner/_work/_tool/Python/3.10.12/x64/lib/python3.10/runpy.py", line 196, in _run_module_as_main
return _run_code(code, main_globals, None,
File "/opt/actions-runner/_work/_tool/Python/3.10.12/x64/lib/python3.10/runpy.py", line 86, in _run_code
exec(code, run_globals)
File "/opt/actions-runner/_work/chronicle-siem-detection-rules-dev/rule_cli/main.py", line 268, in
update_remote_rules()
File "/opt/actions-runner/_work/chronicle-siem-detection-rules-dev/rule_cli/main.py", line 85, in update_remote_rules
rule_updates = Rules.update_remote_rules(http_session=http_session)
File "/opt/actions-runner/_work/chronicle-siem-detection-rules-dev/rule_cli/rules.py", line 557, in update_remote_rules
rule_id = local_rule.rule_id
AttributeError: 'Rule' object has no attribute 'rule_id'

Detailed instructions URLs are no longer valid

Hi there,

It looks like these two URLs are 404'ing:

Detection UI: https://<your chronicle instance>/docs/detection-engine/detection-engine-ui.html
Detection API: https://<your chronicle instance>/docs/detection-engine/detection-engine-api.html

Thanks for publishing these!

chronicle_auth.py doesn't read in dotenv environment variable

Version 3.12.2
Arch: 64
Packages:
annotated-types, 0.6.0
cachetools, 5.3.3
certifi 2024.2.2
charset-normalizer, 3.3.2
google-auth, 2.29.0
idna, 3.7
pip, 24.0
pyasn1, 0.6.0
pyasn1_module, 0.4.0
pydantic, 2.6.4
pydantic_core, 2.16.3
pydantic-dotenv, 1.0.1
PyYAML, 6.0.1
requests, 2.31.0
rsa, 4.9
ruamel.yaml, 0.18.6
ruamel.yaml.clib, 0.2.8
typing_extensions, 4.11.0
urllib, 2.2.1

(venv312) PS \\rule_manager_c> python -m rule_cli --pull-latest-rules
14-May-24 13:28:16 Eastern Daylight Time | INFO | <module> | Rule CLI started
14-May-24 13:28:16 Eastern Daylight Time | INFO | <module> | Attempting to pull latest version of all rules from Chronicle and update local files
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "\\venv312\rule_manager_c\rule_cli\__main__.py", line 407, in <module>
    pull_latest_rules()
  File "\\venv312\rule_manager_c\rule_cli\__main__.py", line 63, in pull_latest_rules
    http_session = initialize_http_session()
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File venv312\rule_manager_c\rule_cli\__main__.py", line 53, in initialize_http_session
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "\\venv312\rule_manager_c\rule_cli\__main__.py", line 407, in <module>
    pull_latest_rules()
  File "\\venv312\rule_manager_c\rule_cli\__main__.py", line 63, in pull_latest_rules
    http_session = initialize_http_session()
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "\\venv312\rule_manager_c\rule_cli\__main__.py", line 53, in initialize_http_session
    os.environ["CHRONICLE_API_CREDENTIALS"]
    ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen os>", line 685, in __getitem__
KeyError: 'CHRONICLE_API_CREDENTIALS'
(venv312) PS \\rule_manager_c>

Additionally following the setup directions there is a .env file at the root of the rule_manager_c named ruleimport.env with all the correct fields from SecOps and GCP Instance IDs.

Rule_Manager - Skip archived Rules flag

@threat-punter would it be possible in the Rule Manager to add in a feature to allow the skipping of Archived rules for all the processes (get/update/etc)? I tried to poke around and find where to update the code but couldn't figure it out, would be a great feature.

Would be nice when running python -m rule_cli something like --skip-archive.