Skip to content

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 the register_hooks method 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 for on_preload hooks. However, we strongly recommend the use of on_postload hooks 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 the register_hooks methods 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