{"id":27976455,"url":"https://github.com/misp/misp-stix","last_synced_at":"2025-05-08T01:26:59.416Z","repository":{"id":37207821,"uuid":"350412169","full_name":"MISP/misp-stix","owner":"MISP","description":"MISP-STIX-Converter - Python library to handle the conversion between MISP and STIX formats","archived":false,"fork":false,"pushed_at":"2025-04-28T14:51:41.000Z","size":7950,"stargazers_count":53,"open_issues_count":27,"forks_count":21,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-28T15:42:01.858Z","etag":null,"topics":["cyberthreatintelligence","misp","stix","stix2"],"latest_commit_sha":null,"homepage":"https://misp.github.io/misp-stix/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MISP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-22T16:24:24.000Z","updated_at":"2025-04-24T15:12:09.000Z","dependencies_parsed_at":"2023-11-11T19:27:34.112Z","dependency_job_id":"bd2091d2-284a-48d9-bd7d-dafc6b5db4ef","html_url":"https://github.com/MISP/misp-stix","commit_stats":{"total_commits":1472,"total_committers":10,"mean_commits":147.2,"dds":"0.34850543478260865","last_synced_commit":"57c7a33f0f7adc491b7021179f7f0aa9bd8c88f9"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MISP%2Fmisp-stix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MISP%2Fmisp-stix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MISP%2Fmisp-stix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MISP%2Fmisp-stix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MISP","download_url":"https://codeload.github.com/MISP/misp-stix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252980578,"owners_count":21835266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cyberthreatintelligence","misp","stix","stix2"],"created_at":"2025-05-08T01:26:58.814Z","updated_at":"2025-05-08T01:26:59.400Z","avatar_url":"https://github.com/MISP.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MISP-STIX - Python library to handle the conversion between MISP standard and STIX\n\n\u003cimg src=\"https://raw.githubusercontent.com/MISP/misp-stix/main/documentation/logos/misp-stix.png\" width=\"125\" height=\"125\"\u003e\n\n[![Python version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)\n[![MISP-STIX version](https://badge.fury.io/gh/MISP%2Fmisp-stix.svg)](https://badge.fury.io/gh/MISP%2Fmisp-stix)\n[![Github Actions](https://github.com/MISP/misp-stix/workflows/misp-stix/badge.svg)](https://github.com/MISP/misp-stix/actions?query=workflow%3Amisp-stix)\n[![License](https://img.shields.io/github/license/MISP/misp-stix.svg)](#License)\n\nMISP-STIX-converter is a Python library (\u003e=3.9) to handle all the conversions between the [MISP standard format](https://www.misp-standard.org/) and STIX formats.\n\nThe package is available as [misp-stix](https://pypi.org/project/misp-stix/) in PyPI.\n\n## Features\n\n- MISP standard format conversion to STIX 1.x (1.1.1 and 1.2)\n- MISP standard format conversion to STIX 2.x (2.0 and 2.1)\n- Maps [MISP Objects](https://github.com/MISP/misp-objects) and [MISP galaxies](https://github.com/misp/misp-galaxy) with [respective semantically similar objects](https://github.com/MISP/misp-stix/tree/main/documentation)\n- STIX to MISP standard format\n- Provides an extendable library for mapping and facilitate extension\n\nThis library is used by the [MISP core software](https://github.com/MISP/MISP) to perform STIX conversion and serving as a useful tool for anyone looking for a clean way of converting between the MISP standard format and various STIX versions (1.1.1, 1.2, 2.0, 2.1).\n\nA complete [documentation is available](./documentation/) including the mappings between the different formats.\n\n## Install from pip\n\n**It is strongly recommended to use a virtual environment**\n\nIf you want to know more about virtual environments, [python has you covered](https://docs.python.org/3/tutorial/venv.html)\n\nFrom the current repository:\n```\npip3 install misp-stix\n```\n\nPackage details at PyPI: [misp-stix](https://pypi.org/project/misp-stix/)\n\n## Install the latest version from the repository for development purposes\n\n**Note**: poetry is strongly recommended; e.g., `pip3 install poetry`\n\n```\ngit clone https://github.com/MISP/misp-stix.git \u0026\u0026 cd misp-stix\ngit submodule update --init\npoetry install\n```\n\nIf you already have poetry face any issue with it while installing or updating misp-stix with it, you can try `pip3 install -U poetry` to make sure you have a version \u003e= 1.2\n\nAlternatively, you can set up a virtual environment with the following:\n\n```\nvirtualenv -p python3 venv\nsource ./venv/bin/activate\npip install -U pip\n# Manual install of setuptools to avoid some dependencies issues\npip install setuptools\npip install .\n```\n\n### Running the tests\n\nTests for MISP format export as STIX 1.1.1 \u0026 1.2:\n```bash\npoetry run pytest tests/test_stix1_export.py\n```\n\nTests for MISP format export as STIX 2.0:\n```bash\npoetry run pytest tests/test_stix20_export.py\n```\n\nTests for MISP format export as STIX 2.1:\n```bash\npoetry run pytest tests/test_stix21_export.py\n```\n\n## Usage\n\n### Command-line Usage\n\nIf you are not already within your virtual environment, you can either choose to prefix all the following example commands with `poetry run`, or simply activate your python environment:\n\n```bash\n# If you chose to use the recommended option\npoetry shell\n\n# OR\n\n# Another option that should work if you followed the example mentioned above with the install instructions\n./venv/bin/activate\n```\n\nAt this point, you should be able to use the command-line feature. Here are a few examples:\n\n```bash\n# Convert an Events collections to STIX 2.1\nmisp_stix_converter export --version 2.1 -f tests/test_events_collection_1.json\n\n# Convert a MISP Event and set a specific name for the STIX 2.1 output file\nmisp_stix_converter export --version 2.1 -f tests/test_event.misp.json -o tests/test_event.stix21.json\n\n# Convert a STIX 2 Bundle to MISP, and set specific distributions\nmisp_stix_converter import -f tmp/test_bundle.stix21.json -o tmp/test_bundle.misp.json -d 1 -cd 1\n# This will set the distribution for the Event, Attributes and Galaxy Clusters to `this community`\n\n# Convert multiple STIX 2 Bundles to MISP and directly push the results to MISP, knowing your authentication key\nmisp_stix_converter import -f tmp/*.stix21.json --url https://localhost --api_key _YOUR_AUTHENTICATION_KEY_\n# This will create a MISP Event for each file\n```\n\n#### Parameters\n\nFor more details on the different options presented with the examples, here is the complete description.\n\n```bash\nusage: misp_stix_converter [-h] [--debug] {export,import} ...\n\nConvert MISP \u003c-\u003e STIX\n\noptions:\n  -h, --help       show this help message and exit\n  --debug          Show errors and warnings\n\nMain feature:\n  {export,import}\n    export         Export MISP to STIX - try `misp_stix_converter export -h` for more help.\n    import         Import STIX to MISP - try `misp_stix_converter import -h` for more help.\n```\n\n##### Export parameters\n\n```bash\nusage: misp_stix_converter export [-h] -f FILE [FILE ...] -v {1.1.1,1.2,2.0,2.1} [-s] [-m] [--output-dir OUTPUT_DIR] [-o OUTPUT_NAME] [--level {attribute,event}] [--format {json,xml}] [-n NAMESPACE] [-org ORG]\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --file FILE [FILE ...]\n                        Path to the file(s) to convert.\n  -v, --version {1.1.1,1.2,2.0,2.1}\n                        STIX specific version.\n  -s, --single-output   Produce only one result file (in case of multiple input file).\n  -m, --in-memory       Store result in memory (in case of multiple result files) instead of storing it in tmp files.\n  --output-dir OUTPUT_DIR\n                        Output path - used in the case of multiple input files when the `single_output` argument is not used.\n  -o, --output-name OUTPUT_NAME\n                        Output file name - used in the case of a single input file or when the `single_output` argument is used.\n\nSTIX 1 specific arguments:\n  --level {attribute,event}\n                        MISP data structure level.\n  --format {json,xml}   STIX 1 format.\n  -n, --namespace NAMESPACE\n                        Namespace to be used in the STIX 1 header.\n  -org ORG              Organisation name to be used in the STIX 1 header.\n```\n\n##### Import parameters\n\n```bash\nusage: misp_stix_converter import [-h] -f FILE [FILE ...] [-v {1,2}] [-s] [-o OUTPUT_NAME] [--output-dir OUTPUT_DIR] [-d {0,1,2,3,4}] [-sg SHARING_GROUP] [--galaxies-as-tags] [--no-force-galaxy-cluster]\n                                  [--org-uuid ORG_UUID] [-cd {0,1,2,3,4}] [-csg CLUSTER_SHARING_GROUP] [-t TITLE] [-p PRODUCER] [-c CONFIG] [-u URL] [-a API_KEY] [--skip-ssl]\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --file FILE [FILE ...]\n                        Path to the file(s) to convert.\n  -v, --version {1,2}   STIX major version - default is 2\n  -s, --single-event    Produce only one MISP event per STIX file(in case of multiple Report, Grouping or Incident objects).\n  -o, --output-name OUTPUT_NAME\n                        Output file name - used in the case of a single input file or when the `single_event` argument is used.\n  --output-dir OUTPUT_DIR\n                        Output path - used in the case of multiple input files when the `single_event` argument is not used.\n  -d, --distribution {0,1,2,3,4}\n                        Distribution level for the imported MISP content (default is 0) - 0: Your organisation only - 1: This community only - 2: Connected communities - 3: All communities - 4: Sharing Group\n  -sg, --sharing-group SHARING_GROUP\n                        Sharing group ID when distribution is 4.\n  --galaxies-as-tags    Import MISP Galaxies as tag names instead of the standard Galaxy format.\n  --no-force-galaxy-cluster\n                        Do not force the creation of custom Galaxy clusters in some specific cases when STIX objects could be converted either as clusters or MISP objects for instance.\n  --org-uuid ORG_UUID   Organisation UUID to use when creating custom Galaxy clusters.\n  -cd, --cluster-distribution {0,1,2,3,4}\n                        Galaxy Clusters distribution level in case of External STIX 2 content (default id 0) - 0: Your organisation only - 1: This community only - 2: Connected communities - 3: All communities - 4:\n                        Sharing Group\n  -csg, --cluster-sharing-group CLUSTER_SHARING_GROUP\n                        Galaxy Clusters sharing group ID in case of External STIX 2 content.\n  -t, --title TITLE     Title used to set the MISP Event `info` field.\n  -p, --producer PRODUCER\n                        Producer of the imported content - Please make sure you use a name from the list of existing producer Galaxy Clusters.\n  -c, --config CONFIG   Config file containing the URL and the authentication key to connect to your MISP.\n  -u, --url URL         URL to connect to your MISP instance.\n  -a, --api-key API_KEY\n                        Authentication key to connect to your MISP instance.\n  --skip-ssl            Skip SSL certificate checking when connecting to your MISP instance.\n```\n\n### In Python scripts\n\nGiven a MISP Event (with its metadata fields, attributes, objects, galaxies and tags), declared in an `event` variable in Python dict format, you can get the result of a conversion into one of the supported STIX versions:\n\n- Convert a MISP Event in STIX1:\n\n```python\nfrom misp_stix_converter import MISPtoSTIX1EventsParser\n\nparser = MISPtoSTIX1EventsParser(\n    'MISP-Project', # Example of Org name\n    '1.1.1' # STIX1 version (1.1.1 or 1.2)\n)\nparser.parse_misp_event(event)\n\nstix_package = parser.stix_package\n```\n\n- Convert a MISP Event in STIX1 using directly its file name:\n\n```python\nfrom misp_stix_converter import misp_to_stix1\n\nresponse = misp_to_stix1(\n    filename, # file name of the file containing a MISP Event\n    'xml', # return format (XML or JSON)\n    '1.1.1' # STIX1 version (1.1.1 or 1.2)\n)\n# if everything went well, response is a dictionary where `success` = 1\n```\nThe resulting STIX1 Package is then available in a `filename.out` file\n\n- Convert a MISP Event in STIX2:\n\n```python\n# for STIX 2.0\nfrom misp_stix_converter import MISPtoSTIX20Parser\n# for STIX 2.1\nfrom misp_stix_converter import MISPtoSTIX21Parser\n\nparser20 = MISPtoSTIX20Parser()\nparser20.parse_misp_event(event)\n\nparser21 = MISPtoSTIX21Parser()\nparser21.parse_misp_event(event)\n\n# To get the list of parsed STIX objects\nstix_20_objects = parser20.stix_objects\nstix_21_objects = parser21.stix_objects\n\n# To get the list of parser STIX objects within a STIX 2.0 or 2.1 Bundle\nbundle20 = parser20.bundle\nbundle21 = parser21.bundle\n```\n\n- Convert a MISP Event in STIX2 using directly its file name:\n\n```python\nfrom misp_stix_converter import misp_to_stix2\n\nresponse_20 = misp_to_stix2(filename, version='2.0')\nresponse_21 = misp_to_stix2(filename, version='2.1')\n# Again response_20 \u0026 response_21 have a `success` field equal to 1 if everything went well\n```\nThe resulting STIX2 Bundle is the available in a `filename.out` file, or you can define the output name with the `output_name` argument.\n\nIf you get some MISP collection of data, it is also possible to convert it straight into some STIX format:\n\n```python\nfrom misp_stix_converter import MISPtoSTIX1EventsParser, MISPtoSTIX20Parser, MISPtoSTIX21Parser\n\nfilename = _PATH_TO_YOUR_FILE_CONTAINING_MISP_FORMAT_\n\nparser1 = MISPtoSTIX1EventsParser('MISP', '1.1.1')\nparser1.parse_json_content(filename)\nstix_package = parser1.stix_package\n\nparser20 = MISPtoSTIX20Parser()\nparser20.parse_json_content(filename)\nstix_20_objects = parser20.stix_objects\nbundle20 = parser20.bundle\n\nparser21 = MISPtoSTIX21Parser()\nparser21.parse_json_content(filename)\nstix_21_objects = parser21.stix_objects\nbundle21 = parser21.bundle\n```\n\nBut in order to parse multiple data collections, you can also use the following helpers:\n\n```python\nfrom misp_stix_converter import misp_event_collection_to_stix1, misp_event_collection_to_stix2\n\ninput_filenames = [filename for filename in Path(_PATH_TO_YOUR_MISP_FILES_).glob('*.json')]\n\nstix1_response = misp_event_collection_to_stix1(\n    *input_filenames,\n    output_name=output_filename, # path to the file where the results are going to be written\n    return_format='xml', # STIX1 return format (XML or JSON)\n    version='1.1.1' # STIX1 version (1.1.1 or 1.2)\n)\n\nstix20_response = misp_event_collection_to_stix2(\n    *input_filenames,\n    version='2.0' # STIX 2 version\n)\n\nstix21_response = misp_event_collection_to_stix2_1(\n    *input_filenames,\n    version='2.1',\n    single_output=True, # For a single resulting file\n    output_name=output_file_name, # path to the file where the results are going to be written\n    in_memory=True # To keep results in memory before writing the full converted content at the end in the result file\n)\n```\nAgain, all the responses should have a `success` field equal to 1 and the resulting STIX1 Package and STIX 2.0 \u0026 2.1 Bundles are available in the specific output file names.\n\n### Samples and examples\n\nVarious examples are provided and used by the different tests scripts in the [tests](tests/) directory.\nThose example files are showing the results of MISP format exported in the various supported STIX formats.\n\n## MISP \u003c--\u003e STIX Mapping\n\nA specific documentation concerning the mapping between MISP and the various supported STIX versions is also provided in the [documentation](documentation/) directory.\nYou can find there all the different cases illustrated with examples.\n\n# License\n\nmisp-stix is released under a BSD 2-Clause \"Simplified\" License allow easy reuse with other libraries.\n\n~~~\nCopyright 2019-2025 Christian Studer\nCopyright 2019-2025 CIRCL - Computer Incident Response Center Luxembourg c/o \"security made in Lëtzebuerg\" (SMILE) g.i.e.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n~~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisp%2Fmisp-stix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmisp%2Fmisp-stix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisp%2Fmisp-stix/lists"}