agentic-misp-mcp

MISP workflows for agents — investigate, pivot, report, and propose controlled writes without turning your MCP server into a raw API proxy.

agentic-misp-mcp is an early-stage MCP server for security analysts working with MISP threat intelligence. It gives AI agents a small set of analyst-oriented workflows: search an IOC, investigate context, pivot through related indicators, summarize events, generate reports, and prepare tightly controlled write proposals.

It exists because agents should not need unrestricted MISP API access to help with SOC work. Instead of exposing every endpoint, this project exposes opinionated workflows with bounded output, policy checks, and audit logging.

Status

• Early development; APIs, outputs, and internals may still change.

• Mocked test coverage exists for core workflows and policy paths.

• Live read-only lab validation has passed against MISP 2.5.42 using Docker, stdio transport, and MCP Inspector.

• Core controlled-write validation has been performed in the same MISP lab (submit_ioc_with_approval, add_sighting_with_approval, tag_event_with_approval, publish_event_with_approval, plus role/policy blocking); two real bugs found during that pass are fixed (see below).

• Edge-case validation and production-hardening checks remain pending: propose_event/propose_attribute payload validation, large event/result-set behavior, rate-limit/timeout/TLS failure modes, warninglist endpoint compatibility across MISP versions, broader MISP version compatibility, and final sign-off. See docs/live-validation-plan.md.

• Production deployment is not yet validated. See docs/production-readiness.md for the production-readiness scope, requirements, and acceptance criteria.

• Not production-ready: validated in a lab, not production-certified.

• Current MCP tool count: 19.

• Primary transport: stdio.

• HTTP transport exists but is experimental.

• Requires Python 3.11+.

• License: MIT.

Related MCP server: misp-mcp

Quick start

There are two ways to run agentic-misp-mcp: local (Python/uv, no Docker needed) or Docker. Pick one — both end up in the same place, an MCP server your client can talk to.

Prerequisites

• A MISP instance you can reach, and an API key for it (MISP_URL, MISP_API_KEY).

• Python 3.11+ for the local path, or Docker for the Docker path.

• An MCP client to actually use it (Claude Desktop, Claude Code, MCP Inspector, etc.).

Option A — Local install (Python / uv)

1. Install:

   pip install -e ".[dev]"
   # or, with uv:
   uv sync --extra dev

2. Configure your MISP connection:

   cp .env.example .env
   # edit .env — at minimum set MISP_URL and MISP_API_KEY

3. Validate configuration (no MISP connection is made; the API key is redacted):

   agentic-misp-mcp config-check
   # or: uv run agentic-misp-mcp config-check

4. Run the server over stdio (the primary supported transport):

   agentic-misp-mcp --transport stdio
   # or: uv run agentic-misp-mcp --transport stdio

5. Point your MCP client at it. Example config (works from any working directory, since uv --directory targets the repo explicitly):

   {
     "mcpServers": {
       "agentic-misp-mcp": {
         "command": "uv",
         "args": [
           "--directory", "/path/to/agentic-misp-mcp",
           "run", "agentic-misp-mcp", "--transport", "stdio"
         ],
         "env": {
           "MISP_URL": "https://misp.example.local",
           "MISP_API_KEY": "your_misp_api_key_here"
         }
       }
     }
   }

   If you installed with pip into an environment already on your PATH, you can use "command": "agentic-misp-mcp" with "args": ["--transport", "stdio"] instead of the uv wrapper.

Option B — Docker

1. Build the image:

   git clone https://github.com/hdyrawan/agentic-misp-mcp.git
   cd agentic-misp-mcp
   docker build -t agentic-misp-mcp:local .

2. Create an env file outside the repository (never commit real credentials) and a directory for audit logs:

   mkdir -p ~/.config/agentic-misp-mcp
   cp .env.example ~/.config/agentic-misp-mcp/.env
   # edit ~/.config/agentic-misp-mcp/.env — at minimum set MISP_URL and MISP_API_KEY
   mkdir -p ~/.local/state/agentic-misp-mcp/logs

   (Prefer Compose? docker-compose.example.yml does the same thing — see docs/configuration.md.)

3. Validate configuration:

   docker run --rm \
     --env-file ~/.config/agentic-misp-mcp/.env \
     -v ~/.local/state/agentic-misp-mcp/logs:/app/logs \
     agentic-misp-mcp:local config-check

4. Run the server over stdio:

   docker run --rm -i \
     --env-file ~/.config/agentic-misp-mcp/.env \
     -v ~/.local/state/agentic-misp-mcp/logs:/app/logs \
     agentic-misp-mcp:local --transport stdio

5. Point your MCP client at it (assumes your client can spawn docker on the same host — for a remote/headless Docker host, run the client there too, or see the SSH-tunnel note below):

   {
     "mcpServers": {
       "agentic-misp-mcp": {
         "command": "docker",
         "args": [
           "run", "--rm", "-i",
           "--env-file", "/home/you/.config/agentic-misp-mcp/.env",
           "-v", "/home/you/.local/state/agentic-misp-mcp/logs:/app/logs",
           "agentic-misp-mcp:local",
           "--transport", "stdio"
         ]
       }
     }
   }

Verify it's working

Either path: config-check should print Configuration check: OK with MISP_API_KEY is set ([REDACTED]). Then ask your MCP client to run a read-only tool — for example search_ioc with a known indicator — and confirm you get a structured JSON result back. See "Testing against a live MISP lab" below for a deeper validation walkthrough (MCP Inspector, SSH tunneling, a read-only test checklist).

Live lab validation status

The first live validation was performed against a controlled, non-production MISP lab.

The first positive live IOC test used 54.87.87.13, which matched MISP event 187, OSINT - NANHAISHU RATing the South China Sea. The generated IOC report classified the IOC as suspicious with medium confidence based on live MISP matches, actionable to_ids attributes, related event context, and extracted related IOCs.

Additional read-only validation confirmed that domain-side searches for composite domain|ip attributes work, including mines.port0.org and eholidays.mooo.com. SHA256 lookup was also validated using a related payload-delivery hash from the same event.

Because the first positive live test used historical OSINT data, analyst workflows should correlate hits with current local telemetry before blocking or escalation.

Safety model

This project is workflow-first, not endpoint-first.

• Read-only by default.

• Controlled write tools exist but are disabled by default: AGENTIC_MISP_MCP_ENABLE_WRITE=false.

• Approval is required by default when writes are enabled: AGENTIC_MISP_MCP_REQUIRE_APPROVAL=true.

• MISP_API_KEY is loaded only from environment variables.

• No API key, token, password, authorization header, or secret passthrough through MCP tool arguments.

• No raw MISP API proxy.

• No generic user/organisation/server/settings admin tools.

• No shell execution or unrestricted filesystem tools.

• Every MCP tool call is audited with sanitized arguments and policy decision fields.

Important approval limitation: lab approval mode and production approval mode are different. In AGENTIC_MISP_MCP_APPROVAL_MODE=lab (the default), approved=true is only a programmatic lab gate; AGENTIC_MISP_MCP_APPROVAL_TOKEN is an optional shared-secret control for that lab flow and is not the production approval mechanism. In AGENTIC_MISP_MCP_APPROVAL_MODE=production, approved=true alone never executes a write. Production execution requires a persisted approval_request_id that was approved out of band with the operator CLI, is one-time-use, TTL-bound, and exact operation-hash-bound.

Current MCP tools

Read-only investigation

• search_ioc(value, limit=20) — find normalized MISP attribute matches.

• investigate_ioc(value, limit=20) — combine matches, warninglists, related events, scoring, and next steps.

• summarize_event(event_id) — summarize a MISP event without returning full raw event JSON.

• check_warninglists(value) — check an IOC against warninglists when available.

Pivoting and event intelligence

• pivot_ioc(value, limit=20) — pivot from one IOC into useful related context.

• find_related_iocs(value, limit=20) — rank related indicators.

• extract_event_iocs(event_id, limit=100) — extract supported IOC types from an event.

• explain_event_context(event_id) — explain what an event appears to represent.

• find_events_by_tag(tag, limit=20) — find events associated with a tag.

Reporting

• generate_ioc_report(value) — deterministic structured IOC report.

• generate_event_report(event_id) — deterministic structured event report.

• generate_markdown_ioc_report(value) — Markdown IOC report for analyst notes or escalation.

• generate_markdown_event_report(event_id) — Markdown event report.

Proposal-only tools that never write to MISP

These tools build reviewable payloads only. They are policy-gated, but they never invoke MISP write endpoints.

• propose_event(...) — build an event creation proposal; never writes to MISP.

• propose_attribute(...) — build an attribute creation proposal; never writes to MISP.

Approval-gated write tools

These tools are blocked unless write mode and role allow the action; write execution also requires explicit approval by default.

• submit_ioc_with_approval(..., approved=False, approval_token=None, approval_request_id=None) — add an attribute only when policy and approval allow.

• add_sighting_with_approval(..., approved=False, approval_token=None, approval_request_id=None) — add a sighting only when policy and approval allow.

• tag_event_with_approval(event_id, tag, approved=False, approval_token=None, approval_request_id=None) — tag an event only when policy and approval allow.

• publish_event_with_approval(event_id, approved=False, approval_token=None, approval_request_id=None) — publish an event only for curator/admin roles and approval.

Write-tool results are explicit: blocked, pending_approval, or executed. There are no silent writes.

Testing against a live MISP lab (optional)

Beyond the Quick start above, this section covers the deeper flow used for this project's own live-lab validation (see the validation table below) — useful if you want to reproduce it, or run the same checks against your own non-production MISP lab. It assumes you already completed the Docker Quick start above (image built, env file and log directory created).

Test MISP connectivity from inside the container

docker run --rm \
  --env-file ~/.config/agentic-misp-mcp/.env \
  --entrypoint python \
  agentic-misp-mcp:local \
  -c "import os, httpx; verify=os.environ.get('MISP_VERIFY_TLS','true').lower()=='true'; r=httpx.get(os.environ['MISP_URL'].rstrip('/') + '/servers/getVersion', headers={'Authorization': os.environ['MISP_API_KEY'], 'Accept':'application/json'}, verify=verify, timeout=10); print('STATUS:', r.status_code); print(r.text[:1000])"

A STATUS: 200 response confirms the container can reach the MISP API before running any MCP tools.

Run with MCP Inspector

Against Docker:

npx @modelcontextprotocol/inspector@0.22.0 \
  docker run --rm -i \
    --env-file ~/.config/agentic-misp-mcp/.env \
    -v ~/.local/state/agentic-misp-mcp/logs:/app/logs \
    agentic-misp-mcp:local --transport stdio

Against a local (non-Docker) install:

npx @modelcontextprotocol/inspector@0.22.0 \
  uv --directory /path/to/agentic-misp-mcp run agentic-misp-mcp --transport stdio

For headless/CI use (no browser UI), pass --cli and --method:

npx -y @modelcontextprotocol/inspector --cli \
  uv --directory /path/to/agentic-misp-mcp run agentic-misp-mcp \
  --method tools/list

Headless host access with SSH tunnel

MCP Inspector's browser UI serves its client and proxy on ports 6274 and 6277. When Inspector runs on a headless Linux host, forward both ports over SSH and open the UI from your workstation browser:

ssh -L 6274:localhost:6274 -L 6277:localhost:6277 user@mcp-host.example.local

Then browse to http://localhost:6274 on the workstation. (The --cli mode above avoids needing this entirely.)

Check audit logs

tail -n 20 ~/.local/state/agentic-misp-mcp/logs/audit.jsonl | jq .

Audit entries are JSONL, with sanitized arguments and policy decision fields. Successful calls, validation failures, runtime errors, blocked write attempts, and MISP-side write rejections (outcome: "failed") are all recorded — see docs/security.md for the full outcome semantics.

Read-only live test checklist

Use this checklist for a controlled, non-production MISP lab:

• Run config-check.

• Confirm /servers/getVersion returns HTTP 200 from inside the Docker container.

• Connect MCP Inspector over stdio.

• Run tools/list.

• Run search_ioc for a known non-matching IOC and confirm clean no-match behavior.

• Run search_ioc for a known matching IPv4 indicator.

• Run search_ioc for a known matching domain indicator.

• Run search_ioc for a known matching SHA256 indicator.

• Run investigate_ioc for a known matching IOC.

• Run summarize_event for a known event ID.

• Run generate_ioc_report for a known matching IOC.

• Run check_warninglists for representative public, private, or lab indicators.

• Attempt one write tool while AGENTIC_MISP_MCP_ROLE=read_only and AGENTIC_MISP_MCP_ENABLE_WRITE=false; confirm it is blocked.

• Search for the attempted test write value and confirm MISP was not modified.

• Check audit.jsonl for successful calls, validation failures, runtime errors, and blocked write decisions.

• Confirm no write tools were executed.

The specific IOC and event ID values used in one lab may not exist in another MISP instance. Use known-good indicators from your own lab dataset. For the controlled-write path (propose_event/propose_attribute/the four _with_approval tools), see docs/approval-flow.md and docs/live-validation-plan.md — never run write testing against anything but an isolated lab.

Example agent prompts

• "Investigate this IOC: 1.2.3.4. Give me verdict, confidence, related events, and next steps."

• "Pivot from this domain and list related IOCs worth hunting: example.test."

• "Summarize MISP event 42 for a SOC handoff."

• "Generate a Markdown IOC report for http://evil.example.test/x."

• "Propose a MISP event for this phishing cluster, but do not write it yet."

• "Submit this IOC to event 42 with approval after showing the pending approval payload."

Configuration

See docs/configuration.md for more examples.

Production deployment

This project is not yet certified production-ready — see docs/production-readiness.md for the full scope, requirements, and the acceptance criteria that must pass before that changes. This section shows the conservative deployment shape for the one target that document is scoped against first: read-only investigation and reporting (AGENTIC_MISP_MCP_ROLE=read_only, AGENTIC_MISP_MCP_ENABLE_WRITE=false) over stdio, via Docker.

1. Build the image:

   git clone https://github.com/hdyrawan/agentic-misp-mcp.git
   cd agentic-misp-mcp
   docker build -t agentic-misp-mcp:local .

2. Configure a production env file outside the repository, starting from the production-oriented template (placeholders only — see .env.production.example for the full file with inline guidance):

   mkdir -p /path/to/agentic-misp-mcp-runtime/logs
   cp .env.production.example /path/to/agentic-misp-mcp-runtime/.env
   # edit /path/to/agentic-misp-mcp-runtime/.env — set MISP_URL and MISP_API_KEY;
   # leave MISP_VERIFY_TLS=true, AGENTIC_MISP_MCP_ROLE=read_only,
   # AGENTIC_MISP_MCP_ENABLE_WRITE=false, and AGENTIC_MISP_MCP_REQUIRE_APPROVAL=true as-is.

3. Run config-check before starting the server, every time the configuration changes:

   docker run --rm \
     --env-file /path/to/agentic-misp-mcp-runtime/.env \
     -v /path/to/agentic-misp-mcp-runtime/logs:/app/logs \
     agentic-misp-mcp:local config-check

   This validates configuration and confirms the audit-log path is writable. It does not connect to MISP.

4. Test MISP connectivity before wiring up an MCP client, to confirm the deployment can actually reach MISP with the configured TLS settings:

   docker run --rm \
     --env-file /path/to/agentic-misp-mcp-runtime/.env \
     --entrypoint python \
     agentic-misp-mcp:local \
     -c "import os, httpx; verify=os.environ.get('MISP_VERIFY_TLS','true').lower()=='true'; r=httpx.get(os.environ['MISP_URL'].rstrip('/') + '/servers/getVersion', headers={'Authorization': os.environ['MISP_API_KEY'], 'Accept':'application/json'}, verify=verify, timeout=10); print('STATUS:', r.status_code)"

   Expect STATUS: 200. A TLS or connection error here means fix the deployment's network/CA configuration before proceeding — do not fall back to MISP_VERIFY_TLS=false to make this pass; that setting is lab-only (see docs/production-readiness.md).

5. Run the server over stdio, with the audit log directory mounted so logs persist across container restarts:

   docker run --rm -i \
     --env-file /path/to/agentic-misp-mcp-runtime/.env \
     -v /path/to/agentic-misp-mcp-runtime/logs:/app/logs \
     agentic-misp-mcp:local --transport stdio

   Point your MCP client at this same docker run invocation (see the Docker Quick start above for an example client config) — the client, not this container, decides when to start/stop the process, so there is no separate "daemon" to manage.

HTTP transport is not the default recommendation for production. It is experimental, has no built-in authentication or TLS, and refuses to bind 0.0.0.0 unless AGENTIC_MISP_MCP_ALLOW_INSECURE_HTTP_BIND=true is explicitly set. If you use it in production at all, it must sit behind an authenticated, TLS-terminating gateway (reverse proxy or service mesh) that terminates TLS and enforces authentication before any traffic reaches this server — stdio remains the primary supported production transport.

Before treating any deployment as production, review docs/production-readiness.md's Docker hardening checklist (read-only root filesystem, resource limits, base-image patching) and release/sign-off checklist in full — this section covers the conservative deployment shape, not the complete readiness bar.

Security notes

• Use stdio by default.

• Treat HTTP transport as experimental. Binding to 0.0.0.0 is refused by default because HTTP mode has no built-in auth/TLS; use 127.0.0.1 or place it behind authenticated TLS termination and explicitly opt in.

• Keep .env, audit logs, and API keys out of git.

• Automated tests still use mocked MISP responses.

• First manual read-only live lab validation has passed against MISP 2.5.42; controlled-write validation has since passed against the same lab. Broader MISP version compatibility remains pending.

• A read-only write-block test confirmed that approved=true does not bypass disabled write mode or the read_only role.

• Blocked policy decisions are audited with allowed=false, success=false, and outcome=blocked.

• Successful allowed calls are audited with outcome=success; runtime failures are audited with outcome=error; a controlled write that reaches MISP but is rejected by MISP itself (saved/published: false) is audited with outcome=failed.

• Approval tokens and other sensitive values are redacted in audit logs.

• See SECURITY.md and docs/security.md for reporting and deployment guidance.

Documentation

• docs/security.md — security model, tool boundary, audit logging.

• docs/configuration.md — full environment variable reference.

• docs/testing.md — what the mocked test suite covers and does not cover yet.

• docs/roles.md — read_only / analyst_write / curator / admin policy roles.

• docs/approval-flow.md — lab approval flow plus the v0.2.0-beta.1 production approval flow.

• docs/live-validation-plan.md — completed lab validation evidence and remaining validation work.

• docs/live-beta-validation-v0.2.0-beta.1.md — live beta validation checklist before tagging v0.2.0-beta.1.

• docs/production-readiness.md — production-readiness scope, requirements, and release/sign-off acceptance criteria.

• docs/openapi-inventory.md — sample MISP OpenAPI endpoint classification (planning only).

Development

uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev pytest -q

Equivalent Make targets:

make lint
make format-check
make test
make check

CI runs the same checks on Python 3.11 and 3.12.

Known live validation limitations

The first positive live validation used historical OSINT data from 2016. This is useful for proving MISP API compatibility and MCP workflow behavior, but it should not be treated as current threat activity without telemetry correlation.

Future scoring improvements should consider stale-intel labeling or event-age weighting.

Controlled write execution has been validated against an isolated lab (see the table above). Two real bugs surfaced during that pass and are now fixed:

• A present-but-empty AGENTIC_MISP_MCP_APPROVAL_TOKEN (e.g. KEY= in a .env file) was parsed as a configured empty-string token rather than "no token configured," silently blocking every controlled-write execution. Blank/whitespace-only tokens now normalize to unset.

• tag_event_with_approval and publish_event_with_approval reported status: "executed" even when MISP itself rejected the operation (saved/published: false on an HTTP 200 response, e.g. an unrecognized tag name). They now report a distinct status: "failed", with a matching outcome: "failed" audit entry, so a caller cannot mistake a MISP-side rejection for a real write. See docs/approval-flow.md.

Roadmap

• Complete remaining live lab validation: propose_event/propose_attribute payload validation, warninglist edge cases, large event/result-set behavior, rate-limit/timeout/TLS failure modes, broader MISP version compatibility, and final sign-off (docs/live-validation-plan.md section 9). (Read-only tools, error paths for unreachable MISP_URL/invalid MISP_API_KEY, and the four _with_approval controlled-write tools are now validated.)

• Add broader audit outcome tests for additional write tools and error paths.

• Add stale-intel labeling or event-age weighting for historical OSINT context.

• Compatibility notes for MISP version differences, especially warninglists and event shapes.

• Release tagging and packaging once the live validation story is documented.

• Additional controlled workflows only when they preserve the no-raw-proxy, policy-gated model.

Contributing

Contributions are welcome, but keep the project boundary intact: no raw API proxy, no secret passthrough, no unaudited tool path, and no write behavior without policy and approval gates. Start by reading PROJECT_STATE.md, docs/security.md, and src/agentic_misp_mcp/tools/registry.py.

Commits should be attributed to their human author only — do not add AI co-author trailers (for example Co-Authored-By: <AI assistant>) to commits in this repository, regardless of what tooling was used to help write them.

v0.2.0-beta.1 production-write beta candidate

The current main branch contains the v0.2.0-beta.1 production-write beta candidate. It is suitable for isolated pilot validation, not GA production use. The default approval mode remains AGENTIC_MISP_MCP_APPROVAL_MODE=lab, preserving the existing approved=true lab flow. A new opt-in production mode adds persisted SQLite approvals for the four existing write-executing tools only: submit_ioc_with_approval, add_sighting_with_approval, tag_event_with_approval, and publish_event_with_approval. No new MISP endpoints, raw proxy behavior, or admin tools are exposed.

In production mode, approved=true alone is blocked, even if AGENTIC_MISP_MCP_REQUIRE_APPROVAL=false. Execution requires an operator-approved approval_request_id from agentic-misp-mcp approvals ...; no MCP tool can approve or reject. Each production approval is one-time-use, TTL-bound by AGENTIC_MISP_MCP_APPROVAL_TTL_SECONDS, and bound to the exact canonical operation hash. The LLM/agent must not have shell access to the approval CLI or write access to the SQLite approval database. If redemption succeeds but the later MISP write fails, the approval remains consumed; the operator must approve a new request for any retry. Publishing is disabled by default with AGENTIC_MISP_MCP_ENABLE_PUBLISH=false; additional production guardrails include AGENTIC_MISP_MCP_ALLOWED_ATTRIBUTE_TYPES, AGENTIC_MISP_MCP_ALLOWED_ATTRIBUTE_CATEGORIES, and AGENTIC_MISP_MCP_ALLOWED_TAGS.

See docs/production-write.md for the full beta deployment guidance and approval-store permission requirements.