Skip to main content

PyMISP - Python Library to Access MISP

PyMISP is the Python client for the MISP REST API. Use it to search intelligence, work with events and objects, submit sightings and build integrations without assembling every HTTP request yourself. API permissions and distribution still apply to the account behind its key.

Note

Examples were checked with MISP 3.0.0 (3.0_wip, commit 99ebee729) and PyMISP 2.5.34.4. The server’s GET /servers/getVersion reports pymisp_recommended_version; use that recommendation when selecting a client version. The client and server do not need matching major-version numbers.

Install the client

Use a virtual environment and install the maintained package:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pymisp

For a reproducible deployment, pin the tested package and dependencies in your project’s lock file. A source checkout is useful when developing PyMISP itself; follow its upstream installation instructions.

Configure authentication

Create a suitably restricted key under Account → My Profile → Auth keys. Supply the URL and key through environment variables or your secret store. Keep TLS verification enabled:

import os
from pymisp import PyMISP

misp = PyMISP(
    os.environ["MISP_URL"],
    os.environ["MISP_KEY"],
    ssl=os.environ.get("MISP_CA_BUNDLE") or True,
    timeout=30,
    debug=False,
)

MISP_CA_BUNDLE, when set, is the path to the CA bundle for a private certificate authority. Do not disable certificate verification to fix an unknown issuer. Avoid debug logging with real keys or sensitive response data. Upstream example scripts may read a local keys.py; keep such a file outside version control and follow that script’s configuration contract.

Create private exercise data

Build an event locally, choose its audience and add context before sending it:

from pymisp import MISPEvent

draft = MISPEvent()
draft.info = "Integration exercise: Python draft"
draft.distribution = 0
draft.threat_level_id = 4
draft.analysis = 0
draft.published = False
draft.add_attribute("domain", "automation.example.org", to_ids=False)

created = misp.add_event(draft, pythonify=True)
if not isinstance(created, MISPEvent):
    raise RuntimeError("MISP did not accept the event")

print(created.uuid)

To add another observation, use misp.add_attribute(created, {...}, pythonify=True) with the appropriate type, category, distribution and detection flag. For structured data, use a MISPObject and the relevant template. Review the saved event before publication; creating it does not require publishing it. A production importer should retain the source identity and use UUIDs/reconciliation to avoid duplicate copies on retries.

MISP 3.0 targets and client coverage

MISP 3.0 adds value-level research workflows and additional collection targets. An attribute UUID identifies one occurrence; an AttributeValue target uses the SHA-256 of a stored component value. Use object_sha256, related_object_sha256 or element_sha256 as appropriate, rather than putting the address in a UUID field.

Not every new route or target is wrapped by every PyMISP release. Use the documented REST API for an unsupported operation, with the same account, TLS verification and error handling. For example, a Requests session can retrieve the stored address without guessing its normalization:

import os
import requests

session = requests.Session()
session.headers.update({
    "Authorization": os.environ["MISP_KEY"],
    "Accept": "application/json",
})
response = session.get(
    os.environ["MISP_URL"].rstrip("/") + "/values/view",
    params={"value": "example.org"},
    timeout=30,
    verify=os.environ.get("MISP_CA_BUNDLE") or True,
)
response.raise_for_status()
value_result = response.json()

See Automation & API for the address fields and payloads. A collection reference or note does not bypass the visibility of its source data.

Example scripts and feeds

Browse the maintained examples directory and use each script’s --help before running it. Examples can create, delete, publish or export data; inspect the intended action and account scope first.

For generating a native MISP feed, use the upstream feed-generator tooling and review the exported distribution and source set. To consume one, configure a MISP feed and its import policy. Avoid an unbounded loop that downloads an entire public manifest and blindly calls add_event: source publication, audience, duplicates and attachments need handling.

Recorded example: fetch exercise events

The following result was executed against the local MISP 3.0 training fixture and committed under _freeze/. Normal book/CI builds reuse it; they do not contact a live instance. Maintainers refresh it explicitly with the intended instance, key and Python environment configured.

import os
from pymisp import PyMISP

misp = PyMISP(
    os.environ["MISP_URL"], os.environ["MISP_KEY"],
    ssl=os.environ.get("MISP_CA_BUNDLE") or True,
    timeout=30, debug=False,
)
events = misp.search(
    controller="events", eventinfo="%Integration exercise%",
    limit=5, page=1, pythonify=True,
)
if not isinstance(events, list):
    raise RuntimeError("Event search failed")
for event in events:
    print(f"{event.info} | distribution={event.distribution} | "
          f"published={event.published} | attributes={len(event.attributes)}")
Integration exercise: private observations | distribution=0 | published=False | attributes=2
Integration exercise: Python draft | distribution=0 | published=False | attributes=1

For a scheduled connector, add bounded pagination, modification checkpoints, retries and removal handling. See the polling workflow and connector lifecycle.