NAME
    RTIR-Extension-MISP - Integrate RTIR with MISP

DESCRIPTION
    MISP <https://www.misp-project.org/> is a platform for sharing threat
    intelligence among security teams, and this extension provides
    integration from RTIR <https://bestpractical.com/rtir>.

RTIR VERSION
    Works with RTIR 6.0

INSTALLATION
    perl Makefile.PL
    make
    make install
        May need root permissions

    Edit your /opt/rt6/etc/RT_SiteConfig.pm
        Add this line:

            Plugin('RTIR::Extension::MISP');

    make initdb
        Only run this the first time you install this module.

        If you run this twice, you will end up with duplicate data in your
        database.

        If you are upgrading this module, check for upgrading instructions
        in case changes need to be made to your database.

    Clear your mason cache
            rm -rf /opt/rt6/var/mason_data/obj

    Restart your webserver

CONFIGURATION
  Base MISP Configuration
    Set the following in your RT_SiteConfig.pm with details for the MISP
    instance you want RTIR to integrate with.

        Set(%ExternalFeeds,
            'MISP' => [
                {   Name        => 'MISP',
                    URI         => 'https://mymisp.example.com',  # Change to your MISP
                    Description => 'My MISP Feed',
                    DaysToFetch => 5,  # For the feed page, how many days back to fetch
                    ApiKeyAuth  => 'API SECRET KEY',  # Change to your real key
                },
            ],
        );

  MISP Custom Fields
    This extension ships a MISP custom field grouping in etc/MISP_Config.pm
    which is picked up automatically for file-based installs. If your
    installation has edited %CustomFieldGroupings via the RT database (Admin
    > Tools > Configuration), the database value takes precedence over
    file-based config and the MISP grouping must be added manually by
    merging the following into your existing CustomFieldGroupings setting:

        {
            "RT::Ticket": {
                "Incidents": [
                    "MISP",
                    ["MISP Event ID", "MISP Event UUID", "MISP RTIR Object ID"]
                ]
            }
        }

  Page Layouts
    Since this extension integrates with RTIR, which defines its own page
    layouts, the MISP page components must be added manually via Admin >
    Page Layouts to avoid overwriting existing layouts.

    Ticket Create (Incidents)
        Add CustomFieldCustomGroupings:MISP (or the default CustomFields
        grouping) so that the MISP Event ID and UUID are set when creating a
        ticket from the External Feeds page.

    Ticket Display (Incidents)
        Add CustomFieldCustomGroupings:MISP (or CustomFields) to show the
        MISP custom fields on the incident, and MISPEventDetails to display
        the MISP event details widget.

DETAILS
    This integration adds several different ways to work between the MISP
    and RTIR systems as described below.

  Consume Feed from MISP
    After adding the MISP configuration described above, the Feeds page in
    RTIR at RTIR > Tools > External Feeds will have a new MISP option
    listed. This feed pulls in events for the past X number of days based on
    the DaysToFetch configuration. From the feed display page, you can click
    the "Create new ticket" button to create a ticket with information from
    the MISP event.

  MISP Event Details Widget
    This extension provides a MISPEventDetails page layout widget for RT 6.
    When the MISP Event ID custom field has a value, the widget displays
    event details fetched from the MISP REST API including threat level,
    analysis status, creator org, and attribute counts. See "Page Layouts"
    above for instructions on adding it to your Incidents Display layout.

  Update MISP Event
    On an incident with a MISP Event ID, the Actions menu will have an
    option "Update MISP Event". If you select this action, RTIR will update
    the existing MISP event with an RTIR object, including data from the
    incident ticket.

  Create MISP Event
    If MISP Event ID has no value, the Actions menu on incidents shows an
    option to "Create MISP Event". Select this to create an event in MISP
    with details from the incident ticket.

  Customizing MISP Sync with Callbacks
    When creating or updating a MISP event, this extension fires two Mason
    callbacks that allow you to customize the data sent to and received from
    MISP without modifying the extension itself. This can be used to push
    additional indicators (domains, hashes, URLs from custom CFs), add
    taxonomy tags, perform data mappings, or take action based on the result
    of the sync.

    BeforeMISPSync
        Fires before the MISP event is created or updated. Receives $Ticket,
        $Actions, and $ARGSRef.

    AfterMISPSync
        Fires after the MISP event is created or updated. Receives $Ticket,
        $Actions, $ARGSRef, $OK (1 on success, 0 on failure), and $Msg (the
        result message). The MISP Event ID is available on the ticket via
        $Ticket->FirstCustomFieldValue('MISP Event ID').

    Callback files should be placed at:

        html/Callbacks/<YourPlugin>/RTIR/Incident/Display.html/ProcessArguments/BeforeMISPSync
        html/Callbacks/<YourPlugin>/RTIR/Incident/Display.html/ProcessArguments/AfterMISPSync

AUTHOR
    Best Practical Solutions, LLC <modules@bestpractical.com>

    All bugs should be reported via email to
        bug-RTIR-Extension-MISP@rt.cpan.org
    or via the web at
        http://rt.cpan.org/Public/Dist/Display.html?Name=RTIR-Extension-MISP
LICENSE AND COPYRIGHT
    This software is Copyright (c) 2021 by Best Practical Solutions, LLC

    This is free software, licensed under:

      The GNU General Public License, Version 2, June 1991