Hooks
Introduced in IRIS v1.4.0
Hooks are a mean for modules to react on specific events that occurs on IRIS. By subscribing to a hook, a module is automatically notified when the associated event occurs. This offers a multitude of possibilities, from adding insight to IRIS objects, to pushing information to another platform or even changing how IRIS works.
Types
There are 3 types of hooks.
On preload: Triggered before an object is processed and committed to database. It is triggered right after a request is received, and the data associated with the hook is usually the request content itself. In most of the cases, modules should not subscribe to these hooks.On postload: Triggered after an object is processed and committed to database. It is triggered after IRIS processed the request and the data associated with the hook is usually a list of SqlAlchemy objects (such as IOC, Assets, etc).Manual: Triggered by manual action of a user. When a module subscribes to these hooks, it needs to provide a "menu option name" which will be displayed to users. When they click this option, the associated hook is triggered for this module only. Multiple manual hooks can be registered for one module.
Danger
on_preload hooks must run synchronously, i.e not queued in RabbitMQ. This effectively blocks the current user request until the module finishes the processing. We highly recommend to only use on_postload hooks for a better user experience. These hooks are transparent for users and rely on already verified and committed data. Handling on_preload hooks implies the received data is unsafe - directly coming from remote clients - and the module needs to process the data as fast as possible.
Subscribing and unsubscribing
Two methods are provided by IrisModuleInterface to subscribe and unsubscribe to hooks.
def register_to_hook(module_id: int,
iris_hook_name: str,
manual_hook_name: str = None,
run_asynchronously: bool = True)
def deregister_from_hook(module_id: int,
iris_hook_name: str)
The registration method expects the following arguments:
module_id: The ID of the calling module. This information is given by IRIS when theregister_hooksmethod is called.iris_hook_name: The name of the hook to which subscribe. This must be one of the hook listed in the section below.manual_hook_name: The name of the UI menu that is provided to users if the registration concerns a manual hook. If nothing is provided, IRIS will create a name composed as follows:<module_name>::<hook_name>. This value is ignored if the signal is not manual.run_asynchronously: Set to True (default) to run the module in a RabbitMQ task upon hook triggering. If set to False, the module is called immediately, which have for effect to effectively block the current user request until the module finishes. This is the behavior to use foron_preloadhooks. However, we strongly recommend the use ofon_postloadhooks to prevent any unwanted (see warning section above).
The deregistration method expects the following arguments:
module_id: The ID of the calling module. This information is given by IRIS when theregister_hooksmethods is called.iris_hook_name: The name of the hook to which unsubscribe. If the module is not subscribed to the specified hook the function returns without errors.
Please see the modules documentation for more details on how to implement these methods.
Available hooks
The following hooks are natively available for subscription.
| Hook name | Description |
|---|---|
| on_preload_case_create | Triggered on case creation, before commit in DB |
| on_postload_case_create | Triggered on case creation, after commit in DB |
| on_preload_case_delete | Triggered on case deletion, before commit in DB |
| on_postload_case_delete | Triggered on case deletion, after commit in DB |
| on_postload_case_update | Triggered on case update, before commit in DB |
| on_manual_trigger_case | Triggered upon user action |
| on_postload_alert_create | Triggered on alert creation, after commit in DB |
| on_postload_alert_update | Triggered on alert update, after commit in DB |
| on_postload_alert_delete | Triggered on alert deletion, after commit in DB |
| on_postload_alert_escalate | Triggered on alert escalation, after commit in DB |
| on_postload_alert_merge | Triggered on alert merge, after commit in DB |
| on_postload_alert_unmerge | Triggered on alert unmerge, after commit in DB |
| on_preload_asset_create | Triggered on asset creation, before commit in DB |
| on_postload_asset_create | Triggered on asset creation, after commit in DB |
| on_preload_asset_update | Triggered on asset update, before commit in DB |
| on_postload_asset_update | Triggered on asset update, after commit in DB |
| on_preload_asset_delete | Triggered on asset deletion, before commit in DB |
| on_postload_asset_delete | Triggered on asset deletion, after commit in DB |
| on_manual_trigger_asset | Triggered upon user action |
| on_preload_note_create | Triggered on note creation, before commit in DB |
| on_postload_note_create | Triggered on note creation, after commit in DB |
| on_preload_note_update | Triggered on note update, before commit in DB |
| on_postload_note_update | Triggered on note update, after commit in DB |
| on_preload_note_delete | Triggered on note deletion, before commit in DB |
| on_postload_note_delete | Triggered on note deletion, after commit in DB |
| on_manual_trigger_note | Triggered upon user action |
| on_preload_ioc_create | Triggered on ioc creation, before commit in DB |
| on_postload_ioc_create | Triggered on ioc creation, after commit in DB |
| on_preload_ioc_update | Triggered on ioc update, before commit in DB |
| on_postload_ioc_update | Triggered on ioc update, after commit in DB |
| on_preload_ioc_delete | Triggered on ioc deletion, before commit in DB |
| on_postload_ioc_delete | Triggered on ioc deletion, after commit in DB |
| on_manual_trigger_ioc | Triggered upon user action |
| on_preload_event_create | Triggered on event creation, before commit in DB |
| on_preload_event_duplicate | Triggered on event duplication, before commit in DB. This event only received the event ID which will be duplicated |
| on_postload_event_create | Triggered on event creation, after commit in DB |
| on_preload_event_update | Triggered on event update, before commit in DB |
| on_postload_event_update | Triggered on event update, after commit in DB |
| on_preload_event_delete | Triggered on event deletion, before commit in DB |
| on_postload_event_delete | Triggered on event deletion, after commit in DB |
| on_manual_trigger_event | Triggered upon user action |
| on_preload_evidence_create | Triggered on evidence creation, before commit in DB |
| on_postload_evidence_create | Triggered on evidence creation, after commit in DB |
| on_preload_evidence_update | Triggered on evidence update, before commit in DB |
| on_postload_evidence_update | Triggered on evidence update, after commit in DB |
| on_preload_evidence_delete | Triggered on evidence deletion, before commit in DB |
| on_postload_evidence_delete | Triggered on evidence deletion, after commit in DB |
| on_manual_trigger_evidence | Triggered upon user action |
| on_preload_task_create | Triggered on task creation, before commit in DB |
| on_postload_task_create | Triggered on task creation, after commit in DB |
| on_preload_task_update | Triggered on task update, before commit in DB |
| on_postload_task_update | Triggered on task update, after commit in DB |
| on_preload_task_delete | Triggered on task deletion, before commit in DB |
| on_postload_task_delete | Triggered on task deletion, after commit in DB |
| on_manual_trigger_task | Triggered upon user action |
| on_preload_global_task_create | Triggered on global task creation, before commit in DB |
| on_postload_global_task_create | Triggered on global task creation, after commit in DB |
| on_preload_global_task_update | Triggered on task update, before commit in DB |
| on_postload_global_task_update | Triggered on global task update, after commit in DB |
| on_preload_global_task_delete | Triggered on task deletion, before commit in DB |
| on_postload_global_task_delete | Triggered on global task deletion, after commit in DB |
| on_manual_trigger_global_task | Triggered upon user action |
| on_preload_report_create | Triggered on report creation, before generation in DB |
| on_postload_report_create | Triggered on report creation, before download of the document |
| on_preload_activities_report_create | Triggered on activities report creation, before generation in DB |
| on_postload_activities_report_create | Triggered on activities report creation, before download of the document |
| on_postload_asset_commented | Triggered on asset comment, after commit in DB |
| on_postload_asset_comment_update | Triggered on asset comment update, after commit in DB |
| on_postload_asset_comment_delete | Triggered on asset comment deletion, after commit in DB |
| on_postload_evidence_commented | Triggered on evidence comment, after commit in DB |
| on_postload_evidence_comment_update | Triggered on evidence comment update, after commit in DB |
| on_postload_evidence_comment_delete | Triggered on evidence comment deletion, after commit in DB |
| on_postload_task_commented | Triggered on task comment, after commit in DB |
| on_postload_task_comment_update | Triggered on task comment update, after commit in DB |
| on_postload_task_comment_delete | Triggered on task comment deletion, after commit in DB |
| on_postload_ioc_commented | Triggered on ioc comment, after commit in DB |
| on_postload_ioc_comment_update | Triggered on ioc comment update, after commit in DB |
| on_postload_ioc_comment_delete | Triggered on ioc comment deletion, after commit in DB |
| on_postload_event_commented | Triggered on event comment, after commit in DB |
| on_postload_event_comment_update | Triggered on event comment update, after commit in DB |
| on_postload_event_comment_delete | Triggered on event comment deletion, after commit in DB |
| on_postload_note_commented | Triggered on note comment, after commit in DB |
| on_postload_note_comment_update | Triggered on note comment update, after commit in DB |
| on_postload_note_comment_delete | Triggered on note comment deletion, after commit in DB |
| on_postload_alert_commented | Triggered on alert comment, after commit in DB |
| on_postload_alert_comment_update | Triggered on alert comment update, after commit in DB |
| on_postload_alert_comment_delete | Triggered on alert comment deletion, after commit in DB |
Last update:
2023-05-30