MispFleet

Async Python library and CLI to operate many MISP instances as one coordinated fleet

Overview

MispFleet is not another thin wrapper around a single MISP REST API. Its differentiator is the orchestration layer: query, compare, govern, and synchronize multiple MISP instances through one consistent asynchronous interface — as a CLI or as a Python library.

Key Features

Supported Outputs

Data           JSON, JSONL, YAML, terminal tables
Threat Intel   STIX 2.1 export, TAXII 2.1 push, OpenCTI
State          SQLite (local) or MariaDB (shared) checkpoints & audit
Credentials    env vars, OS keyring, interactive prompt, in-memory

Why MispFleet if PyMISP already exists?

PyMISP is the official Python library for MISP, and it is excellent at what it does: a rich, typed object model (MISPEvent, MISPAttribute, MISPObject, …) over the REST API of one MISP instance. If you work against a single server, PyMISP is the right tool — and MispFleet does not replace it.

MispFleet solves a different problem: operating many MISP instances as one coordinated fleet. PyMISP gives you PyMISP(url, key), a single synchronous connection; everything beyond that — iterating over servers, running requests concurrently, aggregating partial failures, preserving provenance, comparing or reconciling instances — is left for you to hand-roll. MispFleet makes that orchestration layer a first-class, typed, tested library.

¹ An experimental pymisp-async (aiohttp) exists as a separate project; the mainline PyMISP is synchronous.

In short: use PyMISP to talk to a MISP instance; use MispFleet to run a set of them. The two are complementary — MispFleet ships its own async client rather than wrapping PyMISP, but they target different layers of the same problem. For deep single-instance API coverage and MISP's canonical object generators, reach for PyMISP; for fleet-wide search, diffing, governed copy, and synchronization, reach for MispFleet.

Installation

From PyPI (Recommended)

python3.14 -m pip install mispfleet

Python 3.14 is the only supported runtime for the first major version.

From Source

git clone https://github.com/seifreed/MispFleet.git
cd MispFleet
python3.14 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

Optional Extras

pip install "mispfleet[all]"       # keyring + mariadb + telemetry + http2
pip install "mispfleet[keyring]"   # OS keyring credential provider
pip install "mispfleet[mariadb]"   # shared MariaDB state backend
pip install "mispfleet[telemetry]" # OpenTelemetry metrics
pip install "mispfleet[http2]"     # HTTP/2 transport

Quick Start

# Create and validate a fleet configuration
mispfleet config init
mispfleet config validate

# Check health across every configured server
mispfleet servers health --all

# Federated search across the fleet
mispfleet search value evil.example --all --format json

Usage

Command Line Interface

# Compare one event between two servers
mispfleet event diff EVENT_UUID --left production --right research

# Plan a copy without mutating anything, then apply the reviewed plan
mispfleet event copy EVENT_UUID --from research --to production --dry-run
mispfleet apply plan.json

Main Commands

Python Library

Basic Usage

import asyncio
from pathlib import Path

from mispfleet import MispFleet, SearchQuery, ServerSelector


async def main() -> None:
    async with await MispFleet.from_file(Path("mispfleet.yml")) as fleet:
        result = await fleet.search(
            SearchQuery(value="evil.example", metadata_only=True),
            selector=ServerSelector.group("all"),
        )
        for match in result.matches:
            print(match.server, match.event_uuid)


if __name__ == "__main__":
    asyncio.run(main())

Configuration

version: 1
defaults:
  verify_tls: true
  request_timeout: 60
  connect_timeout: 10
  concurrency: 5
servers:
  production:
    url: https://misp.company.example
    credential:
      provider: env
      key: MISPFLEET_PRODUCTION_API_KEY
    role: primary
    groups: [internal, all]
  partner-cert:
    url: https://misp.partner.example
    credential:
      provider: env
      key: MISPFLEET_PARTNER_CERT_API_KEY
    role: partner
    read_only: true
    groups: [partners, all]

API keys are never stored in the configuration file: credentials are references to environment variables, the OS keyring, an interactive prompt, or in-memory values.

Safety Model

• Read operations run directly; mutating and cross-server operations support plan and dry-run modes.
• Copying an event is a two-stage operation: plan produces a deterministic, credential-free plan file; apply re-validates it before mutating anything.
• Partial fleet failures are represented as data, never as silent total success.
• Secrets are redacted from logs, exceptions, plans, and debug output.

Requirements

• Python 3.14
• See pyproject.toml for dependencies and extras

Development

python3.14 -m venv .venv && .venv/bin/pip install -e '.[dev]'
black --check . && ruff check . && mypy .
pytest
bandit -r . && pip-audit

Contributing

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support the Project

If this project is useful in your workflows, you can support development:

License

This project is licensed under the MIT license. See LICENSE.

Attribution

• Author: Marc Rivero López | @seifreed
• Repository: github.com/seifreed/MispFleet

_{Built for practical multi-instance MISP operations and threat-intel automation}