MISP connector

Summary

sharing::misp::1.0 publishes one Tide object as one MISP Event. Each MISP instance is one [[misp]] block in sharing.toml. The Event carries exactly one instance of the upstream opentide MISP object, and its opentide-object attribute holds the source document verbatim. Exposure is the block's max_tlp ceiling and the MISP distribution that the object's metadata.tlp permits. The connector does not filter fields out of the document.

This first revision keeps the block small: where to connect, what to select, and how high TLP may go. Distribution width, sharing groups, file export, and Event title decoration are not configurable in 1.0.

The pinned template is schemas/misp/opentide.definition.json, copied from MISP/misp-objects objects/opentide/definition.json. Refresh direction is upstream MISP → this repository, the reverse of vocabulary sync. A refresh that changes the pinned relation set is a revision of this spec.

Requirements

• Each MISP instance MUST be one [[misp]] entry in sharing.toml.
• A [[misp]] block MUST set name, url, api_key, and max_tlp. Every other key has a default.
• A key not listed in this spec MUST be rejected as a configuration error before any instance is contacted.
• The publishing organisation MUST be the block's organisation_uuid when set, otherwise the object's metadata.organisation.uuid. An object with neither MUST fail and MUST NOT be written. The resolved value MUST be verified against the API key's organisation before any write.
• The connector MUST emit exactly one opentide object per Event and zero Event-level attributes.
• The opentide-object value MUST be the verbatim UTF-8 YAML bytes of the source document. Comments, key order, indentation, and blank lines MUST be preserved. The connector MUST NOT re-serialise, encode, truncate, split, or wrap that body.
• No configuration value, API key, authorization header, or ${ENV_VAR} substitution result MAY be injected into the document, object, envelope, tag set, share report, share state, or CLI output.
• The connector MUST NOT create, modify, enable, delete, or upload a galaxy or cluster.
• pull is not supported.

Definition

Capability

[[misp]] block

[[misp]]
name = "misp-internal"
enabled = true
url = "https://misp.internal.example.org"
api_key = "${MISP_INTERNAL_API_KEY}"
max_tlp = "amber"
object_types = ["threat", "objective", "rule"]
rule_statuses = ["PRODUCTION"]

[[misp]]
name = "misp-isac"
enabled = true
url = "https://misp.isac.example.net"
api_key = "${MISP_ISAC_API_KEY}"
max_tlp = "green"
object_types = ["rule"]
publish = true
organisation_uuid = "00000000-0000-4000-8aaa-000000000002"

Requests use an implementation default timeout, which SHOULD be 30 seconds.

Not configurable in 1.0

These keys are rejected like any other unknown key. They name behaviour this revision fixes rather than exposes; a later revision MAY add them.

Publishing organisation

The publishing organisation is half of the Event lookup key. opentide already records an owning organisation on each object as metadata.organisation.uuid (metadata.md), so the connector consumes that value first:

An object where both are absent is failed / organisation_uuid_missing. Other objects continue. The connector MUST NOT fall back to the API key's organisation.

MISP records the API key's organisation as the Event creator, whatever the payload says. Before any create or update, the connector MUST read that organisation with GET /users/view/me and compare it case-insensitively to the resolved value:

A mismatch is never written through, because an Event created under another organisation would not match the lookup key on the next run and would duplicate. An object whose metadata.organisation belongs to someone else can be republished by setting organisation_uuid on the block to the publisher's own organisation.

preview makes no request. It resolves the organisation from the same two sources. A resolved value is noted organisation_unverified. A missing value is failed / organisation_uuid_missing, the same as a push.

Distribution

1.0 derives distribution from the object's TLP only. Objects above the block's max_tlp are skipped_tlp and never reach this table. max_tlp = "red" shares TLP:RED; there is no second flag.

sharing_group_id is always 0. Wider distribution (connected or all communities) and sharing groups are out of scope for 1.0.

HTTP subset

Minimum server: a MISP release that ships opentide template version 5 (uuid 892fd46a-f69e-455c-8c4f-843a4b8f4295).

Every request MUST send the API key as Authorization: <key>. The key MUST NOT appear in query strings. On 401 or 403, the block MUST fail with authentication failed and MUST NOT dump response bodies.

restSearch is not assumed to constrain creator organisation and object attribute in one predicate. The connector MUST keep a hit only when both halves of the lookup key match, and MUST exclude every other hit from the match count. A foreign organisation's Event is an informational note, not a match and not an error.

PyMISP is the recommended opentide library. The spec is HTTP/JSON. Any client that speaks this subset conforms.

A galaxy lookup that fails for transport, timeout, or authorization fails the affected object with galaxy_lookup_failed. It MUST NOT degrade into a guessed value.

Tags

Emission order: TLP, PAP, threat-actor clusters, then mitre-attack-pattern clusters. Ascending code point order within each group. Each distinct tag string at most once.

A missing or unmapped metadata.tlp fails the object with unmapped_tlp. An unmapped metadata.pap fails it with unmapped_pap. An absent metadata.pap emits no PAP tag.

Cluster values MUST be the value string the instance returns. The connector MUST NOT derive a cluster value from an opentide vocabulary field.

A sub-technique emits its own cluster tag only. The parent is emitted only when the object lists the parent identifier separately.

preview makes no lookup. It omits cluster tags with note cluster_not_resolved and still emits the Event.

Golden fixtures MUST assert galaxy tag shape (misp-galaxy:<galaxy>="<non-empty>") rather than one instance's cluster value. Cluster strings are not stable across galaxy versions.

Event envelope

The connector sets exactly these Event fields:

uuid, timestamp, orgc_id, org_id, Orgc, Org, event_creator_email, EventReport, and CryptographicKey are server-owned and MUST NOT be set on create. The Event uuid is assigned by the instance and is sent only to address an existing Event on update.

An object whose top-level name is absent or empty after trimming, or whose metadata.created is absent or not a valid YYYY-MM-DD date, is failed with the field named. No remote Event is created or modified.

threat_level_id (1 High, 2 Medium, 3 Low, 4 Undefined) is derived, never configured. Threat uses top-level criticality. Rule uses top-level severity. Objective has no source and is 4.

Match the full vocabulary name, case-sensitive first, then case-insensitive equality. Never substring. A rule severity is matched against both severity::1.0 and alert_severity::1.0 rows. Low and Medium resolve identically on every scale that contains them.

opentide object

Pinned template identity:

opentide-type MUST be one of the template values_list entries: threat, objective, rule. Those strings are the opentide family names.

Every emitted attribute MUST set type to text, category to Other, to_ids to false, and distribution to 5 (inherit the Event). The object itself MUST set distribution to 5, so a stored object cannot outreach its Event.

disable_correlation MUST follow the table. Correlation of uuid and opentide-relation text MAY surface related events on an instance that correlates text. This spec does not require that UI behaviour. The authoritative link is the attribute value.

A missing template fails the object with template_missing. A missing required relation on the instance template fails it with template_relation_missing, naming each absent relation. A template version other than 5, while all six required relations exist and opentide-type accepts the family name, is an informational note. The connector still emits the pinned relation set.

Updates touch the seven envelope fields, the tag set, and the one opentide object. Remote objects or Event-level attributes the connector did not emit stay, with an informational note. The remote Event uuid and creator organisation are never rewritten.

Relations

opentide-relation points from child to parent:

Values are 36-character lowercase canonical UUIDs of Tide objects (or, for a rule, a signal), never MISP Event or object UUIDs, at most one attribute per distinct UUID, ordered ascending. A non-canonical UUID fails the object. An absent, null, or empty source emits zero relations. A relation UUID whose object was not shared to that block is still emitted, with an informational note.

No extends_uuid is set and no MISP event extension is created.

Identity

lookup key = (Event.Orgc.uuid == resolved publishing organisation)
           ∧ (opentide object uuid attribute == Tide metadata.uuid)

Orgc.uuid is compared as a canonical UUID, case-insensitively. The uuid attribute is compared as an exact case-sensitive string. An Event satisfying only one half is not a match.

The content hash is the SHA-256 of the verbatim UTF-8 bytes of the emitted object document, written as lowercase hex. It is computed locally before any request.

If the instance rejects opentide-object for length, fail that object with attribute_too_large and write nothing. The connector MUST NOT split the document across attributes.

Payload

The emitted document is one YAML document whose root is a mapping. It passes uuid-format and schema checks against its own metadata.schema whenever the source object does.

Nothing in the document is removed for any block, TLP value, or flag. Withholding content is done by raising metadata.tlp, lowering the block's max_tlp, or leaving the object out of the block's selection.

preview and push produce a byte-identical opentide-object value and the same outcome class for the same object and block, apart from the notes that only a live instance can settle (organisation, clusters).

Retract

Retract operates on records present in state or on the remote, not on objects that were never pushed.

Preflight reasons

These are preflight (exit 1) for this connector, before the exit rules in sharing.md: an unknown key in a [[misp]] block, a missing name, url, api_key, or max_tlp, an unset api_key variable, a malformed organisation_uuid, and organisation_uuid_mismatch on every selected block.

Validation check sharing-config

opentide validate SHOULD offer sharing-config (off by default, on for opentide share push). It checks sharing.toml and every [[misp]] block in the merged result:

Relationships

• sharing.md — sharing.toml, CLI, exit statuses, share state
• metadata.md — metadata.tlp, optional metadata.pap, metadata.organisation.uuid
• vocabularies/tlp.vocab.toml, vocabularies/pap.vocab.toml — tag strings
• schemas/misp/opentide.definition.json — pinned template version 5

Defaults & overrides

A block needs name, url, api_key, and max_tlp. It ships disabled, selects all three families and PRODUCTION rules, takes its organisation from each object unless the block sets one, and does not publish.

Examples

• Two instances: fixtures/sharing/valid/sharing.toml
• Golden Events for the committed object fixtures: rule, objective, threat
• Invalid key not configurable in 1.0: fixtures/sharing/invalid/unknown-distribution.toml. Every invalid fixture and its checker code is listed in validation.md.

History