Migration guide

October 2026 development update

This section describes the current working-tree behavior. It supersedes the historical 0.9.0 notes below.

1. Upgrade to Node.js 22.19.0 or newer and run npm ci. The MCP SDK and bundled Inspector have been updated; node-nmap is no longer a dependency.
2. Use stdio for a local MCP client. Legacy MCP_TRANSPORT=sse is removed. Streamable HTTP binds to loopback by default. Public binding requires bearer verification, an issuer, audience, exact origin list, and HTTPS public URL.
3. Give authenticated HTTP tokens read, write, or execute scopes for the operations they need. Map provider-specific names with MCP_AUTH_READ_SCOPE, MCP_AUTH_WRITE_SCOPE, and MCP_AUTH_EXECUTE_SCOPE. MCP_AUTH_SCOPES is ignored. Remote scanner calls also require MCP_REMOTE_EXECUTION_ENABLED=true on a dedicated deployment.
4. Create an engagement with its signed authorization reference, allowed and excluded targets, and authorization time window. Active tools require that engagement ID. Existing calls without it will fail schema validation.
5. Supply recordIds explicitly to createClientReport, including [] when no scanner evidence is attached. Existing scopeMode and elicitation arguments are removed; executable scope comes from the engagement record.
6. Set MCP_NUCLEI_TEMPLATES_DIR to an absolute reviewed, signed HTTP template directory before using Nuclei. Caller-selected template paths are disabled. The optional docker-compose.nuclei.yml mounts a host template directory read-only. Docker Compose defaults to local stdio; HTTP and Linux packet capture use explicit profiles.
7. Set PENTEST_DATA_DIR to a private persistent directory and migrate any records you need from older logs manually. The new evidence and report files have a different format and do not import legacy scan journals.
8. Remove all client calls to setMode. There is one researcher workflow and all MCP actions are logged. The package is licensed AGPL-3.0-or-later.
9. For managed assessment, save an assessment plan with exact allowedToolNames, then configure a private PENTEST_AGENT_PROFILES_FILE. Local codex exec and claude -p profiles need dedicated home, work, and MCP data directories but no hosted API key. Container Codex adds a pinned image and bridge root. API profiles are report-only.
10. Use modelDataPolicy: "local-agent" when engagement data must stay in a local CLI process. Use approved-provider only when that provider and the client-work route are approved. Daybreak access is optional.
11. After an interrupted managed run, the durable start receipt blocks replay. Confirm that the former model process stopped, then call reconcileAgentAssessment with its run ID, reviewer, and rationale. This closes the former worker scope when its private directory is available.
12. Replace packaged fixture receipts with scripts/run-real-acceptance.mjs. The verifier has no default target or authorization and writes evidence only to the explicitly selected private data directory.

Historical migration: 0.8.x -> 0.9.0

Summary

Version 0.9.0 hardens tool resolution, expands full workflow coverage, and reduces report/admin overhead.

Breaking / Notable Changes

• Node.js baseline is now >=22.7.5 (required for bundled latest MCP Inspector)
• Streamable HTTP (MCP_TRANSPORT=http) is the recommended network mode
• SSE remains supported but deprecated
• Auth config moved to MCP_AUTH_* + MCP_OIDC_* variables
• New tools added: trafficCapture, hydraBruteforce, privEscAudit, extractionSweep
• New report-admin tools: listEngagementRecords, getEngagementRecord
• createClientReport now supports SoW capture through MCP elicitation (scopeMode=ask) with automatic template fallback
• httpx resolution is hardened:
  • prefers httpx-toolkit
  • validates fallback httpx is ProjectDiscovery-compatible
  • rejects Python HTTPX CLI collisions
• Bundled inspector launcher added: pentest-mcp inspector

Environment Variable Migration

Preferred (new)

• MCP_AUTH_ENABLED
• MCP_AUTH_MODE (currently bearer)
• MCP_AUTH_SCOPES
• MCP_AUTH_AUDIENCE
• MCP_OIDC_ISSUER
• MCP_OIDC_JWKS_URL
• MCP_OIDC_INTROSPECTION_URL

Legacy aliases (temporary)

• MCP_OAUTH_ENABLED -> MCP_AUTH_ENABLED
• MCP_OAUTH_PROVIDER_URL -> MCP_OIDC_ISSUER
• MCP_OAUTH_SCOPES -> MCP_AUTH_SCOPES

Transport Migration

Recommended

MCP_TRANSPORT=http npm start

Legacy compatibility

MCP_TRANSPORT=sse npm start

SSE mode now emits deprecation warnings and should be phased out.

Docker Migration

No compose profile names changed. Existing profiles still work:

docker-compose --profile stdio up
docker-compose --profile http up
docker-compose --profile sse up

Docker image now includes hydra, sqlmap, tcpdump, and an httpx-toolkit alias to ProjectDiscovery httpx.

Inspector Migration

Instead of installing Inspector separately:

pentest-mcp inspector

You can pass Inspector flags directly:

pentest-mcp inspector --help

Validation Checklist

1. Confirm Node runtime is 22.7.5+.
2. Run npm install and npm run build.
3. Start in http mode and verify /health.
4. Test one recon tool (httpxProbe) and one workflow tool (hydraBruteforce or extractionSweep).
5. Run pentest-mcp inspector and confirm Inspector comes up without separate install.
6. If auth is enabled, verify both missing-token and valid-token paths.