registry / AI-agent control-surface risk / docdex

docdex

Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.

This report shows the evidence for docdex@0.2.98. 5 of 8 known versions are blocked or flagged. The newest version, 0.2.99, is allowed. See all versions.

AI Security Review

scanned 3mo ago · by lpm-firewall-ai

The confirmed postinstall chain mutates a broad foreign AI-agent control surface and establishes persistence. This meets the block policy despite package-aligned loopback networking and release-download integrity checks.

Static reason

High-risk behavior combination matched malicious policy.; source matched previously finalized malicious package; routed for review; source fingerprint signature matched known malicious package; routed for review

Trigger

npm postinstall

Impact

Foreign AI clients gain a new default MCP endpoint and agent behavior is influenced automatically.

Mechanism

broad AI-agent MCP registration and persistent local-daemon setup

Policy narrative

Installing the package invokes install.js, which fetches and installs a platform binary, then invokes postinstall_setup.js. That setup writes a Docdex MCP server into configuration files for multiple unrelated AI products, including Codex, and enables a user-level persistent daemon. The lifecycle script also copies agent instructions containing mandatory behavioral directives into ~/.docdex/agents.md. These actions occur without an explicit user setup command.

AI rationale

Evidence

package.jsonlib/install.jslib/postinstall_setup.jsassets/agents.mdlib/uninstall.jslib/update_check.js

Network endpoints4

127.0.0.1:28491/sse127.0.0.1:28491/v1/mcpgithub.com/${repoSlug}/releases/downloadregistry.npmjs.org/docdex/latest

Decision evidence

public snapshot

AI identified this as a dangerous AI-agent capability at 99.0% confidence with low false-positive risk.

Evidence for policy risk

package.json runs lib/install.js on postinstall.
lib/install.js unconditionally calls runPostInstallSetup after downloading/extracting a binary.
lib/postinstall_setup.js writes Docdex MCP entries into Claude, Cursor, Windsurf, VS Code, Codex, and other client configs.
lib/postinstall_setup.js registers and starts a persistent user daemon via launchd/systemd/schtasks.
assets/agents.md contains mandatory directives that are installed to ~/.docdex/agents.md during postinstall.

Evidence against

Installer downloads from the declared GitHub release path and verifies SHA-256 metadata.
MCP URLs are loopback-only: 127.0.0.1:28491.
update_check.js only contacts the npm registry during an interactive, enabled update check.

Behavioral surface

Source

ChildProcessCryptoDynamicRequireEnvironmentVarsFilesystemNetwork

Supply chain

HighEntropyStringsUrlStrings

Source & flagged code

12 flagged

package.jsonView file

Lines 1-40json

2 "name": "docdex",

3 "version": "0.2.98",

4 "mcpName": "io.github.bekirdag/docdex",

5 "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",

6 "bin": {

7 "docdex": "lib/cli_entry.js",

8 "docdexd": "lib/cli_entry.js",

9 "docdex-mcp-stdio": "lib/mcp_stdio_cli.js"

10 },

11 "files": [

12 "bin",

13 "lib",

14 "assets",

15 "README.md",

16 "CHANGELOG.md",

17 "LICENSE"

18 ],

19 "scripts": {

20 "postinstall": "node ./lib/install.js",

High

Install Time Lifecycle Scripts

Package defines install-time lifecycle scripts.

package.jsonView on unpkg · L20

Medium

Ambiguous Install Lifecycle Script

Install-time lifecycle script is not statically allowlisted and needs review.

package.jsonView on unpkg · L20

21 "preuninstall": "node ./lib/uninstall.js",

22 "postuninstall": "node ./lib/uninstall.js",

23 "test": "node --test",

24 "pack:verify": "node --test test/packaging_guardrails.test.js"

25 },

26 "engines": {

27 "node": ">=18"

28 },

29 "os": [

30 "darwin",

31 "linux",

32 "win32"

33 ],

34 "cpu": [

35 "arm64",

36 "x64"

37 ],

38 "repository": {

39 "type": "git",

40 "url": "git+https://github.com/bekirdag/docdex.git"

bin/docdex-mcp-stdio.jsView file

Lines 1-20javascript

1#!/usr/bin/env node

2"use strict";

4const { runBridge } = require("../lib/mcp_stdio_bridge");

Medium

Dynamic Require

Package source references dynamic require/import behavior.

bin/docdex-mcp-stdio.jsView on unpkg · L3

6async function

lib/postinstall_setup.jsView file

Lines 1-24javascript

1#!/usr/bin/env node

2"use strict";

4const fs = require("node:fs");

5const net = require("node:net");

lib/install.jsView file

Lines 23-63javascript

23const { runPostInstallSetup } = require("./postinstall_setup");

24const { resolveDistBaseDir, resolveDistBaseCandidates } = require("./paths");

26const MAX_REDIRECTS

bin/docdex.jsView file

•matchType = normalized_sha256 matchedPackage = docdex@0.2.96 matchedPath = bin/docdex.js matchedIdentity = npm:ZG9jZGV4:0.2.96 similarity = 1.000 summary = normalized source hash matched finalized malicious source

High

Known Malware Source Similarity

Source file is highly similar to a previously finalized malicious package; route for source-aware review.

bin/docdex.jsView on unpkg

lib/cli_entry.jsView file

High

Known Malware Source Similarity

Source file is highly similar to a previously finalized malicious package; route for source-aware review.

lib/cli_entry.jsView on unpkg

Source & flagged code

12 flagged · loading source

package.jsonView file

•scripts.postinstall = node ./lib/install.js

High

Install Time Lifecycle Scripts

Package defines install-time lifecycle scripts.

package.jsonView on unpkg

•scripts.postinstall = node ./lib/install.js

Medium

Ambiguous Install Lifecycle Script

Install-time lifecycle script is not statically allowlisted and needs review.

package.jsonView on unpkg

bin/docdex-mcp-stdio.jsView file

3L4: const { runBridge } = require("../lib/mcp_stdio_bridge"); L5:

Medium

Dynamic Require

Package source references dynamic require/import behavior.

bin/docdex-mcp-stdio.jsView on unpkg · L3

Findings

1 Critical8 High6 Medium5 Low

CriticalAi Agent Control Hijacklib/install.js

HighInstall Time Lifecycle Scriptspackage.json

HighSandbox Evasion Gated Capabilitylib/postinstall_setup.js

HighTrigger Reachable Persistencelib/postinstall_setup.js

HighKnown Malware Source Similaritylib/install.js

HighKnown Malware Source Similaritylib/postinstall_setup.js

HighKnown Malware Source Similaritybin/docdex.js

HighKnown Malware Source Similaritylib/cli_entry.js

HighKnown Malware Source Fingerprint Signaturelib/install.js

MediumAmbiguous Install Lifecycle Scriptpackage.json

MediumDynamic Requirebin/docdex-mcp-stdio.js

Affected versions and remediation

This report applies to docdex@0.2.98.

The versions list below shows the verdict for each recorded version.

Avoid installing docdex@0.2.98. Remove it from direct dependencies and check your lockfile for transitive copies.
Choose an independently verified alternative or release. This report does not establish that other versions are safe.
If this version ran, investigate the affected machine and build environment. Rotate credentials it could access and rebuild from a trusted environment.

Evidence last updated: 2026-08-08 09:36:16.173Z (UTC).

Think this verdict is wrong? Dispute it on GitHub or read how reports are produced.

Versions

8 known versions

0.2.99latestScan Failed—AllowUnder ReviewAug 27, 2026, 1:21 PM 0.2.98shownMaliciousSoft block: AI-agent control surfaceBlockPublishedAug 8, 2026, 9:33 AM 0.2.97MaliciousSoft block: AI-agent control surfaceBlockPublishedAug 7, 2026, 2:49 PM 0.2.96MaliciousSoft block: AI-agent control surfaceBlockPublishedAug 7, 2026, 11:09 AM

AI Security Review

Decision evidence

Source & flagged code

Source & flagged code

Findings

Affected versions and remediation

Versions

Related packages

Other AI-agent control-surface risk packages

Runtime surface

Behavioral surface

Related packages

Other AI-agent control-surface risk packages

Source & flagged code