Plugin4Shell Explained: How a Zero-Click Exploit Targets Your Codex CLI Setup

On 17 September 2026, security researcher Air disclosed a vulnerability in the Codex CLI marketplace plugin auto-update system that allows an attacker to silently replace a pinned plugin with malicious code — without any action from the developer.¹ The vulnerability, named Plugin4Shell after the Log4Shell naming pattern that has become shorthand for critical supply-chain exploits, is patched in Codex CLI v0.146.0. Users below that version with auto-update enabled on marketplace plugins remain at risk.

This article explains the attack mechanism, the developer trust assumptions it violates, and the concrete steps Codex CLI teams should take to verify and harden their environments.

The Exploit Mechanism

To understand Plugin4Shell, it helps to understand how Codex CLI’s marketplace plugin system resolves plugin versions.

When a developer installs a marketplace plugin, Codex CLI records a pinned reference — typically a commit SHA — in the plugin manifest. The intent is that future auto-update checks will fetch only newer versions of that plugin from the registered git origin, while the pinned SHA acts as a known-good anchor for rollback.

The vulnerability lies in how the auto-updater resolves that SHA against the remote repository. Git’s ref resolution rules treat commit hashes and branch names as distinct namespaces, but when a ref is looked up against a remote, the disambiguation depends on what the remote reports first. If an attacker controls the plugin repository — or has write access to its hosting platform — they can create a branch whose name is formatted to match a SHA pattern. When the auto-updater queries the remote, it receives the attacker-controlled branch as a candidate match for the pinned SHA and substitutes it silently.¹

Because auto-update runs without any user-visible action, this is a zero-click exploit. The developer does not need to install anything, run any command, or interact with the malicious content. The substitution happens the next time the auto-updater checks for updates in the background.

The exploit is not a novel class of vulnerability. Hash-shaped branch name bypass has appeared in other supply-chain tooling, and the underlying git ambiguity is documented behaviour.² What makes Plugin4Shell significant is the attack surface it targets: a developer tool that runs with the same privileges as the developer, in the same environment where code is being generated, reviewed, and committed. Poisoning Codex CLI’s plugin environment is a path to poisoning every repository the developer touches.

Who Is Affected

The conditions required for exploitation are:

Codex CLI version below v0.146.0
At least one marketplace plugin installed with auto-update enabled
That plugin hosted on a git platform that permits SHA-shaped branch names (confirmed affected: Bitbucket, self-hosted Gitea, GitLab Community Edition with default branch-naming policies)

GitHub.com enforces branch-naming restrictions that block SHA-shaped names by default, which significantly limits the attack surface for plugins hosted there — but does not eliminate it entirely, as restrictions can be disabled at the repository level.¹

Users who have disabled marketplace auto-update, or who have no marketplace plugins installed, are not affected by this specific exploit path.

Immediate Actions

If you have not already patched to v0.146.0 or later, the remediation steps are straightforward.

Step 1: Check your current version.

codex --version

Any output below 0.146.0 means you are in the affected range.

Step 2: Upgrade.

codex update

Or, if you installed via a package manager:

# macOS Homebrew
brew upgrade codex

# npm global install
npm update -g @openai/codex

Step 3: If you cannot patch immediately, disable marketplace auto-update.

codex plugins set-auto-update off

This prevents the exploit path while you arrange the upgrade. It does not protect against a plugin that was already substituted before you disabled auto-update, so patching remains the correct resolution.

Step 4: Audit installed plugins for non-GitHub origins.

codex plugins list --show-origin

Any plugin listed with a Bitbucket, GitLab, or self-hosted origin should be treated as higher risk and temporarily disabled until you can verify the plugin’s integrity against a known-good commit hash.

Why Auto-Update Became the Attack Vector

Plugin4Shell illustrates a tension that appears repeatedly in developer tooling security: the feature designed to improve security posture becomes the attack surface.

Auto-update exists because the alternative — manual plugin updates — results in developers running stale plugin versions with known vulnerabilities. This is the same logic that drove automatic OS updates, automatic browser updates, and automatic dependency updates in package managers. The security argument for auto-update is sound. The problem is that auto-update is only as trustworthy as the verification step that precedes it.

In Plugin4Shell’s case, the verification step — confirming that the git ref returned by the remote corresponds to the pinned commit SHA — was insufficient. The fix in v0.146.0 adds strict hash validation: the auto-updater now confirms that the resolved object is a commit, not a branch, before accepting it as a match for a pinned SHA.¹ This closes the specific bypass, but the broader design question remains: what level of trust should a developer tool extend to a plugin’s git origin?

The community discussion following disclosure surfaced two competing positions.³ One camp argues that marketplace plugins should be distributed as signed artefacts with a separate signature chain that does not rely on git ref resolution at all — analogous to how npm’s package-lock.json records exact content hashes rather than version ranges. The other camp notes that this raises the barrier to publishing plugins and fragments the ecosystem. OpenAI has not yet announced a signed-artefact distribution model for the marketplace.

Mapping Plugin4Shell Risk to AGENTS.md and Codex CLI Configuration

For teams running Codex CLI in production or CI/CD environments, Plugin4Shell is a useful forcing function for reviewing how plugin risk is managed at the configuration level.

Explicit plugin version locking in AGENTS.md. If your Codex CLI sessions rely on specific plugins, record the expected plugin version and origin hash in AGENTS.md so any deviation is visible:

# Plugin Versions (as of 2026-09-21)
- codex-plugin-github-actions@v2.3.1 (sha: a1b2c3d4...)
- codex-plugin-terraform-format@v1.0.8 (sha: e5f6a7b8...)
Run `codex plugins list --show-origin` to verify before any session that modifies infrastructure.

This does not prevent substitution, but it makes verification part of the session pre-flight and creates an audit trail.

Disable auto-update in CI environments. Automated sessions should never silently update plugins mid-run. Add the following to your CI configuration:

# codex.config.toml (CI profile)
[plugins]
auto_update = false

Or set the environment variable:

CODEX_PLUGINS_AUTO_UPDATE=false codex exec ...

Restrict plugin origins in your organisation’s Codex CLI policy. For teams where Codex CLI sessions touch production or shared infrastructure, consider an allowlist of approved plugin origins. Plugins sourced from GitHub.com repositories with branch-naming restrictions are lower risk than those from self-hosted instances. A blanket policy of github.com/your-org/* for plugin origins significantly reduces the attack surface.

PreToolUse hook for plugin integrity checks. A hook that runs codex plugins list --show-origin and compares against a known-good manifest before each session can catch substitution before any tools execute:

#!/bin/bash
# .codex/hooks/pre-session-integrity.sh
EXPECTED=$(cat .codex/plugin-manifest.json)
ACTUAL=$(codex plugins list --json)
if [ "$EXPECTED" != "$ACTUAL" ]; then
  echo "PLUGIN INTEGRITY FAILURE: manifest mismatch. Aborting session." >&2
  exit 1
fi

The Broader Supply Chain Context

Plugin4Shell does not exist in isolation. The past twelve months have seen a pattern of supply-chain attacks targeting developer tooling: compromised npm packages in popular Codex CLI extension ecosystems, malicious VS Code extensions with auto-update payloads, and prompt-injection attacks embedded in documentation that Codex CLI retrieves via MCP servers.⁴

The attack model converges on a common insight: an AI coding agent that has been given broad permissions over a developer’s environment is a high-value target precisely because of those permissions. Compromising the agent’s execution environment — through a poisoned plugin, a malicious MCP server response, or an injected prompt in a fetched document — is a path to influencing every repository, credential, and service the agent can reach.

Teams that have thought carefully about Codex CLI’s writable_roots configuration, network isolation, and credential handling are better positioned to contain the blast radius of a supply-chain compromise. But containment is not prevention. Plugin4Shell is a reminder that the security of an agentic coding environment depends on the integrity of every component in the tool’s execution context — including the plugins that extend its capabilities.

The fix is in v0.146.0. Upgrading is the correct first step. The harder work is building the organisational habits — version locking, origin audits, pre-flight integrity checks — that make the next Plugin4Shell less impactful when it arrives.

Summary

Plugin4Shell (disclosed 17 September 2026) exploits a git ref resolution gap in Codex CLI’s marketplace plugin auto-update system, allowing an attacker who controls a plugin repository to substitute a malicious branch for a pinned commit hash — without any user interaction.¹ The fix ships in v0.146.0. Users below that version with auto-update enabled should upgrade immediately; those who cannot patch should disable auto-update via codex plugins set-auto-update off and audit plugins with non-GitHub origins. For teams running Codex CLI in production or CI environments, the incident is a prompt to add plugin version locking to AGENTS.md, disable auto-update in CI profiles, and implement PreToolUse integrity checks against a known-good plugin manifest.³

Citations

Air (2026, September 17). Plugin4Shell: zero-click vulnerability lets attackers swap pinned Codex marketplace plugins for malicious code. Coordinated disclosure; coverage by Ajit Singh. https://singhajit.com/dev-weekly/2026/sep-14-20/claude-code-projects-plugin4shell-gemini-38-live/ ↩ ↩² ↩³ ↩⁴ ↩⁵
Git SCM Documentation. gitrevisions — Specifying Revisions and Ranges. Ambiguous SHA-shaped ref resolution. https://git-scm.com/docs/gitrevisions ↩
OpenAI Codex CLI Plugin System Documentation. Marketplace Plugins: Installation, Versioning, and Auto-Update. https://github.com/openai/codex/blob/main/codex-rs/docs/plugins.md ↩ ↩²
OpenAI Codex CLI Security Advisory — v0.146.0 Plugin Hash Validation Fix. https://github.com/openai/codex/security/advisories ↩