AI Coding Agent Prompt Poisoning Defense: Five Detection Gates for Coding Agents

1. The Bottom Line: Not a Product Bug, but a Property of How Agents Work

When a forged “project specification” file is lured into being written to the Downloads directory, an AI coding tool that reads it may follow the “spec” and modify global configuration, pull external dependencies, and make network requests. The problem is not a flaw in the tool’s code. It is that this class of tool is built to read project instructions and act on them.

Security teams therefore should not pin their hopes on waiting for a vendor patch. A more realistic path is to turn the risk into detection gates in the pipeline: control the entry point, watch configuration, separate prompt from execution, restrict outbound access, and prepare a response plan for the worst case.

For context, existing public reproduction material indicates that two independent attack chains can both trigger similar behavior. The success rates cited in that material vary widely, and it does not provide complete sample sizes, tool versions, or verifiable links. This article therefore does not treat those figures as precise statistics. It cites them only to show that the risk tends to reproduce across tools. Testing and security teams should assess the actual impact based on their own tools, operating systems, and download policies.

2. How the Attack Chain Lands: Five Actions to Harden One by One

1) A web page writes an instruction file into the Downloads directory

The Downloads directory is one of the locations a browser can write to most easily. Whether a file can be written without extra confirmation depends on the browser’s download policy, user confirmation settings, extension permissions, and OS isolation mechanisms. On its own, downloading a text file is not the same as executing malicious code. However, it can become the delivery point for later attempts to get a coding agent to read a “project spec.”

2) The user launches a coding agent from the Downloads directory

Some coding agent sessions run from the Downloads directory, and some tools combine a local browser, debugging environment, or development workflow. This behavior may be a normal habit in itself. However, it expands the attack surface: the agent may read text files in the directory and treat their contents as project instructions.

3) The agent reads an instruction file disguised as a spec

Real samples are usually not obvious malicious code. Instead, they tend to be long documents titled something like Engineering Work Standards, Team Development Conventions, or Local Environment Notes. The malicious content is usually tucked into sections such as “local dev environment,” “dependency installation,” or “debugging configuration.” It asks the agent to modify global configuration, install external packages, add a mirror source, or write credentials.

4) Global configuration is modified, and later sessions inherit the pollution

This is the key step that escalates a one-time prompt injection into a persistent risk. If the agent’s global config, plugin config, MCP config, environment variables, or project templates are modified, later sessions may keep using the poisoned settings without the user noticing.

5) The agent acts according to the tampered configuration

The ultimate risks include installing malicious dependencies, contacting external addresses, reading or writing sensitive files, invoking local tools, and leaking environment information. At this point, the defense objective is no longer to identify whether a piece of text is malicious. It is to constrain the configuration, network, and sensitive-operation boundaries the agent can reach.

3. Five Practical Detection Gates

Gate 1: Entry-Point Control — Block Agents from Being Launched Directly in Untrusted Directories

Objective: Reduce the chances of an agent reading project instructions directly from the Downloads directory, temp directories, or other browser-controlled locations.

Recommended measures:

• Prohibit launching coding agents directly from locations such as the Downloads directory, temp directories, the trash, and browser cache directories.
• If files must be handled in the Downloads directory, first move them into a trusted workspace and obtain human confirmation.
• Maintain an explicit inventory of project-level instruction files, such as AGENTS.md, CLAUDE.md, .rules, and .cursorrules. Refer to the tool’s documentation for the exact names.
• Config directories may be located in ~/.config/<tool-name>, ~/Library/Application Support/<tool-name>, the project root, or an enterprise policy directory. Refer to the tool’s documentation for the actual paths.
• Tag the source of every instruction file the agent reads: a trusted project root, a remote repository, a temporary download, or content pasted by the user.

Gate 2: Config Integrity Verification — Catch Unauthorized Global Config Changes

Objective: Establish a configuration baseline in a trusted state, then detect files that are added, deleted, or modified.

Recommended measures:

• Build hash baselines for global config, plugin config, extension config, MCP config, environment variable templates, and dependency manifests.
• Run checks before the agent starts, after dependency installation, and after plugin upgrades.

Suggested alert tiers:

• Low: Expected changes caused by upgrades, plugin writes, or user edits. These require manual confirmation.
• Medium: Unexpected new config files, unknown modification timestamps, or files from unexpected sources.
• High: Config that now includes a new external repository, a download script, credential writes, or an unknown network address.

False-positive handling: Do not automatically roll back whenever the config changes. First compare the change timestamp, the operator, upgrade logs, plugin install records, and file origin. If the change turns out to be a normal upgrade, re-establish the baseline. If it cannot be explained, isolate the environment and have someone review it manually.

Gate 3: Prompt/Execution Separation — Spec Text Must Not Trigger Sensitive Actions Directly

Objective: Separate the “prompt layer” from the “execution layer” so that instruction files do not hold excessive privileges.

The following actions should be downgraded to mandatory manual confirmation, or approved by an independent policy engine:

• Modifying the agent’s own global configuration;
• Installing or updating dependency packages;
• Adding external package repositories, mirror sources, or script sources;
• Making network requests that are not on the allowlist;
• Reading or writing credential files, tokens, keys, or certificates;
• Executing downloaded scripts or binaries.

Principle: A project spec can say what should be done, but it cannot press the “Install,” “Connect externally,” “Change config,” or “Read credentials” buttons on the user’s behalf.

Gate 4: Outbound Allowlist — Block Data Exfiltration and Callbacks to Malicious Dependencies

Objective: Even if the poisoned file is read, limit the agent’s ability to connect outward afterward.

Recommended measures:

• Configure an outbound allowlist for the environment where coding agents run. Allow only known package repositories, internal artifact repositories, required API endpoints, and dev/debug endpoints.
• Deny all other outbound traffic by default, and log DNS requests, proxy requests, and download activity.
• Configure the package manager with an allowlist of approved repositories, and prohibit switching to third-party mirrors at will.
• For high-risk sessions, enable network isolation or a temporary sandbox that restricts access to the enterprise intranet and cloud credentials.

Gate 5: Rotate on Discovery — Once Poisoning Is Confirmed, Assume Credentials Are Exposed

Objective: Shrink the exposure window so that a one-time event does not turn into a long-term backdoor.

Response procedure:

• Once config poisoning is confirmed, or suspicious dependencies, external downloads, or abnormal outbound connections are found, assume that the related tokens, keys, and access credentials are exposed.
• Immediately rotate affected credentials, including API tokens, access keys, cloud credentials, SSH keys, and package repository tokens.
• Preserve complete audit logs, including config hashes, file modification times, network logs, agent session records, and dependency install records.
• Take a forensic snapshot before rolling back, then restore to the trusted baseline.
• Do not automatically block every change. First have someone check whether it is a false positive, then decide whether to block, roll back, or rotate.

4. Config Drift Check Script

The script below monitors coding-agent config files for unexpected changes. Run snapshot the first time to build a baseline, then run check for subsequent checks. Wire the exit codes into CI or startup hooks: 0 means no drift, 2 means an environment error, 3 means the manifest itself is abnormal, and 4 means drift was detected and manual review is required.

#!/usr/bin/env bash
# config-drift-check.sh
# Purpose: Monitor coding-agent config files for unexpected modifications.
# Note: In production, keep MANIFEST_DIR outside the config directory, and back it up or sign it regularly.
set -euo pipefail
CONFIG_DIR="${CONFIG_DIR:-$HOME/.config}"
MANIFEST_DIR="${MANIFEST_DIR:-$HOME/.config-drift-guard}"
MANIFEST="$MANIFEST_DIR/integrity.manifest"
MANIFEST_HASH="$MANIFEST_DIR/manifest.sha256"
if ! command -v sha256sum >/dev/null 2>&1; then
  echo "GNU sha256sum is required. On macOS, install coreutils and use gsha256sum, or wrap sha256sum with shasum -a 256." >&2
  exit 2
fi
if [ ! -d "$CONFIG_DIR" ]; then
  echo "Config directory does not exist: $CONFIG_DIR" >&2
  exit 2
fi
mkdir -p "$MANIFEST_DIR"
chmod 700 "$MANIFEST_DIR" 2>/dev/null || true
list_files() {
  find "$CONFIG_DIR" -type f \
    \( -name '*.json' -o -name '*.toml' -o -name '*.yaml' -o -name '*.yml' \) -print0 \
    | sort -z
}
count_records() {
  tr -cd '\0' < "$1" | wc -c | tr -d '[:space:]'
}
release_manifest() {
  if command -v chattr >/dev/null 2>&1; then
    chattr -i "$MANIFEST" "$MANIFEST_HASH" 2>/dev/null || true
  fi
  chmod 644 "$MANIFEST" "$MANIFEST_HASH" 2>/dev/null || true
}
protect_manifest() {
  chmod 444 "$MANIFEST" "$MANIFEST_HASH" 2>/dev/null || true
  if command -v chattr >/dev/null 2>&1; then
    chattr +i "$MANIFEST" "$MANIFEST_HASH" 2>/dev/null || true
  fi
}
snapshot() {
  release_manifest
  tmp=$(mktemp)
  # sha256sum -z output: 64-char hash + separator + file path + NUL.
  # This format handles spaces, asterisks, and newlines in paths.
  list_files | while IFS= read -r -d '' f; do
    sha256sum -z -- "$f"
  done > "$tmp"
  mv "$tmp" "$MANIFEST"
  sha256sum "$MANIFEST" > "$MANIFEST_HASH"
  protect_manifest
  echo "Baseline established: $MANIFEST"
}
verify_manifest() {
  if [ ! -f "$MANIFEST" ] || [ ! -f "$MANIFEST_HASH" ]; then
    echo "Baseline or baseline hash file is missing. Run snapshot in a trusted environment first." >&2
    exit 2
  fi
  expected=$(awk '{print $1}' "$MANIFEST_HASH")
  current=$(sha256sum "$MANIFEST" | awk '{print $1}')
  if [ "$expected" != "$current" ]; then
    echo "Baseline manifest hash mismatch; it may have been deleted or tampered with. Review manually before restoring." >&2
    exit 3
  fi
}
check() {
  verify_manifest
  tmp=$(mktemp)
  list_files | while IFS= read -r -d '' f; do
    sha256sum -z -- "$f"
  done > "$tmp"
  base_count=$(count_records "$MANIFEST")
  cur_count=$(count_records "$tmp")
  if cmp -s "$MANIFEST" "$tmp"; then
    echo "No config drift"
    rm -f "$tmp"
    exit 0
  fi
  echo "Config drift detected. Proceed to the manual review workflow." >&2
  while IFS= read -r -d '' record; do
    hash=${record:0:64}
    path=${record:66}
    if [ ! -f "$path" ]; then
      echo "[Deleted] $path" >&2
    else
      cur=$(sha256sum -- "$path" | awk '{print $1}')
      if [ "$cur" != "$hash" ]; then
        echo "[Modified] $path" >&2
      fi
    fi
  done < "$MANIFEST"
  if [ "$base_count" -ne "$cur_count" ]; then
    echo "[Count change] Baseline file count=$base_count, current file count=$cur_count; if the new files come from an upgrade or plugin, confirm manually." >&2
  fi
  rm -f "$tmp"
  exit 4
}
case "${1:-check}" in
  snapshot) snapshot ;;
  check) check ;;
  *) echo "Usage: $0 {snapshot|check}"; exit 1 ;;
esac

Usage tips:

• First run: ./config-drift-check.sh snapshot
• Subsequent checks: ./config-drift-check.sh check
• Put MANIFEST_DIR outside the config directory, for example in an enterprise audit directory, a read-only volume, or a dedicated security host.
• If the environment supports it, sign or back up the manifest externally. Otherwise an attacker could modify both the config and the local baseline.
• If a macOS environment uses shasum -a 256, generate a manifest in the same format yourself, or install GNU coreutils.

5. Control Mapping Table

Control	Focus	Specific checks	Log fields	Evidence source	Owner	Triggered action and timeframe
Entry-point control	Source directory of instruction files	Block launching agents directly from Downloads or temp directories; project instruction files must be explicitly declared	Source path, file hash, user, session ID	Agent logs, browser download records, EDR logs	Security engineering	Block and alert; respond within 5 minutes
Config integrity	Whether global config was changed	Baseline hash comparison, new-file monitoring, manifest self-check	Config file, old hash, new hash, change time	Drift script, file system audit	Platform security	Manual review; severity assigned within 30 minutes
Prompt/execution separation	Separation of specs from actions	Config changes, package installs, outbound connections, and credential reads/writes require secondary confirmation	Action type, approver, target resource	Agent policy logs, approval records	Application owner	High-risk actions blocked immediately
Outbound allowlist	Outbound network destinations	Allow only known repositories and internal service addresses; deny by default	Source process, destination domain, IP, port, result	Firewall, proxy gateway, DNS logs	Network security	Block unknown outbound connections; review within 1 hour
Rotate on discovery	Credential exposure surface	After poisoning is confirmed, rotate tokens and keys and retain audit records	Credential type, impact scope, rotation time	Key management system, audit logs	Security response	Start rotation within 15 minutes of confirmation

6. FAQ and Long-Tail Search Scenarios

How do I detect tampering with AI coding tool configuration?

Use baseline snapshots, hash comparison, and manifest self-verification. Focus on global config, plugin config, MCP config, environment variable templates, and dependency manifests. When you find a change, do not roll back immediately. First review manually whether it comes from an upgrade, a plugin write, or a user edit.

How do I prevent prompt injection via the Downloads directory?

Entry-point control is the core. Do not let coding agents read project specs directly from the Downloads directory or temp directories. Move files into a trusted workspace, and tag and confirm the source of instruction files. Combine this with an outbound allowlist to limit the agent’s ability to connect outward.

How do I prevent poisoning of engineering spec files?

Break the risk into five layers: entry-point control, config integrity, prompt/execution separation, outbound allowlist, and rotate on discovery. In particular, prevent a “spec file” from triggering global config changes, dependency installations, and external network requests.

Does a config drift alert always mean an attack?

Not necessarily. Upgrades, plugin updates, and user edits can all cause drift. The correct workflow is alert first, review second, then decide whether to block or roll back. If a change cannot be explained and comes with new dependencies, abnormal outbound connections, or credential reads, treat it as a poisoning incident.

7. Closing Thoughts

The most valuable thing about this type of attack is not how clever any particular sample is. It is the structural risk it exposes in agentic tools: even when a tool is “working as designed,” malicious content can still be executed. Defense therefore needs to shift from “fixing product defects” to “constraining behavioral boundaries.”

For testing and security teams, the actionable steps are:

• Control the Downloads directory entry point;
• Build a config integrity baseline;
• Separate prompt text from sensitive execution actions;
• Add an outbound allowlist for the agent;
• Rotate credentials quickly once poisoning is confirmed.

With these in place, even if instruction-file poisoning occurs, you can keep the impact within a scope that is detectable, reversible, and traceable.