diff --git a/docs/tutorial/PyMISP Objects.ipynb b/docs/tutorial/PyMISP Objects.ipynb new file mode 100644 index 0000000..d7ee112 --- /dev/null +++ b/docs/tutorial/PyMISP Objects.ipynb @@ -0,0 +1,373 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Using the PyMISP objects\n", + "## MISPEvent" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymisp import MISPEvent\n", + "\n", + "event = MISPEvent()\n", + "\n", + "event.info = 'This is my new MISP event' # Required\n", + "event.distribution = 0 # Optional, defaults to MISP.default_event_distribution in MISP config\n", + "event.threat_level_id = 2 # Optional, defaults to MISP.default_event_threat_level in MISP config\n", + "event.analysis = 1 # Optional, defaults to 0 (initial analysis)\n", + "\n", + "print(event.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Tag Event" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "event.add_tag('tlp:white')\n", + "\n", + "print(event.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Set the Event date" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# As text\n", + "event.set_date('2018-04-13')\n", + "print('Simple', event.date)\n", + "event.set_date('Sat Oct 11 00:13:46 2017')\n", + "print('Mess', event.date)\n", + "\n", + "from datetime import date\n", + "d = date.today()\n", + "print(type(d))\n", + "event.set_date(d)\n", + "print(event.date)\n", + "\n", + "\n", + "from datetime import datetime\n", + "d = datetime.now()\n", + "print(type(d))\n", + "event.set_date(d)\n", + "print(event.date)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Add Attribute to event" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "attribute = event.add_attribute('ip-dst', '8.8.8.8') # Minimal parameters\n", + "\n", + "print(type(attribute))\n", + "\n", + "print(attribute.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Modify existing attribute" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "attribute.to_ids = False\n", + "\n", + "print(attribute.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Set parameters (inline)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "attribute_second = event.add_attribute('ip-dst', '8.8.8.9', disable_correlation=True) # Minimal parameters\n", + "\n", + "print(attribute_second.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Tag Attribute" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "attribute.add_tag('tlp:amber')\n", + "\n", + "print(attribute_second.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Soft delete attribute" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "attribute.delete()\n", + "print(attribute.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## MISPObject" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymisp import MISPObject\n", + "\n", + "circl_attr = event.add_attribute('ip-dst', '149.13.33.14')\n", + "\n", + "\n", + "misp_object = MISPObject('domain-ip', standalone=False, default_attributes_parameters=circl_attr)\n", + "# Notes: \n", + "# * standalone: this object will be attached to a MISPEvent, so the references will be in the dump\n", + "# * default_attributes_parameters: keep parameters from a MISPAttribute (usefull when expanding a existing one) \n", + "misp_object.comment = 'My Fancy new object'\n", + "\n", + "obj_attr = misp_object.add_attribute('domain', value='circl.lu')\n", + "obj_attr.add_tag('tlp:green')\n", + "misp_object.add_attribute('ip', value='149.13.33.14')\n", + "misp_object.add_attribute('first-seen', value='2018-04-11')\n", + "misp_object.add_attribute('last-seen', value='2018-06-11')\n", + "misp_object.add_reference(circl_attr.uuid, 'related-to', 'Expanded with passive DNS entry')\n", + "\n", + "event.add_object(misp_object)\n", + "print(event.to_json())\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Helpers for MISPObjects " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymisp.tools import FileObject\n", + "\n", + "file_obj = FileObject(filepath='../../tests/viper-test-files/test_files/EICAR.com', standalone=False)\n", + "print(file_obj.to_json())" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "event.add_object(file_obj)\n", + "print(event.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Playing with a malware sample" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sample = file_obj.get_attributes_by_relation('malware-sample')[0]\n", + "print(sample)\n", + "print(sample.malware_binary)\n", + "print(sample.malware_binary.getvalue())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Use lief to extract indicators out of binaries" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymisp.tools import make_binary_objects\n", + "\n", + "file_obj, bin_obj, sections = make_binary_objects(filepath='../../tests/viper-test-files/test_files/whoami.exe', standalone=False)\n", + "\n", + "event.add_object(file_obj)\n", + "event.add_object(bin_obj)\n", + "for s in sections:\n", + " event.add_object(s)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## References" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(bin_obj.uuid)\n", + "print(bin_obj.references[0].to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Dump valid MISP Event ready to push to MISP" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(event.to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Update an existing MISPEvent" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymisp import MISPEvent\n", + "\n", + "existing_event = MISPEvent()\n", + "existing_event.load_file('../../tests/mispevent_testfiles/existing_event.json')\n", + "\n", + "print(existing_event.attributes[0])\n", + "print(existing_event.attributes[0].tags)\n", + "print(existing_event.attributes[0].timestamp)\n", + "print(existing_event.attributes[0].to_json())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Edit, removes the timestamp when exporting" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "existing_event.attributes[0].add_tag('tlp:white')\n", + "print(existing_event.attributes[0].to_json())" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.6.3" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}