From 2360950848c319e46c9b7b3c36ab4971acb4c127 Mon Sep 17 00:00:00 2001 From: Kamforka Date: Sat, 30 Sep 2023 13:36:25 +0200 Subject: [PATCH 1/3] #291 - enhance readme --- README.md | 275 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 236 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index c715b580..67450c1e 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,267 @@ -
-

- -

-
-
-

- - Discord - - - License - - - Pypi page - - - ci action badge - -

-
+![TheHive Logo](https://thehive-project.org/img/logo.png) +[![Discord](https://img.shields.io/discord/779945042039144498)](https://chat.thehive-project.org) +[![License](https://img.shields.io/github/license/TheHive-Project/TheHive4py)](./LICENSE) +[![Pypi Page](https://img.shields.io/pypi/dm/thehive4py)](https://pypi.org/project/thehive4py) +[![CI Action Badge](https://github.com/TheHive-Project/TheHive4py/actions/workflows/ci.yml/badge.svg)](https://github.com/TheHive-Project/TheHive4py/actions/workflows/ci.yml) # thehive4py - IMPORTANT: The library is still under development and is in beta phase. Use it with caution and expect breaking changes before the first stable release! +> **IMPORTANT:** This library is currently in active development and is in the beta phase. Please use it with caution and be prepared for potential breaking changes until the first stable release! -Rebooted version of thehive4py for TheHive5! Stay tuned, more to come! +**What's New:** This is a rebooted version of `thehive4py` designed specifically for TheHive 5. Stay tuned, as we have more exciting updates in store! -## Development +Welcome to `thehive4py`, the Python library designed to simplify interactions with TheHive 5.x. Whether you're a cybersecurity enthusiast or a developer looking to integrate TheHive into your Python projects, this library has got you covered. -### Setting up a virtual environment (optional) +Feel free to explore the library's capabilities and contribute to its development. We appreciate your support in making TheHive integration in Python more accessible and efficient. -You can setup a venv (see the [official docs for this](https://docs.python.org/3/tutorial/venv.html): +# Quickstart +## Requirements +`thehive4py` works with all currently supported python versions, at the time of writing `py>=3.8`. One can check the official version support and end of life status [here](https://devguide.python.org/versions/). + +## Installation +The `thehive4py` can be installed with pip like: + +``` +pip install "thehive4py>=2.0.0b" +``` + +**Important Note**: Since `thehive4py` 2.x is still in beta it is necessary to specify the beta version number during pip install, otherwise the latest version of 1.x would be installed. + +## Create a client + +You can create a `thehive4py` client instance in two different ways, depending on your authentication method: + +**Method 1: Username/password authentication** + +If you're using a username and password for authentication, you can create a client like this: + +```python +from thehive4py import TheHiveApi + +hive = TheHiveApi( + url="https://thehive.example.com", + username="analyst@example.com", + password="supersecret", + ) +``` + +**Method 2: Apikey authentication** + +Alternatively, if you prefer using an API key for authentication, use this method: + +```python +from thehive4py import TheHiveApi + +hive = TheHiveApi( + url="https://thehive.example.com", + apikey="c0ff33nc0d3", + ) +``` + +Choose the authentication method that best suits your needs and security requirements. + + +## Create an alert + +To create a new alert, you can use the client's `alert.create` method with the following minimally required fields: + +- `type`: The type of the alert. +- `source`: The source of the alert. +- `sourceRef`: A unique reference for the alert. +- `title`: A descriptive title for the alert. +- `description`: Additional information describing the alert. + +Here's an example that demonstrates how to create a new alert with these required fields: + +```python +my_alert = hive.alert.create( + alert={ + "type": "my-alert", + "source": "my-source", + "sourceRef": "my-reference", + "title": "My test alert", + "description": "Just a description", + } +) +``` +The above snippet will create a new alert with the minimally required fields and will store the output alert response in the `my_alert` variable. + + +**Important Note**: Attempting to create another alert with the same values for `type`, `source`, and `sourceRef` will not be accepted by the backend as the combination of the three fields should be unique per alert. + +## Add alert observables + +To make your alerts more informative and actionable, you can add observables to them. Observables are specific pieces of data related to an alert. In this example, we'll enhance the previous alert with two observables: an IP address (`93.184.216.34`) and a domain (`example.com`). + +**Method 1: Adding observables individually** + +You can add observables to an existing alert using the `alert.create_observable` method as shown below: + +```python +hive.alert.create_observable( + alert_id=my_alert["_id"], + observable={"dataType": "ip", "data": "93.184.216.34"}, +) +hive.alert.create_observable( + alert_id=my_alert["_id"], + observable={"dataType": "domain", "data": "example.com"}, +) ``` -# Create and activate venv -python3 -m venv -source /bin/activate + +This method is useful when you want to add observables to an alert after its initial creation. + +**Method 2: Adding observables during alert creation** + +Alternatively, if you already know the observables when creating the alert, you can use the `observables` field within the alert creation method for a more concise approach: + + +Alternatively in case the observables are known during alert time we can use the `alert.create` method's `observables` field as a shortcut: + +```python +my_alert = hive.alert.create( + alert={ + "type": "my-alert", + "source": "my-source", + "sourceRef": "my-reference", + "title": "My test alert", + "description": "Just a description", + "observables": [ + {"dataType": "ip", "data": "93.184.216.34"}, + {"dataType": "domain", "data": "example.com"}, + ], + } +) +``` + +This method not only saves you from making additional network requests but also reduces the chance of errors, making your code more efficient and reliable. + +By incorporating observables into your alerts, you provide valuable context and information for further analysis and incident response. + +## Update an alert + +If you need to add or modify fields in an existing alert, you can easily update it using client's `alert.update` method. In this example, we'll add a tag (`my-tag`) and change the alert's title: + +```python +hive.alert.update( + alert_id=my_alert["_id"], + fields={ + "title": "My updated alert", + "tags": ["my-tag"], + }, +) ``` -### Install the package for development +The code above updates the alert's title and adds a new tag to the alert in TheHive. -To install the package with the dev dependencies one can run: +**Important Note**: It's essential to understand that the `my_alert` object in your Python code will not automatically reflect these changes. `thehive4py` doesn't provide object relationship mapping features. To get the latest version of the alert after making modifications, you need to fetch it again: +```python +my_alert = hive.alert.get(alert_id=my_alert["_id"]) +``` + +After this request, `my_alert["title"]` will be `"My Updated Alert"`, and `my_alert["tags"]` will include `"my-tag"`. This ensures that you have the most up-to-date information in your Python code. + +## Create a case + +You have two options to create a case in `thehive4py`: either promote an existing alert to a case or create a new, empty case. + +**Method 1: Promote an existing alert to a case** + +You can convert an existing alert into a case and associate it with that alert using the `alert.promote_to_case` method: + +```python +my_case = hive.alert.promote_to_case(alert_id=my_alert["_id"]) +``` + +This method will create a case based on the existing alert and automatically assign the alert to the case. Any observables from the alert will also be copied as case observables. + +**Method 2: Create an empty case** + +Alternatively, you can create a new, empty case using the `case.create` method: + +```python +my_case = hive.case.create( + case={"title": "My First Case", "description": "Just a description"} +) +``` + +This method creates a fresh case with no alerts or observables attached. + +To merge an existing alert into a new case at a later time, use the `alert.merge_into_case` method: + +```python +hive.alert.merge_into_case(alert_id=my_alert["_id"], case_id=my_case["_id"]) +``` + +By choosing the method that suits your workflow, you can efficiently manage cases and alerts within TheHive using `thehive4py`. + +# Development + +## Setting up a virtual environment (optional) + +A virtual environment is highly recommended for clean and isolated Python development. It allows you to manage project-specific dependencies and avoid conflicts with other projects. In case you don't know what is/how to use a virtual environment let's find out more [here](https://docs.python.org/3/library/venv.html#module-venv). + +## Install the package for development + +If you are a first time contributor to github projects please make yourself comfortable with the page [contributing to projects](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). + +Navigate to the cloned repository's directory and install the package with development extras using pip: + ``` pip install -e '.[dev]' ``` + +This command installs the package in editable mode (`-e`) and includes additional development dependencies. + +Now, you have the `thehive4py` package installed in your development environment, ready for contributions. + +## Contributing + +To contribute to `thehive4py`, follow these steps: + +1. **Create an issue:** Start by creating an issue that describes the problem you want to solve or the feature you want to add. This allows for discussion and coordination with other contributors. + +2. **Create a branch:** Once you have an issue, create a branch for your work. Use the following naming convention: `-title-of-branch`. For example, if you're working on issue #1 and updating the readme, name the branch `1-update-readme`. + +3. **Commit prefix:** When making commits, prefix them with `# - commit message`. This practice helps in easy navigation and tracking of commits back to the corresponding issue. For instance, use `#1 - update readme` as the commit message. + + +## Run CI checks before pushing changes -### Run CI checks before pushing changes +To ensure the integrity of your changes and maintain code quality, you can run CI checks before pushing your changes to the repository. Use one of the following methods: -To check the integrity of changes made one can run: +**Method 1: Manual check** + +Run the CI checks manually by executing the following command: ``` python scripts/ci.py ``` -or to execute the checks automatically just install the pre-commit hooks come with the repo: +This command will trigger the CI checks and provide feedback on any issues that need attention. + +**Method 2: Automatic checks with pre-commit hooks [experimental]** + +**Important Note**: The pre-commit hooks are not thoroughly tested at the moment and probably broken + +For a more streamlined workflow, you can install pre-commit hooks provided by the repository. These hooks will automatically execute checks before each commit. To install them, run: ``` pre-commit install ``` -### Run CD commands to build and publish +With pre-commit hooks in place, your changes will be automatically validated for compliance with coding standards and other quality checks each time you commit. This helps catch issues early and ensures a smooth contribution process. -To build the package one can run: +## Testing -``` -python scripts/cd.py build -``` \ No newline at end of file +`thehive4py` primarily relies on integration tests, which are designed to execute against a live TheHive 5.x instance. These tests ensure that the library functions correctly in an environment closely resembling real-world usage. + +However, due to licensing constraints with TheHive 5.x, the integration tests are currently not available for public or local use. + +To ensure code quality and prevent broken code from being merged, a private image is available for the integration-test workflow. This means that any issues should be detected and addressed during the PR phase. + +The project is actively working on a solution to enable developers to run integration tests locally, providing a more accessible and comprehensive testing experience. + +While local testing is in development, relying on the automated PR checks ensures the reliability and quality of the `thehive4py` library. \ No newline at end of file From fd1ac96ada89d9d9ecb4eff2602481aa2798a628 Mon Sep 17 00:00:00 2001 From: Kamforka Date: Sat, 30 Sep 2023 13:44:20 +0200 Subject: [PATCH 2/3] #291 - delete setup.py --- setup.py | 50 -------------------------------------------------- 1 file changed, 50 deletions(-) delete mode 100644 setup.py diff --git a/setup.py b/setup.py deleted file mode 100644 index a3bb2d5d..00000000 --- a/setup.py +++ /dev/null @@ -1,50 +0,0 @@ -from setuptools import find_packages, setup - - -def parse_version(): - with open("thehive4py/__init__.py") as init_fp: - for line in init_fp: - if line.strip().startswith("__version__"): - return line.split("=")[1].strip().strip('"') - raise ValueError("Unable to parse version number") - - -REQUIREMENTS = ["requests>=2.27"] - - -EXTRAS_REQUIRE = {"lint": ["flake8", "black", "mypy"], "test": ["pytest"]} -EXTRAS_REQUIRE["dev"] = EXTRAS_REQUIRE["lint"] + EXTRAS_REQUIRE["test"] - - -def read(fname): - """Read the content of the file `fname`.""" - with open(fname) as fp: - content = fp.read() - return content - - -setup( - name="thehive4py", - version=parse_version(), - description="Python client for TheHive5", - long_description=read("README.md"), - long_description_content_type="text/markdown", - author="Szabolcs Antal", - author_email="antalszabolcs01@gmail.com", - packages=find_packages(), - install_requires=REQUIREMENTS, - extras_require=EXTRAS_REQUIRE, - license="AGPL-V3", - keywords="thehive api rest client", - classifiers=[ - "Development Status :: 4 - Beta", - "Intended Audience :: Developers", - "Intended Audience :: Information Technology", - "Natural Language :: English", - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "License :: OSI Approved :: GNU Affero General Public License v3", - ], - python_requires=">=3.8", -) From dbb87d70dc6e7a557e3bcc058dcb6877f3e0500e Mon Sep 17 00:00:00 2001 From: Kamforka Date: Sat, 30 Sep 2023 15:04:44 +0200 Subject: [PATCH 3/3] #291 - update action badges --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 67450c1e..7bc4a2d1 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,8 @@ [![Discord](https://img.shields.io/discord/779945042039144498)](https://chat.thehive-project.org) [![License](https://img.shields.io/github/license/TheHive-Project/TheHive4py)](./LICENSE) [![Pypi Page](https://img.shields.io/pypi/dm/thehive4py)](https://pypi.org/project/thehive4py) -[![CI Action Badge](https://github.com/TheHive-Project/TheHive4py/actions/workflows/ci.yml/badge.svg)](https://github.com/TheHive-Project/TheHive4py/actions/workflows/ci.yml) +[![Static-Checks Action Badge](https://github.com/TheHive-Project/TheHive4py/actions/workflows/static-checks.yml/badge.svg)](https://github.com/TheHive-Project/TheHive4py/actions/workflows/static-checks.yml) +[![Integration-Tests Action Badge](https://github.com/TheHive-Project/TheHive4py/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/TheHive-Project/TheHive4py/actions/workflows/integration-tests.yml) # thehive4py