Skip to main content

Appendix A — Appendices

These references cover authentication, access-control inspection, companion projects and background processing. Use the installed branch’s settings and implementation together with the deployment’s configuration process; service paths and role IDs are not universal defaults. The MISP as a Threat Intelligence Platform annex maps practical outcomes to capabilities and implementation chapters. For the project’s origins, community, CIRCL stewardship and open standards, read MISP: A Community History, 2011–2026. The glossary explains the terminology used throughout the guide.

Note

Checked against MISP 3.0.0, 3.0_wip commit 99ebee729. The examples use reserved names and synthetic private data. Authentication mechanisms and third-party integrations need their own deployment tests; the presence of a plugin is not a compatibility guarantee.

External authentication

Choose the mechanism

Authentication establishes an identity; MISP still needs a user account, organisation, role and applicable access checks. Distinguish the browser login, a trusted front-end assertion and a REST API key. Configuring one does not automatically configure or revoke all the others.

Mechanism Identity source and configuration
CustomAuth A configured server/header value matches an existing user’s external authentication key. Uses Plugin.CustomAuth_*; this is not LDAP auto-provisioning.
LdapAuth The plugin searches a directory, validates credentials or a trusted header, and resolves/provisions the MISP account. See LDAP.
OidcAuth An OpenID Connect provider supplies the browser identity and claims. Check the plugin’s issuer, callback, dependency, role/organisation mapping and mixed-login configuration.
ShibbAuth / CertAuth A correctly configured web server/SP validates SAML or client certificates and supplies verified server variables. The MISP plugin maps that result; it does not replace the front-end protocol validation.
Other shipped plugins AadAuth and LinOTPAuth have their own requirements and activation paths. Read the installed implementation and its README before selecting one.

For CakePHP authentication handlers, inspect Security.auth and Security.auth_enforced. The latter removes the built-in Form authenticator when enabled. A plugin’s own mixedAuth setting is separate. Bootstrap/plugin loading and additional dependencies vary by mechanism; do not assume every plugin is activated by one identical setting.

Identity verification, local account mapping and access to a particular resource are separate stages.

Identity verification, local account mapping and access to a particular resource are separate stages.

The branch’s plugin references are OidcAuth, ShibbAuth, CertAuth, AadAuth and LinOTPAuth. Test the actual login, logout, MFA, recovery and API paths before enforcing a new mechanism.

Configure CustomAuth

Open Administration → Server Settings & Maintenance → Integrations → Custom authentication (/servers/serverSettings/customauth). The MISP 3.0 page groups the supported settings and provides their current validation/help; use the durable configuration source for managed deployments.

The actual Custom authentication settings in MISP 3.0. Header authentication remains disabled in this documentation instance.

The actual Custom authentication settings in MISP 3.0. Header authentication remains disabled in this documentation instance.
Setting Meaning in the pinned implementation
Plugin.CustomAuth_enable Enables the header mechanism. Keep it off until the front end and account mapping are ready.
Plugin.CustomAuth_header Names the server-variable suffix to read; the default is AUTHORIZATION.
Plugin.CustomAuth_use_header_namespace, Plugin.CustomAuth_header_namespace Control the prefix, normally HTTP_. Confirm the exact variable PHP receives.
Plugin.CustomAuth_required Controls required versus mixed CustomAuth behaviour. It is separate from the CakePHP plugin/Form settings.
Plugin.CustomAuth_only_allow_source Compares one exact value with MISP’s calculated remote IP. It is not a URL or CIDR allowlist.
Plugin.CustomAuth_name The display name used in user controls, messages and logs.
Plugin.CustomAuth_disable_logout Controls the normal logout affordance for external-authentication users.
Plugin.CustomAuth_custom_password_reset The external password-reset URL offered to users.
Plugin.CustomAuth_custom_logout The external logout URL. The historical name custom_password_logout is not this setting.

For example, a front-end HTTP header X-Remote-User commonly reaches PHP as HTTP_X_REMOTE_USER: with the default prefix, the CustomAuth header setting would be X_REMOTE_USER. Check the actual server environment rather than copying the HTTP spelling with hyphens. A dedicated identity header also avoids confusing this value with a REST API key in the default Authorization header.

Configure the trusted front end to remove client-supplied identity headers and supply its own verified value. Restrict direct access to the backend. The source check uses MISP’s remote-IP calculation, which can be affected by forwarded-IP configuration; it is not a substitute for establishing the proxy trust boundary.

Map users and inspect authentication failures

When CustomAuth is enabled, the user form exposes the external-authentication flag and key. The asserted value must match an existing account with external_auth_required enabled and the intended external_auth_key. Keep the account’s role/organisation, disabled state, recovery process and API-key lifecycle under administrative control.

MISP.disableUserSelfManagement changes which self-service operations users may perform; it is not a general account-locking or external-authentication switch. Check the relevant operation’s permissions rather than assuming every other account function is unaffected.

Use authentication and audit logs to correlate a failed request, account and front-end assertion. The branch normally masks external keys in failure logs; unsafe cleartext-key logging changes that. Review diagnostic output before sharing it. See user authentication for keys and MFA.

ACL descriptors

Query the installed ACL

A site administrator can inspect the controller/action ACL through /servers/queryACL. Use an authenticated JSON request. The following are read-only descriptors:

Request path Result
/servers/queryACL/printRoleAccess/ROLE_ID Role name and allowed controller/action patterns for one existing local role ID.
/servers/queryACL/printRoleAccess Descriptors for all local roles.
/servers/queryACL/printAllFunctionNames Controller/function names discovered by the installed source scanner.
/servers/queryACL/findMissingFunctionNames Discovered functions without an explicit mapping according to that scanner.

Find the intended role under Administration → Roles; role IDs and permission combinations belong to the local database. A missing role ID returns an error. The output for a different release or another installation can differ, so this appendix no longer embeds hundreds of stale example URLs.

The current role catalogue identifies the local role IDs and permissions used by the ACL query.

The current role catalogue identifies the local role IDs and permissions used by the ACL query.

Interpret the descriptor’s limits

printRoleAccess evaluates the component’s controller/action rules with the selected role and a synthetic user context using the host organisation. Some rules are dynamic. The result is not a proof that a particular real user can read or modify every record behind a listed path. Controller/model checks still enforce ownership, distribution, sharing groups and resource-specific constraints. API-key scope and authentication restrictions are separate again.

A descriptor can contain wildcard patterns or route-name variants. It does not enumerate all HTTP methods, parameters, entity IDs or deployments behind a reverse proxy. Treat it as input to a WAF/access review, then test real permitted and denied requests; do not install it as a complete network policy without those checks.

The missing-function report is a development diagnostic, not a list of routes to open to every user. Inspect app/Controller/Component/ACLComponent.php, the discovered action and its model checks when adding a feature. See roles and developer testing.

MISP project resources

Use the MISP organisation to find project-owned repositories. Match the application, client, definitions and deployment revisions you actually use. A project-owned repository has its own releases and dependencies; this list does not certify every combination with the developing 3.0 branch.

Purpose Starting points
Application and deployment MISP core, misp-docker and the development guide.
Clients and automation PyMISP, misp-modules and misp-stix.
Structured data and knowledge misp-objects, misp-taxonomies and misp-galaxy.
Contextual lists misp-warninglists and misp-noticelist.
Community and authoring Cerebrate, MISP Engineering Bay and workflow blueprints.
Formats and guidance MISP standards, MISP formats, this book and threat-intelligence best practices.

For companion definitions, the files on disk, imported database entries and enabled state are separate. Follow the relevant data-model and update guidance. Normal book rendering does not fetch the latest content or connect to an instance.

Third-party integrations

Choose an integration for a specific input, output and workflow. The MISP tools directory and the product/provider’s current documentation are better discovery points than an unversioned historical list of connectors. For deployment, use the maintained release process of the chosen tool and verify its MISP server/client requirements.

Integration class Check before enabling it
SIEM, IDS and detection tooling Search/export scope, format support, pagination/checkpoints, update/delete behaviour and downstream interpretation of IDS flags.
Case management and response Ownership, observation/report mapping, relationship direction, retries and which actions change records in either system.
Enrichment, sample analysis and lookup Which data leaves the instance, provider credentials/terms, cached versus live results and provenance of returned claims.
Deployment or configuration management Supported branch/runtime, dependency pins, upgrades, secrets, jobs and a tested restore procedure.

Run a bounded test with reserved values and a suitably scoped key, then inspect the saved records and delivery result. A successful HTTP response or a connector’s presence in a list is not an end-to-end validation. Older integration claims such as “tested by the core team” do not establish current 3.0 compatibility. See External Connectors and Automation & API.

Threat-intelligence resources

Use external resources for a defined research question and preserve the source, date and uncertainty of any result you bring into MISP. Public availability is separate from reliability, licensing and the authority to redistribute information.

LDAP authentication

Configure the directory and authenticator

The shipped LdapAuth implementation uses the PHP LDAP extension in the application runtime. Install it through the deployment’s supported package/image process and verify both web and console runtimes. The plugin’s README provides the broader option reference; use the checked-out implementation to resolve any difference.

Merge the following fragments into the deployment-managed configuration. Supply $directoryOrgId and $directoryRoleId from the intended existing MISP organisation and role; no numeric role ID has a universal privilege meaning. Replace the reader-secret placeholder through the deployment’s secret-management process.

'LdapAuth' => [
    'ldapServer' => 'ldaps://ldap.example.org:636',
    'ldapDn' => 'ou=People,dc=example,dc=org',
    'ldapReaderUser' => 'cn=misp-reader,ou=Services,dc=example,dc=org',
    'ldapReaderPassword' => '<reader-secret-from-your-deployment>',
    'ldapSearchFilter' => '(objectClass=inetOrgPerson)',
    'ldapSearchAttribute' => 'mail',
    'ldapEmailField' => ['mail'],
    'ldapNetworkTimeout' => 10,
    'ldapDefaultOrgId' => $directoryOrgId,
    'ldapDefaultRoleId' => $directoryRoleId,
    'mixedAuth' => false,
    'updateUser' => true,
],

Also include the handler in Security.auth:

'Security' => [
    // Merge with the deployment's other Security settings.
    'auth' => ['LdapAuth.Ldap'],
    'auth_enforced' => true,
],

A LdapAuth block alone does not select the handler. Security.auth_enforced removes the built-in local Form authenticator; LdapAuth.mixedAuth controls the LDAP plugin’s own local fallback when a submitted user is absent from the directory. Setting only one does not express the whole login policy. Verify an out-of-band administrative recovery path and the intended browser/API/MFA behaviour before enforcing directory-only access.

The organisation default is ldapDefaultOrgId, not the historical ldapDefaultOrg spelling. Keep certificate verification and a correct CA/hostname in place for LDAPS or configured StartTLS; changing to plaintext is not a TLS diagnosis.

Resolve identity, organisation and role

ldapSearchAttribute selects the login identifier. ldapEmailField supplies the value used to find/link the MISP account; fields are tried in order and attribute names are matched without case sensitivity. dn is a special full-DN value, not its first character. Choose a unique, stable value. Changing it can create a second account while leaving the original account and its keys in place; there is no immutable LDAP identity link that automatically merges them.

Option Current resolution rule
ldapOrgField Read an organisation ID/name from the entry, resolving it against existing MISP organisations.
ldapOrgGroupMapping Map memberships to existing organisations; used after the attribute path when both are configured. Mapping order decides precedence among matching groups.
ldapDefaultOrgId Used when neither directory organisation mechanism is configured. A configured mapping that cannot resolve does not silently use this default.
ldapRoleField Read a role ID/name from the entry, resolving it against existing MISP roles.
ldapRoleGroupMapping Map memberships to roles after the attribute path; mapping order decides precedence.
ldapDefaultRoleId Scalar fallback when no role mapping is configured. The legacy array form remains a group map, with directory membership order rather than the new map’s precedence. The explicit new map takes priority when both are supplied.
updateUser With true, refresh an existing account’s organisation/role on login. With false, an existing account skips that provisioning refresh.

For example, directory membership can resolve both the organisation and role without assigning an arbitrary default. The example names must match the intended local records:

'ldapUseMemberOf' => true,
'ldapOrgGroupMapping' => [
    'CN=MISP-Research,OU=Groups,DC=example,DC=org' => 'Example Research',
],
'ldapRoleGroupMapping' => [
    'CN=MISP-Readers,OU=Groups,DC=example,DC=org' => 'Read Only',
],

With ldapUseMemberOf, mapping keys are full group DNs. Without it, the normal group lookup returns group CNs. ldapNestedGroups uses Active Directory’s matching-rule-in-chain OID; it is AD-specific, not a generic recursive lookup for every LDAP server. Test membership, precedence, missing attributes and unmapped users before relying on the resulting access scope.

ldapCheckUserAccountControl optionally checks the AD ACCOUNTDISABLE bit. Without that option, a directory entry’s presence is not the same as a check of that AD disabled flag. Missing organisation/role mappings, a disabled directory account and a local MISP disabled account are different states; inspect the actual refusal and saved account state.

Use a trusted front-end LDAP assertion

The 3.0 plugin also supports ldapHeaderAuth, ldapHeaderAuthHeader and ldapHeaderAuthTrustedProxies. This path accepts an identity asserted by a front end such as an authenticating Apache, then queries the directory and applies the same account-mapping rules. It does not authenticate an arbitrary header as a standalone MISP API key.

The trusted-proxy list supports exact addresses and IPv4/IPv6 CIDRs. It checks the direct REMOTE_ADDR, not a forwarded client-IP header. An empty list or untrusted peer does not trust the assertion and leaves the normal login path available. A trusted asserted identity must be found in LDAP; this path has no mixedAuth fallback to a local account. Strip untrusted identity headers at the edge and prevent direct clients from reaching the trusted backend path.

These controls are different from CustomAuth’s single calculated-source-IP comparison and header namespace rules. Follow the mechanism actually enabled on the instance.

Reconcile accounts outside a login

MISP 3.0 supports LDAP in User check_validity as well as OIDC. Start with the console help and a scoped report-only check before considering updates or disabling accounts:

sudo -u www-data /var/www/MISP/app/Console/cake User check_validity --help

The command’s --update option can refresh organisation/role when updateUser permits it; --block_invalid additionally disables invalid accounts. The LDAP implementation protects site administrators from automatic disabling/movement, skips already disabled users, and does not re-enable them as a reconciliation side effect. With mixedAuth enabled, an account absent from LDAP is left alone because it may be a legitimate local account. A failed reader bind aborts rather than judging every account absent. If both OIDC and LDAP handlers are configured, the command selects OIDC.

The recurring-task UI exposes separate report only and disable invalid users actions. The latter includes update/blocking behaviour; it is an operational change. The scheduler must be running, and results should be reviewed in the task/job logs. This is not an automatic revocation guarantee for every existing session, API key or external system. Include those credentials and retained accounts in the organisation’s offboarding process.

Diagnose the relevant layer

Check, in order: the active handler and login policy; application-runtime DNS/TLS and reader bind; search base/filter and returned identity fields; organisation/role/group mapping; then MISP disabled state, MFA and session/API behaviour. Use finite connection timeouts and test wrong credentials, missing mappings and removed/disabled users as well as successful logins.

The shipped standalone TestLdapAuth.php diagnostic prints configuration including the reader password. Keep its output private; it is not a safe file to attach unchanged to an issue. The branch also includes LDAP integration tests that require a real test directory and MISP instance, can alter configuration and provision accounts, and describe their fixture cleanup. Run those in an isolated environment, not against an operational directory as a connectivity probe.

Background jobs and recurring tasks

Use the current backend

MISP 3.0 uses SimpleBackgroundJobs, Redis and Supervisor. Install the release’s locked runtime/dependencies through the deployment process. Adding packages with composer require in an existing application or following a CakeResque migration recipe is not the current installation procedure. MISP.background_jobs controls background execution; there is no SimpleBackgroundJobs.enabled switch in this branch’s settings.

Inspect Administration → Server Settings & Maintenance → Background jobs. Configure the job Redis host, database/namespace and authentication separately from other Redis uses. Configure the Supervisor endpoint and credentials to match the actual process manager. The source supports HTTP XML-RPC or a Unix socket via SimpleBackgroundJobs.supervisor_host such as unix:/run/supervisor.sock, with the required cURL support and socket permissions. Reuse the deployment’s supported endpoint rather than exposing a new unauthenticated management port.

The actual background-job settings and status page. The capture instance leaves background execution disabled.

The actual background-job settings and status page. The capture instance leaves background execution disabled.

Distinguish queue workers from the scheduler

The ordinary queues are default, email, cache, prio and update. Their workers run cake start_worker QUEUE. The task scheduler is a different process: cake scheduler_worker discovers due recurring tasks and queues their work. Merely launching start_worker scheduler does not substitute for that polling process.

A Supervisor deployment needs the matching programs in the group MISP manages, normally misp-workers. The following shows the two process types, not a complete worker-pool configuration. The other ordinary queues need their own program sections and capacity:

[group:misp-workers]
programs=default,scheduler

[program:default]
directory=/var/www/MISP
command=/var/www/MISP/app/Console/cake start_worker default
user=www-data
numprocs=1
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true

[program:scheduler]
directory=/var/www/MISP
command=/var/www/MISP/app/Console/cake scheduler_worker
user=www-data
numprocs=1
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true

Adapt paths, service identity, logging/rotation and concurrency to the deployment. Check the actual release’s installation template and command help; a copied service file can lag the worker implementation. Run only the intended scheduler/pool, and review pending/in-flight jobs before replacing older services. Verify the new processes and job outcomes before retiring the old ones; queue flushing is destructive, not a normal migration step.

Inspect jobs and recurring tasks

Read-only starting points are:

sudo -u www-data /var/www/MISP/app/Console/cake Worker status
sudo -u www-data /var/www/MISP/app/Console/cake Worker showQueues
sudo -u www-data /var/www/MISP/app/Console/cake start_worker --help
sudo -u www-data /var/www/MISP/app/Console/cake scheduler_worker --help

Use Worker showJobStatus with the actual SQL job ID or process UUID. Worker restart and Worker restartDead change process state; check their help and scope first. Supervisor’s reported process state, Redis reachability, a waiting queue and a completed job answer different questions. Inspect each when diagnosing a stalled operation.

Recurring tasks are supported in this branch at /tasks/index. The UI defines an interval, next execution, action and execution user. Review that user’s permissions and the distinction between a report-only task and an action that updates, imports, disables users or pushes data. A saved schedule does not prove the scheduler ran or its queued job succeeded.

The scheduler dispatches due tasks; a separate worker performs the queued action and records its result.

The scheduler dispatches due tasks; a separate worker performs the queued action and records its result.

The current scheduled-task form, shown as a disabled unsaved draft with no task created.

The current scheduled-task form, shown as a disabled unsaved draft with no task created.

See background jobs, recurring tasks and workflows for operational procedures. Workflow triggers, recurring tasks and an external cron/orchestration system are distinct mechanisms.