Herald

Table of Contents

• Herald

  • Client

Client

class Herald.Client

A client object representing ‘Herald’ Service:

import almdrlib

client = almdrlib.client('herald')

Available methods:

• get_account_integration()

• get_account_integrations()

• get_account_notification()

• get_account_notification_by_type()

• get_account_subscription()

• get_account_subscription_subscribers()

• get_account_subscriptions()

• get_integration_types()

• get_notification()

• get_notification_types()

• get_sent_incident_notifications()

• sent_notification()

get_account_integration(**kwargs)

Get the specified account integration

Request Syntax

response = client.get_account_integration(
    account_id='string'
    id='string'
)

Parameters

• account_id (string) –

  [REQUIRED]

  AIMS Account ID

• id (string) –

  [REQUIRED]

  Entity ID

Return type

dict

Returns

Response Syntax

'dict'

Response Definitions

get_account_integrations(**kwargs)

List the specified account integration

Request Syntax

response = client.get_account_integrations(
    account_id='string'
)

Parameters

account_id (string) –

[REQUIRED]

AIMS Account ID

Return type

dict

Returns

Response Syntax

{
    'integrations': [
        {
            'account_id': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'header': {
                'X-Header': 'string'
            },
            'id': 'string',
            'modified': {
                'at': 'number',
                'by': 'string'
            },
            'name': 'string',
            'target_url': 'string',
            'type': 'string'
        }
    ]
}

Response Definitions

• integrations (list) –

  • (dict) –

    • account_id (string) –

    • created (dict) –

      • at (number) –

      • by (string) –

    • header (dict) –

      • X-Header (string) –

    • id (string) –

    • modified (dict) –

      • at (number) –

      • by (string) –

    • name (string) –

    • target_url (string) –

    • type (string) –

get_account_notification(**kwargs)

Get a notification by account id and notification id

Request Syntax

response = client.get_account_notification(
    account_id='string'
    notification_id='string'
)

Parameters

• account_id (string) –

  [REQUIRED]

  AIMS Account ID

• notification_id (string) –

  [REQUIRED]

  Notification id

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'asset_data': {
        'deployment_id': 'string',
        'tag_keys': [
            {}
        ],
        'tags': [
            {}
        ]
    },
    'attachments': [
        {
            'description': 'string',
            'name': 'string',
            'url': 'string'
        }
    ],
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'notification_data': {
        'appliance': 'string',
        'attackers': [
            'string'
        ],
        'class': 'string',
        'detection_source': 'string',
        'status': 'string',
        'targets': [
            'string'
        ],
        'threat_level': 'string'
    },
    'payload': {
        'analyst_notes': 'string',
        'attack_summary': 'string',
        'cid': 'number',
        'class': 'string',
        'create_date': 'string',
        'customer_name': 'string',
        'deployment_name': 'string',
        'incident_id': 'string',
        'investigation_report': 'string',
        'location_ip': 'string',
        'long_incident_id': 'string',
        'start_date': 'string',
        'status': 'string',
        'threat': 'string'
    },
    'status': 'string',
    'type': 'string'
}

Response Definitions

• account_id (string) –

• asset_data (dict) –

  • deployment_id (string) –

  • tag_keys (list) –

    • (dict) –

  • tags (list) –

    • (dict) –

• attachments (list) –

  • (dict) –

    • description (string) –

    • name (string) –

    • url (string) –

• created (dict) –

  • at (number) –

  • by (string) –

• id (string) –

• modified (dict) –

  • at (number) –

  • by (string) –

• notification_data (dict) –

  • appliance (string) –

  • attackers (list) –

    • (string) –

  • class (string) –

  • detection_source (string) –

  • status (string) –

  • targets (list) –

    • (string) –

  • threat_level (string) –

• payload (dict) –

  • analyst_notes (string) –

  • attack_summary (string) –

  • cid (number) –

  • class (string) –

  • create_date (string) –

  • customer_name (string) –

  • deployment_name (string) –

  • incident_id (string) –

  • investigation_report (string) –

  • location_ip (string) –

  • long_incident_id (string) –

  • start_date (string) –

  • status (string) –

  • threat (string) –

• status (string) –

• type (string) –

get_account_notification_by_type(**kwargs)

Request Syntax

response = client.get_account_notification_by_type(
    account_id='string'
    continuation_id='string'
    limit='integer'
    since='integer'
    sort='\'desc\'|'\'asc\''
    type='string'
    until='integer'
)

Parameters

• account_id (string) –

  [REQUIRED]

  AIMS Account ID

• continuation_id (string) –

  [REQUIRED]

  Continuation id - continue from that result

• limit (integer) –

  [REQUIRED]

  Controls the maximum number of items per page.

• since (integer) –

  [REQUIRED]

  Show items created since

• sort (string) –

  [REQUIRED]

  Direction to sort created at by

  Valid values: "desc", "asc"

  Default: desc

• type (string) –

  [REQUIRED]

  A notification type

• until (integer) –

  [REQUIRED]

  Show items created until

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'asset_data': {
        'deployment_id': 'string',
        'tag_keys': [
            {}
        ],
        'tags': [
            {}
        ]
    },
    'attachments': [
        {
            'description': 'string',
            'name': 'string',
            'url': 'string'
        }
    ],
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'notification_data': {
        'appliance': 'string',
        'attackers': [
            'string'
        ],
        'class': 'string',
        'detection_source': 'string',
        'status': 'string',
        'targets': [
            'string'
        ],
        'threat_level': 'string'
    },
    'payload': {
        'analyst_notes': 'string',
        'attack_summary': 'string',
        'cid': 'number',
        'class': 'string',
        'create_date': 'string',
        'customer_name': 'string',
        'deployment_name': 'string',
        'incident_id': 'string',
        'investigation_report': 'string',
        'location_ip': 'string',
        'long_incident_id': 'string',
        'start_date': 'string',
        'status': 'string',
        'threat': 'string'
    },
    'status': 'string',
    'type': 'string'
}

Response Definitions

• account_id (string) –

• asset_data (dict) –

  • deployment_id (string) –

  • tag_keys (list) –

    • (dict) –

  • tags (list) –

    • (dict) –

• attachments (list) –

  • (dict) –

    • description (string) –

    • name (string) –

    • url (string) –

• created (dict) –

  • at (number) –

  • by (string) –

• id (string) –

• modified (dict) –

  • at (number) –

  • by (string) –

• notification_data (dict) –

  • appliance (string) –

  • attackers (list) –

    • (string) –

  • class (string) –

  • detection_source (string) –

  • status (string) –

  • targets (list) –

    • (string) –

  • threat_level (string) –

• payload (dict) –

  • analyst_notes (string) –

  • attack_summary (string) –

  • cid (number) –

  • class (string) –

  • create_date (string) –

  • customer_name (string) –

  • deployment_name (string) –

  • incident_id (string) –

  • investigation_report (string) –

  • location_ip (string) –

  • long_incident_id (string) –

  • start_date (string) –

  • status (string) –

  • threat (string) –

• status (string) –

• type (string) –

get_account_subscription(**kwargs)

List a subscription for an account by subscription id

Request Syntax

response = client.get_account_subscription(
    account_id='string'
    include_subscribers='False|True'
    subscription_id='string'
)

Parameters

• account_id (string) – [REQUIRED]

• include_subscribers (boolean) –

  Includes subscribers per corresponding Subscription ID

  Default: false

• subscription_id (string) – [REQUIRED]

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'active': 'string',
    'class': 'string',
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'name': 'string',
    'notification_type': 'string',
    'subscriber_count': 'number',
    'subscribers': [
        {
            'id': 'string',
            'subscriber': 'string',
            'subscriber_type': 'string',
            'subscription_id': 'string'
        }
    ]
}

Response Definitions

• account_id (string) –

• active (string) –

• class (string) –

• created (dict) –

  • at (number) –

  • by (string) –

• id (string) –

• name (string) –

• notification_type (string) –

• subscriber_count (number) –

  Available in List subscriptions for an account by subscription id

• subscribers (list) –

  Available in List subscriptions for an account by subscription id

  • (dict) –

    • id (string) –

      Available in List subscriptions for an account by subscription id

    • subscriber (string) –

    • subscriber_type (string) –

    • subscription_id (string) –

      Available in List subscriptions for an account by subscription id

get_account_subscription_subscribers(**kwargs)

List all subscribers subscribed to that subscription

Request Syntax

response = client.get_account_subscription_subscribers(
    account_id='string'
    subscription_id='string'
)

Parameters

• account_id (string) – [REQUIRED]

• subscription_id (string) – [REQUIRED]

Return type

dict

Returns

Response Syntax

{
    'subscribers': [
        {
            'id': 'string',
            'subscriber': 'string',
            'subscriber_type': 'string',
            'subscription_id': 'string'
        }
    ]
}

Response Definitions

• subscribers (list) –

  • (dict) –

    • id (string) –

      Available in List subscriptions for an account by subscription id

    • subscriber (string) –

    • subscriber_type (string) –

    • subscription_id (string) –

      Available in List subscriptions for an account by subscription id

get_account_subscriptions(**kwargs)

List subscriptions for an account

Request Syntax

response = client.get_account_subscriptions(
    account_id='string'
    class='string'
    external_id='string'
    include_subscribers='False|True'
    notification_type='string'
)

Parameters

• account_id (string) – [REQUIRED]

• class (string) – Class name

• external_id (string) – external_id of subscriptions. When present, class=schedule is assumed

• include_subscribers (boolean) –

  Includes subscribers per corresponding Subscription ID

  Default: false

• notification_type (string) – Notification type

Return type

dict

Returns

Response Syntax

{
    'subscriptions': [
        {
            'account_id': 'string',
            'active': 'string',
            'class': 'string',
            'created': {
                'at': 'number',
                'by': 'string'
            },
            'id': 'string',
            'name': 'string',
            'notification_type': 'string',
            'subscriber_count': 'number',
            'subscribers': [
                {
                    'id': 'string',
                    'subscriber': 'string',
                    'subscriber_type': 'string',
                    'subscription_id': 'string'
                }
            ]
        }
    ]
}

Response Definitions

• subscriptions (list) –

  • (dict) –

    • account_id (string) –

    • active (string) –

    • class (string) –

    • created (dict) –

      • at (number) –

      • by (string) –

    • id (string) –

    • name (string) –

    • notification_type (string) –

    • subscriber_count (number) –

      Available in List subscriptions for an account by subscription id

    • subscribers (list) –

      Available in List subscriptions for an account by subscription id

      • (dict) –

        • id (string) –

          Available in List subscriptions for an account by subscription id

        • subscriber (string) –

        • subscriber_type (string) –

        • subscription_id (string) –

          Available in List subscriptions for an account by subscription id

get_integration_types(**kwargs)

Get the list of available integration types

Request Syntax

response = client.get_integration_types(
)

Return type

dict

Returns

Response Syntax

{
    'integration_types': [
        {
            'name': 'string'
        }
    ]
}

Response Definitions

• integration_types (list) –

  • (dict) –

    • name (string) –

get_notification(**kwargs)

Get a notification by ID

Request Syntax

response = client.get_notification(
    notification_id='string'
)

Parameters

notification_id (string) –

[REQUIRED]

Notification id

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'asset_data': {
        'deployment_id': 'string',
        'tag_keys': [
            {}
        ],
        'tags': [
            {}
        ]
    },
    'attachments': [
        {
            'description': 'string',
            'name': 'string',
            'url': 'string'
        }
    ],
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'notification_data': {
        'appliance': 'string',
        'attackers': [
            'string'
        ],
        'class': 'string',
        'detection_source': 'string',
        'status': 'string',
        'targets': [
            'string'
        ],
        'threat_level': 'string'
    },
    'payload': {
        'analyst_notes': 'string',
        'attack_summary': 'string',
        'cid': 'number',
        'class': 'string',
        'create_date': 'string',
        'customer_name': 'string',
        'deployment_name': 'string',
        'incident_id': 'string',
        'investigation_report': 'string',
        'location_ip': 'string',
        'long_incident_id': 'string',
        'start_date': 'string',
        'status': 'string',
        'threat': 'string'
    },
    'status': 'string',
    'type': 'string'
}

Response Definitions

• account_id (string) –

• asset_data (dict) –

  • deployment_id (string) –

  • tag_keys (list) –

    • (dict) –

  • tags (list) –

    • (dict) –

• attachments (list) –

  • (dict) –

    • description (string) –

    • name (string) –

    • url (string) –

• created (dict) –

  • at (number) –

  • by (string) –

• id (string) –

• modified (dict) –

  • at (number) –

  • by (string) –

• notification_data (dict) –

  • appliance (string) –

  • attackers (list) –

    • (string) –

  • class (string) –

  • detection_source (string) –

  • status (string) –

  • targets (list) –

    • (string) –

  • threat_level (string) –

• payload (dict) –

  • analyst_notes (string) –

  • attack_summary (string) –

  • cid (number) –

  • class (string) –

  • create_date (string) –

  • customer_name (string) –

  • deployment_name (string) –

  • incident_id (string) –

  • investigation_report (string) –

  • location_ip (string) –

  • long_incident_id (string) –

  • start_date (string) –

  • status (string) –

  • threat (string) –

• status (string) –

• type (string) –

get_notification_types(**kwargs)

Get available notification types

Request Syntax

response = client.get_notification_types(
)

Return type

dict

Returns

Response Syntax

{
    'notification_types': [
        {
            'default_email_subject': 'string',
            'default_template': 'string',
            'name': 'string',
            'notification_type': 'string',
            'templates': [
                'string'
            ]
        }
    ]
}

Response Definitions

• notification_types (list) –

  • (dict) –

    • default_email_subject (string) –

    • default_template (string) –

    • name (string) –

    • notification_type (string) –

    • templates (list) –

      • (string) –

get_sent_incident_notifications(**kwargs)

Get list of sent incident notifications for a provided account id and long incident id

Request Syntax

response = client.get_sent_incident_notifications(
    account_id='string'
    long_incident_id='string'
)

Parameters

• account_id (string) –

  [REQUIRED]

  Account id

• long_incident_id (string) –

  [REQUIRED]

  Notification id

Return type

dict

Returns

Response Syntax

{
    'notifications': [
        {
            'id': 'string',
            'integration_statuses': [
                {
                    'integration_id': 'string',
                    'integration_response': {
                        'body': 'string',
                        'code': 'string'
                    },
                    'queue_data': {
                        'config': {
                            'target_url': 'string',
                            'type': 'string'
                        },
                        'id': 'string'
                    },
                    'status': '\'QUEUED\'|'\'SENT\'',
                    'type': 'string'
                }
            ],
            'statuses': [
                {
                    'destination': 'string',
                    'sent_at': 'number',
                    'status': '\'PENDING\'|'\'SENT\'|'\'DELIVRD\'|'\'READ\'|'\'FAILED\''
                }
            ],
            'subject': 'string',
            'subkey': 'string',
            'type': 'string'
        }
    ]
}

Response Definitions

• notifications (list) –

  • (dict) –

    • id (string) –

    • integration_statuses (list) –

      • (dict) –

        • integration_id (string) –

        • integration_response (dict) –

          • body (string) –

          • code (string) –

        • queue_data (dict) –

          • config (dict) –

            • target_url (string) –

            • type (string) –

          • id (string) –

        • status (string) –

          Valid values: "QUEUED", "SENT"

        • type (string) –

    • statuses (list) –

      • (dict) –

        • destination (string) –

        • sent_at (number) –

        • status (string) –

          Valid values: "PENDING", "SENT", "DELIVRD", "READ", "FAILED"

    • subject (string) –

    • subkey (string) –

    • type (string) –

sent_notification(**kwargs)

Sends a notification

Request Syntax

response = client.sent_notification(
    account_id='string'
    asset_data={
        'deployment_id': 'string',
        'tag_keys': [
            {}
        ],
        'tags': [
            {}
        ]
    }
    attachments=[
        {
            'description': 'string',
            'name': 'string',
            'url': 'string'
        }
    ]
    notification_data={
        'appliance': 'string',
        'attackers': [
            'string'
        ],
        'class': 'string',
        'detection_source': 'string',
        'status': 'string',
        'targets': [
            'string'
        ],
        'threat_level': 'string'
    }
    payload={
        'analyst_notes': 'string',
        'attack_summary': 'string',
        'cid': 'number',
        'class': 'string',
        'create_date': 'string',
        'customer_name': 'string',
        'deployment_name': 'string',
        'incident_id': 'string',
        'investigation_report': 'string',
        'location_ip': 'string',
        'long_incident_id': 'string',
        'start_date': 'string',
        'status': 'string',
        'threat': 'string'
    }
    type='string'
)

Parameters

• account_id (string) –

  [REQUIRED]

  AIMS Account ID

• asset_data (dict) –

  [REQUIRED]

  • deployment_id (string) –

  • tag_keys (list) –

    • (dict) –

  • tags (list) –

    • (dict) –

• attachments (list) –

  • (dict) –

    • description (string) –

    • name (string) –

    • url (string) –

• notification_data (dict) –

  [REQUIRED]

  • appliance (string) –

  • attackers (list) –

    • (string) –

  • class (string) –

  • detection_source (string) –

  • status (string) –

  • targets (list) –

    • (string) –

  • threat_level (string) –

• payload (dict) –

  [REQUIRED]

  • analyst_notes (string) –

  • attack_summary (string) –

  • cid (number) –

  • class (string) –

  • create_date (string) –

  • customer_name (string) –

  • deployment_name (string) –

  • incident_id (string) –

  • investigation_report (string) –

  • location_ip (string) –

  • long_incident_id (string) –

  • start_date (string) –

  • status (string) –

  • threat (string) –

• type (string) – [REQUIRED]

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'asset_data': {
        'deployment_id': 'string',
        'tag_keys': [
            {}
        ],
        'tags': [
            {}
        ]
    },
    'attachments': [
        {
            'description': 'string',
            'name': 'string',
            'url': 'string'
        }
    ],
    'created': {
        'at': 'number',
        'by': 'string'
    },
    'id': 'string',
    'modified': {
        'at': 'number',
        'by': 'string'
    },
    'notification_data': {
        'appliance': 'string',
        'attackers': [
            'string'
        ],
        'class': 'string',
        'detection_source': 'string',
        'status': 'string',
        'targets': [
            'string'
        ],
        'threat_level': 'string'
    },
    'payload': {
        'analyst_notes': 'string',
        'attack_summary': 'string',
        'cid': 'number',
        'class': 'string',
        'create_date': 'string',
        'customer_name': 'string',
        'deployment_name': 'string',
        'incident_id': 'string',
        'investigation_report': 'string',
        'location_ip': 'string',
        'long_incident_id': 'string',
        'start_date': 'string',
        'status': 'string',
        'threat': 'string'
    },
    'status': 'string',
    'type': 'string'
}

Response Definitions

• account_id (string) –

• asset_data (dict) –

  • deployment_id (string) –

  • tag_keys (list) –

    • (dict) –

  • tags (list) –

    • (dict) –

• attachments (list) –

  • (dict) –

    • description (string) –

    • name (string) –

    • url (string) –

• created (dict) –

  • at (number) –

  • by (string) –

• id (string) –

• modified (dict) –

  • at (number) –

  • by (string) –

• notification_data (dict) –

  • appliance (string) –

  • attackers (list) –

    • (string) –

  • class (string) –

  • detection_source (string) –

  • status (string) –

  • targets (list) –

    • (string) –

  • threat_level (string) –

• payload (dict) –

  • analyst_notes (string) –

  • attack_summary (string) –

  • cid (number) –

  • class (string) –

  • create_date (string) –

  • customer_name (string) –

  • deployment_name (string) –

  • incident_id (string) –

  • investigation_report (string) –

  • location_ip (string) –

  • long_incident_id (string) –

  • start_date (string) –

  • status (string) –

  • threat (string) –

• status (string) –

• type (string) –