How MISP and TheHive integration fits your incident workflow
This page covers the integration method, prerequisites, configuration and checks for connecting MISP and TheHive, so that events shared in MISP reach analysts as alerts in TheHive and observables from closed or active cases return to MISP as events. If your SOC or CSIRT already runs MISP for sharing and TheHive for case handling, the work is less about the software and more about deciding which events should become work, which case data is safe to share, and who is accountable when the two systems disagree. Those decisions shape the build more than any single setting does.
Start by agreeing on the direction of flow and the filters that apply to each one. Inbound, the question is which MISP events, tags, or distribution levels should create alerts, so analysts are not flooded with indicators that carry no action. Outbound, the question is which case observables may leave your organization, and at what distribution level and sharing group. MISP supports distribution levels and sharing groups down to individual attributes, so the policy can be precise. Write these rules down before configuration, because they determine what the integration is allowed to send and receive.
Confirm the exact connector or script, its import and export modes, and its licensing terms against the current TheHive and MISP documentation. Do not rely on older blog posts or community examples for this, since the supported options change between releases. Check the MISP version against the project's download guidance: MISP 2.5 is the recommended version for new deployments, and MISP 2.4 is end of life with security fixes only. Ask TheHive for its license terms in writing, including whether a paid license applies when one TheHive instance connects to more than one MISP server. DeployOpen confirms these points against your specific versions before build starts.
Plan the operational details early. Create a dedicated MISP user and API key for the integration, with the narrowest role that still permits the required reads and writes, and set a rotation process for that key. Decide how updates are handled, meaning whether a change to a MISP event updates an existing alert or creates a new one, and how duplicate alerts are avoided. Test with sample events in a non-production environment, and check that an observable pushed from a case does not return to MISP and create a loop. Record the results, since they become the acceptance criteria for go-live.
What you need in place before connecting MISP and TheHive
Five items must be settled before the connection is configured: the MISP release, the MISP and TheHive accounts, the network and certificate path, and the licensing position. Each has a clear owner, and an open answer on any one of them can delay the build or change its design.
Supported MISP version
Run MISP 2.5 for a new deployment. The MISP project recommends this release for new installs and lists 2.4 as end of life, so the project advises against new 2.4 instances. Before you build, confirm in the integration documentation for your TheHive release that the connector supports the MISP version you plan to run. Confirm the version with the MISP administrator, and record it in the build plan so later upgrades start from a known baseline.
Dedicated MISP user and API key
Create a MISP user for this integration only, not a personal analyst account. Give the user the role and sharing group permissions needed to read and write the events the sync touches, and nothing wider. Generate an API key for that user and store it in your secrets manager. Confirm with the MISP administrator who owns the key, how it is rotated, and how a key revoked during an incident would be replaced without breaking the sync.
TheHive instance and service account
Confirm that a TheHive instance is running and that the team responsible for it accepts the integration. Create a service account for the connection with an organization and profile limited to the alert and case actions the integration needs. Do not reuse an administrator login. Confirm with the TheHive administrator which organization will receive MISP events as alerts and which will hold the case observables sent back to MISP.
Network paths and TLS certificates
Map which system opens the connection, which ports must be allowed between MISP and TheHive, and whether any proxy or load balancer sits in the path. Both endpoints should present certificates that the calling system trusts, including any internal certificate authority. Check that certificate names match the hostnames used in the configuration. Network and security teams should confirm these paths in writing before the build, because certificate or firewall gaps are a common cause of failed connections.
License position for multiple MISP servers
Confirm whether your TheHive license covers connections to more than one MISP server. Some deployments connect a single MISP instance, while others connect several, for example a production instance and a separate sharing instance. Ask the TheHive vendor or licensing contact to state the position in writing for your planned server count, and have procurement record it with the contract. Raise this early, because it can change the number of instances in the design.
How MISP events become TheHive alerts and observables
Two data flows matter here, and each is controlled by different settings. In the inbound direction, TheHive reads MISP events and creates alerts from them, with the event's attributes becoming candidate observables. In the outbound direction, observables that an analyst records in a TheHive case are sent to MISP as new events or as attributes added to an existing event. Plan the two directions as separate decisions, because a setting that is safe for one can expose data in the other. Before go-live, confirm in the vendor documentation for your TheHive and MISP versions which mechanism you will use (connector, script or API client), how it selects events and observables, and which filtering options it supports, such as tags, organizations or time windows.
Distribution levels and sharing groups decide what leaves the MISP instance. Each event carries a distribution setting that limits which organizations and communities can receive it. Attributes can carry their own distribution setting, and sharing groups extend control to named sets of organizations. The integration acts with the permissions of the MISP user and organization behind its API key, so it can only retrieve what that account is allowed to see. Ask your MISP administrator which role and organization the integration account uses, then test with one event at each distribution level before enabling broader synchronization. Do not assume the connector respects TLP markings until you have checked how it maps them to MISP distribution values.
Outbound, the main decision is what an observable becomes in MISP. A single case can produce one new event, or its observables can be attached to an event that already exists for the same campaign or incident. Each option changes how other MISP users see the data, and the wrong choice either clutters the feed or buries indicators where nobody reads them. Decide the distribution for outbound events before the first push, and confirm how the integration maps case sharing settings and TLP labels to MISP distribution. Also check how repeated pushes are handled. Illustrative example: an analyst updates an IP observable after a case is reopened. You need to know whether the update modifies the existing attribute, creates a duplicate or is ignored.
The correlation engine in MISP adds value at the point where data arrives. When an attribute is added, MISP looks for matches in its existing data using exact matches and advanced patterns, including fuzzy hashes and CIDR overlaps, under granular controls. For an alert pulled from MISP, a correlation hit can point the analyst to earlier events that share an indicator, which helps decide whether the alert belongs in an existing case. Correlation only applies to attribute types that are set to be correlated, so review that configuration before relying on it. Confirm whether the connector passes correlation context to TheHive or whether analysts must check MISP separately. A correlation hit is a lead, not a verdict, so review the context of the source event before acting on it.
Configuration sequence for MISP and TheHive integration
This sequence connects MISP and TheHive in a deliberate order so each direction is proven before the next one opens. Each step closes with a check you can record, which gives your security operations team a working import path, a controlled export path and a written trail of what was configured.
Confirm versions, licenses and edition terms
The platform owner confirms the MISP version and the TheHive edition, then checks each license before any account is created. The MISP download page recommends MISP 2.5 for new deployments and states that 2.4 is end of life, so an existing 2.4 instance should be scheduled for upgrade first. Ask TheHive's vendor in writing whether connecting more than one MISP server needs a paid license, and record the answer. Done when the versions, license terms and support status are written down and signed off by the owner of each platform.
Create a MISP API key with minimum rights
A MISP administrator creates a dedicated user for TheHive, separate from any personal account, and assigns a role that carries only the permissions the import and export directions need. Administrator, sync and publishing rights stay off unless a specific flow requires them, and each one is justified in the change record. Test the key with a read-only search against the MISP API, then attempt an action the role should not allow. Done when the read succeeds, the blocked action is refused and the key is stored in your secrets manager.
Create the TheHive service account
A TheHive administrator creates a service account for the integration, scoped to the organization that will receive MISP alerts and create case observables. Give it the profile that covers alert and case handling in your TheHive version, and no platform administration rights. Generate its API key and store it alongside the MISP key. Verify with an authenticated API call that returns the account identity, then confirm the account can see only the intended organization. Done when the identity and scope match the change record.
Set up network and certificate trust
The network team opens only the paths the integration needs, from the TheHive host to the MISP HTTPS endpoint, plus any reverse path your chosen connector design requires. Confirm that path with the connector documentation before opening it. Both platforms should use certificates issued by a certificate authority that both sides trust, with the full chain installed and hostnames matching what each side calls. Keep certificate verification enabled in both connectors. Test the TLS handshake from the TheHive host with validation on. Done when the handshake validates and the record lists every open port and certificate owner.
Configure the import direction with a narrow filter
Set the TheHive side to pull MISP events only when they carry a dedicated test tag, and accept only the distribution levels your policy allows for alerting. Choose a tag that no production workflow uses, so the first run cannot flood the alert queue. Confirm which MISP attribute types map to TheHive observable types and which are dropped, then record that mapping. Verify by listing the events the filter matches in MISP and comparing that list with the alerts TheHive creates after one sync. Done when the two lists match and no untagged event produced an alert.
Test the import with one known event
Create a single MISP event with a known set of attributes, for example one IP address, one domain and one file hash (illustrative). Tag it with the test tag and publish it. Run the import and confirm that exactly one alert appears in TheHive, with each attribute present as an observable of the expected type and the event title carried through. Run the sync a second time and confirm that no duplicate alert is created. Done when the alert matches the source event and the second sync changes nothing.
Enable export and check distribution levels
Turn on the export direction only after the import test passes. Create a test case observable in TheHive with a chosen MISP distribution level, then confirm it appears in MISP as an attribute on an event with that distribution level and nothing broader. Check that the exported item carries a marker so the import filter does not pull it back into TheHive as a new alert, which is the loop to avoid. Record the distribution level used for each observable type in the runbook. Done when the exported attribute shows the expected distribution and the next sync creates no new alert from it.
Mapping MISP attributes and TheHive observables
This table compares how MISP event fields, attribute types, categories, tags and distribution levels land in TheHive alerts, observables and tags. Read each row as a decision point: some MISP types have a direct observable type, while others are better kept as context in the alert description. Where mapping depends on the connector version, the row says so, and you should check it against vendor documentation before writing alert rules.
| MISP field | TheHive target | Decision or caveat |
|---|---|---|
| Event info and threat level | Alert title and severity | Threat level scales do not map one to one to alert severity. Define a rule and confirm in vendor docs. |
| Event distribution level | No direct alert field | Decide which distribution levels are imported. Confirm in vendor docs which levels the connector processes. |
| Attribute type (for example ip-dst, domain, sha256, url) | Observable data type | Types with a matching TheHive observable type can be imported. Confirm the supported type list in vendor docs. |
| Attribute type with no observable match | Alert description or case task notes | Keep unmatched types as context unless your analysts can use them as pivots. Confirm handling in vendor docs. |
| Attribute category (for example Network activity, Payload delivery) | Observable tag or description text | Categories are not observable types. Decide whether to filter by category or carry it as a tag. Confirm in vendor docs. |
| to_ids flag on attributes | Filter for observable creation | Creating observables only from flagged attributes reduces noise. Confirm whether the connector applies this filter. |
| Event and attribute tags (TLP, PAP, taxonomies) | TheHive tags and case TLP | Confirm how the connector carries TLP and PAP values onto alerts, cases and observables. |
| Observables returned from cases to MISP | MISP attribute type and event distribution | Set the outgoing distribution explicitly so case data is not shared more widely than intended. Confirm in vendor docs. |
How updates, re-imports and duplicates behave
The first risk is a duplicate. If the MISP to TheHive import runs again on the same event, the connector must recognize the event it already created, or TheHive ends up with several alerts, cases or observables for one piece of intelligence. Ask the connector maintainers how the link is kept: whether the MISP event UUID is stored on the TheHive alert, which field holds it, and whether the connector checks for an existing alert before it creates a new one. Then run one event through the import twice in staging and count the alerts, cases and observables that result. Repeat the test after MISP publishes a new version of the same event, because a changed event may be treated as new, as an update, or as nothing at all, depending on the connector's configuration.
Once an event is imported, each field needs a single owner. MISP is normally the source of truth for the intelligence itself: the event description, attribute values, tags such as TLP markings, and distribution. TheHive is normally the source of truth for the investigation: case status, severity after analyst review, assignees, tasks, observables that analysts have enriched or marked as malicious, and the final verdict. Write this down as a field matrix before go-live, with one column for the owning system and one for the direction of sync. Where a field has two plausible owners, choose one writer and make the other side read-only, or document that the last write wins. Confirm in the connector documentation whether a change to a MISP attribute overwrites an observable that an analyst has already edited in TheHive.
Closed and merged cases need explicit rules because neither product may propagate these states the way the team expects. Decide whether a closed case should still push its observables back to MISP, whether a merged case keeps the MISP event reference of the case it was merged from, and whether an alert marked as imported or ignored in TheHive is re-imported on the next run. Also check whether deleting an alert or case in TheHive removes or alters anything in MISP, and whether deleting an event in MISP affects TheHive. Many deployments find that deletions are not carried across, which leaves orphaned records on one side. Test every state transition you plan to use and record the outcome in your runbook so that operators know what they will see.
The export direction carries the highest sharing risk. Case comments, task logs, analyst names and free-text case descriptions often contain internal detail such as customer names, internal hostnames or unresolved suspicions. If the export maps these fields into MISP event information, attribute comments or tags, they can leave your instance through synchronization with other servers or a sharing community. Limit the export to the attributes and tags your sharing policy permits, set the MISP distribution to the narrowest level that fits the purpose, and review a sample of exported events before you enable automatic push. In staging, create a dummy case with a clearly marked internal note and confirm that the note never appears in the MISP event or in any synchronized copy.
Securing the MISP to TheHive connection
Each control below narrows what the MISP and TheHive connection can reach, who can use it, and what leaves your organization through it. Together they cover credentials, transport, network paths, logging and data sharing decisions. Review them during design, and again whenever keys rotate, a version changes or a new case type starts sending observables.
Separate API keys per direction
Create one MISP API key for the direction that brings MISP events into TheHive as alerts, and a second, separate key for the direction that pushes TheHive observables back to MISP. Each key should belong to a dedicated MISP user with the narrowest role that allows its job, so a leaked key cannot publish or edit events it never needed to touch. Confirm with your MISP administrator which permissions each path requires, and record which key serves which workflow so rotating one key does not break the other direction.
Store keys in a secrets manager
Keep both API keys out of TheHive and MISP configuration files, environment files kept in version control, and shell history. Store them in the secrets manager your platform team already operates, and have the deployment tooling inject them at runtime. Check whether the connector accepts a secret reference or needs the value supplied at startup, because that decides how rotation is performed. Confirm that the access policy on each secret lets only the service account for that side read it.
Verify certificates in both directions
Both calls cross the network, so each side should validate the certificate presented by the other. On the TheHive side, confirm that the MISP URL uses HTTPS with a certificate chain issued by an authority the TheHive host trusts, and that certificate verification is not disabled in the connector settings. The outbound path from MISP to TheHive should also validate TheHive's certificate. Internal certificate authorities often need their chain added to the trust store of the service making the call, which is easy to overlook. Test with a deliberately invalid certificate to confirm the connection refuses it.
Restrict traffic with network allow-lists
Limit which hosts can open connections between the two platforms. Allow the TheHive backend to reach the MISP HTTPS endpoint, and allow only the MISP host or its outbound proxy to reach the TheHive API port, with all other paths denied. Account for any misp-modules or helper services that make calls on the integration's behalf. Confirm the exact ports, reverse proxy addresses and load balancer addresses with your network team and the vendor documentation, and review the rules after every infrastructure change.
Enable audit logging on both platforms
Turn on and retain audit logs in MISP and TheHive for every API call made by the integration accounts, including event creation, event edits, observable uploads and failed authentication. Forward these logs to the central platform your security team reviews, and alert on repeated authentication failures or on writes from the integration account outside expected windows. Confirm what each product logs by default, since some actions may require explicit configuration. Agree the retention period with your compliance owner before go-live.
Review distribution before sharing observables
When TheHive pushes an observable to MISP, the resulting attribute or event carries a distribution level and, where used, a sharing group that decide who receives it. Set a deliberate default for pushed observables and confirm the connector applies it on every push. Require a reviewer, or a rule in the case workflow, to check tags and distribution on cases that contain customer data, personal data or unpublished incident details before the share happens. Confirm how your connector version maps TheHive case fields to MISP distribution settings.
Common failures in MISP and TheHive integration
This table lists failures that follow from configuration in a MISP and TheHive connection, with the likely cause, the check to run and the fix for each. Use it to test every path before go-live and when alerts stop arriving or sharing stalls. Most failures trace to API keys, trust chains, attribute type mapping and distribution settings, and each can be verified on its own.
| Failure | Likely cause | How to check | Fix |
|---|---|---|---|
| Expired or wrong-scope API key | Key was rotated, expired, or issued to a user without the roles the connector needs | Run a read call from the TheHive host using the key and review the MISP user's role and status | Create a dedicated sync user with the required permissions, then update the key in the TheHive connector settings |
| Certificate chain errors | MISP is served with an internal CA or an incomplete chain, and the TheHive runtime does not trust it | Fetch the chain from the TheHive host with openssl and compare it with the connector's trust store | Serve the full chain from MISP, or add the internal CA to the TheHive trust store and restart the service |
| Events arrive without observables | MISP attribute types do not map to the observable types the connector expects | Compare the event's attribute types with the connector mapping and inspect one imported alert | Adjust the type mapping for the affected attributes, then re-import the affected events |
| Duplicate alerts after re-sync | Source reference changes on re-sync, or overlapping import windows run twice | Check whether duplicate alerts share the same MISP event ID and source reference | Keep the source reference stable, align the import window, and merge or remove duplicate alerts |
| Distribution level blocks sharing | Events or cases carry organization-only or community-only distribution that the export step does not allow | Check the distribution and sharing group on the event before the export runs | Set distribution per the sharing policy in the export step, and agree levels with the sharing community first |
| Version drift after a MISP upgrade | API responses or connector expectations change, and the connector was not retested on the new MISP version | Record MISP versions before and after upgrade, then run a test event round trip in staging | Upgrade in staging first, retest the round trip, then promote the change to production |
| Connection limit for multiple MISP servers | The planned number of MISP connections exceeds what the TheHive license covers | Confirm the license terms for connections to more than one MISP server before adding one | Confirm licensing with TheHive before configuration, or limit the connector to one MISP server |
Licensing and scaling when more than one MISP server is involved
The licensing terms for connecting TheHive to more than one MISP server must be confirmed with the vendor before any architecture work starts, because those terms can change how many connections you design, where they run and what they cost. Do not assume that the terms covering a single MISP connection also cover several. Ask the vendor to state in writing whether a multi-server connection needs a paid license, and whether the price depends on the number of MISP instances, the number of TheHive organizations or users, or the hosting model. Also ask whether any connector or integration component you plan to use carries its own terms. Keep the answers in the project file alongside the design decisions they affect.
On the MISP side, the MISP software is licensed under the GNU Affero General Public License version 3 (AGPL v3). That license applies to the MISP code you run and to any changes you make to it, and the AGPL includes obligations that apply when a modified version is made available to users over a network. Taxonomies and galaxy data are licensed separately, under CC0 1.0 Universal or the 2-clause BSD license, depending on the dataset. Inventory the taxonomies and galaxies enabled on each instance, since synchronized or mirrored instances can pull in data with different terms. Have your legal team review the AGPL position for any custom MISP modifications before you build them into the design.
Each additional MISP server adds its own database, cache, synchronization configuration, sharing group decisions and alert flow into TheHive, so the number of instances is the main driver of both build effort and recurring cost. Model the instance count in the quote before the design is approved. Ask the implementation partner to list every MISP instance in scope, including test and production environments, and to state whether the design assumes one TheHive instance receives alerts from all of them. The one-time cost covers design, configuration, testing and documentation for each connection. The recurring cost covers license fees, support and upgrades for each MISP instance, which should be reflected in the quote as separate lines rather than a single total.
Before signing, complete four actions. First, obtain the TheHive and connector licensing terms in writing, including any change in price or terms at renewal. Second, write down the planned MISP instances, their purpose and the datasets each one will carry. Third, ask for the quote to show costs per instance and per connection, so a change in scope can be priced directly. Fourth, set a review point before each license renewal and before any new MISP server is added, because either event can change the terms that the architecture depends on.
Questions teams ask before they connect MISP and TheHive
What drives the cost of a MISP and TheHive integration?
Cost follows the scope agreed in writing. The main drivers are the number of MISP instances, the complexity of field mapping between MISP attributes and TheHive observables, the number of event filters (by tag, distribution or organization), the test scope, and licensing. Each extra instance or filter adds design, build and test work. DeployOpen's services are quoted as fixed-scope effort, and the work is paid to DeployOpen. Licenses are bought from the software vendors and are a separate cost, which may recur. Ask the quote to itemize services by instance and filter, describe the test scope, and name every license that applies. DeployOpen does not publish prices.
How long does a MISP and TheHive integration take?
No duration can be stated without a written scope, so ask for one in the quote. Timing depends mainly on how many MISP instances connect, how complex the field mapping is, and where the platforms run: a cloud account, a data center or an air-gapped network. Network approvals and service account provisioning often set the pace at the start. Review time depends on analyst availability, because someone on your side must check sample events and mapped cases before production use. Ask for the phases, the client dependencies in each phase, and the point at which production cutover begins.
What does the integration need from our team before work starts?
The work needs access, network paths and people. Typical requirements are:
- API keys for each MISP instance
- Service accounts in TheHive with only the permissions the import and export modes need
- Network approvals so each platform can reach the other along the paths you use
- Sample events covering the tags and distributions you plan to import
- Analyst time to review mapped alerts and cases
Agree who owns each account and how keys are rotated. Confirm with each vendor which API permissions each mode requires for the versions you run.
Does connecting more than one MISP server require a paid license?
Yes. A paid TheHive license is needed to connect more than one MISP server. Confirm the current terms, edition and fees directly with the vendor before you choose an architecture. The answer affects whether you consolidate MISP instances or run a separate connection for each one. DeployOpen can include license selection and configuration in the written scope, but licenses are purchased from the vendor and appear as a separate line in the quote. Ask for each license as its own line item, including whether it recurs.
Can an in-house team build this integration without a partner?
Yes, if the team has the skills. An in-house team needs working knowledge of MISP administration, TheHive administration, API authentication, event filtering and basic scripting for mapping logic. The harder parts are usually the test plan and update behavior: how changes to a MISP event reach an existing TheHive alert or case, and how observables return to MISP without creating loops. Teams with a single administrator often find that analyst review time limits progress before tooling does. You can outsource only the parts you choose and keep design and sign-off in-house. Ask any partner to quote those parts separately.
What should we test before sending production MISP events to TheHive?
Test with sample events first, then with filtered production data, before enabling full sync. Cover the tag and distribution filters, duplicate events, updated events, how alerts map to TheHive fields, and the observables that return to MISP as events. Check that returned data does not re-import into a loop. Record the expected result for each sample so analysts can sign off. Confirm your MISP version before testing. MISP 2.5 is recommended for new deployments, and the project states that 2.4 is end of life with security fixes only, so upgrade first if you run 2.4. Ask the quote to name the test scope and the sign-off owner.
Does the integration change how our MISP instance is licensed or upgraded?
Connecting the platforms does not change MISP's license terms. MISP is licensed under the GNU AGPL version 3, and its taxonomies and galaxies carry separate CC0 or BSD 2-clause terms. Upgrade planning matters more than licensing here. The MISP project recommends MISP 2.5 for new deployments and states that 2.4 is end of life with security fixes only, so an instance still on 2.4 should upgrade before it connects. TheHive licensing is a separate question, covered by the paid license for multiple MISP servers. Confirm all license terms with each vendor and your legal team before go-live.
How DeployOpen scopes and delivers the MISP and TheHive integration
DeployOpen scopes the MISP and TheHive integration as a written, fixed-scope engagement inside your own infrastructure. The work covers MISP and TheHive configuration, API access, import and export behavior, and the handover documents your analysts and platform team need to run it.
How we scope
- Confirm which MISP events should become TheHive alerts, and which case observables return to MISP as events.
- Agree import and export modes, tag and distribution filters, and update behavior before any configuration starts.
- Confirm the TheHive license terms for more than one MISP server, and record them in the written scope.
How we build
- Create dedicated MISP and TheHive API keys with the access each side needs, stored in your secrets management.
- Configure the import path so MISP events arrive as TheHive alerts, and test it against a staging instance first.
- Build the export path so case observables return to MISP as events at the agreed distribution level.
How we hand over
- Document the API keys, mappings, filters and update behavior, so your team can audit each connection path.
- Run a joint test with your analysts that covers alert creation, observable export and a rollback of the connection.
- Provide the written handover pack and the operating notes your platform and SOC teams need after go-live.
How we support
- Set up ongoing support, upgrades and testing for the integration as a retainer if your team wants continuous cover.
- Plan integration checks after each MISP or TheHive upgrade, so API and field changes are reviewed before they reach analysts.
- Keep the integration configuration in your infrastructure, with access managed by your team after handover.
