Metadata-Version: 2.4
Name: misp-stix
Version: 2026.9.16
Summary: Python scripts used by MISP to export MISP format into STIX and to import STIX into MISP format.
License: BSD-3-Clause
License-File: LICENSE
Author: Christian Studer
Author-email: christian.studer@circl.lu
Maintainer: Christian Studer
Maintainer-email: christian.studer@circl.lu
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Dist: cybox (>=2.1.0.21,<3.0.0.0)
Requires-Dist: maec (>=4.1.0.17,<5.0.0.0)
Requires-Dist: mixbox (>=1.0.5,<2.0.0)
Requires-Dist: pycountry (>=24.6.1,<25.0.0)
Requires-Dist: pymisp (>=2.5.34.1,<3.0.0.0)
Requires-Dist: setuptools (>=83)
Requires-Dist: stix (>=1.2.0.11,<2.0.0.0)
Requires-Dist: stix-edh (==1.0.3)
Requires-Dist: stix2 (>=3.0.2,<4.0.0)
Project-URL: Bug Tracker, https://github.com/MISP/misp-stix/issues
Project-URL: Documentation, https://misp.github.io/misp-stix/
Project-URL: Repository, https://github.com/MISP/misp-stix
Project-URL: Source, https://github.com/MISP/misp-stix
Description-Content-Type: text/markdown

# MISP-STIX - Python library to handle the conversion between MISP standard and STIX

<img src="https://raw.githubusercontent.com/MISP/misp-stix/main/documentation/logos/misp-stix.png" width="125" height="125">

[![Python version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![MISP-STIX version](https://badge.fury.io/gh/MISP%2Fmisp-stix.svg)](https://badge.fury.io/gh/MISP%2Fmisp-stix)
[![Github Actions](https://github.com/MISP/misp-stix/workflows/misp-stix/badge.svg)](https://github.com/MISP/misp-stix/actions?query=workflow%3Amisp-stix)
[![License](https://img.shields.io/github/license/MISP/misp-stix.svg)](#License)

MISP-STIX-converter is a Python library (>=3.10) to handle all the conversions between the [MISP standard format](https://www.misp-standard.org/) and STIX formats.

The package is available as [misp-stix](https://pypi.org/project/misp-stix/) in PyPI.

## Features

- **Bidirectional conversion** — Full support for MISP to STIX 1.x (1.1.1 and 1.2), STIX 2.x (2.0 and 2.1), and back to MISP standard format.
- **Indicator-Observable fingerprinting** — Matches STIX Indicators with their corresponding Observable objects using content fingerprinting, preserving the `to_ids` flag accurately during round-trip conversions.
- **Dual export for detection-ready attributes** — Attributes with `to_ids=True` produce both an Indicator (with a STIX pattern) and an Observed Data object, linked by a Relationship, so downstream tools can use whichever representation they support.
- **Broad object type coverage** — [MISP Objects](https://github.com/MISP/misp-objects) and [MISP Galaxies](https://github.com/misp/misp-galaxy) are mapped to [semantically similar STIX objects](https://github.com/MISP/misp-stix/tree/main/documentation), including artifact, malware, malware-analysis, http-request, network traffic, and more.
- **ACS Marking support** — Round-trip conversion of ACS (Access Control System) marking definitions between STIX 2.1 Marking Definitions and MISP Galaxy Clusters.
- **Comprehensive pattern parsing** — Parses STIX 2.x indicator patterns covering x509 certificates, processes, Windows registry keys, email messages, domain-IP pairs, AS numbers, network traffic, PE extensions, and other object types.
- **Internal vs External import** — Higher fidelity reconstruction for MISP-generated STIX content (recognises `x-misp-*` custom objects), with heuristic matching for third-party STIX data.
- **Extendable mapping library** — Provides a modular mapping architecture to facilitate extension and customisation.

This 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).

A complete [documentation is available](./documentation/) including the mappings between the different formats.

## Install from pip

**It is strongly recommended to use a virtual environment**

If you want to know more about virtual environments, [python has you covered](https://docs.python.org/3/tutorial/venv.html)

From the current repository:
```
pip3 install misp-stix
```

Package details at PyPI: [misp-stix](https://pypi.org/project/misp-stix/)

## Install the latest version from the repository for development purposes

**Note**: poetry is strongly recommended; e.g., `pip3 install poetry`

```
git clone https://github.com/MISP/misp-stix.git && cd misp-stix
git submodule update --init
poetry install
```

If 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 >= 1.2

Alternatively, you can set up a virtual environment with the following:

```
virtualenv -p python3 venv
source ./venv/bin/activate
pip install -U pip
# Manual install of setuptools to avoid some dependencies issues
pip install setuptools
pip install .
```

### Running the tests

Tests for MISP format export as STIX 1.1.1 & 1.2:
```bash
poetry run pytest tests/test_stix1_export.py
```

Tests for MISP format export as STIX 2.0:
```bash
poetry run pytest tests/test_stix20_export.py
```

Tests for MISP format export as STIX 2.1:
```bash
poetry run pytest tests/test_stix21_export.py
```

## Usage

### Command-line Usage

If 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:

```bash
# If you chose to use the recommended option
poetry shell

# OR

# Another option that should work if you followed the example mentioned above with the install instructions
./venv/bin/activate
```

At this point, you should be able to use the command-line feature. Here are a few examples:

```bash
# Convert an Events collections to STIX 2.1
misp_stix_converter export --version 2.1 -f tests/test_events_collection_1.json

# Convert a MISP Event and set a specific name for the STIX 2.1 output file
misp_stix_converter export --version 2.1 -f tests/test_event.misp.json -o tests/test_event.stix21.json

# Convert a STIX 2 Bundle to MISP, and set specific distributions
misp_stix_converter import -f tmp/test_bundle.stix21.json -o tmp/test_bundle.misp.json -d 1 -cd 1
# This will set the distribution for the Event, Attributes and Galaxy Clusters to `this community`

# Convert multiple STIX 2 Bundles to MISP and directly push the results to MISP, knowing your authentication key
misp_stix_converter import -f tmp/*.stix21.json --url https://localhost --api_key _YOUR_AUTHENTICATION_KEY_
# This will create a MISP Event for each file
```

#### Parameters

For more details on the different options presented with the examples, here is the complete description.

```bash
usage: misp_stix_converter [-h] [--debug] {export,import} ...

Convert MISP <-> STIX

options:
  -h, --help       show this help message and exit
  --debug          Show the full lists of errors and warnings - both are reported either way, this only lifts the cap on how many are shown

Main feature:
  {export,import}
    export         Export MISP to STIX - try `misp_stix_converter export -h` for more help.
    import         Import STIX to MISP - try `misp_stix_converter import -h` for more help.
```

##### Export parameters

```bash
usage: 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] [--overwrite] [--level {attribute,event}] [--format {json,xml}]
                                  [-n NAMESPACE] [-org ORG]

options:
  -h, --help            show this help message and exit
  -f, --file FILE [FILE ...]
                        Path to the file(s) to convert.
  -v, --version {1.1.1,1.2,2.0,2.1}
                        STIX specific version.
  -s, --single-output   Produce only one result file (in case of multiple input file).
  -m, --in-memory       Store result in memory (in case of multiple result files) instead of storing it in tmp files.
  --output-dir OUTPUT_DIR
                        Output directory - default is the directory the input files come from. Created if it does not exist.
  -o, --output-name OUTPUT_NAME
                        Output file name - used in the case of a single input file or when the `single_output` argument is used.
  --overwrite           Replace an output file that already exists - without it a conversion writing onto an existing file fails and leaves it as it is.

STIX 1 specific arguments:
  --level {attribute,event}
                        MISP data structure level.
  --format {json,xml}   STIX 1 format.
  -n, --namespace NAMESPACE
                        Namespace to be used in the STIX 1 header - must be a URI.
  -org ORG              Organisation name to be used in the STIX 1 header.
```

##### Import parameters

```bash
usage: misp_stix_converter import [-h] -f FILE [FILE ...] [-v {1,2}] [-s] [-o OUTPUT_NAME] [--output-dir OUTPUT_DIR] [--overwrite] [--max-input-size MB] [-d {0,1,2,3,4}] [-sg SHARING_GROUP] [--galaxies-as-tags]
                                  [--no-force-galaxy-cluster]
                                  [--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]

options:
  -h, --help            show this help message and exit
  -f, --file FILE [FILE ...]
                        Path to the file(s) to convert.
  -v, --version {1,2}   STIX major version - default is 2
  -s, --single-event    Produce only one MISP event per STIX file, in case of multiple Report or Grouping objects. STIX 1 always produces one, whether this is set or not.
  -o, --output-name OUTPUT_NAME
                        Output file name - used in the case of a single input file or when the `single_event` argument is used.
  --output-dir OUTPUT_DIR
                        Output directory - default is the directory the input files come from. Created if it does not exist.
  --overwrite           Replace an output file that already exists - without it a conversion writing onto an existing file fails and leaves it as it is.
  --max-input-size MB   Maximum accepted input size, in MB - a document larger than this is refused before it is parsed (default is 100). Use 0 to turn the limit off: conversion costs 2 to 7 times the
                        input size in memory, and a few seconds of CPU per MB of STIX 2.
  -d, --distribution {0,1,2,3,4}
                        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
  -sg, --sharing-group SHARING_GROUP
                        Sharing group ID when distribution is 4.
  --galaxies-as-tags    Import MISP Galaxies as tag names instead of the standard Galaxy format.
  --no-force-galaxy-cluster
                        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.
  --org-uuid ORG_UUID   Organisation UUID to use when creating custom Galaxy clusters.
  -cd, --cluster-distribution {0,1,2,3,4}
                        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:
                        Sharing Group
  -csg, --cluster-sharing-group CLUSTER_SHARING_GROUP
                        Galaxy Clusters sharing group ID in case of External STIX 2 content.
  -t, --title TITLE     Title used to set the MISP Event `info` field.
  -p, --producer PRODUCER
                        Producer of the imported content - Please make sure you use a name from the list of existing producer Galaxy Clusters.
  -c, --config CONFIG   Config file containing the URL and the authentication key to connect to your MISP.
  -u, --url URL         URL to connect to your MISP instance.
  -a, --api-key API_KEY
                        Authentication key to connect to your MISP instance.
  --skip-ssl            Skip SSL certificate checking when connecting to your MISP instance.
```

#### Conversion cost and input limits

An import parses the document it is given in full before it converts it, so the
cost of a conversion is decided by the size of the input:

- **Memory**: 2 to 7 times the input size, on top of whatever the caller already
  holds - the whole document is materialised, and nothing streams.
- **CPU**: a few seconds of a single core per MB of STIX 2 (measured between
  1.9 and 6.5 s/MB on indicator-heavy bundles, growing linearly with the number
  of objects). A 100 MB TAXII poll is therefore several CPU-minutes of work,
  produced by whoever uploads it for the price of the upload.

Both STIX loaders refuse a document above a maximum input size **before parsing
it**, so an oversized document costs a `stat()` rather than a full parse. The
default is **100 MB**, and the caller raises it - or turns it off with `0` - per
conversion:

```python
from misp_stix_converter import stix_2_to_misp

# a 250 MB bundle this caller knows it wants
stix_2_to_misp('bundle.json', max_size=250 * 1024 * 1024)
# no limit at all
stix_2_to_misp('bundle.json', max_size=0)
```

`max_size` is accepted by `stix_1_to_misp`, `stix1_to_misp_instance`,
`stix_2_to_misp`, `stix2_to_misp_instance`, by the parsers'
`parse_stix_content()` and by the loading helpers themselves
(`load_stix1_package`, `load_stix2_file`, and `load_stix2_content` for the
serialised content it is given as a string or a `BytesIO` - a `dict` or `list`
the caller already built is past the point a limit could save anything); the
command line names the same limit in MB with `--max-input-size`. A document
above the limit is reported as an error, and raises `STIXInputSizeError` (a
`STIXLoadingError`) for the callers that use the library directly.

The limit bounds one conversion, not the load a host accepts: since the cost is
linear in the input size and paid entirely in one worker, an integrator running
imports concurrently - MISP core included - should also cap how many run at
once.

#### Object template names

A MISP object names the template that describes it, and that name is resolved against the
template directories on disk. A name a document supplied that is not a plain template name -
one holding a path separator, a `..`, or any character a template directory does not use - is
never resolved: the object is converted under the name **`unknown-template`**, keeping the
name the document sent in the object's `comment`. This applies on import, to an
`x-misp-object`'s `x_misp_name`, and on export to the events and objects handed in as JSON,
where a name stored earlier would otherwise be resolved when the event is exported. Names
that do resolve - the templates pymisp ships and custom ones alike - are unaffected.

### In Python scripts

#### Public surface

Two modules are supported places to import from: the package itself, and
`misp_stix_converter.tools`. Each declares what it holds in an `__all__`, and
everything below them - `misp2stix`, `stix2misp`, the per-converter modules -
is internal: reachable, but free to move from one release to the next.

The package holds the conversion functions, the parser and mapping classes of
both directions, the exceptions they raise, `__version__`, and the `main` the
`misp_stix_converter` command runs:

```python
from misp_stix_converter import misp_to_stix1, misp_to_stix2, misp_collection_to_stix2
from misp_stix_converter import stix_1_to_misp, stix_2_to_misp
from misp_stix_converter import MISPtoSTIX1EventsParser, MISPtoSTIX20Parser, MISPtoSTIX21Parser
from misp_stix_converter import ExternalSTIX1toMISPParser, InternalSTIX1toMISPParser
from misp_stix_converter import ExternalSTIX2toMISPParser, InternalSTIX2toMISPParser
from misp_stix_converter import MISPtoSTIX21Mapping, InternalSTIX2toMISPMapping
from misp_stix_converter import InvalidMISPInputError, MissingSTIXContentError
from misp_stix_converter import STIXInputSizeError, STIXLoadingError
```

`misp_stix_converter.tools` holds the steps a caller drives itself rather than
through a conversion function - loading a document, deciding whether it came
from MISP, and writing a STIX 1 Package by parts (the `write_*` helpers, one
per collection type, with their headers and footers):

```python
from misp_stix_converter.tools import load_stix1_package, load_stix2_content, load_stix2_file
from misp_stix_converter.tools import is_stix1_from_misp, is_stix2_from_misp
from misp_stix_converter.tools import stix1_framing, stix1_attributes_framing
from misp_stix_converter.tools import stix20_framing, stix21_framing
```

Given 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:

- Convert a MISP Event in STIX1:

```python
from misp_stix_converter import MISPtoSTIX1EventsParser

parser = MISPtoSTIX1EventsParser(
    'MISP-Project', # Example of Org name
    '1.1.1' # STIX1 version (1.1.1 or 1.2)
)
parser.parse_misp_event(event)

stix_package = parser.stix_package
```

- Convert a MISP Event in STIX1 using directly its file name:

```python
from misp_stix_converter import misp_to_stix1

response = misp_to_stix1(
    filename, # file name of the file containing a MISP Event
    'xml', # return format (XML or JSON)
    '1.1.1' # STIX1 version (1.1.1 or 1.2)
)
# if everything went well, response is a dictionary where `success` = 1
```
The resulting STIX1 Package is then available in a `filename.out` file

**STIX 1 export is not thread-safe.** The identifier namespace an exported STIX 1
Package uses lives in a module-level generator inside `mixbox`, so it is process-wide.
`misp_to_stix1`, `misp_event_collection_to_stix1` and `misp_attribute_collection_to_stix1`
set it for the duration of one conversion and put back whatever they found, which keeps
sequential and nested exports apart — but two exports running at the same time in one
process share that one generator and can attribute identifiers to each other's
organisation. Convert in one thread, or in separate processes.

Driving a parser yourself (the `MISPtoSTIX1EventsParser` example above) or calling the
`stix1_framing` / `stix1_attributes_framing` helpers directly gets no such window: the
framing helpers set the namespace and leave it set, and a parser used on its own never
sets it at all. Wrap those calls yourself if the same process exports for more than one
organisation.

- Convert a MISP Event in STIX2:

```python
# for STIX 2.0
from misp_stix_converter import MISPtoSTIX20Parser
# for STIX 2.1
from misp_stix_converter import MISPtoSTIX21Parser

parser20 = MISPtoSTIX20Parser()
parser20.parse_misp_event(event)

parser21 = MISPtoSTIX21Parser()
parser21.parse_misp_event(event)

# To get the list of parsed STIX objects
stix_20_objects = parser20.stix_objects
stix_21_objects = parser21.stix_objects

# To get the list of parser STIX objects within a STIX 2.0 or 2.1 Bundle
bundle20 = parser20.bundle
bundle21 = parser21.bundle
```

- Convert a MISP Event in STIX2 using directly its file name:

```python
from misp_stix_converter import misp_to_stix2

response_20 = misp_to_stix2(filename, version='2.0')
response_21 = misp_to_stix2(filename, version='2.1')
# Again response_20 & response_21 have a `success` field equal to 1 if everything went well
```
The resulting STIX2 Bundle is the available in a `filename.out` file, or you can define the output name with the `output_name` argument.

If you get some MISP collection of data, it is also possible to convert it straight into some STIX format:

```python
from misp_stix_converter import MISPtoSTIX1EventsParser, MISPtoSTIX20Parser, MISPtoSTIX21Parser

filename = _PATH_TO_YOUR_FILE_CONTAINING_MISP_FORMAT_

parser1 = MISPtoSTIX1EventsParser('MISP', '1.1.1')
parser1.parse_json_content(filename)
stix_package = parser1.stix_package

parser20 = MISPtoSTIX20Parser()
parser20.parse_json_content(filename)
stix_20_objects = parser20.stix_objects
bundle20 = parser20.bundle

parser21 = MISPtoSTIX21Parser()
parser21.parse_json_content(filename)
stix_21_objects = parser21.stix_objects
bundle21 = parser21.bundle
```

But in order to parse multiple data collections, you can also use the following helpers:

```python
from misp_stix_converter import misp_event_collection_to_stix1, misp_collection_to_stix2

input_filenames = [filename for filename in Path(_PATH_TO_YOUR_MISP_FILES_).glob('*.json')]

stix1_response = misp_event_collection_to_stix1(
    *input_filenames,
    output_name=output_filename, # path to the file where the results are going to be written
    return_format='xml', # STIX1 return format (XML or JSON)
    version='1.1.1' # STIX1 version (1.1.1 or 1.2)
)

stix20_response = misp_collection_to_stix2(
    *input_filenames,
    version='2.0' # STIX 2 version
)

stix21_response = misp_collection_to_stix2(
    *input_filenames,
    version='2.1',
    single_output=True, # For a single resulting file
    output_name=output_file_name, # path to the file where the results are going to be written
    in_memory=True # To keep results in memory before writing the full converted content at the end in the result file
)
```
Again, all the responses should have a `success` field equal to 1 and the resulting STIX1 Package and STIX 2.0 & 2.1 Bundles are available in the specific output file names.

Note that `success` = 1 only tells you the conversion wrote its output: a conversion that dropped part of the content says so as well. Any response - from the conversion functions in both directions - may therefore carry an `errors` field, and a `warnings` one, next to `success`, both keyed by the event or bundle identifier the messages belong to. The `debug` argument controls how detailed both fields are, never whether they are reported: by default each distinct message appears once - errors with the number of times each happened - capped at ten messages per identifier with a trailing entry naming how many were left out, and `debug=True` returns the full lists instead. When driving the parser classes in memory rather than through these functions, `parser.diagnostics()` returns the same default summary as a dict, plus a `counts` entry giving the number of distinct warnings and of error occurrences taken before the cap. The two warnings about the import classification - the Internal parser chosen from the document content, or a detection result the `classification` parameter overruled - are recorded through `parser.record_classification(detected, overridden=...)`, which the conversion functions call once the document is loaded; an in-memory consumer running the detection itself (`is_stix2_from_misp`, `is_stix1_from_misp`) calls it the same way to get them.

### Samples and examples

Various examples are provided and used by the different tests scripts in the [tests](tests/) directory.
Those example files are showing the results of MISP format exported in the various supported STIX formats.

## MISP <--> STIX Mapping

A specific documentation concerning the mapping between MISP and the various supported STIX versions is also provided in the [documentation](documentation/) directory.
You can find there all the different cases illustrated with examples.

# License

misp-stix is released under a BSD 2-Clause "Simplified" License allow easy reuse with other libraries.

~~~
Copyright 2019-2026 Christian Studer
Copyright 2019-2026 CIRCL - Computer Incident Response Center Luxembourg c/o LHC g.i.e.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. 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.

THIS 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.
~~~

