Skip to content

misp-stix 2026.11.12 - Introducing the STIX 2.1 MISP Extension definitions

Latest

Choose a tag to compare

@chrisr3d chrisr3d released this 13 Nov 10:46
· 80 commits to main since this release
2fe47f7

Changelog - 2026.10.12 → 2026.11.12

This release moves the STIX 2.1 export off the custom objects and properties STIX 2.1 deprecates, onto extension definitions of MISP's own, the MISP Extensions, and teaches the import to read them. A STIX 2.1 bundle MISP writes no longer carries any x-misp-* object or x_misp_* property: the MISP attributes, objects and galaxy clusters no STIX object represents become misp-attribute, misp-object and misp-galaxy-cluster objects, the MISP values a standard object has no property for go into one property extension on that object, and the bundle carries the definitions it uses, with the MISP Project identity creating them. The first section states what moves where, for whoever reads MISP's STIX 2.1 output, imports STIX into MISP, or calls the library; the policy documentation, the JSON schemas and example bundles are in the repository. The import reads both syntaxes, so the bundles earlier releases wrote import as before, apart from the import fixes below; a reader on 2026.10.12 or earlier loses content from the new ones, so upgrade the readers. STIX 2.0 has no extension definitions and keeps its custom objects and properties; its output changes only where four fixes stop it losing content. Along the way, a sighting naming an organisation the bundle does not carry no longer costs the whole document on import, and the domain-ip values and the values read from an artifact take their to_ids from the pattern. Five fixes come from contributed pull requests: on export, an event galaxy, a 2.1 annotation or an event creator that fails no longer costs the whole document; on import, an AND inside a pattern value no longer splits it, and a hash MISP has no type for no longer costs its object. It requires pymisp 3.0, and so Python 3.11 or later: Python 3.10 is no longer supported, and 3.15 now is. Every change shipped with tests; the suite stands at 3,043 tests. No security advisory accompanies this release. The consumer-visible behaviour changes are collected in their own section near the end.

STIX 2.1 export: MISP Extensions replace the custom properties

STIX 2.1 deprecates custom objects and properties (section 11) in favour of extension definitions (section 7.3). The STIX 2.1 export now writes MISP's own content through four of them, with fixed ids, created by the MISP Project:

Extension Extension type Extension definition id
MISP Attribute Extension new-sdo, defining misp-attribute extension-definition--c1f2c0fa-3786-4f27-bf57-cf050ecfc104
MISP Object Extension new-sdo, defining misp-object extension-definition--a093107b-933f-4d72-a9a6-6d7318adadda
MISP Galaxy Cluster Extension new-sdo, defining misp-galaxy-cluster extension-definition--573a76d8-f8a0-4f53-bc93-f2777576b7b9
MISP Property Extension property-extension, on standard objects extension-definition--5ece67ea-2e8b-4ed0-bb69-26d69053ee0b

Each definition is at version 1.0.0, created 2026-11-12T00:00:00.000Z. The rules below are what a reader of MISP's 2.1 output needs to migrate. The policy documentation, the JSON schemas and examples (a directory to give stix2_validator --schemas) and the packaged definition objects give the detail; where the documentation and a schema disagree, the schema wins.

What moves where

  • A custom property on a standard object moves into the property extension. Where the export wrote x_misp_<name> on a STIX domain object, an Observable Object, an Indicator, a Note or an Opinion, it writes <name> in the object's extensions, under the property extension's id, next to any predefined extension (windows-pebinary-ext, socket-ext, …). A url object whose leftovers, the values its standard properties leave over, were x_misp_domain, x_misp_host, x_misp_ip and x_misp_port now reads:
"extensions": {
    "extension-definition--5ece67ea-2e8b-4ed0-bb69-26d69053ee0b": {
        "extension_type": "property-extension",
        "domain": "example.com",
        "host": "www.example.com",
        "misp_ip": "198.51.100.7",
        "port": "443"
    }
}
  • The names, and how to read them back. A name is the old one without its x_misp_ prefix: the object relation or galaxy meta key lowercased, every character outside a-z, 0-9 and _ turned into _. It is escaped where the STIX base schema cannot take it bare: a name shorter than three characters, not starting with a letter, or one the extension keeps for itself (extension_type, original_names, windows_pebinary_ext, sections, values) takes the prefix misp_ (ip gives misp_ip); a name ending in _hex or _bin, which the base schema types as hexadecimal or binary, takes a trailing _. To read a name back, drop the trailing _ after _hex or _bin, then the misp_ prefix when what is left would itself be escaped (misp_ip gives ip, misp_uuid stays). The object template named by the misp:name label spells an object relation back. For galaxy meta, x_misp_original_names becomes original_names in the extension: it maps each name the naming changed to the key as MISP spells it, and is written only when the naming changed one. Six MISP fields keep fixed names, with no escape: filename, url, malware_sample and attachment, which were x_misp_filename, x_misp_url, x_misp_malware_sample and x_misp_attachment, and on an Opinion, opinion and author_ref, which were x_misp_opinion and x_misp_author_ref. When two values of one object land on one name, the last one is kept, as before, now with a Warning.
  • The custom objects become the misp-* types. x-misp-attribute, x-misp-object and x-misp-galaxy-cluster become misp-attribute, misp-object and misp-galaxy-cluster, with the same uuid in their id (x-misp-object--<uuid> becomes misp-object--<uuid>) and the same labels. Each holds its definition in extensions, as {"extension_type": "new-sdo"}, and its properties lose their x_misp_ prefix:
Type Up to 2026.10.12 From 2026.11.12
misp-attribute x_misp_type attribute_type, since type is the STIX type
x_misp_value, x_misp_category, x_misp_comment value, category, comment
none to_ids, first_seen, last_seen, data
misp-object x_misp_name, x_misp_meta_category, x_misp_comment name, meta_category, comment
x_misp_attributes attributes: at least one, each item with MISP's own keys (type, object_relation, value, category, comment, to_ids, uuid, data), plus first_seen and last_seen
none first_seen, last_seen
misp-galaxy-cluster x_misp_name, x_misp_type, x_misp_value galaxy_name, galaxy_type, value
x_misp_description, holding <galaxy description> | <cluster description> galaxy_description, and description, the cluster's own
x_misp_meta, x_misp_original_names meta, original_names
  • What the misp-* types always carry. to_ids is written every time, true or false, on a misp-attribute and in every item of attributes; first_seen and last_seen whenever MISP has them; data, in base64, whenever the attribute carries a payload. new-sdo makes created and modified required, so a misp-galaxy-cluster takes the export time when neither it nor the record it sits on has a timestamp. A misp-object needs one attribute at least: an object pymisp leaves with none, every attribute having failed its validation, is no longer exported, with an Error, where the empty x-misp-object it used to be failed on import.
  • Nested Rooms hold the values of MISP objects nested in STIX structures. The values a pe object, its pe-section objects and the registry-key-value objects leave over went out as x_misp_* properties inside windows-pebinary-ext, inside each section and inside each registry value, where STIX 2.1 gives a custom key no place. They move into rooms of the property extension of the file or windows-registry-key holding them: windows_pebinary_ext for the pe, windows_pebinary_ext.sections for its sections, values for the registry values. A room standing for a STIX list is a dictionary keyed by the zero-based position of the STIX item, in decimal, holding only the items with values; a room with nothing in it is left out. A registry value holding only MISP values keeps its STIX item as {}, so that its position holds. The values of the registry-key object itself stay at the top level of the extension.
"extensions": {
    "windows-pebinary-ext": {"pe_type": "exe", "sections": [{"name": ".rsrc"}, {"name": ".text"}]},
    "extension-definition--5ece67ea-2e8b-4ed0-bb69-26d69053ee0b": {
        "extension_type": "property-extension",
        "entropy": "1.234",
        "windows_pebinary_ext": {
            "lang_id": "080904B0",
            "sections": {"1": {"text": "Code section"}}
        }
    }
}
  • Patterns compare the values where the observable now holds them. A 2.1 Indicator compares a MISP value through the property extension's path: url:x_misp_domain = 'circl.lu' becomes url:extensions.'extension-definition--5ece67ea-2e8b-4ed0-bb69-26d69053ee0b'.domain = 'circl.lu'. A reference step goes in front for the artifact and the parent process (file:content_ref.extensions.'…'.filename, and process:parent_ref.extensions.'…'.<name> with parent- removed from the relation), and the room path for a pe, a section or a registry value (file:extensions.'…'.windows_pebinary_ext.sections.'1'.text, windows-registry-key:extensions.'…'.values.'0'.<name>). The fixed literals move too: a domain-ip's domain-name:x_misp_hostname is domain-name:extensions.'…'.hostname. A registry value's leftovers, compared at the top level of the key, are compared in its room, where the observable holds them. A value the observable holds in a list is compared through [*], since a bare path to a list never matches; a value with data is compared on its .data, then on its .value, which under [*] may match two different items. The pattern stays the only carrier of a leftover's to_ids, and such a comparison matches only Observed Data carrying the extension.
  • One value is a scalar, two or more a list. Each MISP value in the property extension, and each key of a misp-galaxy-cluster's meta, holds its value itself when there is one and a list when there are more, as object relations already did. Galaxy meta changes shape: MISP holds every meta value as a list, and a key holding one value now goes out as a string ("50", not ["50"]), while a key holding no value is left out. An item is a string, a boolean, or {"value": …, "data": …} for a value with a payload. Standard STIX properties keep the shape STIX gives them: aliases stays a list of one.
  • The bundle carries the MISP Project identity and the definitions it uses. A 2.1 bundle using a MISP Extension holds its definition and the identity creating it, identity--55f6ea65-aa10-4c5a-bf01-4f84950d210f ("name": "MISP"), each once whatever the number of events. In an event they go with the identities, ahead of the Report or Grouping, most often as [organisation identity, MISP Project identity, definitions…, report, objects…]; the identity of a sighting's organisation may come between them and the Report. So objects[1] is no longer the Report, and fetch_stix_objects and stix_objects hold them in front of it. A definition first used by a later event goes ahead of that event's Report. In an attribute or object collection, which has no Report, they go ahead of the first object using them. The Report's object_refs does not list them. A bundle with no MISP Extension content holds neither, and an event whose organisation uuid is the MISP Project's keeps its own identity. A consumer should rely neither on this order nor on the definitions being there: the ids are fixed.
  • The labels and the STIX 2.0 output do not change. misp:type=…, misp:category=…, misp:name=…, misp:tool=… and the other labels are a standard property and stay as they are, so a bundle is recognised as MISP's as before. STIX 2.0 has no extension definitions: its export keeps the x-misp-* objects and the x_misp_* properties, and changes only where four fixes stop it losing content (see the STIX 2 export section).

Importing

  • The import reads both syntaxes. The Internal import reads the MISP Extensions and keeps reading the custom objects and properties, object by object, both on one object included, where the extension's value wins with a Warning. STIX 2.1 bundles written up to 2026.10.12 import into the same MISP content as before, apart from the fixes of the STIX 2 import section. A galaxy meta key holding one value comes back in pymisp's meta as the value itself from a new bundle, and as a list of one from an older one: MISP stores both as the same meta element. The extension is recognised by its id alone, so a bundle without the definitions, or with another definition version, reads the same. An Indicator with no Observed Data next to it reads its extension paths too, rooms included, so a bundle cut down to its Indicators imports whole. Malformed MISP Extension content costs its object, with the usual Error, and a message about an extension value names it by its path in the bundle.
  • Identities that only create definitions. An identity named only as the creator of extension definitions, as the MISP Project identity is, converts to nothing: in a collection, the Internal import reported it as an undefined object, and the External import made an organization object of it.
  • The External import ignores the property extension, as it ignores x_misp_* properties, and gives a misp-* object the "Unable to load" Error an x-misp-* object gets.
  • A reader on 2026.10.12 or earlier loses content from the new bundles: upgrade the readers, a MISP instance importing the 2.1 files an upgraded instance exports included. Such a reader loses, each with an Error, every misp-* object (Unable to load STIX object type: misp-*, then Unknown STIX object type: misp-*), every analyst Opinion, whose MISP opinion it looks for in x_misp_opinion, every Observed Data holding an artifact with a file name (the malware sample of a file or lnk object, an image), and every Indicator with no Observed Data comparing an extension path. It drops silently the MISP values in a property extension, on any standard object and galaxy meta included, so that a url object of five attributes comes back with one, and the organisation of a false-positive sighting.
  • Parsing with stix2. A bundle whose MISP content sits only in property extensions now parses with stix2.parse and its default allow_custom=False, which refused the x_misp_* properties. A bundle holding a misp-* object still needs allow_custom=True, as the x-misp-* objects did: stix2 knows no misp-* type until something registers it, as importing misp_stix_converter does, and refuses a Report or Grouping naming one in its object_refs.

What the 2.1 output now carries that the custom objects and properties lost

  • to_ids false on a custom attribute and in a custom object's attributes, which came back as the attribute type's default.
  • first_seen and last_seen of custom attributes, custom objects and their attributes, which the custom objects dropped.
  • A custom galaxy cluster's own description, apart from its galaxy's: x_misp_description joined the two, and the import gave them back as the cluster's.
  • The payload of a malware-sample whose MD5 is not valid, which falls back to a misp-attribute with its data.
  • The galaxy meta first_seen and last_seen on attack-pattern, location, tool and vulnerability, which have no such properties: they went out as unprefixed top-level properties, which failed the whole document when the cluster had no other leftover meta, and were dropped on import otherwise.
  • A galaxy meta key folding onto a name the extension keeps for itself, such as Original Names, which was dropped with a Warning: it is escaped and kept.
  • A pe whose only leftovers are a section's, which fell back to custom objects with an Error, since stix2 refuses a custom section in a PE extension that is not custom.
  • On a file with a malware sample, an attachment with no data, which carried its attribute uuid as its data.

Commits

STIX 2 export

  • A network socket lost to an out-of-enum value, in both versions. A network-socket carrying a socket-ext field, whose only value with no STIX property was an out-of-enum socket-type or domain-family, went out whole as a custom object, with an Error: the socket-ext write set no allow_custom. It exports as network-traffic, the value kept as a MISP value.

  • STIX 2.0 galaxy first_seen and last_seen. A galaxy cluster becoming an attack-pattern, malware, threat-actor, tool or vulnerability, none of which has these properties in STIX 2.0, carries them as x_misp_first_seen and x_misp_last_seen, like any other meta the type has no property for. They went out as unprefixed top-level properties: the whole document failed with ExtraPropertiesError when nothing else on the cluster turned custom properties on, and the import dropped them otherwise. Campaign and intrusion-set keep their own properties.

  • 2.1 rule objects. On the crs-rule, nova-rule, sigma, suricata, wazuh-rule and yara objects, two relations folding to one name keep the last value, with the Warning, as on every other object, where both values were merged into a list.

  • An event galaxy that failed lost the whole document, in both versions (#121). Event galaxies were the only galaxies with no catch of their own, so a region cluster with no description, and in 2.1 one valued without its - code, raised out of the export. A galaxy that fails is now lost alone, with an Error, and its tag goes out as a label of the Report or Grouping. A 2.1 region cluster valued without its code, such as Antarctica, exports as a Location named after the value.

  • A 2.1 annotation without text lost the whole document (#122). An annotation referencing an object but holding no text built a Note without its required content, and the export raised MissingPropertiesError. It goes out as a misp-object, as an annotation with no reference does, and an annotation failing for any other reason falls back to the misp-object with an Error, as the file, pe and registry objects do.

  • An event creator missing its uuid lost the whole document, in both versions (#118). Reporting an Orgc with no uuid or no name raised a TypeError out of the export. It is reported with an Error, Error with the Orgc field missing its uuid value., and the event exports without its creator identity.

  • 5cf9bbb - network sockets, rule objects

  • 09d647f, f3b580d - STIX 2.0 galaxy seen dates

  • caa0fb3, 10e0945, 090f1c8 - event galaxies that fail, region clusters without their code

  • 6570e9a, 58785b6, fb390ad, 2d125ff - annotations without text or failing

  • 69dcd33, 20812ba, 2f063fc - an event creator missing its uuid

STIX 2 import

  • A sighting naming an organisation the bundle lacks lost the whole document. The Internal import parses sightings after every object, where no per-object catch runs, so in both versions a Sighting whose where_sighted_refs named no identity the bundle carries, a Sighting with no where_sighted_refs at all, which is what the export writes for a MISP sighting with no organisation, and a false-positive Opinion whose author reference named an absent identity each raised out of the conversion. Such a Sighting is now dropped with an Error naming it and the identity, and one with no where_sighted_refs is imported with no organisation. The Opinion keeps the reference's uuid as its organisation, with its own author name and a Warning; with no author name, or a reference that is no identity id, it is dropped with an Error. The 2.0 x-misp-opinion is parsed with the sightings, under the same rules: it takes the name of an identity the bundle carries, and an Opinion of a MISP object finds the object under the uuid the import gives it. The External import skips such a Sighting silently, as before, and no longer fails on a Sighting in a bundle carrying no identity at all.

  • to_ids from the pattern. The values of a domain-ip object and the values read from an artifact (the malware sample of a file or lnk object, an image's url) took their attribute type's default, whatever the pattern compared. They take their to_ids from the Indicator's pattern, as the other observable values do, in both versions. The flagged domain and hostname of a domain-ip holding leftovers, a file's malware sample and an image's url carry the Indicator's id in their comment and a uuid derived from it, as other flagged values do.

  • A merged record's timestamps. The check that a Merged Indicator loses no value compared a datetime in its pattern, as str spells it, with the STIX timestamp its Observed Data carries, and warned that a value both held was lost: a vulnerability's created or published, a person's passport-creation, a first-seen. It also reads the pattern value as the timestamp it names now.

  • An AND inside a pattern value, in both versions (#132). The Internal import split a MISP Indicator's pattern on every AND, those inside a quoted value included: an object holding a file name such as evil AND you.exe was lost with an Error, and a filename|md5 attribute took wrong values with no message at all. The pattern is now split outside quoted values only, in every pattern reader.

  • A hash MISP has no type for lost its object, in both versions (reported in #133). A hash whose name MISP does not map, such as a CRC32 next to an MD5, cost the whole object holding it, with an Error, in the External and Internal imports, and in a PE section of a MISP bundle the hash itself. Such a name is valid STIX: the value is kept as a text attribute whose relation is the name lowercased (crc32), with a Warning.

  • e076469, 3ece97d - sightings and Opinions naming an absent identity

  • b9b5e7d, 9de3df2 - to_ids of domain-ip and artifact values

  • 9cab8c0 - merged record timestamps

  • 0977603, a50076e, a7ff86a, 624ffe0, 5b6f0cc, 993f1a1 - an AND inside a pattern value

  • 5acd4a5, 82f5eb2 - hashes MISP has no type for

Dependencies

  • pymisp ^3.0.0, was ^2.5.34.1. pymisp 3.0 needs Python 3.11 or later.

  • Python >=3.11,<3.16, was ^3.10: Python 3.10 is no longer supported, Python 3.15 is, and the CI runs the suite on every version from 3.11 to 3.15.

  • The package metadata moves to the standard [project] table: the license is declared as the SPDX expression BSD-3-Clause, and the Python classifiers follow the supported range. Building from source needs poetry-core 2.0 or later.

  • pycountry ^26.2.16, was ^24.6.1.

  • For development: jsonschema ^4.26.0 and flake8 ^7.4.1, and a third submodule, data/cti-stix2-json-schemas, holding the STIX JSON schemas the MISP Extension schemas build on, which the schema tests need offline: run git submodule update --init data/cti-stix2-json-schemas once. The wheel ships the packaged definition objects, and neither this submodule nor the schemas under data/.

  • 42374e3, b25255c - pymisp, the Python range, the package metadata, the lock file

  • 9bf7875 - pycountry, flake8

  • 36fee10 - jsonschema, the schema submodule

Documentation

  • The policy documentation of the MISP Extensions, in the style of the STIX specification, sits next to their schemas, with eight example bundles frozen from the 2.1 export of test events, which the test suite validates against the schemas.

  • The mapping documentation's 2.1 export sections describe the MISP Extensions, its import sections say the bundles written up to 2026.10.12 still import, and the README names the MISP Extensions the import recognises. The tests now generate the 2.1 custom attribute and object mappings, and the regenerated documentation also shows the mapping changes earlier commits made without a rebuild, in the 2.0 files too.

  • 9a76ab4, 9645066, c9e387f - policy documentation and examples

  • 044e07c, 69a027c, e1976f0 - mapping documentation and README

Behaviour changes to check before upgrading

  • STIX 2.1 output writes MISP Extensions instead of x-misp-* objects and x_misp_* properties, and a bundle using them holds the MISP Project identity and the definitions ahead of its Report; a reader on 2026.10.12 or earlier loses content from it. "STIX 2.1 export: MISP Extensions replace the custom properties" states the migration rules (325c257, aed9253, 212056b, 57ca35d).
  • STIX 2.0 galaxy clusters may carry x_misp_first_seen and x_misp_last_seen on attack-pattern, malware, threat-actor, tool and vulnerability, where unprefixed properties failed the document or were dropped on import (09d647f).
  • STIX 2 network sockets: one carrying an out-of-enum socket-type or domain-family next to a socket-ext field exports as network-traffic in both versions, where it fell back to a custom object with an Error (5cf9bbb).
  • STIX 2.1 export messages: a Warning when two values of one object land on one property name, naming the pe, section or registry value it happens in, the last value being kept, on the 2.1 rule objects too, where both were merged; an Error for an object pymisp leaves with no attribute, which is not exported; the non-canonical number Warning says the value went into the MISP property extension (325c257, e3d5e34, ded9fa8, 5cf9bbb, aed9253).
  • STIX 2 import of sightings: a Sighting naming no identity the bundle carries is dropped with an Error, and a false-positive Opinion naming an absent one is kept with a Warning or dropped with an Error, where the whole document was lost (e076469).
  • STIX 2 import to_ids: the domain-ip values and the values read from an artifact take their to_ids from the pattern, where they took their type's default; imported again, the flagged domain and hostname of a domain-ip with leftovers, a file's malware sample and an image's url carry the Indicator's id in their comment, and take other uuids than 2026.10.12 gave them (b9b5e7d).
  • STIX 2 export of what failed and stopped it: an event galaxy that fails is lost alone, with an Error, its tag going out as a label; a 2.1 annotation without text goes out as a misp-object; a 2.1 region cluster valued without its code exports as a Location; an event creator missing its uuid is reported with an Error. Each of them lost the whole document (caa0fb3, 10e0945, 6570e9a, 58785b6, 69dcd33).
  • STIX 2 import of pattern values and hashes: an AND inside a pattern value stays in the value, where its object was lost or its attribute took wrong values; a hash MISP has no type for comes in as a text attribute named after it, with a Warning, where its object was lost with an Error (5b6f0cc, 5acd4a5).
  • Python 3.11 or later and pymisp 3.0 are required: Python 3.10 is no longer supported (42374e3).
  • pycountry 26 is required (9bf7875).

Contributors

Full Changelog: 2026.10.12...2026.11.12