Can a README hijack your coding agent? A defensive checklist

Yes, a README can steer an AI coding agent if the agent treats its text as instructions. This is indirect prompt injection: the model reads external content that contains directions and may follow them. You cannot filter it away completely, so the defense is limiting what the agent can do after reading untrusted text.

Why are docs a risk?

OWASP describes indirect prompt injection as occurring when an LLM accepts input from external sources such as websites or files. A README, a docs page, an issue comment, a code comment and a package description are all external files from the agent's point of view. If an agent reads them to learn how to use a library, it is reading text written by a stranger.

OWASP's example is a webpage with hidden instructions that makes a summarizing model leak the conversation. The same mechanism applies when the page is documentation. The agent does not need to be fooled about who wrote it. It needs only to treat the content as part of its prompt.

The UK NCSC explains why this is hard: LLMs do not enforce a security boundary between instructions and data inside a prompt. Its design rule is that when a model processes information from a party, its privileges should drop to that party's level. For a README written by an unknown contributor, that means very low privilege.

What can go wrong in practice?

The risk is not the text. It is the tools. An agent that can run shell commands, read environment variables, write files or make network calls turns a persuasive paragraph into an action. Instructions such as "run this setup command" are normal in docs, which makes the pattern hard to spot.

So ask one question for each project: if the agent obeyed the worst sentence in any file it reads, what is the worst thing it could do?

The checklist

Scope

• Run agents in a sandbox or container without your real credentials.
• Give each task only the directories it needs.

Tools

• Require approval for shell commands, package installs, file deletes and network calls.
• Block access to secret stores, SSH keys and cloud credentials by default.

Content

• Treat third-party docs, issues and dependency files as untrusted data.
• Mark untrusted content clearly in the agent's context where the tool supports it.
• Prefer pinned, reviewed dependencies over whatever a README suggests installing.

Output

• Review diffs before accepting them, especially changes to build files, CI workflows and install scripts.
• Validate outputs with deterministic checks such as tests and linters.

Visibility

• Log prompts, file reads, tool calls and failed calls. The NCSC notes failed tool calls can reveal someone probing.

What to do

1. List what your coding agent can reach: files, shell, network, credentials, repositories.
2. Remove anything it does not need, and keep real secrets out of its environment.
3. Turn on approval for commands that change things or touch the network.
4. Do not let the agent follow install steps from untrusted docs without a human reading them.
5. Review every change to CI workflows and package scripts by hand.
6. Pin dependencies and check new ones before adding them.
7. Keep logs of agent actions and review them after unusual sessions.
8. Test your setup with a harmless planted note in a test README, and confirm the agent does not act on it.

Where do guardrails help?

Controls that sit between an agent and its tools can enforce rules the model cannot be trusted to follow. Our MCP guardrail demo shows that idea in action.

Open the full demo at /demos/mcp-guardrail.

Quick check

Sources

• OWASP GenAI: LLM01 Prompt Injection, fetched 18 October 2026.
• NCSC: Prompt injection is not SQL injection, fetched 18 October 2026.

Last reviewed: 18 October 2026.