HelloWorldV2

Overview

This is the Hello World v2 integration for getting started.

Configure Hello World v2 in Cortex

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

helloworld-say-hello

Prints hello to a specified name.

Base Command

helloworld-say-hello

Input

Context Output

Command example

!helloworld-say-hello name="Dbot"

Context Example

{
    "HelloWorld": {
        "Hello": {
            "name": "Dbot"
        }
    }
}

Human Readable Output

Hello Dbot

helloworld-alert-list

Lists example alerts as they would appear in a fetch operation.

Base Command

helloworld-alert-list

Input

Context Output

Command example

!helloworld-alert-list limit="3" severity="low"

Context Example

{
    "HelloWorld": {
        "Alert": [
            {
                "date": "2023-09-14T11:30:39.882955",
                "id": 1,
                "name": "XSOAR Test Alert #1",
                "severity": "low",
                "status": "Testing"
            },
            {
                "date": "2023-09-14T11:30:39.882955",
                "id": 2,
                "name": "XSOAR Test Alert #2",
                "severity": "low",
                "status": "Testing"
            },
            {
                "date": "2023-09-14T11:30:39.882955",
                "id": 3,
                "name": "XSOAR Test Alert #3",
                "severity": "low",
                "status": "Testing"
            }
        ]
    }
}

Human Readable Output

Items List (Sample Data)

date	id	name	severity	status
2023-09-14T11:30:39.882955	1	XSOAR Test Alert #1	low	Testing
2023-09-14T11:30:39.882955	2	XSOAR Test Alert #2	low	Testing
2023-09-14T11:30:39.882955	3	XSOAR Test Alert #3	low	Testing

Command example

!helloworld-alert-list alert_id=2

Context Example

{
    "HelloWorld": {
        "Alert": {
            "date": "2023-09-14T11:30:39.882955",
            "id": 2,
            "name": "XSOAR Test Alert #2",
            "severity": "low",
            "status": "Testing"
        }
    }
}

Human Readable Output

Items List (Sample Data)

date	id	name	severity	status
2023-09-14T11:30:39.882955	2	XSOAR Test Alert #2	low	Testing

helloworld-alert-note-create

Create a note in the API.

Base Command

helloworld-alert-note-create

Input

Context Output

Command example

!helloworld-alert-note-create alert_id=2 note_text=test

Context Example

{
    "HelloWorld": {
        "Note": {
            "msg": "Note was created for alert #2 successfully with comment: test",
            "status": "success"
        }
    }
}

Human Readable Output

Note was created successfully.

ip

The returned IP information and reputation.

Base Command

ip

Input

Context Output

Command example

!ip ip="8.8.8.8"

Context Example

{
    "DBotScore": {
        "Indicator": "8.8.8.8",
        "Reliability": "C - Fairly reliable",
        "Score": 3,
        "Type": "ip",
        "Vendor": "HelloWorld"
    },
    "HelloWorld": {
        "IP": {
            "id": "x.x.x.x",
            "ip": "8.8.8.8",
            "links": {
                "self": "https://www.virustotal.com/api/v3/ip_addresses/x.x.x.x"
            },
            "type": "ip_address"
        }
    },
    "IP": {
        "Address": "8.8.8.8",
        "Malicious": {
            "Description": "Hello World returned reputation -4",
            "Vendor": "HelloWorld"
        },
        "Relationships": [
            {
                "EntityA": "8.8.8.8",
                "EntityAType": "IP",
                "EntityB": "h",
                "EntityBType": "URL",
                "Relationship": "related-to"
            },
            {
                "EntityA": "8.8.8.8",
                "EntityAType": "IP",
                "EntityB": "x",
                "EntityBType": "URL",
                "Relationship": "related-to"
            }
        ]
    }
}

Human Readable Output

IP (Sample Data)

id	ip	links	type
x.x.x.x	8.8.8.8	self: https://www.virustotal.com/api/v3/ip_addresses/x.x.x.x	ip_address

Attributes

as_owner	asn	continent	country	jarm	last_analysis_stats	last_modification_date	network	regional_internet_registry	reputation	tags	total_votes	whois_date
EMERALD-ONION	396507	NA	US	:jarm:	harmless: 72 malicious: 5 suspicious: 2 timeout: 0 undetected: 8	1613300914	:cidr:	ARIN	-4		harmless: 0 malicious: 1	1611870274

helloworld-get-events

Retrieves alerts from the HelloWorld API. Use this command for development and debugging only, as it may produce duplicate events, exceed API rate limits, or disrupt the fetch mechanism.

Base Command

helloworld-get-events

Input

Context Output

There is no context output for this command.

Command example

!helloworld-get-events severity="low" limit=3

Human Readable Output

HelloWorld Events

id	severity	user	action	date	status
1	low	userB@test.com	Testing	2023-09-14T11:30:39.882955	Error
2	low	userA@test.com	Testing	2023-09-14T11:30:39.883955	Success
3	low	userB@test.com	Testing	2023-09-14T11:30:39.884955	Error

helloworld-job-submit

Submits a job to the HelloWorld API and polls for completion. Used for asynchronous APIs and long-running operations.

Base Command

helloworld-job-submit

Input

Context Output

Command example

#### Context Example

```json
{
    "HelloWorld": {
        "Job": {
            "id": "abc-123",
            "msg": "The configuration has successfully been updated.",
            "status": "complete",
            "type": "HelloWorldRefreshConfig"
        }
    }
}

Human Readable Output

HelloWorld Job abc-123 - Complete

id	msg
abc-123	The configuration has successfully been updated.

helloworld-get-assets

Retrieves resources and assets in the HelloWorld environment.

Base Command

helloworld-get-assets

Input

Context Output

There is no context output for this command.

Command example

!helloworld-get-assets limit=3

Human Readable Output

HelloWorld Assets

id	name	type	status	created
1	Server-01	server	active	2024-01-15T10:00:00
2	Database-01	database	active	2024-01-16T11:30:00
3	Storage-01	storage	active	2024-01-17T09:15:00

helloworld-get-vulnerabilities

Retrieves vulnerabilities found in the HelloWorld environment.

Base Command

helloworld-get-vulnerabilities

Input

Context Output

There is no context output for this command.

Command example

!helloworld-get-vulnerabilities limit=3

Human Readable Output

HelloWorld Vulnerabilities

id	cve_id	severity	description	published
1	CVE-MOCK-0001	critical	Remote code execution vulnerability	2026-01-10T08:00:00
2	CVE-MOCK-0002	high	SQL injection vulnerability	2026-01-12T14:30:00
3	CVE-MOCK-0003	medium	Cross-site scripting vulnerability	2026-01-14T16:45:00

Developer Guide

This section documents the key architectural patterns and code features in Hello World v2 and provides guidelines for building robust Cortex integrations.

Key Patterns and Features

How to Build an Integration

Below is a step-by-step guide on how to build an integration that implements a basic automation command and fetch flow.

1. Import the Required Modules
2. Define a Configuration Parameters Validation Model
3. Create an API Client Class
4. Implement Standard Automation Command Pattern
5. Implement Standard Fetch Flow Pattern
6. Setup Execution Configuration
7. Define the Main Function

1. Import the Required Modules

At the top of the integration code file, import the required modules. This can include built-in Python modules such as enum, typing, and asyncio, as well as Content-related imports such as CommonServerPython and ContentClientApiModule.

# Use enumerations to group related constants or define all possible values of configuration parameter or command argument
# For example, severity values: critical, high, moderate, low, unknown
from enum import Enum

# Use `typing` and/or `collections.abc` for defining attribute types in validation models and for type hinting.
from typing import Any
from collections.abc import Awaitable

# Import `CommonServerPython` and `demisto` class, which contain many useful helper and utility functions
from CommonServerPython import *
import demistomock as demisto

# Optionally use `CommonServerUserPython` (for custom integrations) to override constants, functions, and classes defined in `CommonServerPython`
from CommonServerUserPython import *

# Import `ContentClientApiModule` to use the new `ContentClient` class, which contains improved error handling, thread safety, and authentication handling.
from ContentClientApiModule import *

# Add any other required imports depending on your code
from datetime import datetime, UTC, timedelta

2. Define a Configuration Parameters Validation Model

Define the schema that corresponds to the configuration parameters in the integration YML file.
Use Pydantic classes that inherit from ContentBaseModel (or its subclasses like BaseParams) for robust input validation with user-friendly error messages.

You can use an AI agent to automatically generate models from the configuration parameters defined in the integration YML file.

class Credentials(ContentBaseModel):
    """Credentials model for API authentication."""

    username: str
    password: SecretStr


class MyIntegrationParams(BaseParams):
    """Integration parameters with validation.
    
    Attributes:
        url: API base URL (trailing slash removed automatically).
        credentials: Username and password for API Authentication.
        max_fetch: Maximum incidents per fetch.
    """
    # `proxy` and `insecure` are already defined in `BaseParams`
    url: AnyUrl
    credentials: Credentials
    # Ensure attribute name matches the param `name` field value in the YML
    # To follow Python "snake_case" format, use an `alias` value for mapping to the `camelCase` param name in the YML
    is_fetch: bool | None = Field(default=False, alias="isFetch")  # corresponds to "Fetch incidents" checkbox
    first_fetch: str  = "1 week"
    max_fetch: int = 50

    @property
    def first_fetch_datetime(self) -> datetime:
        """Cast first fetch to a datetime object."""
        return arg_to_datetime(self.first_fetch) or (datetime.now(tz=UTC) - timedelta(weeks=1))

    @validator('url', reuse=True)
    def clean_url(cls, v) -> str:
        """Remove trailing slash from URL."""
        return v.rstrip('/')
    
    @validator('max_fetch', reuse=True)
    def validate_max_fetch(cls, v) -> int:
        """Check that max fetch is not above the permitted value."""
        max_fetch = arg_to_number(v)
        if max_fetch > 1000:
            raise ValueError("The maximum number of incidents per fetch must not be greater than 1000.")
        return max_fetch

3. Create an API Client Class

Create a MyIntegrationClient class that inherits from ContentClient to leverage built-in retry logic, rate limit handling, authentication, and thread safety.

For authentication, define a custom AuthHandler if needed or use any of the included ones in ContentClientApiModule such as APIKeyAuthHandler, BearerTokenAuthHandler, or BasicAuthHandler.

# Example client class that inherits from ContentClient and adds two integration-specific methods

class MyIntegrationClient(ContentClient):

    def __init__(self, params: HelloWorldParams):
        """Initialize client with ContentClient capabilities.

        Args:
            params (MyIntegrationParams): Validated integration configuration parameters.
        """
        credentials: Credentials = params.credentials
        super().__init__(
            base_url=params.url,
            verify=params.verify,
            proxy=params.proxy,
            auth_handler=BasicAuthHandler(username=credentials.username, password=credentials.password),
            client_name="MyIntegrationClient",
            diagnostic_mode=is_debug_mode(),  # enable if commands are run with `debug-mode=true`
        )

    def get_item_by_id(self, item_id: int) -> dict[str, Any]:
        """Get an item in MyIntegration by its ID.

        Args:
            item_id (int): Item ID.

        Returns:
            dict[str, Any]: Item dictionary.
        """
        endpoint = f"api/items/{item_id}"
        return self.get(endpoint)  # JSON response bodies are decoded by default

    def get_items_list(self, limit: int, start_time: str | None = None) -> list[dict]:
        """Get a list of items in MyIntegration up to the limit.

        Args:
            limit (int): Maximum number of items to return.
            start_time (str | None): Optional start time in ISO 8601 format.

        Returns:
            list[dict]: List of items.
        """
        endpoint = "api/items"
        query_params = assign_params(limit=limit, start_time=start_time)  # use `assign_params` to remove empty values
        return self.get(endpoint, params=query_params)

4. Implement Standard Automation Command Pattern

Define an arguments validation model and a command function for each command. Define additional (helper) functions if needed.

You can use an AI agent to automatically generate models from the command arguments defined in the integration YML file.

The code snippet below demonstrates how to implement a basic automation command.

See the following references for example implementations of more complex commands:

# Basic automation command example implementation

class MyIntegrationItemListArgs(BaseArgs):
    """Arguments for `my-integration-item-list` command.
    
    Attributes:
        item_id: Optional item ID to retrieve.
        limit: Maximum number of items to retrieve (default: 10).
    """
    item_id: int | None = None
    limit: int = 10


def my_integration_item_list_command(client: MyIntegrationClient, args: MyIntegrationItemListArgs) -> CommandResults:
    """Run `my-integration-item-list` command logic.

    Args:
        client (MyIntegrationClient): An initialized API client instance.
        args (MyIntegrationItemListArgs): Validated command arguments.

    Returns:
        CommandResults: Command results containing context and human-readable outputs.
    """

    if args.item_id:
        items = client.get_item_by_id(item_id=args.item_id)
    else:
        items = client.get_items_list(limit=args.limit)

    return CommandResults(
        outputs_prefix="MyIntegration.Item",  # Context output prefix
        outputs_key_field="id",  # Objects under the defined prefix will be deduplicated according to this field value
        outputs=items,  # The items to return to the context output
        readable_output=tableToMarkDown("My Integration Items", items),  # Human-readable entry to return to the war room
    )

5. Implement Standard Fetch Flow Pattern

The code snippet below demonstrates how to implement a basic fetch-incidents flow.

See the following references for example implementations of more complex fetch flows:

# Basic fetch-incidents example implementation

class MyIntegrationLastRun(BaseLastRun):
    """State management for fetch-incidents.
    
    Attributes:
        start_time: ISO 8601 timestamp of the last fetched item.
        last_item_ids: List of item IDs from the last fetch time to prevent duplicates.
    """
    start_time: str | None = None
    last_item_ids: list[int] = []


def fetch_incidents(
    client: MyIntegrationClient,
    last_run: MyIntegrationLastRun,
    max_fetch: int,
    first_fetch_datetime: datetime,
) -> MyIntegrationLastRun:
    """Fetch new items as incidents.

    Args:
        client (MyIntegrationClient): An initialized API client instance.
        last_run (MyIntegrationLastRun): Last run state from previous fetch invocation.
        max_fetch (int): Maximum number of incidents to fetch.
        first_fetch_datetime (datetime): Date from which to start fetching incidents.
    """
    default_batch_limit: int = 100
    start_time: str = last_run.start_time or first_fetch_datetime.isoformat()
    last_item_ids: list[int] = last_run.last_item_ids

    unique_items: list[dict] = []

    while len(unique_items) < max_fetch:
        # Send requests in batches to avoid exceeding the API's maximum `limit` value
        remaining_count = max_fetch - len(unique_items)
        batch_limit = min(default_batch_limit, remaining_count)
        items = client.get_items_list(limit=batch_limit, start_time=start_time)

        # Deduplication logic
        for item in items:
            if item["id"] in last_item_ids:
                continue
            unique_items.append(item)
    
    if unique_items:
        start_time = unique_items[-1]["time"]
        last_item_ids = [item["id"] for item in unique_items if item["time"] == start_time]
    
        # Formatting and incident creation logic
        incidents = format_as_incidents(unique_items)
        demisto.createIncidents(incidents)  # create incidents

    return MyIntegrationLastRun(start_time=start_time, last_item_ids=last_item_ids)

6. Setup Execution Configuration

Inherits from the BaseExecutionConfig class in BaseContentApiModule to centralize command execution context, prevent redundant system calls (via the demisto class), and provide type-safe access to configuration parameters, command arguments, and fetch last run state.

class MyIntegrationExecutionConfig(BaseExecutionConfig):

    @property
    def params(self) -> MyIntegrationItemListArgs:
        return MyIntegrationItemListArgs(**self._raw_params)

    @property
    def item_list_args(self) -> MyIntegrationItemListArgs:
        """Get validated arguments for `my-integration-item-list` command."""
        return MyIntegrationItemListArgs.get(**self._raw_args)

    @property
    def last_run(self) -> MyIntegrationLastRun:
        """Get validated last run object for `fetch-incidents` flow."""
        return MyIntegrationLastRun(**self._raw_last_run)

7. Define the Main Function

Define and implement a main() function, which would serve as the entrypoint into the integration logic.

This function should initialize the Execution Configuration and API Client classes and route to the implemented command functions.

def main():
    execution = ExecutionConfig()
    command: str = execution.command
    client = None

    try:
        params: MyIntegrationParams = execution.params
        client = MyIntegrationClient(params)

        # Ensure the integration implements connection / configuration testing logic
        if command == "test-module":
            return_results(my_integration_test_module(client, params))
        
        # Route to automation command
        elif command == "my-integration-item-list":
            args = execution.item_list_args
            return_results(my_integration_item_list_command(client, args))
        
        elif command == "fetch-incidents":
            last_run = execution.last_run
            next_run = fetch_incidents(client, last_run, max_fetch=params.max_fetch, first_fetch_datetime=params.first_fetch_datetime)
            next_run.set()

        else:
            raise NotImplementedError(f"Command {command} is not implemented")

    # Log exceptions and return errors
    except Exception as e:
        demisto.error(f"[Main] Failed to execute {command=}: {str(e)}. {traceback.format_exc()}")
        return_error(f"Failed to execute {command} command.\nError:\n{str(e)}")
    
    finally:
        demisto.debug(f"[Main] Generating diagnostic report after executing {command=}.")
        if client:
            client.log_optional_diagnostic_report()


if __name__ in ("__main__", "__builtin__", "builtins"):
    main()

AI Agent Prompts

Uplift an Existing Integration

Update the logic in MyIntegration.py to follow the style of HelloWorldV2.py.

REFERENCE DOCUMENTATION
- The ContentClientApiModule README.md file
- The "Developer Guide" section in the HelloWorldV2 README.md file
- The HelloWorldV2.py code file

FOCUS AREAS
Focus on implementing key features <including fetch if relevant> and avoid common pitfalls, as documented.

REQUIREMENTS
- Maintain backward compatibility with existing YML configuration parameters and command arguments (Do not add any new commands and keep existing ones)
- Preserve all integration-specific logic (authentication methods, API quirks, data transformations)
- Include consistent debug and diagnostic logging that captures specific variable context
- Pass type checking with Pydantic validation models
- Follow the region-based organization from HelloWorldV2

Make sure to update the unit test to match the new code in MyIntegration.py in the style of HelloWorldV2_test.py. Mock API responses and helper functions where needed.
Update the API Module dependencies and Docker image in MyIntegration.yml to match HelloWorldV2.yml

Create a New Integration

Create a new integration called MyIntegration available in the <xsoar|marketplacev2|platform> marketplaces with supported modules <...> and support level <xsoar|partner|community|...> inside my <new|existing> MyPack pack.

REFERENCE DOCUMENTATION
- The ContentClientApiModule README.md file
- The "Developer Guide" section in the HelloWorldV2 README.md file
- The HelloWorldV2.py code file

FOCUS AREAS
Focus on implementing key features <including fetch if relevant> and avoid common pitfalls, as documented.

API DETAILS
- Base URL: <https://api.example.com>
- Authentication: <OAuth2|Basic|API Key|Custom>
- Rate Limits: <X requests per minute/hour>

CONFIGURATION PARAMETERS 
For each parameter, define in YML and include in the parameter validation model:
1. **Required** `url` - "Server URL" (type: 0, default: https://api.example.com)
2. **Required** `credentials` - "Client ID/Client Secret" (type: 9)
3. **Optional** `proxy` - "Use system proxy settings" (type: 8, inherited from BaseParams)
4. **Optional** `insecure` - "Trust any certificate" (type: 8, inherited from BaseParams)
5. **Optional** `<param_name>` - "<Display Name>" (type: <0-16>, default: <value>)
6. Add more parameters as needed with clear descriptions

COMMANDS TO IMPLEMENT
For each command, define: YML configuration, argument validation model, command function, and client method.
1. **test-module**: Validate connectivity and authentication
   - No arguments
   - Returns: "ok" on success
2. **<integration-name>-<command-name>**: <Brief description>
   - Arguments:
     - **<Required|Optional>** `<arg_name>`: <description> (Python type: <str|int|bool>, default: <value>)
   - Context Outputs:
     - `<IntegrationName>.<CommandPrefix>.<key>` : <description> (YML type: <string|number|boolean|object>)
   - API Endpoint: <GET|POST|PUT|DELETE> /v1/<endpoint>
   - Request <Params|Body>: <list parameters>
   - Returns: CommandResults with readable markdown table and outputs_prefix="<IntegrationName>.<CommandPrefix>"
3. <Add more commands following the same pattern

REQUIREMENTS
- Ensure matching configuration parameters and command arguments in both the YML and code
- Pass type checking with Pydantic validation models
- Follow the region-based organization from HelloWorldV2
- Include consistent debug and diagnostic logging that captures specific variable context

Make sure to write parameterized unit tests in the style of HelloWorldV2_test.py that check edge cases and cover at least 80% of the code. Mock API responses and helper functions where needed.
Update the API Module dependencies and Docker image in MyIntegration.yml to match HelloWorldV2.yml

Pitfalls to Avoid

Avoid the following where possible to adhere to best practices:

• Do not create an API Client that inherits from BaseClient in CommonServerPython; inherit from ContentClient in ContentClientApiModule instead, which is backwards compatible.
• Do not call demisto.params() directly; define a params property under the ExecutionConfig class and use execution.params instead.
• Do not forget to define an alias for YML configuration parameter or command argument mapping if the field name in the YML is in the “camelCase” format in the validation models. For example: snake_case_name: str = Field(alias="camelCaseName").
• Do not skip defining a custom Pydantic @validator function for specific field(s) under the validation model for complex validation logic.
• Do not forget to call client.log_optional_diagnostic_report() in finally block of the main() function.
• Do not forget to accommodate all tenant types if the integration supports multiple marketplaces. For example send_events_to_xsiam is not supported on Cortex XSOAR tenants.

Additional Resources

• Python Integration Development Guide and Code Standards
• Reputation Commands and DBotScore Documentation
• Pydantic 1.10 Documentation
• Python Type Hints

<~PLATFORM>

License Requirements

The following configuration parameters require the Cortex XSIAM license:

• Fetch events

The following configuration parameters require Cortex XSIAM with the Exposure Management add-on:

• Fetch assets and vulnerabilities

The following configuration parameters require one of these licenses: Cortex XSIAM or Agentix:

• Fetch incidents

</~PLATFORM>