Skip to content

Darktrace MCP v1.1.2

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 06 Oct 21:56
· 30 commits to main since this release
v1.1.2
126e5ea
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Changelog

1.1.2 — 2026-10-06

  • Docker setup is self-service. Choosing 2) docker in setup no longer asks for an image ID. The wizard resolves the docker path, checks that the daemon answers (docker version) and explains what to install or start when it does not, proposes ghcr.io/nuoframework/darktrace-mcp:<package version>, accepts a tag, a name@sha256: digest or a local sha256: image ID (strictly validated), offers Pull it now? [Y/n] when the image is missing (--pull for --yes runs) and shows docker pull progress. Client entries keep starting the immutable image ID with --pull=never, the caller's UID:GID and read-only token mounts; setup.json and the summary record the image ID and the registry digest for comparison with the GitHub Release notes. Nothing is written when a preflight step fails.
  • config and test with Docker. config <client> reuses the saved image ID and prints its digest. test / doctor --online first runs the image's --check-config in a container with the client entry's mounts and user and no network, then checks the appliance from the host.
  • No saved appliance URL in prompts. The wizard's URL prompt is Darktrace appliance URL (https://...): with no default and never prints a previously saved address; an empty answer is refused. --url and non-interactive reruns keep working.
  • Plugin bundle. claude-plugin/ packages the server as a Claude Code plugin (manifest with userConfig for the appliance URL, both tokens, profiles, the sensitive-write acknowledgement and the signature date format; a package.json and package-lock.json that install the published package at the pinned version when the plugin is installed; .mcp.json starting node on the installed entry; an icon; the darktrace-investigation skill) and, in the same folder, the portable plugin.json and mcp.json that Codex reads (Codex keeps the pinned npx launcher). Root .claude-plugin/marketplace.json and .agents/plugins/marketplace.json expose it as a repository marketplace for Claude Code and Codex. Plugin distribution describes the Claude Directory submission and the per-release version bump.
  • uninstall. New darktrace-mcp uninstall (alias remove --all) shows a plan, asks once (--yes, --dry-run), removes the darktrace entry from every client (backups kept), deletes the stored tokens, setup.json, the installer directory and the fixed copies (--keep-copies keeps them), removes the image ID recorded by setup with --docker (never other images), and prints the npm uninstall -g command when the package is installed globally. Symbolic links and unknown files are never touched.
  • Signed releases with provenance. The github-release job now signs every release asset with cosign (keyless Sigstore bundle <asset>.sigstore.json, identity release.yml@refs/tags/v<version>) and attests SLSA v1 build provenance for all assets with actions/attest (darktrace-mcp-<version>.intoto.jsonl, full bundle darktrace-mcp-<version>.provenance.sigstore.json, also stored in the GitHub attestations API). Verification commands: releases. The new sign-release.yml workflow adds signature bundles to releases published before this change without touching their assets (supply-chain checks).
  • Pinned npm fallback. publish-npm no longer runs npm install -g npm@^11 when the bundled npm is too old; it downloads the npm 11.21.0 tarball, verifies its registry sha512 integrity and runs it in place.
  • Property-based tests. 22 new tests with fast-check (test/unit/*-properties.test.ts) cover validatePathSegment, checkInput and validateSearchHash, the request signer (determinism, wire encoding round trip, encoded and unencoded signature modes, the Advanced Search Base64 segment, JSON bodies, UTC dates) and the canonical JSON and argsDigest behind preview binding and the audit chain. Functional CI pin 245 → 267 (release pins).
  • Runtime image: zlib 1.3.2-r1. Alpine v3.24 replaced zlib-1.3.2-r0 with 1.3.2-r1, whose recipe backports the fix for CVE-2026-85091 (the High finding retained in the patched runtime review). The architecture pins in the Dockerfile now name the r1 packages and their SHA-256; nothing else in the pinned input set changed. The CI Docker gates fetch and verify the set on every run, so the old pins could no longer be fetched.
  • Scorecard. scorecard.yml passes repo_token: ${{ secrets.SCORECARD_TOKEN || github.token }} so the owner can enable the Branch-Protection check with a fine-grained token. Supply-chain checks now record each Scorecard check, its status and the accepted gaps, and the remaining OpenSSF Best Practices silver criteria.
  • CodeQL. The open code-scanning alerts in the release and Docker scripts are fixed (scripts/prepare-docker-runtime.mjs, scripts/lab-read-smoke.mjs, scripts/verify-release.mjs); no production source changed. scripts/prepare-docker-runtime.mjs also fetches the committed APK revisions from the Alpine archive when the repository index has moved on, so the pinned input set stays reproducible.
  • Release workflow. publish-npm fails only when npm publish itself fails; it then polls the public registry for up to 15 minutes and records the tarball shasum and sha512 integrity when the version is still propagating. github-release runs unless a gate or a publish actually failed, and records the npm status in the release body (releases).
  • Dependencies. Runtime zod 4.2.0 → 4.6.5; development @types/node 24.0.0 → 26.6.4 and fast-check 4.10.2 added; GitHub Actions pins bumped by Dependabot. @modelcontextprotocol/server stays at 2.3.0.
  • Repository and documentation. No lab appliance hostnames remain in evidence, reports or probe defaults. CONTRIBUTING.md describes the pull request process and acceptance requirements; SECURITY.md states the vulnerability response-time commitment; both READMEs carry the OpenSSF Best Practices (project 15261) and Scorecard badges. The Darktrace/Email API shapes observed from a console capture are recorded as documentation only (observed shapes); the email action stays excluded.
  • Version pins. Install snippets, server.json, manifest.json and the version literal now say 1.1.2. The Claude Code plugin in claude-plugin/ keeps its exact pin on 1.1.1 until the registry shows 1.1.2 (plugin distribution); the release pins are in release-pins-1.1.2.md.

Known limitations in 1.1.2

  • Surface and lab evidence unchanged. 1.1.2 registers the same 77 executable operations in 50 tools as 1.1.1, with the same tool contracts and profile hashes; 59 operations have lab evidence, 6 of them partial. No new lab run was made for 1.1.2: production source changes are limited to src/cli/ and the version literal. Every item under known limitations in 1.1.1 still applies.
  • Distribution. Release assets are signed and carry build provenance from this release; the ghcr image still has no attestation, and the image published by release.yml is rebuilt, not the image the CI Docker job tested. The runtime image carries zlib 1.3.2-r1 (the Alpine backport for CVE-2026-85091); no new vulnerability scan of the 1.1.x runtime is recorded. The Docker setup path resolves and records the image digest but verifies no signature for the image: compare the digest with the release notes.
  • Plugin pin lag. The plugin installs an exact npm version, so the plugin on main follows a release by one merge; until that merge it installs the previous version.
  • Uninstall scope. uninstall removes only what setup wrote: the darktrace client entries, the token files, setup.json, the fixed copies and, with --docker, the one recorded image ID. A global npm install -g is reported, not removed; files it does not recognise are left in place.

1.1.1 — 2026-10-06

  • Lab evidence (gap campaign, 2026-10-06). New live runs on the Darktrace 7.1.0 lab, through the MCP stdio path and the final write controls (report). Now validated: post_devices, post_aianalyst_investigations, post_pcaps, get_pcaps_filename (both the whole-file and the output_limit_exceeded branch), get_advancedsearch_api_search_query, get_advancedsearch_api_analyze_field_analysis_query and get_advancedsearch_api_graph_graphmode_interval_query with the current Base64 path encoding, and post_antigena (activate, extend, clear, reactivate). 59 operations have lab evidence, 6 of them partial (was 56 and 11). Narrower partial notes for manual Antigena (connection only; pol, gpol, quarantineOutgoing got HTTP 400 on a client-sensor device), subnets (label, uniqueHostnames) and the intel feed (addentry, addlist, expiry, removeentry; hostname accepted but not read back). The three tag DELETE operations applied live, but the lab gateway still answers HTTP 502, so they stay not lab-validated with that note.
  • Lab driver. scripts/lab-gap-campaign.mjs drives the built server over MCP stdio for owner-authorised lab campaigns (token files only; critical actions through preview, confirm and the server dialog). scripts/lab-status-tap.mjs optionally records the HTTP status of each appliance response (method, route prefix and status only).
  • Error-code naming. Full model, component and enum lists surface the public error code response_limit_exceeded; earlier lab notes used the internal error kind too_large. PCAP output refusals remain output_limit_exceeded.
  • CI and supply-chain controls. CodeQL runs the JavaScript/TypeScript security-extended queries on production source and release scripts. ESLint with TypeScript and security rules runs in CI. Dependabot checks npm and GitHub Actions dependencies weekly, with runtime major upgrades reviewed by hand. OpenSSF Scorecard publishes scheduled analysis and SARIF results. Release helper fixes use fresh private temporary directories, exclusive output writes and descriptor-based reads that reject symlinks.

Known limitations in 1.1.1

  • Email. The action remains excluded; Email reads remain unvalidated because the lab token gets HTTP 403. Schemas come from darktrace-sdk 0.10.1.
  • Lab scope. One Darktrace 7.1.0 appliance and one broad token: 59 operations with evidence, 6 partial. Manual Antigena covers connection only (pol, gpol, quarantineOutgoing got HTTP 400 on a client-sensor device; quarantine and quarantineIncoming were not run). Subnet writes cover label and uniqueHostnames. Intel-feed writes cover addentry, addlist, expiry and removeentry; hostname was accepted but its flag could not be read back. Models, components and enums cover responsedata only; full lists fail with response_limit_exceeded. get_cves still gets HTTP 500 (Darktrace/OT only) and get_filtertypes HTTP 302; redirects are never followed.
  • PCAP. Whole-file downloads and the output_limit_exceeded refusal were checked live. Captures above about 45 KB still exceed the 60,000-character output budget.
  • DELETE. delete_tags_tid_entities_teid, delete_tags_entities and delete_tags_tid applied live, but the lab gateway answered HTTP 502. They remain not lab-validated; the server reports write_outcome_unknown, never retries, and opens the write breaker after three failed or unknown outcomes in one process.
  • Lab residue. The campaign left a completed capture, an investigation and its alert, an empty intel-feed source, and cleared Antigena actions. Device and subnet changes were restored; tags were deleted. Earlier undeletable test comments remain. See the campaign report.
  • The remaining limitations recorded for 1.1.0 still apply: consent and taint controls, per-process state, auditing, protected targets, token scope, egress, signing, distribution and preview eviction. The 1.1.0 lab-scope and PCAP notes below are historical; this section supersedes them.

1.1.0 — 2026-10-06

  • Public distribution. The package is @nuoframework/darktrace-mcp on the public npm registry (published from CI with npm trusted publishing and provenance), the image is ghcr.io/nuoframework/darktrace-mcp:<version> (linux/amd64 and linux/arm64, pinned by digest), and the server is described for the MCP Registry as io.github.nuoframework/darktrace-mcp (mcpName in package.json, server.json). Bootstrap: npx -y @nuoframework/darktrace-mcp@1.1.0 setup. When run from the npx cache, setup copies the verified package tree to ~/.local/share/darktrace-mcp/<version>/ and writes absolute node + dist/src/index.js paths, so clients never launch npx. These channels are live only after the owner's publication steps (releases).
  • Full API surface with profiles. 77 of the 79 catalogue operations are executable, as 50 tools. One operation is excluded (the Darktrace/Email action, below) and one is deprecated (GET /aianalyst/incidents). DARKTRACE_PROFILES selects read (default), sensitive, write, critical or all. Every Darktrace/Email read needs sensitive. 56 operations have evidence from one Darktrace 7.1.0 lab, 11 of them only partial; the others are marked "not lab-validated" (tool reference).
  • Write controls. Ordinary writes accept dryRun:true for a value-free preview; without it they run, relying on the host's tool-permission prompt (DARKTRACE_WRITE_APPROVAL=host, the default). Critical actions need a dryRun:true preview, then confirm:true with its single-use previewId (5 minutes) and, by default, an accepted server confirmation dialog (approved:true, at most one per session and four per process, 30-second deadline); a call without confirm:true is refused with confirmation_required. DARKTRACE_CRITICAL_APPROVAL=host needs DARKTRACE_ACKNOWLEDGE_HOST_APPROVAL=true. Writes are rate-limited (at most 10 per minute), a breaker stops all writes after three failed or unknown outcomes in a row until restart, optional protected targets and fixed per-call target caps apply, and every preview, refusal and write is written to a hash-chained audit line on stderr.
  • Sensitive and write together. Any profile list with both sensitive and write, including all, starts only with DARKTRACE_ACKNOWLEDGE_SENSITIVE_WRITE=true.
  • Darktrace/Email action excluded. darktrace_email_action is not registered in any profile: its signing and request schema are unvalidated and the lab token got 403.
  • Older variables. DARKTRACE_SENSITIVE_READ and DARKTRACE_WRITE_CRITICAL still work on their own. When DARKTRACE_PROFILES is set they may only agree with it or narrow it; a value that would add an unlisted capability stops startup.
  • Easier installation. New darktrace-mcp setup wizard (hidden token entry, 0600 token files under ~/.config/darktrace-mcp/, permission preset, automatic configuration of Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, OpenCode and Gemini CLI with backups), plus config <client>, remove and test. One-line installers scripts/install.sh and scripts/install.ps1.
  • Claude Desktop extension. npm run pack:mcpb builds a .mcpb bundle; Claude Desktop stores the tokens in the OS keychain.
  • Documentation restructure. Short bilingual READMEs; task-oriented guides (getting started, clients, configuration, troubleshooting, security overview) with Spanish versions in docs/es/; generated tool reference (npm run docs:tools); past review and release reports moved to docs/history/.

Known limitations in 1.1.0

From the 1.1.0 final gate review §4. None is an exploitable defect found in the server, and none is an owner acceptance of risk.

  1. Email. The email action is excluded. Email reads are not lab-validated (the lab token got 403). Their schemas come from darktrace-sdk 0.10.1, and responses may be sparse.
  2. Lab scope. One 7.1.0 appliance and one broad token. Partial tests: Antigena manual block and clear only; subnets label only; intel feed add and remove only; models, components and enums only with responsedata (full lists return too_large). Appliance errors: get_cves returns 500 and get_filtertypes returns 302. Most write evidence predates the final write controls; after them, only the intel-feed critical flow, the post_tags preview, the confirmation_required refusal and POST Advanced Search were checked live. The GET Advanced Search forms passed live only before their path encoding changed; the current encoding has probe evidence for = only.
  3. PCAP. A download is returned whole or fails with output_limit_exceeded. Captures above about 45 KB do not fit the 60,000-character output budget. The current contract was never tested live.
  4. DELETE and the write breaker. The lab gateway answers 502 to every DELETE after applying it, which the server records as outcome:"unknown". Three in a row open the write breaker until restart.
  5. Sensitive and write together. There is no taint control. Once acknowledged, ordinary free-text writes (comments, tag descriptions, labels) can carry sensitive data out of the appliance. Comments cannot be deleted and every appliance user can see them.
  6. Approval. Ordinary writes default to writeApproval=host: no server prompt. host mode delegates critical consent to the host. Auto-answering clients or "always allow" rules remove the human; the server cannot verify that a human answered.
  7. Per-process state. Rate limits, the breaker, previews and the audit chain are per process; several host processes multiply the budgets. Audit chains share one genesis and carry no boot identifier. The audit goes to stderr only, with no external anchor. A restart resets the breaker.
  8. Sensitive reads are not audited.
  9. Protected targets are opt-in and match literal values only. For post_antigena they match the action codeid, not the device. maxTargets is owner policy.
  10. Token scope. There is no least-privilege token mapping per profile. Appliance token permissions remain the real ceiling.
  11. Data egress. Every result, including Base64 PCAP data and email metadata, reaches the MCP host and its model provider.
  12. Signing. GET Advanced Search depends on proxies keeping percent-encoding byte-exact. A combined query and JSON body is refused.
  13. Distribution. No image attestation; the SBOMs are inventories, not clearances. The ghcr image is rebuilt in release.yml; it is not the CI-tested image. For 1.1.0, the linux/arm64 image passed the local Docker gates; linux/amd64 is verified only by CI on the release commit, and there is no vulnerability scan of the 1.1.0 runtime yet. Docker Desktop needs DARKTRACE_TOKEN_FILE_OWNER=root-or-current. The server.json OCI launch passes tokens as container environment variables, readable by anyone with Docker access. Native Windows cannot protect token files.
  14. Previews. The preview store evicts the oldest live critical preview once it holds 256 (availability only).
  15. Lab residue. Undeletable [mcp-test] and [mcp-ux] comments remain on the lab appliance.

1.0.0 — prepared 2026-10-06

  • Reviewed lab harness now requires schema-2 source/runtime and complete installed host SDK/Zod tree binding before SDK import; bounded deterministic hashing rejects symlinks and special files. Docker preflight/session use init, PID and memory limits. This is offline readiness, not final lab or image approval.

Private stable artifact preparation: package/server metadata is now 1.0.0, with private: true, unchanged dependencies and immutable false write capability. Historical alpha assets remain unchanged; publication approval is separate.

  • Added a private local Docker build recipe and hardened stdio setup with explicit nonroot identity, read-only token mounts, disabled daemon logging, no ports/TTY, restricted privileges/resources and immutable image selection for operator use. Final candidate image, appliance and provider gates remain separate.
  • Corrected object-first response unions so device arrays keep their reviewed projection; unmodeled fields still use bounded safe output. Output projection and text neutralization are not universal compatibility or sensitive-data-removal guarantees.
  • Bound MR-04's four complete MCP tools/list contracts (descriptions, input schemas, annotations and order) to reviewed fixture/profile hashes in candidate build evidence and checksums. Preparation compares generated listings with the versioned oracle and never recaptures it automatically.
  • Added release evidence verification for missing/altered contracts, metadata and checksums, full generator inputs including operation inventory, and source-only Docker/Spanish README/vector inputs. Runtime package allowlist and locked three-library runtime dependency/SRI remain unchanged.
  • Extended offline JSON/TOML and documentation launch checks to absolute installed executables, user-scoped setup, project-config trust warnings and reviewed immutable Docker templates; negative warnings are not executable advice.
  • Made isolated security receipts report a nullable revision with factual Git probe metadata when Git or a checkout is unavailable; test completeness and security assertions remain required.

No new CI, lab or image success is asserted by this section. Per-operation live compatibility is partial; unresolved compatibility/security, final independent artifact review and deployment/provider approval prevent stable publication.

0.1.0-alpha.0 — prepared 2026-10-05

Private alpha; no npm release or container publication.

  • Added English operator guides and Spanish quickstart with source installation and current MCP client configuration.

  • Documented API 6.1 evidence, the unvalidated 7.1 lab target and the 79-operation inventory: 54 executable by profile, five critical previews, 19 blocked and one excluded.

  • Added portable explicit build tooling, private package metadata, a shipped npm shrinkwrap and a compiled-runtime file allowlist.

  • Added offline CI and local private artifact inspection; credential examples use separate token-file paths and contain no secrets.

  • Added versioned private GitHub Release preparation, SHA256SUMS, verified runtime CycloneDX SBOM and installed-file inventory.

  • Added isolated reproducible archive verification, exact three-library runtime/SRI checks, help/version/doctor checks and JSON/TOML example validation.

  • Added test:security and Node 22/24 CI; manual preparation workflow has read-only repository permissions and does not publish.

Release publication, final independent review and live compatibility validation remain owner gates. This changelog is not release approval or a statement that all baseline controls have passed audit.

Published artifacts (126e5ea)

npm

Status: published

npx -y @nuoframework/darktrace-mcp@1.1.2 setup
{
  "name": "@nuoframework/darktrace-mcp",
  "version": "1.1.2",
  "dist.integrity": "sha512-TIdr8PaJ3/OtItU008JNS+Wq2eRTNkflMhPp+bG3fDl4R+XcZLhRoBdUhEqwmXlKJDoFQ30Wcp0WKv6Fev7E3Q==",
  "dist.shasum": "b83bb7b6a1eae79f8bd67c66459901a2a5f13098",
  "dist.tarball": "https://registry.npmjs.org/@nuoframework/darktrace-mcp/-/darktrace-mcp-1.1.2.tgz"
}

ghcr.io

ghcr.io/nuoframework/darktrace-mcp:1.1.2
ghcr.io/nuoframework/darktrace-mcp@sha256:fa261c2f7423fa79c66b0b5ddf74d6d8bb53b59a64608dda869959b43900d9ee
linux/amd64 sha256:8a7f06cb4c62ffe003e792a058dd7f38e4f51d00aa4a7fa757887f9971fe20f5
linux/arm64 sha256:2967fab09f65fd985e1c8304dc1e008642be51ea69a33fd2b376922639b0905b

Pin clients to the digest: darktrace-mcp setup --runtime docker --image ghcr.io/nuoframework/darktrace-mcp@sha256:fa261c2f7423fa79c66b0b5ddf74d6d8bb53b59a64608dda869959b43900d9ee

Claude Desktop bundle (.mcpb)

a6bed56e7fd3dcf891a4f13d5c516baeaf701dbec11e47247bd83b7135c67478  darktrace-mcp-1.1.2.mcpb

Docker gates (ci.yml at 126e5ea)

Verify downloads with sha256sum -c SHA256SUMS.

Signatures and provenance

Every asset has a keyless Sigstore signature from this workflow run (<asset>.sigstore.json, cosign) and SLSA build provenance (darktrace-mcp-1.1.2.intoto.jsonl; full bundle darktrace-mcp-1.1.2.provenance.sigstore.json; GitHub attestation). Verify, for example, the npm tarball:

gh attestation verify nuoframework-darktrace-mcp-1.1.2.tgz --repo nuoframework/darktrace-mcp
cosign verify-blob --bundle nuoframework-darktrace-mcp-1.1.2.tgz.sigstore.json \
  --certificate-identity https://github.com/nuoframework/darktrace-mcp/.github/workflows/release.yml@refs/tags/v1.1.2 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com nuoframework-darktrace-mcp-1.1.2.tgz
Assets 26
Loading