opencybersecurityalliance / kestrel-huntbook

This repository hosts community contributed Kestrel huntflows (.hf) and huntbooks (.ipynb)

Community-Contributed Kestrel Huntbooks

This repository hosts community-contributed Kestrel huntflows/huntbooks/patterns.

Basics about Kestrel:

• What is Kestrel?
• Kestrel main repo

Three ways to view/execute/use huntbooks in this repo:

1. Launch a Kestrel cloud sandbox

Use the following links to launch a Kestrel sandbox in public cloud to view, execute, and play with the huntbooks.

• Tutorial huntbooks (the Kestrel cloud sandbox opening the tutorial directory)
• Real-world huntbooks (the Kestrel cloud sandbox opening the huntbooks directory)
• Black Hat USA 2022 huntbooks (the Kestrel cloud sandbox opening the blackhat22 directory)

Beyond playing with the huntbooks, you can perform hunts directly in the sandbox. After launching your sandbox instance, you can connect your own data sources by creating a stix-shifter interface config file named stixshifter.yaml using the text editor in the Jupyter UI. Any huntbook in the same directory in your sandbox instance will be able to use data sources defined in the stixshifter.yaml.

This cloud sandbox environment is managed by binder, and sandboxes will be spun up at sponsored public cloud such as Google Cloud. The uses are administered by those organizations, and subject to their own terms of use. Your data will be transmitted and analyzed in the public cloud if you perform hunts in the sandbox with data connected/retrieved from your organization's networks.

The Kestrel sandbox will launch Kestrel runtime with all analytics in the kestrel-lanalytics repo. GeoLite2 Geolocation Data from MaxMind, which is copied into your sandbox instance to run analytics hunt step piniponmap, is subject to MaxMind license. Please confirm that your uses comply with those limitations, which include CC-BY-SA-4 terms, some prohibited uses, and an indemnity in favor of MaxMind. MaxMind's license terms are separate from OASIS' license for Kestrel.

2. Deploy Kestrel in your hunting environment

After viewing and playing huntbooks in the Kestrel cloud sandbox environment, it is recommended to deploy Kestrel in your orgainzation's hunting environment (in your cloud or on-premises) to perform hunts where no data will be transmitted outside your orgainzation networks.

How to deploy Kestrel:

• Install/setup Kestrel
• Connect to data sources
• Setup Kestrel analytics

Examples of hunting stack setup:

• Docker services for Kestrel core, Elasticsearch, and Kestrel analytics
• Sysmon + Elasticsearch + Kestrel
• Sysflow/Sysmon + Elasticsearch + Kestrel

3. Open huntbook files on GitHub directly

You can open *.ipynb huntbook files on GitHub. This is a fallback option if Kestrel cloud sandbox is not working. This option only allows you to view huntbooks, but not re-execute or adjust any hunt steps. And Kestrel syntax highlight is not supported with this approach.

How to Contribute

1. Submit a PR with a description of the new huntbook to add.
2. If the huntbook has testing data, consider to put the data in data-bucket-kestrel
3. Get approval from one of the maintainers.
4. Share the link (and the cloud sandbox link) of your huntbook with others.

kestrel-huntbook's Issues

Broken links for "Examples of a hunting stack setup"

The two examples in the README.md lead to a 404 error. Perhaps one of them is supposed to link to this: https://opencybersecurityalliance.org/kestrel-sysflow-open-hunting-stack/