### Installation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/index.md

Install the thehive4py library using pip.

```bash
pip install thehive4py
```

--------------------------------

### Quickstart

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/index.md

Initialize the TheHiveApi client with the URL and API key.

```python
from thehive4py import TheHiveApi

hive = TheHiveApi(url="http://localhost:9000", apikey="h1v3b33")
```

--------------------------------

### Auth with username and password

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/client.md

Example of authenticating the client using a username and password.

```python
--8<-- "examples/client/auth_with_username_and_password.py"
```

--------------------------------

### Auth with apikey

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/client.md

Example of authenticating the client using an API key.

```python
--8<-- "examples/client/auth_with_apikey.py"
```

--------------------------------

### Specify the organisation during init

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/client.md

Example of instantiating a client with a specific organization explicitly set in the constructor.

```python
--8<-- "examples/client/org_via_constructor.py"
```

--------------------------------

### SSL Verification

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/client.md

Example of configuring SSL verification with a custom certificate bundle or directory.

```python
--8<-- "examples/client/ssl.py"
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Command to install pre-commit hooks for automatic checks before each commit.

```bash
pre-commit install
```

--------------------------------

### Install the package for development

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Installs the thehive4py package with development extras using pip.

```bash
pip install -e .[dev]
```

--------------------------------

### Retries

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/client.md

Example of configuring a custom retry mechanism with a specific number of attempts and backoff factor for GET methods and 500 status codes.

```python
--8<-- "examples/client/retries.py"
```

--------------------------------

### Add observables during alert creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Example of creating an alert with associated IP and domain observables.

```python
--8<-- "examples/alert/observable_during_alerting.py"
```

--------------------------------

### Promote alert to case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Example of promoting an alert to a new case using the alert.promote_to_case method.

```python
--8<-- "examples/alert/case_promote.py"
```

--------------------------------

### Switch organisations during runtime

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/client.md

Example of instantiating a client without an explicit organization and then switching organizations at runtime using the session_organisation property.

```python
--8<-- "examples/client/org_during_runtime.py"
```

--------------------------------

### Add comment to an alert

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Example of creating an alert and then adding a comment to it.

```python
--8<-- "examples/alert/comment.py"
```

--------------------------------

### Add comment to a case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Example of creating a case and then adding a simple comment to it.

```python
--8<-- "examples/case/comment.py"
```

--------------------------------

### Add pages during case creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Example of creating a case with two pages (notes and summary) during the initial case creation.

```python
--8<-- "examples/case/pages_during_creation.py"
```

--------------------------------

### Get Single Alert

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Shows how to retrieve a single alert by its ID using the alert.get method.

```python
from thehive4py.endpoints.alert import AlertEndpoint

# Assume alert_id is the ID of the alert you want to fetch
alert_id = "some_alert_id"

# Fetch the alert
response = AlertEndpoint.get(alert_id)

# Print the fetched alert (optional)
print(response.json())

```

--------------------------------

### Add logs to tasks

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Example of enriching a case task with a task log containing an attachment.

```python
--8<-- "examples/case/task_with_task_log.py"
```

--------------------------------

### Add pages to an existing case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Example of adding pages retroactively to an existing case using the case.create_page method.

```python
--8<-- "examples/case/pages_after_creation.py"
```

--------------------------------

### Fetch Case with Get

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Retrieves a single case using the case.get method with the case's id.

```python
from thehive4py.api import TheHive

hive = TheHive( থhive_url='http://localhost:9000', api_key='YOUR_API_KEY')

case_id = 'YOUR_CASE_ID'
output = hive.case.get(case_id)
print(output)

```

--------------------------------

### Add procedures to an existing case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Example of enriching an existing case with MITRE ATT&CK procedures (TTPs) using the case.create_task method.

```python
--8<-- "examples/case/procedures_after_creation.py"
```

--------------------------------

### Create a client with username/password authentication

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

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",
    )
```

--------------------------------

### Simple Alert Creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Demonstrates how to create the most simplistic alert possible using the alert.create method, specifying only the required fields.

```python
from thehive4py.endpoints.alert import AlertEndpoint

# Define required fields for a simple alert
input_alert = {
    "type": "Phishing",
    "source": "MySecurityTool",
    "sourceRef": "CASE-12345",
    "title": "Suspicious email received",
    "description": "An email with suspicious links was reported by a user."
}

# Create the alert
response = AlertEndpoint.create(input_alert)

# Print the response (optional)
print(response.json())

```

--------------------------------

### Create a new alert

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Demonstrates how to create a new alert with the minimally 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",
    }
)
```

--------------------------------

### Create a client with API key authentication

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

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="h1v3b33",
    )
```

--------------------------------

### Add file based observables

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Shows how to add file-based observables with attachments to an alert.

```python
--8<-- "examples/alert/observable_from_file.py"
```

--------------------------------

### Run the entire test suite locally

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Command to execute the whole test suite locally using the 'test' session in noxfile.py.

```bash
nox --session=test
```

```bash
nox -s test
```

--------------------------------

### Minimalistic Case Creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Demonstrates how to create the most minimalistic case possible using the case.create method.

```python
from thehive4py.api import TheHive
from thehive4py.models import Case, CaseObservable, CaseArtifact

hive = TheHive( থhive_url='http://localhost:9000', api_key='YOUR_API_KEY')

case = Case(
    title='My first case',
    description='This is a case description',
    tlp=1,
    severity=1,
    status='New',
    tags=['minimalistic'],
    owner='admin',
    assignees=['admin']
)

output = hive.case.create(case)
print(output)

```

--------------------------------

### Advanced Alert Creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Shows how to create a more complex alert by defining the input alert object outside the create method call, leveraging type hints for better readability.

```python
from thehive4py.endpoints.alert import AlertEndpoint
from thehive4py.models.alert import Alert

# Define a more complex alert object with additional fields
input_alert = Alert({
    "type": "Malware",
    "source": "VirusScanner",
    "sourceRef": "SCAN-XYZ789",
    "title": "Malware detected on endpoint",
    "description": "A new strain of malware was detected on the \"Workstation-01\" endpoint.",
    "severity": 3,
    "tags": ["malware", "detection", "endpoint"],
    "customFields": {
        "ioc_type": "hash",
        "ioc_value": "a1b2c3d4e5f6..."
    }
})

# Create the alert by passing the input_alert object
response = AlertEndpoint.create(input_alert)

# Save the response to output_alert to use it later
output_alert = response.json()

# Print the output alert (optional)
print(output_alert)

```

--------------------------------

### List available nox sessions

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Command to list all available CI check sessions in noxfile.py.

```bash
nox --list
```

--------------------------------

### Add observables individually to an alert

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Shows how to add observables to an existing alert using the `alert.create_observable` method.

```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"},
)
```

--------------------------------

### Fetch multiple alerts with find

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Demonstrates fetching multiple alerts using the alert.find method with both raw dictionary filters and thehive4py's filter builders.

```python
--8<-- "examples/alert/fetch_with_find.py"
```

--------------------------------

### Update Bulk Alerts

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Illustrates how to update multiple alerts simultaneously using the alert.bulk_update method, providing a list of alert IDs and the fields to apply uniformly.

```python
from thehive4py.endpoints.alert import AlertEndpoint

# Assume original_alert_ids is a list of alert IDs to be updated
original_alert_ids = ["alert_id_1", "alert_id_2", "alert_id_3"]

# Define the fields to update for all alerts
fields_to_update = {
    "ids": original_alert_ids,
    "title": "Bulk updated title",
    "tags": ["bulk_update", "incident"]
}

# Perform the bulk update
response = AlertEndpoint.bulk_update(fields_to_update)

# Print the response (optional)
print(response.json())

```

--------------------------------

### Add observables to an existing alert

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Demonstrates adding single and bulk observables to an existing alert, including handling mixed data types.

```python
--8<-- "examples/alert/observable_after_alerting.py"
```

--------------------------------

### Merge alert into case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Shows how to merge a new alert into an existing parent case using the alert.merge_into_case method.

```python
--8<-- "examples/alert/case_merge.py"
```

--------------------------------

### Advanced Case Creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Demonstrates how to create a more advanced case using the InputCase type hint and the case.create method.

```python
from thehive4py.api import TheHive
from thehive4py.types import InputCase

hive = TheHive( থhive_url='http://localhost:9000', api_key='YOUR_API_KEY')

input_case = InputCase(
    title='My second case',
    description='This is a case description',
    tlp=1,
    severity=1,
    status='New',
    tags=['advanced'],
    owner='admin',
    assignees=['admin']
)

output_case = hive.case.create(input_case)
print(output_case)

```

--------------------------------

### Create an empty case

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Creates a new, empty case.

```python
my_case = hive.case.create(
    case={"title": "My First Case", "description": "Just a description"}
)
```

--------------------------------

### Add observables during alert creation

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

An alternative method to add observables by including them in the `observables` field during alert creation.

```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"},
        ],
    }
)
```

--------------------------------

### Promote an existing alert to a case

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Converts an existing alert into a case and associates it with that alert.

```python
my_case = hive.alert.promote_to_case(alert_id=my_alert["_id"])
```

--------------------------------

### Delete alerts in bulk

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Illustrates deleting multiple alerts in a single request using the alert.bulk_delete method.

```python
--8<-- "examples/alert/delete_bulk.py"
```

--------------------------------

### Execute a portion of the test suite

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Command to execute only a specific part of the test suite by passing arguments to the nox session, which are then forwarded to pytest.

```bash
nox -s test -- tests/test_observable_endpoint.py -v
```

--------------------------------

### Update an alert

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Demonstrates how to update an existing alert by adding a tag and changing the title.

```python
hive.alert.update(
    alert_id=my_alert["_id"],
    fields={
        "title": "My updated alert",
        "tags": ["my-tag"],
    },
)
```

--------------------------------

### Fetch updated alert

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Illustrates how to fetch the latest version of an alert after making modifications, as the local object is not automatically updated.

```python
my_alert = hive.alert.get(alert_id=my_alert["_id"])
```

--------------------------------

### Update Single Alert

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Demonstrates how to update a single alert using the alert.update method, specifying the alert ID and the fields to modify.

```python
from thehive4py.endpoints.alert import AlertEndpoint

# Assume alert_id is the ID of the alert you want to update
alert_id = "some_alert_id"

# Define the fields to update
fields_to_update = {
    "title": "Updated alert title",
    "tags": ["updated", "incident"]
}

# Update the alert
response = AlertEndpoint.update(alert_id, fields_to_update)

# Fetch the latest version of the alert to see the changes
updated_alert = AlertEndpoint.get(alert_id).json()

# Print the updated alert (optional)
print(updated_alert)

```

--------------------------------

### Run CI checks manually

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Command to run all CI checks except tests using nox.

```bash
nox
```

--------------------------------

### Retrieve All Observables of a Case

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Retrieves all observables associated with a case.

```python
case_observables = hive.case.find_observables(case_id=my_case["_id"])
```

--------------------------------

### Fetch Cases with Find

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Fetches multiple cases based on arbitrary conditions using the case.find method.

```python
from thehive4py.api import TheHive
from thehive4py.query import CaseFilter

hive = TheHive( থhive_url='http://localhost:9000', api_key='YOUR_API_KEY')

# Create two cases with different tags
case1 = hive.case.create(Case(title='Case 1', tags=['antivirus']))
case2 = hive.case.create(Case(title='Case 2', tags=['phishing']))

# Construct a query filter for cases with 'antivirus' or 'phishing' tags
query = CaseFilter()
query.tags.contains('antivirus') | query.tags.contains('phishing')

output = hive.case.find(query)
print(output)

```

--------------------------------

### Retrieve Specific Observables of a Case (using filter classes)

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Retrieves specific IP observables from a case using filter classes.

```python
ip_observable = hive.case.find_observables(
    case_id=my_case["_id"],
    filters=Eq("dataType", "ip") & Like("data", "93.184.216.34")
)
```

--------------------------------

### Retrieve Specific Observables of a Case (using dict-based approach)

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Retrieves specific IP observables from a case using a dict-based filtering approach.

```python
ip_observable = hive.case.find_observables(
    case_id=my_case["_id"],
    filters={
        "_and": [
            {"_field": "dataType", "_value": "ip"},
            {"_like": {"_field": "data", "_value": "93.184.216.34"}},
        ]
    }
)
```

--------------------------------

### TheHive4py Endpoints Reference

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/reference/endpoints.md

This snippet shows how to import and display the submodules of the thehive4py.endpoints module.

```python
::: thehive4py.endpoints
    options:
        show_submodules: true
```

--------------------------------

### Delete single alert

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/alert.md

Demonstrates deleting a single alert using the alert.delete method.

```python
--8<-- "examples/alert/delete_single.py"
```

--------------------------------

### Add Tasks During Case Creation

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Creates a case with specified tasks (e.g., 'Triage', 'Respond') during the initial case creation.

```python
--8<-- "examples/case/tasks_during_creation.py"
```

--------------------------------

### TheHive4py Types

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/reference/types.md

This snippet shows how to import and display the types available in the thehive4py.types module, with submodules shown.

```python
from thehive4py.types import *

__all__ = [
    "Alert",
    "Artifact",
    "Case",
    "CaseTemplate",
    "CustomField",
    "CustomFieldDefinition",
    "HiveObject",
    "Observable",
    "Organization",
    "Tag",
    "Task",
    "Tlp",
    "User",
    "Job",
    "Attachment",
    "CaseObservable",
    "CaseArtifact",
    "CaseTag",
    "CaseCustomField",
    "CaseTask",
    "CaseAttachment",
    "CaseUser",
    "CaseJob",
    "CaseAlert",
    "CaseObservableArtifact",
    "CaseObservableTag",
    "CaseObservableCustomField",
    "CaseObservableTask",
    "CaseObservableAttachment",
    "CaseObservableUser",
    "CaseObservableJob",
    "CaseObservableAlert",
    "CaseArtifactTag",
    "CaseArtifactCustomField",
    "CaseArtifactTask",
    "CaseArtifactAttachment",
    "CaseArtifactUser",
    "CaseArtifactJob",
    "CaseArtifactAlert",
    "CaseTagCustomField",
    "CaseTagTask",
    "CaseTagAttachment",
    "CaseTagUser",
    "CaseTagJob",
    "CaseTagAlert",
    "CaseCustomFieldTask",
    "CaseCustomFieldAttachment",
    "CaseCustomFieldUser",
    "CaseCustomFieldJob",
    "CaseCustomFieldAlert",
    "CaseTaskAttachment",
    "CaseTaskUser",
    "CaseTaskJob",
    "CaseTaskAlert",
    "CaseAttachmentUser",
    "CaseAttachmentJob",
    "CaseAttachmentAlert",
    "CaseUserJob",
    "CaseUserAlert",
    "CaseJobAlert"
]
```

--------------------------------

### Add File Based Observable to Case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Adds a file-based observable to a case. This requires a file path and the observable's dataType set to 'file'.

```python
--8<-- "examples/case/observable_file.py"
```

--------------------------------

### Add Simple Observable to Case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Adds a simple observable to an existing case. The Case API does not support adding observables during case creation.

```python
--8<-- "examples/case/obervable_simple.py"
```

--------------------------------

### Delete Case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Demonstrates how to delete a single case using the delete method. The case endpoint does not support bulk deletion.

```python
--8<-- "examples/case/delete.py"
```

--------------------------------

### Add Tasks to Existing Case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Adds tasks retroactively to an already created case using the case.create_task method.

```python
--8<-- "examples/case/tasks_after_creation.py"
```

--------------------------------

### Update Bulk Cases

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Updates the same fields with the same values on multiple cases using the case.bulk_update method.

```python
from thehive4py.api import TheHive
from thehive4py.models import Case

hive = TheHive( থhive_url='http://localhost:9000', api_key='YOUR_API_KEY')

# Create two cases for bulk update
case1 = hive.case.create(Case(title='Case A', tags=['tag1']))
case2 = hive.case.create(Case(title='Case B', tags=['tag2']))

original_case_ids = [case1.id, case2.id]

fields = {
    'ids': original_case_ids,
    'title': 'Bulk Updated Title',
    'tags': ['bulk_update', 'common_tag']
}

output = hive.case.bulk_update(fields)
print(output)

```

--------------------------------

### Merge Cases

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Creates two cases and merges them into a single new case. The original cases are deleted and their legacy is preserved in the merged case.

```python
--8<-- "examples/case/merge.py"
```

--------------------------------

### Merge an existing alert into a new case

Source: https://github.com/thehive-project/thehive4py/blob/main/README.md

Merges an existing alert into a new case at a later time.

```python
hive.alert.merge_into_case(alert_id=my_alert["_id"], case_id=my_case["_id"])
```

--------------------------------

### Update Single Case

Source: https://github.com/thehive-project/thehive4py/blob/main/docs/examples/case.md

Updates a single case using the case.update method, requiring the case_id and fields to update.

```python
from thehive4py.api import TheHive

hive = TheHive( থhive_url='http://localhost:9000', api_key='YOUR_API_KEY')

case_id = 'YOUR_CASE_ID'
fields = {
    'title': 'Updated title',
    'tags': ['updated', 'tags']
}

output = hive.case.update(case_id, fields)
print(output)

# Fetch the updated case to see the changes
updated_case = hive.case.get(case_id)
print(updated_case)

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.