Issue 8 4 min read

Treat agent docs as install policy

If your coding agent can run `pip` or `npx` from a vendor's agent-facing docs, that file is part of your software supply chain. About 1.5% of scanned Fortune 500 agent docs already pointed at packages nobody owned.

The Cloud Security Alliance put it cleanly in a September 7 research note: the trust model behind agent-facing documentation is broken. Companies publish machine-readable docs so coding agents stop guessing install steps. Agents treat that text as ground truth. They run the install line. They do not check that the package exists, that the vendor owns it, or that anyone has ever reviewed it.

Researcher Alon Hertz and colleagues scanned 6,214 domains across Fortune 500 firms, defense contractors, and big tech. They found thousands of agent-facing doc files. About 120 sites, roughly 1.5% of the set, referenced packages or domains that were not registered. Bruce Schneier covered the same disclosure: the team claimed a sample of those names, shipped benign phone-home packages, and waited. Callbacks arrived from corporate networks. Parent process chains pointed at Claude, Codex, and Hermes. In some accounts the first Fortune 500 beacon landed in minutes.

This is not Issue 7 again. That piece was about agents publishing into registries. This one is the invert: agents trusting vendor docs and installing from registries. The attacker does not need a model to invent a fake package name. They read the company’s own published install line, claim the empty name, and wait for an approved coding agent to fetch it through npm or PyPI like any normal developer workflow.

Clerk made the failure concrete. Its docs invited npx clerk-next-js-auth-protection, a bare name Clerk never owned on the public registry. Coverage and malware trackers later tied a live malicious package under that name to installer beacons (username, hostname, working directory). Once someone claims the gap, npx can execute the binary without ever writing it into a lockfile. Endpoint tools see an approved agent talking to a trusted registry. Nothing looks like malware until after the install.

That detection gap is the operator problem. The path looks sanctioned at every layer: approved coding tool, standard package manager, public registry, normal publish process. Conventional network and endpoint controls have little reason to stop it. The only difference is the package content. If you only watch for weird binaries and ignore docs-driven installs, you will miss the page.

The pattern sits next to package hallucination, not instead of it. Spracklen and coauthors at USENIX Security 2025 found fabricated package names in 19.7% of generated samples, with 43% of those names repeating across identical re-runs. Slopsquatting waits for the model to invent a name. Agent-facing docs hand the attacker the exact string. Same registry. Higher hit rate.

Jeremy Howard’s llmstxt.org convention exists to give agents a curated map of a site. Adoption grew because teams wanted less hallucination. That goal still holds. The control surface changed. Anything an agent may turn into a shell or package-manager command is now install policy, whether it lives in agent docs, a README, an MCP tool description, or a skill file.

Before the next agent run, inventory these moves:

  1. Diff every install line in your published agent docs against registry ownership and DNS. Close gaps by registering the names under your namespace, even if you are not shipping them yet.
  2. Gate agent package installs on human confirmation, or on publisher identity, registration age, and download history checks, when the command came from external docs.
  3. Treat README files, MCP tool descriptions, and skill files with the same distrust as untrusted instruction text, not as trusted ops runbooks.
  4. Require lockfiles and SCA rules that flag zero-history or brand-new packages before they land in a developer machine or CI runner.
  5. Log which document caused which install. If you cannot answer that, you cannot page the right owner when a beacon lights up.
  6. Prefer scoped packages and vendor-owned namespaces over bare npx names that anyone can claim.

Agent docs that reduce guessing also publish a target list. Treat them like install policy, or someone else will.

Sources

Next issue in two days. See you then.

Subscribe