Least privilege for an AI agent starts with a list of every action its credentials allow. The list of actions its instructions mention is a different and shorter thing. Then each gap between the two gets closed with a limit the system enforces, whatever the model decides. When we drew that map for the agent that drafts posts for this site, only one limit was enforced in code, a check on its output. The rule that matters most, never to push to the branch that deploys the live site, turned out to be a sentence in its prompt, and the GitHub login it runs under can do exactly that. This post is the map, the gap, and the checklist we now use for agent tools and APIs.
List what the credentials allow, not what the prompt says
Most permission reviews of AI agents start from the tools the agent is given and the instructions it follows. That describes intended behaviour. The attack surface is whatever the credentials behind those tools can do, because a model that is confused, manipulated by text it reads, or simply wrong will use whatever is available.
OWASP's entry on excessive agency names the three root causes: excessive functionality, excessive permissions and excessive autonomy. Its mitigations include minimising what each extension can do, giving downstream systems the narrowest permissions, requiring a human to approve high-impact actions, and implementing authorisation in the downstream systems instead of relying on the model to decide whether an action is allowed. The last one is the test we applied to every row below: if the model decided to do this, what would stop it?
Our writing agent's permission map
The agent runs once a day on the owner's Mac, in a separate copy of this site's repository kept for nothing else. Its job is to draft one approved post, run the quality gate, push a branch and open a pull request for a person to review. Here is every relevant action its environment allows, whether the job needs it, and what stops it.
| Action | Needed for the job? | What stops it today | Kind of limit |
|---|---|---|---|
| Read files in its copy of the repository | Yes | Nothing, by design | None needed |
| Read files elsewhere on the Mac | No | Its instructions say to stay in its folder | Prompt only |
| Write the new post and update one topic's status | Yes | Review of the pull request | Human |
| Change site code, scripts or other posts | No | Its instructions forbid it; the pull request is reviewed | Prompt and human |
| Open any web page | Partly, for research | Nothing at read time | Prompt only |
| Cite a web page in a post | Yes | The quality gate rejects any host not on the approved list | Enforced on output |
| Push a draft branch and open a pull request | Yes | Nothing, by design | None needed |
| Push to the production branch, which deploys the live site | No | Its instructions say never to | Prompt only |
| Start the publish-to-live workflow | No | Its instructions; publishing needs the owner's OK | Prompt only |
| Merge its own pull request | No | Its instructions; review mode in its config | Prompt only |
| Edit the repository's automation workflows | No | Nothing beyond its instructions | Prompt only |
| Post on social media | No | No tool for it in its instructions, but it runs on a Mac whose browser is signed in to social accounts | Depends on the run's tool access |
| Spend money | No | No tool for it in its instructions, on the same Mac | Depends on the run's tool access |
Six of the thirteen rows are held only by instructions, and two more depend on which tools the scheduled run happens to be given. That is the honest state of a setup built quickly and reviewed carefully, and it is common, which is why we are publishing it.
A separate folder is not a separate machine
The agent works in its own copy of the repository, which keeps its files apart from the owner's working copy. That is a separation of files. The run still happens under the owner's user account on the owner's Mac, where the browser is signed in to the company's accounts and the command line is logged in to GitHub. Whether the agent could reach any of that depends on which tools the scheduled run is allowed, and that is a setting outside the repository that nobody reviews alongside the code.
The strongest permission is the one that does not exist in the agent's environment at all. A credential that is not there cannot be misused, whatever the model reads or concludes, and no prompt injection can talk past it. Getting there means running the agent somewhere that has nothing to give: a container, a virtual machine or a separate operating-system user holding only the repository and a token made for the job.
The practical lesson is to start from nothing and add, which is the opposite of how agents usually get built. A developer wires an agent into the tools they already use, with the logins they already have, and then writes instructions telling it what not to touch. Every one of those instructions is a permission granted and then argued with.
A check on the output turned a soft rule into a hard one
Reading arbitrary web pages is a soft spot: the agent can open anything, and a page can carry instructions aimed at it. We could not easily stop the reading without stopping the research. What we could stop was the consequence that mattered, which is citing an unvetted source in a published post.
So the rule became a check. Since 31 October the quality gate rejects any draft that links to a host outside an approved list of official documentation, standards bodies and primary sources, and it runs again in GitHub's automation on every pull request, outside the agent's control. The agent can still read a bad page, but it cannot publish a post that rests on one. When you cannot remove a capability, look for the boundary where its effect becomes real and enforce the rule there.
The rule that matters most was a sentence in the prompt
The live site is built from one branch of this repository, production, and a push to it deploys within minutes. A workflow called "publish to live" moves that branch forward, and the owner runs it after checking the staging site. The agent's instructions forbid it from touching either. Its GitHub login, the owner's, has full write access to the repository and permission to run workflows, so nothing below the instructions enforces those rules.
The usual fix is branch protection, which makes GitHub itself refuse direct pushes to a branch. When we checked, GitHub refused the request to read our protection settings, because this is a private repository on a free plan. GitHub's documentation confirms it: protected branches are available for public repositories on its free plans, and for private repositories only on its paid plans. So the protection everybody recommends was not available to us without a plan change, and nobody had noticed because the agent had always followed its instructions.
There are three ways to close it, roughly in order of strength:
- Give the agent its own GitHub account with no write access to the repository at all. It pushes to its own fork and opens pull requests from there, the way an outside contributor would. It cannot touch the live branch because it has no permission to, whatever it is told.
- Move to a plan that supports branch protection, and require a pull request with an approval before anything reaches the live branch.
- At minimum, give the agent its own identity with a fine-grained token limited to this one repository and to the permissions its job uses, so it no longer carries the owner's access to every other repository. This narrows the blast radius, though on its own it still allows a push to the live branch.
The first is what we would recommend to a client in the same position, because it removes the capability instead of guarding it.
A least-privilege checklist for agent tools and APIs
- List every action each credential allows, by reading the provider's permission model. Do not stop at the tools you exposed.
- Give every agent its own identity. Never let it run under a person's login.
- Scope each credential to one resource and the narrowest permissions the job uses. Read and write are separate grants, and so are drafting and sending; we covered the second split in designing the approval step.
- Prefer absence to prohibition. Run the agent in an environment that holds only what it needs; a credential the agent does not have beats an instruction not to use one.
- Enforce in the downstream system. The API, the repository or the payment provider should refuse the action, as OWASP recommends.
- Where a capability must stay, check its output at the boundary where it takes effect, in code the agent cannot change.
- Put budgets in code: calls, tokens, money and time, with a hard stop. Our post on AI agent cost control covers this in detail.
- Make credentials expire, and rotate them when the agent's job changes.
- Mark every "prompt only" row in your map as a known gap with an owner and a date, and redo the map whenever a tool or a credential changes.
The map takes an hour to draw for a small agent, and it changes the conversation from "what did we tell it?" to "what can it do?". If you have an agent in production and would like a second pair of eyes on its map, get in touch.
