### Taegis IPython Line Magic Example

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/README.md

Demonstrates the usage of a Taegis IPython line magic. Line magics start with a single '%' and process a single line of input. This example shows how to interact with users.

```python
%taegis users current-user --assign me --display me
```

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

### Install taegis-magic Python Package

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/Getting_Started.ipynb

Installs the taegis-magic Python package using pip. This is a prerequisite for using the library's features.

```python
!python -m pip install taegis-magic
```

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

### Taegis Magic CLI Examples

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/cli/README.md

Demonstrates various Taegis Magic CLI commands for searching alerts and events, and staging investigation evidence. These commands can output results to JSON files and utilize local databases for tracking.

```bash
$ taegis alerts search --cell "FROM alert WHERE status = 'OPEN' AND metadata.severity >= 0.2 AND investigation_ids IS NULL AND metadata.title = 'Suspicious AWS Account Enumeration'| head 2" --track --database test_database.db > test_results.json
$ taegis events search --cell "FROM cloudaudit WHERE user_name CONTAINS 'jupiter' EARLIEST=-3d | head 2" --track --database test_database.db > test_events.json
$ taegis investigations evidence stage alerts test_results.json --database test_database.db
$ taegis investigations evidence stage events test_events.json --database test_database.db
$ taegis investigations evidence stage search_queries --database test_database.db
$ taegis investigations evidence show --database test_database.db
$ echo "This is a a test" > test_kf.md
$ taegis investigations create --title "CLI Test" --key-findings test_kf.md --priority LOW --type SECURITY_INVESTIGATION --status OPEN --assignee-id @customer --database test_database.db
```

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

### Example: Disable SDK Warnings

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Demonstrates how to use the `--no-sdk-warning` option to suppress SDK-level warnings when running a command. This is useful for reducing noise in the output during specific operations.

```bash
taegis --no-sdk-warning alerts search ...
```

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

### Initialize Taegis GraphQL Service and Get User Info

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/investigation create.ipynb

Initializes the GraphQLService from the taegis_sdk_python library. It then queries for the current user and extracts their user ID and given name to be used in creating an investigation.

```python
from taegis_sdk_python import GraphQLService

service = GraphQLService()
user = service.users.query.current_tdruser()
assignee_id = user.user_id
title = f"{user.given_name} Test"
```

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

### Taegis Cell Magic with External Jinja2 File

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/cell_templates.md

This example demonstrates using the `%%taegis` cell magic with an external Jinja2 template file. The `--cell-template-file "example.ql"` option specifies the path to the template file. The results of the query are then assigned to the `alerts` variable.

```taegis
%taegis alerts search --cell-template --cell-template-file "example.ql" --assign alerts
```

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

### Taegis IPython Cell Magic Example

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/README.md

Illustrates the use of a Taegis IPython cell magic. Cell magics start with '%%' and process the entire cell content, including the first line which is treated as a line magic. This example searches alerts based on specific criteria.

```python
%%taegis alerts search --assign alerts
FROM alert
WHERE
    severity >= 0.6 AND
    status = 'OPEN'
    investigation_ids IS NULL
EARLIEST=-1d | head 5
```

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

### Install Taegis Magic using Pip

Source: https://github.com/secureworks/taegis-magic/blob/main/README.md

Installs the taegis-magic Python package using pip. This command is typically run in a bash or terminal environment.

```bash
python -m pip install taegis-magic
```

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

### Taegis Cell Magic with Jinja2 Template

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/cell_templates.md

This example demonstrates using the `%%taegis` cell magic with the `--cell-template` option. It defines Python variables for IPs, domains, severity, and time range, then uses Jinja2 filters within the query to dynamically generate the WHERE clause. The results are assigned to the `alerts` variable.

```python
# define template variables
ips = ['1.1.1.1', '8.8.8.8']
domains = ['secureworks.com', 'sophos.com']
severity = 0.6
earliest = '-1d'

```

```taegis
%%taegis alerts search --cell-template --assign alerts
FROM alert 
WHERE
    ( 
        {{ ips | in('@ip') }} OR
        {{ domains | regex('@domain') }} 
    ) AND
    severity >= {{ severity }}
EARLIEST={{ earliest }}
```

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

### Create and Search Rules

Source: https://context7.com/secureworks/taegis-magic/llms.txt

Facilitates the creation and management of alerting and suppression rules within Taegis. It includes examples for creating custom alert rules based on process activity and suppression rules for known false positives, as well as searching for existing rules. Requires functions from taegis_magic.commands.rules.

```python
from taegis_magic.commands.rules import create_alerting, create_suppression, search

# Create alerting rule
alert_rule = create_alerting(
    cell="""
    FROM process
    WHERE process.name IN ['powershell.exe', 'cmd.exe']
    AND process.cmd_line CONTAINS 'encoded'
    """,
    name="Suspicious Encoded PowerShell",
    severity=0.8,
    description="Detects PowerShell with encoded commands",
    enabled=True,
    region="us-east-2"
)

# Create suppression rule
suppress_rule = create_suppression(
    cell="""
    FROM alert
    WHERE metadata.title = 'Known False Positive'
    AND host.hostname = 'test-server'
    """,
    name="Suppress Test Server FPs",
    description="Suppress known false positives from test environment",
    enabled=True
)

# Search existing rules
rules = search(
    name_pattern="PowerShell",
    enabled_only=True,
    limit=50
)

for rule in rules.results:
    print(f"{rule['name']}: {rule['enabled']}")
```

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

### Execute Taegis Command with Dynamic Query in Python

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/README.md

This Python example shows how to use the `--cell` option with Taegis magics for dynamic query execution. It constructs a query string, assigns it to a variable, and then uses that variable within the `--cell` option to search for events.

```python
user = "admin"
query = f"FROM process WHERE @user CONTAINS '{user}' EARLIEST=-3d"
%taegis events search --cell "$query" --assign events
```

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

### Initialize Taegis Magic Environment and Load Extensions

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_hunt_report.ipynb

Sets up the logging configuration, imports necessary libraries like pandas and datetime, and loads the 'taegis_magic' IPython extension. It also includes a check to ensure indicators are provided.

```python
import logging

import pandas as pd
from datetime import datetime
from textwrap import dedent
from taegis_magic.pandas.ioc import is_domain, is_hash, is_ip_address
from taegis_magic.pandas.utils import default_schema_columns, groupby

from IPython.display import display_markdown

log = logging.getLogger(__name__)
```

```python
if not INDICATORS:
    log.warning("No indicators provided, skipping notebook execution.")
    raise SystemExit()
```

```python
%load_ext taegis_magic
```

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

### Execute a Taegis Notebook with Parameters

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/README.md

This command-line command executes a specified Taegis notebook (`sample.ipynb`). It allows parameterization for tenant, region, and title, and specifies the kernel as Python 3. This is useful for automating notebook runs across different environments.

```bash
taegis notebook execute sample.ipynb --tenant XXXXX --region charlie --title "My Awesome Report" -k python3
```

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

### Execute Alert Search with Query Template File

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ql_templates/example.ipynb

Executes an alert search query using a query template stored in a file. This command requires tenant ID, region, and the path to the template file.

```python
%taegis alerts search --tenant $tenant_id --region $region --cell-template -cell-template-file "child_alert_query.ql" --assign alerts
```

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

### Define Alert Query Parameters

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ql_templates/example.ipynb

Sets up variables for IP addresses, domains, severity level, and the earliest time for alert queries. These variables are used in constructing dynamic queries.

```python
ips = ["1.1.1.1", "8.8.8.8"]
domains = ["secureworks.com", "sophos.com"]
severity = 0.6
earliest = "-1d"
```

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

### Get Taegis Service Object

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Retrieves a Taegis service object based on the provided organization ID and region. This object is essential for interacting with Taegis APIs to perform searches and other operations.

```python
service = get_service(tenant_id=organization_id, environment=region)
```

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

### Execute Alert Search with Query Template

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ql_templates/example.ipynb

Executes an alert search query using a predefined query template string. This command requires tenant ID, region, and the alert query template to be set.

```python
%taegis alerts search --tenant $tenant_id --region $region -t --cell "$alert_query_template" --assign alerts
```

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

### Prepare Notebook Context for Investigations

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Prepares a list of NotebookContext objects for executing investigations. It iterates through tenants, filters results for each tenant, and creates a context with indicators and investigation title. If no results are found for a tenant, it logs a warning and creates a Taegis investigation with a 'null_findings.report.md' key findings.

```python
notebook_context = []
for tenant_id, region in tenants[['id', 'first_environment']].itertuples(index=False):
    indicators = results[results['counts_by_tenant.tenant_id'] == tenant_id]
    if not indicators.empty:
        notebook_context.append(
            NotebookContext(
                tenant=tenant_id, 
                region=region,
                parameters={
                    'INDICATORS': indicators.to_dict(orient="records"),
                    'INVESTIGATION_TITLE': title,
                })
            )
        )
    else:
        log.warning(f"WARNING: No results found for tenant {tenant_id}")
        %taegis investigations create \
        --title "$title" \
        --key-findings "null_findings.report.md" \
        --priority LOW \
        --type THREAT_HUNT \
        --status AWAITING_ACTION \
        --assignee-id "@customer" \
        --tenant $tenant_id \
        --region $region
```

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

### Get Current Taegis User Information

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Retrieves and displays information about the currently logged-in Taegis user. The output is a JSON array containing user details. Output may be truncated for brevity.

```bash
taegis users current-user
```

```json
[{"id": "xxxxx", "id_uuid": null, "user_id": "auth0|xxxxx", "user_id_v1": "auth0|xxxxx", "created_at": "0000-00-00T00:00:00.000Z", "updated_at": "0000-00-00T00:00:00.000Z","...": "..."}]
```

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

### Get Unique User Name from Suspicious Alerts

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/investigation create.ipynb

Extracts the first unique user name from the 'event_data.user_name' column of the filtered 'alerts_evidence' DataFrame. This identifies the user associated with the suspicious activity.

```python
alerts_evidence["event_data.user_name"].unique()[0]
```

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

### Display Taegis CLI Help

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Displays the general help message for the Taegis CLI, outlining available options and commands. This is useful for understanding the tool's capabilities and structure.

```bash
taegis --help
```

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

### Get Alerts from Aggregation Using Pandas

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/Alerts.ipynb

Imports and uses the get_alerts_from_aggregation function from taegis_magic.pandas.alerts to convert aggregated alert data back into a standard alert format, assigning it to 'alerts'.

```python
from taegis_magic.pandas.alerts import get_alerts_from_aggregation

alerts = aggregate_alerts.pipe(get_alerts_from_aggregation)
```

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

### Initiate Taegis User Device Code Authentication

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Initiates the Device Code Authentication flow for a user. This command prompts the user to copy a URL into their browser to complete the sign-in process via the Taegis Portal. Sign-ins timeout after 5 minutes.

```bash
$ taegis auth login
Copy URL into a browser: https://api.ctpx.secureworks.com/auth/device/code/activate?user_code=XXXX-XXXX
```

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

### Construct Dynamic Alert Search Query

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ql_templates/example.ipynb

Builds a dynamic alert search query using Jinja2 templating within a Taegis magic command. It filters alerts based on IP addresses, domains, and severity, with a specified earliest time.

```python
%%taegis alerts search --tenant $tenant_id --region $region --cell-template --assign alerts
FROM alert 
WHERE
    ( 
        {{ ips | in('@ip') }} OR
        {{ domains | regex('@domain') }} 
        {{ ips | and('@ip', '!MATCHES')}}
    ) AND
    severity >= {{ severity }}
EARLIEST={{ earliest }}
```

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

### Lookup Users within Taegis Clients

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/subjects.md

Shows how to apply the 'lookup_users' function to Taegis client data. It involves searching for clients and assigning them to a variable, then piping this client data through 'lookup_users'. The example displays relevant client and correlated user information.

```python
%taegis clients search --assign clients

lookup_users_clients = clients.pipe(lookup_users, region="charlie", user_id_columns=['created_by', 'updated_by'])
lookup_users_clients([
    'client_id',
    'created_by',
    'created_by.user.email',
    'created_by.user.given_name',
    'created_by.user.family_name',
    'updated_by',
    'updated_by.user.email',
    'updated_by.user.given_name',
    'updated_by.user.family_name',
])
```

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

### Fetch QL Rules with taegis_magic

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/rules.ipynb

Retrieves all QL (Query Language) rules from Taegis and assigns them to the variable `ql_rules`. This command requires the taegis_magic extension to be loaded.

```python
%taegis rules type --rule-type QL --assign ql_rules
```

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

### Jupytext Markdown Cell Tagging Example

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/generate_report.md

Demonstrates how to apply cell tags in jupytext markdown format for Python and Markdown cells. The 'tags' attribute within the code block or HTML comment specifies the tags to be applied, such as 'remove_cell'.

```markdown
```python tags=["remove_cell"]
print('This cell will be removed from the report')
```

<!-- #region tags=["remove_cell"] -->
### Internal Notes
This section will not be included in the final report.
<!-- #endregion -->
```

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

### Select Entity and Alert/Event Data

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/context_automation.md

This code selects specific columns from the DataFrame, including tenant ID, alert title, normalized entity field and value, and any columns starting with '@' (excluding the GROUP_BY column). This is for displaying correlated entity and alert/event information.

```python
entities_df[
    [
        "tenant.id",
        "metadata.title",
        "taegis_magic.entities.field",
        "taegis_magic.entities.value",
    ]
    + [
        column
        for column in entities_df.columns
        if column.startswith("@") and column != GROUP_BY
    ]
]

```

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

### Initialize Taegis Magic and Set Query Context

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/ContextAutomation.ipynb

This code block initializes the Taegis Magic extension and sets up global variables for query context, including the group-by field, region, and tenant ID. It uses pandas for display options.

```python
import pandas as pd

pd.set_option("display.max_rows", None)
pd.set_option("display.max_colwidth", None)

from taegis_magic.pandas.context import (
    normalize_entities,
    relate_entities,
    generate_context_queries,
    display_facets,
    add_threat_intel,
    get_ti_pubs,
)

%load_ext taegis_magic

GROUP_BY = "@user"  # or @ip/@domain/@hash/@host
REGION = "charlie"  # or delta/echo/foxtrot
TENANT = "00000"

```

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

### Create Taegis Notebook Template

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/cli/notebook.md

Creates a new parameterized notebook template for Taegis investigations. This template includes starter code for alert/event searches, data transformations, filters, evidence staging, and report generation.

```bash
taegis notebook create [output_notebook]
```

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

### Create a New Taegis Notebook

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/README.md

This command-line instruction creates a new Jupyter notebook file for use with Taegis. The `OUTPUT_NOTEBOOK` argument specifies the desired file path for the new notebook.

```bash
taegis notebook create [OUTPUT_NOTEBOOK]
```

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

### Get Audit Diffs with Taegis Magic

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/audits.md

This snippet demonstrates how to retrieve audit log differences using Taegis Magic. It first imports the `get_diffs` function and then uses the `%taegis` magic command to search for specific audit events. Finally, it pipes the results to `get_diffs` to extract and display the changed fields.

```python
from taegis_magic.pandas.audits import get_diffs
```

```ipython
%taegis audits search --application investigations --action update --assign investigation_audits
```

```python
investigation_update_diffs = investigation_audits.pipe(get_diffs)

investigation_update_diffs[[
    column
    for column in investigation_update_diffs.columns
    if column.startswith("taegis_magic.diff.")
]]
```

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

### Load Taegis Magic Extensions and Libraries

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Loads the Taegis Magic Jupyter extension and imports necessary libraries for logging, date/time manipulation, path handling, and Taegis-specific functionalities like service retrieval, tenant lookups, IOC searching, and notebook execution.

```python
%load_ext taegis_magic

import logging
from taegis_magic.core.log import get_module_logger, TRACE_LOG_LEVEL

logger = get_module_logger()
logger.setLevel(logging.INFO)
log = logging.getLogger(__name__)

from pathlib import Path
from textwrap import dedent
from datetime import datetime, timezone

from taegis_magic.core.service import get_service
from taegis_magic.pandas.tenants import lookup_first_environment
from taegis_magic.pandas.ioc import threaded_multi_tenant_ioc_search
from taegis_magic.core.notebook import execute_notebook_pool, NotebookContext
```

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

### Taegis Cell Magic with YAML Template

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/cell_templates.md

This example shows how to define a Jinja2 template within a YAML block and then use it with the `%%taegis` cell magic. The `--cell "$alert_query_template"` argument tells the magic to use the content of the `alert_query_template` variable as the template. The results are assigned to the `alerts` variable.

```yaml
alert_query_template: |
  FROM alert 
  WHERE
      ( 
          {{ ips | in('@ip') }} OR
          {{ domains | regex('@domain') }} 
      ) AND
      severity >= {{ severity }}
  EARLIEST={{ earliest }}

```

```taegis
%taegis alerts search --cell-template --cell "$alert_query_template" --assign alerts
```

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

### Taegis Audit Operations (Python)

Source: https://context7.com/secureworks/taegis-magic/llms.txt

This Python snippet illustrates how to perform audit operations using Taegis Magic. It includes functions to retrieve a specific audit by ID, search audit logs based on criteria, and fetch all audits within a specified time range, with an example of normalizing results into a Pandas DataFrame.

```python
from taegis_magic.commands.audits import audit, search, all_audits

# Get specific audit by ID
audit_result = audit(
    id_="audit://12345",
    region="us-east-2"
)

print(f"Action: {audit_result.results[0]['action']}")
print(f"User: {audit_result.results[0]['user']}")

# Search audit logs
audits = search(
    cell="""
    FROM audit
    WHERE action = 'user.login'
    AND status = 'success'
    EARLIEST=-7d
    """,
    limit=1000
)

# Get all audits (paginated)
all_audit_results = all_audits(
    start_time="2024-01-01T00:00:00Z",
    end_time="2024-01-31T23:59:59Z",
    limit=5000
)

audit_df = pd.json_normalize(all_audit_results.results)
print(audit_df.groupby('action')['action'].count())
```

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

### Load Taegis Magic Extension and Initialize Pandas

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/rules.ipynb

Loads the taegis_magic IPython extension and configures Pandas for better display of large dataframes. This is a prerequisite for using other taegis_magic commands.

```python
%load_ext taegis_magic

from taegis_magic.pandas.rules import inflate_filters
import pandas as pd

pd.set_option("display.max_columns", None)
```

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

### Initialize Taegis Magic IOC Hunt Variables

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Initializes variables required for the IOC hunt, such as region, organization ID, tenant IDs, services, and IOC file paths. Default values are set for some parameters, and others are left for user input or dynamic determination.

```python
region = "charlie"  # authentication region, does not limit regions for tenant queries
organization_id = None
tenant_ids = None
services = None
title = None
description = None
ioc_file = None
iocs = None
days = 30
TAEGIS_MAGIC_NOTEBOOK_FILENAME = None
```

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

### Service Initialization

Source: https://context7.com/secureworks/taegis-magic/llms.txt

Initializes and configures the Taegis GraphQL service for making API calls. Supports custom regions, tenants, authentication methods, and middleware.

```APIDOC
## Service Initialization

### Description
Initializes and configures the Taegis GraphQL service for making API calls. Supports custom regions, tenants, authentication methods, and middleware.

### Method
`get_service()`

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from taegis_magic.core.service import get_service

# Basic service initialization
service = get_service()

# Service with custom region and tenant
service = get_service(
    environment="us-east-2",
    tenant_id="12345"
)

# Service with universal authentication
service = get_service(
    use_universal_authentication=True,
    extra_headers={"Custom-Header": "value"}
)

# Service with middleware (retry, logging)
from taegis_sdk_python.middlewares import retry_middleware
service = get_service(
    middlewares=[retry_middleware],
    environments={"custom-region": "https://api.custom.taegis.com/graphql"}
)
```

### Response
#### Success Response (200)
- **service** (object) - A configured Taegis GraphQL service object.

#### Response Example
```json
{
  "service": "<taegis_sdk_python.services.graphql.GraphQLService object at 0x...>"
}
```
```

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

### Create and Checkout New Branch (Git)

Source: https://github.com/secureworks/taegis-magic/blob/main/CONTRIBUTING.md

This command sequence allows you to create a new branch for your work based on the 'main' branch and immediately switch to it. Ensure 'main' is up-to-date before branching.

```bash
git checkout main
git checkout -b <new-branch-name>
```

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

### Print Tenant IDs and Environments

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Iterates through the processed tenants DataFrame and prints the Tenant ID and its corresponding first environment for each tenant.

```python
for id_, environment in tenants[["id", "first_environment"]].itertuples(index=False):
    print(f"Tenant ID: {id_}, Environment: {environment}")
```

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

### Display List of Indicators

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_hunt_report.ipynb

Renders a Markdown list of unique indicators from the provided `INDICATORS` list using `display_markdown` for visual presentation in the notebook output.

```python
display_markdown("List of Indicators:", raw=True)

for ioc in {indicator["matching_value"] for indicator in (INDICATORS or [])}:
    display_markdown(f"- {ioc}", raw=True)
```

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

### Create and Search Investigations

Source: https://context7.com/secureworks/taegis-magic/llms.txt

Demonstrates how to create a new investigation with specified details and how to search for existing investigations based on criteria. This requires investigation and search functionalities from the taegis_magic library.

```python
investigation = create(
    title="Suspicious PowerShell Activity Investigation",
    key_findings=key_findings,
    priority=InvestigationPriority.HIGH,
    type_=InvestigationType.SECURITY_INVESTIGATION,
    status=InvestigationStatus.OPEN,
    assignee_id="@me",
    database="investigation.db"
)

print(f"Investigation ID: {investigation.raw_results.id}")
print(f"Short ID: {investigation.raw_results.short_id}")
print(f"Shareable URL: {investigation.shareable_url}")

# Search existing investigations
search_results = search(
    cell="WHERE status = 'OPEN' AND priority > 2",
    limit=100
)
```

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

### Taegis Configuration Management with Python

Source: https://context7.com/secureworks/taegis-magic/llms.txt

This Python code demonstrates how to configure Taegis authentication, regions, and middleware. It shows enabling universal authentication, adding a custom region, listing configured regions, enabling retry middleware, and setting default logging options.

```python
from taegis_magic.commands.configure import (
    auth_use_universal,
    regions_add,
    regions_list,
    middlewares_retry,
    logging_defaults
)

# Enable universal authentication
auth_use_universal(use_universal_auth=True)

# Add custom region
regions_add(
    name="custom-region",
    url="https://api.custom.taegis.com/graphql"
)

# List configured regions
regions = regions_list()

# Enable retry middleware
middlewares_retry(enable=True)

# Configure logging
logging_defaults(
    option="debug",
    status=True
)
```

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

### Generate Network Range Template - Bash

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/cli/tenant-profiles.md

Generates a basic Excel template for adding multiple network ranges to Taegis Tenant Profiles. The command creates a file named 'taegis_network_range_template.xlsx' by default. No external dependencies are required beyond the Taegis CLI.

```bash
taegis tenant-profiles network template generate [--name filename]
```

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

### Load IOCs from File

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Reads Indicators of Compromise (IOCs) from a specified file if the 'iocs' list is not already populated. It checks for file existence, reads the content, splits it into lines, and validates that the file is not empty. Raises FileNotFoundError or ValueError if issues occur.

```python
if not iocs and ioc_file:
    iocs_file = Path(ioc_file)
    if not iocs_file.exists():
        raise FileNotFoundError(f"IOCs file '{iocs_file}' does not exist.")

    iocs = iocs_file.read_text().splitlines()

    if not iocs:
        raise ValueError(f"IOCs file '{ioc_file}' is empty or contains no valid IOCs.")

iocs
```

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

### Generate Taegis QL from Natural Language and Search Alerts (Python)

Source: https://context7.com/secureworks/taegis-magic/llms.txt

This snippet demonstrates how to generate Taegis Query Language (QL) from a natural language query and then use the generated query to search for alerts. It involves a 'generate' function and then utilizes the 'search' command from 'taegis_magic.commands.alerts'.

```python
nl_query = "Find all alerts from the past week with high severity on Windows hosts"

result = generate(
    cell=nl_query,
    context="alerts"
)

print(f"Generated Query:\n{result.generated_query}")
print(f"\nExplanation:\n{result.explanation}")

# Use generated query
from taegis_magic.commands.alerts import search
alerts = search(cell=result.generated_query, limit=500)
```

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

### Alerts Search Help with Tracking Enabled

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Displays the help message for the `taegis alerts search` command after query tracking has been enabled. It shows that the `--track` option defaults to `track`.

```bash
taegis alerts search --help
```

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

### List Query Tracking Configuration

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Lists the current configuration for query tracking. This command shows whether `taegis alert search` and `taegis event search` commands are set to be tracked by default.

```bash
taegis configure queries list
```

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

### Configure Universal Authentication

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Configures Taegis Magic to use a unified endpoint for authentication across multiple regions. This simplifies authentication by using a single `access_token` from a `universal` region.

```bash
taegis configure auth use-universal-auth true
```

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

### Display Taegis CLI Help Information

Source: https://github.com/secureworks/taegis-magic/blob/main/README.md

Shows the main help message for the Taegis CLI, detailing available options and commands. This is useful for understanding the CLI's capabilities and structure.

```bash
$ taegis --help

 Usage: taegis [OPTIONS] COMMAND [ARGS]...
                                                                                                   
 Taegis Magic main callback.                                                                       
                                                                                                   
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────╮
│ --warning                 --no-warning          [default: warning]                              │
│ --verbose                 --no-verbose          [default: no-verbose]                           │
│ --debug                   --no-debug            [default: no-debug]                             │
│ --trace                   --no-trace            [default: no-trace]                             │
│ --sdk-warning             --no-sdk-warning      [default: no-sdk-warning]                       │
│ --sdk-verbose             --no-sdk-verbose      [default: no-sdk-verbose]                       │
│ --sdk-debug               --no-sdk-debug        [default: no-sdk-debug]                         │
│ --install-completion                            Install completion for the current shell.       │
│ --show-completion                               Show completion for the current shell, to copy  │
│                                                 it or customize the installation.               │
│ --help                -h                        Show this message and exit.                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────╮
│ alerts                                                                                          │
│ audits                                                                                          │
│ clients                                                                                         │
│ configure                                                                                       │
│ events                                                                                          │
│ investigations                                                                                  │
│ preferences                                                                                     │
│ rules                                                                                           │
│ tenants                                                                                         │
│ threat                                                                                          │
│ users                                                                                           │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

```

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

### Provide Feedback on Alerts Using Pandas

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/Alerts.ipynb

Imports necessary components and uses the provide_feedback function from taegis_magic.pandas.alerts to submit feedback on alerts. It specifies the environment, resolution status, and a reason for the feedback.

```python
from taegis_magic.pandas.alerts import provide_feedback
from taegis_sdk_python.services.alerts.types import ResolutionStatus

alerts.pipe(
    provide_feedback, 
    environment="charlie", 
    status=ResolutionStatus.FALSE_POSITIVE, 
    reason="my resolution reason"
)
```

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

### Initialize Taegis GraphQL Service

Source: https://context7.com/secureworks/taegis-magic/llms.txt

Configures and initializes a Taegis GraphQL service object for authentication and custom settings. Supports custom regions, tenants, universal authentication, and middleware like retries and logging.

```python
from taegis_magic.core.service import get_service

# Basic service initialization
service = get_service()

# Service with custom region and tenant
service = get_service(
    environment="us-east-2",
    tenant_id="12345"
)

# Service with universal authentication
service = get_service(
    use_universal_authentication=True,
    extra_headers={"Custom-Header": "value"}
)

# Service with middleware (retry, logging)
from taegis_sdk_python.middlewares import retry_middleware
service = get_service(
    middlewares=[retry_middleware],
    environments={"custom-region": "https://api.custom.taegis.com/graphql"}
)

# Example query execution
results = service.alerts.query.alert_history_by_id(
    id_="alert://priv:event-filter:12345:1668534654520:xxx"
)
```

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

### Import Taegis Magic and Pandas

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/context automation.ipynb

Imports necessary libraries like pandas and specific functions from taegis_magic.pandas.context. It also loads the taegis_magic extension for use in the environment.

```python
import pandas as pd

pd.set_option("display.max_rows", None)
pd.set_option("display.max_colwidth", None)

from taegis_magic.pandas.context import (
    normalize_entities,
    relate_entities,
    generate_context_queries,
    display_facets,
    add_threat_intel,
    get_ti_pubs,
)

%load_ext taegis_magic
```

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

### Fetch REGEX Rules with taegis_magic

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/rules.ipynb

Retrieves all REGEX (Regular Expression) rules from Taegis and assigns them to the variable `regex_rules`. This command requires the taegis_magic extension to be loaded.

```python
%taegis rules type --rule-type REGEX --assign regex_rules
```

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

### Taegis Magic Investigation Management Commands

Source: https://github.com/secureworks/taegis-magic/blob/main/taegis_magic/templates/template.ipynb

Commands for managing investigations within the Taegis platform. This includes listing search queries, staging them, and creating new investigations with specified details like title, priority, and assignee.

```python
# %taegis investigations search-queries list
```

```python
# %taegis investigations search-queries stage
```

```python
# %taegis investigations create \
# --title "$INVESTIGATION_TITLE" \
# --key-findings "$TAEGIS_MAGIC_REPORT_FILENAME" \
# --priority MEDIUM \
# --type THREAT_HUNT \
# --status AWAITING_ACTION \
# --assignee-id "@customer" \
# --tenant $TENANT_ID \
# --region $REGION
```

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

### Execute Taegis Search Queries and Aggregate Results

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_hunt_report.ipynb

Iterates through the categorized indicators by event type, displays search criteria, executes the Taegis search query using the `%taegis` magic command, and aggregates the results into pandas DataFrames. It then displays the top 20 results grouped by schema columns.

```python
results_dfs = {}
for event_type, indicators in indicators_by_type.items():
    display_markdown(f"### Searching {event_type} indicators:", raw=True)
    for indicator in indicators:
        display_markdown(
            f"Search criteria: {indicator['date']} - {indicator['matching_value']}",
            raw=True,
        )
        query = indicator["query"]
        %taegis --verbose events search --tenant $TENANT_ID --region $REGION --assign results --cell "$query" --track --cache

        if event_type not in results_dfs:
            results_dfs[event_type] = results
        else:
            results_dfs[event_type] = pd.concat(
                [
                    results_dfs[event_type],
                    results,
                ]
            ).reset_index(drop=True)

        display_markdown("<br/>", raw=True)

    display_markdown(f"#### Top 20 {event_type} results:", raw=True)
    display_markdown(
        groupby(results_dfs[event_type], columns=default_schema_columns(event_type))
        .sort_values(by="count", ascending=False)
        .head(20)
        .to_html(),
        raw=True,
    )
    display_markdown("<br/>", raw=True)
```

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

### Execute Taegis Notebook for Multiple Tenants

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/cli/notebook.md

Executes a Taegis notebook for a list of specified tenant IDs. Each tenant will have its own generated notebook and markdown report, ensuring data isolation per tenant. This is useful for analyzing data across multiple Taegis tenants.

```bash
tenants = ("xxxxx yyyyy zzzzz")
for tenant in $tenants
do 
    taegis notebook execute test.ipynb --tenant $tenant --region US1
done
```

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

### Taegis IPython Magic Commands for Alerts, Events, and Reports

Source: https://context7.com/secureworks/taegis-magic/llms.txt

This section details various IPython magic commands for interacting with Taegis. It covers loading the extension, performing basic alert and event searches, appending results, caching data, using Jinja2 templates, displaying DataFrames, saving notebooks, and generating HTML reports.

```python
# Load extension
%load_ext taegis_magic

# Basic alert search with DataFrame assignment
%%taegis alerts search --limit 100 --assign alerts_df --display alerts_df
FROM alert
WHERE severity >= 0.7
EARLIEST=-24h

# Append results to existing DataFrame
%%taegis alerts search --limit 100 --append all_alerts
FROM alert
EARLIEST=-7d

# Cache results for faster re-execution
%%taegis events events_by_query --limit 1000 --assign events_df --cache
FROM process
WHERE process.name = 'powershell.exe'
EARLIEST=-48h

# Use Jinja2 templates
%%taegis alerts search --limit {{limit}} --assign df --cell-template
FROM alert
WHERE severity >= {{min_severity}}
EARLIEST=-{{timerange}}

# Display variable as table
%taegis --display alerts_df

# Save notebook
%save_notebook

# Generate HTML report
%generate_report
```

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

### Query Taegis Rules (Python)

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/Subjects.ipynb

Uses the `%taegis` magic command to search for Taegis rules. It specifies the kind as 'tenant' and assigns the results to the 'rules' variable for further processing. This command requires the taegis_magic extension to be loaded.

```python
%taegis rules suppression --kind tenant --assign rules
```

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

### Search Taegis Alerts using CLI

Source: https://github.com/secureworks/taegis-magic/blob/main/README.md

Demonstrates how to search for Taegis alerts using the command-line interface. It specifies a limit, a cell query for the last day's alerts, and requests specific GraphQL output.

```bash
taegis alerts search --limit 2 --cell "FROM alert EARLIEST=-1d" --graphql-output "alerts { list { id metadata { title } } }"
```

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

### Correlate Threat Intelligence with add_threat_intel

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/context_automation.md

The `add_threat_intel` pipe function correlates threat intelligence by taking a list of callables. It can utilize `get_ti_pubs` for CTU TIPS correlation or custom functions. It returns a DataFrame with new columns like `tips.found` and `tips.publications`. Ensure API keys for third-party sources are safeguarded.

```python
# correlate threat intel
# new correlations can be added as a custom callable
for entity in entity_queries:
    for query in entity_queries[entity]:
        print(f"Trying {entity}, {query}...")
        entity_queries[entity][query] = entity_queries[entity][query].pipe(
            add_threat_intel,
            correlations=[get_ti_pubs],
            tenant_id=TENANT,
            region=REGION,
        )
```

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

### Define Global Variables for Taegis Magic Threat Hunt

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_hunt_report.ipynb

Initializes global variables that will be used throughout the Taegis Magic notebook for threat hunting. These include tenant ID, region, investigation title, and a list of indicators.

```python
TENANT_ID = None
REGION = None
INVESTIGATION_TITLE = None
INDICATORS = None
```

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

### Configure Query Tracking (Enable)

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Enables the tracking of `taegis alert search` and `taegis event search` commands. This configuration affects the default behavior, which can still be overridden at runtime.

```bash
taegis configure queries track --status yes
```

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

### Fetch Latest Taegis Threat Publications

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/threat.md

Fetches the 5 latest threat publications from Taegis and assigns them to the 'pubs' variable. The `--display pubs` flag renders a preview of the fetched data directly in the notebook.

```python
%taegis threat publications latest 5 --assign pubs --display pubs
```

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

### Create Taegis Investigation

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/Investigations.ipynb

Creates a new investigation in the Taegis platform. It allows specifying a title, key findings from a file, priority, type, and status. Requires the taegis_magic extension and a file for key findings.

```python
%taegis investigations create --title "Test Investigation" --key-findings "key_findings.md" --priorty LOW --type SECURITY_INVESTIGATION --status OPEN
```

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

### Process and Filter Indicators for Threat Hunting

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_hunt_report.ipynb

Iterates through the provided INDICATORS, generates a query for each, and categorizes them by event type. Indicators with invalid queries are skipped. The processed indicators are stored in the `indicators_by_type` dictionary.

```python
indicators_by_type = {}
for indicator in INDICATORS or []:
    indicator["query"] = generate_query(
        value=indicator["matching_value"],
        date=indicator["date"],
        event_type=indicator["event_type"],
    )
    if indicator["event_type"] not in indicators_by_type:
        indicators_by_type[indicator["event_type"]] = []
    if indicator["query"] != "Error":
        indicators_by_type[indicator["event_type"]].append(indicator)
```

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

### Generate Null Findings Report

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Creates a Markdown report file named 'null_findings.report.md' to be used when no IOCs are found. It includes the report title, description, a list of indicators, and a summary stating that no indicators of compromise were detected.

```python
indicators_template = "\n".join([f"- {ioc}" for ioc in iocs])

Path("null_findings.report.md").write_text(
    dedent(
        f"""
# IoC Hunt Report
                                                  
{description}
                                                  
List of Indicators:
{indicators_template}

## Summary of Findings

No indicators of compromise were found in the last {days} days.
"""
    )
)
```

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

### Build Taegis Tenants Search Filters

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Constructs filter strings for the 'taegis tenants search' command based on provided organization ID, tenant IDs, and services. These filters refine the search to specific tenants or services within the Taegis environment.

```python
tenants_search_filters = []
if organization_id:
    tenants_search_filters.append(f"--filter-by-tenant-hierarchy {organization_id}")
if tenant_ids:
    for tenant_id in tenant_ids:
        tenants_search_filters.append(f"--filter-by-tenant {tenant_id}")
if services:
    for service in services:
        tenants_search_filters.append(f"--filter-by-service {service}")
tenants_search_filter = " ".join(tenants_search_filters)
tenants_search_filter
```

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

### Write Key Findings to Markdown File

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/investigation create.ipynb

Writes the content 'This is a test.' to a markdown file named 'kf.md'. This file is intended to be used as the key findings for a Taegis investigation.

```python
%%writefile kf.md
This is a test.
```

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

### Execute Notebook Pool for Investigations

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Executes a pool of notebooks based on the prepared notebook context. It uses the overall investigation title and specifies the path to the notebook template ('ioc_hunt_report.ipynb').

```python
execute_notebook_pool(
    notebook_context=notebook_context,
    notebook_title=title,
    notebook_path="ioc_hunt_report.ipynb",
)
```

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

### Display Taegis Magic Help Menu in Python

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/README.md

This code snippet invokes the help menu for the Taegis Magic extension directly within a Jupyter notebook cell. It provides information on available arguments and their usage.

```python
%taegis --help
```

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

### Push Changes to Fork (Git)

Source: https://github.com/secureworks/taegis-magic/blob/main/CONTRIBUTING.md

After committing changes to your local issue branch, use this command to push them to your personal fork of the repository on GitHub. This makes your changes available for creating a pull request.

```bash
git push origin <new-branch-name>
```

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

### Natural Language to Taegis QL Conversion

Source: https://context7.com/secureworks/taegis-magic/llms.txt

Provides functionality to convert natural language queries into Taegis QL (Query Language). This is useful for users who prefer to express their search intent in plain English. Requires the 'generate' function from taegis_magic.commands.search.

```python
from taegis_magic.commands.search import generate
```

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

### Execute Context Queries and Store Results

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/notebooks/ContextAutomation.ipynb

This loop iterates through the generated context queries for each entity. It executes Taegis search and event queries using magic commands and stores the results in a dictionary 'entity_queries', keyed by entity value.

```python
entity_queries = {}

for _, row in entities_df[
    [
        "taegis_magic.entities.value",
        "taegis_magic.open_alerts_query",
        "taegis_magic.resolved_alerts_query",
        "taegis_magic.investigations_query",
        "taegis_magic.events_query",
    ]
].iterrows():
    # setup
    entity = row["taegis_magic.entities.value"]
    open_alerts_query = row["taegis_magic.open_alerts_query"]
    resolved_alerts_query = row["taegis_magic.resolved_alerts_query"]
    investigations_query = row["taegis_magic.investigations_query"]
    events_query = row["taegis_magic.events_query"]

    # run queries
    %taegis alerts search --assign open_alerts --region $REGION --tenant $TENANT --cell "$open_alerts_query"
    %taegis alerts search --assign resolved_alerts --region $REGION --tenant $TENANT --cell "$resolved_alerts_query"
    %taegis alerts search --assign investigations --region $REGION --tenant $TENANT --cell "$investigations_query"
    %taegis events search --assign events --region $REGION --tenant $TENANT --cell "$events_query"

    # relate back to entity
    entity_queries[entity] = {}
    entity_queries[entity]["open_alerts"] = open_alerts
    entity_queries[entity]["resolved_alerts"] = resolved_alerts
    entity_queries[entity]["investigations"] = investigations
    entity_queries[entity]["events"] = events

```

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

### Load Taegis Magic and Import Pandas Functions

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/investigaion remove.ipynb

This snippet loads the 'taegis_magic' IPython extension and imports essential pandas-related functions for evidence manipulation. It sets up the environment for using Taegis magic commands and data processing.

```python
%load_ext taegis_magic

from taegis_magic.pandas.investigations import inflate_evidence, lookup_evidence
```

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

### Process and Display Tenant Information

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Filters out the primary organization ID from the search results and adds a 'first_environment' column to the tenants DataFrame. It then displays the 'id', 'name', and 'first_environment' for the relevant tenants.

```python
tenants = tenants[tenants["id"] != organization_id]
tenants["first_environment"] = tenants.pipe(lookup_first_environment)
tenants[["id", "name", "first_environment"]]
```

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

### Manage Custom Regions

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/README.md

Provides commands for managing custom regions within Taegis. This includes adding new regions with their associated URLs, removing existing regions, and listing all configured regions.

```bash
taegis configure regions add [name] [url]
```

```bash
taegis configure regions remove [name]
```

```bash
taegis configure regions list
```

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

### Perform Multi-Tenant IOC Search

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/ioc_threat_hunt/ioc_threat_hunt.ipynb

Executes a threaded multi-tenant IOC search using the provided Taegis service object, list of tenants, IOCs, and the number of days for the search. The results are stored in the 'results' variable.

```python
results = threaded_multi_tenant_ioc_search(
    service=service,
    tenants=tenants,
    iocs=iocs,
    days=days,
)
results
```

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

### Load Taegis Magic Extension and Import HTML

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/threat.md

Loads the taegis_magic Jupyter Notebook extension and imports the HTML class from IPython.display. This is a prerequisite for using taegis_magic commands and rendering HTML content.

```python
%load_ext taegis_magic

from IPython.display import HTML
```

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

### Select First Few Cloud Audit Events

Source: https://github.com/secureworks/taegis-magic/blob/main/examples/investigation create.ipynb

Takes the first few rows from the 'events_df' DataFrame (presumably assigned from a previous events search) and assigns them to 'events_evidence'. This is likely a subset for further processing.

```python
events_evidence = events_df.head()
```

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

### Generate Context Queries with Taegis Magic

Source: https://github.com/secureworks/taegis-magic/blob/main/docs/jupyter/context_automation.md

The generate_context_queries pipe function creates CQL query strings for searching related information within Taegis, such as open alerts, resolved alerts, investigations, and raw events. It can be configured with timeframes for each query type and returns a DataFrame with query columns.

```python
entities_df = entities_df.pipe(
    generate_context_queries,
)
entities_df[
    [
        "taegis_magic.open_alerts_query",
        "taegis_magic.resolved_alerts_query",
        "taegis_magic.investigations_query",
        "taegis_magic.events_query",
    ]
]

```