ThisCalculator

Everyday

Least Privilege Permissions for AI Coding Agents

Updated · Standard formula, shown below

This guide shows you how to lock down AI coding agents—like GitHub Copilot, Cursor, or custom CLI tools—so they can only touch the files, commands, and services they actually need. You’ll set up role-based access, add human approval for risky actions, and audit what the agent does. This reduces the blast radius of a bad suggestion or a compromised tool.

What You’ll Need

  • Access to the repository or project where the agent runs (admin or owner role).
  • If using a cloud-based agent (e.g., GitHub Copilot, Codeium), a paid plan that supports org-level policies or custom permissions.
  • For self-hosted agents (e.g., OpenHands, Aider, or a custom script), a basic understanding of your operating system’s user and group management.
  • A way to run commands—terminal on macOS/Linux, PowerShell on Windows.
  • Optional: a secrets manager (like AWS Secrets Manager or a local vault) to store credentials the agent might need.

Step-by-Step

  1. Map what the agent actually does. List the files it reads/writes, the commands it runs (e.g., npm test, git push), and any external APIs it calls. Keep this list minimal—if it doesn’t need to touch a file, don’t grant access.
  2. Create a dedicated service account for the agent. On a local machine, create a new user (e.g., agent) with no sudo privileges. On a cloud platform, create a service principal or bot account with the least permissive role. Never run the agent as your personal admin account.
  3. Grant file-system permissions only to required paths. For a local agent, use chown and chmod to give the agent user read/write access only to the project directory. For example: chown -R agent:agent /home/agent/project and ensure the agent cannot write outside that folder. On Windows, use ACLs via icacls.
  4. Restrict command execution with a policy or wrapper. If the agent can run shell commands, wrap it in a script that whitelists allowed commands. For example, allow git status, npm test, but deny rm -rf or curl to arbitrary URLs. Use a tool like rbash (restricted bash) or a custom wrapper that checks each command against a list.
  5. Set up approval gates for high-risk actions. In GitHub, enable “require approval for copilot” in repository settings (or org policy). For self-hosted agents, add a manual approval step: the agent pauses and asks for a human to confirm before running a command that modifies files, pushes to remote, or installs packages. You can implement this with a simple prompt in the agent’s loop or a webhook that sends a request to a chat channel.
  6. Use environment variables for secrets, not hardcoded values. Store API keys, tokens, and passwords in a secrets manager or at least in a .env file that the agent can read but not write. Ensure the agent never logs these values—add logging filters if needed.
  7. Enable audit logging. Turn on logging for the agent’s actions. On GitHub, this is in the audit log for Copilot. For local agents, redirect all output to a log file and use a tool like auditd on Linux to track file access and command execution.
  8. Test the permissions with a dry run. Give the agent a trivial task (e.g., “add a comment to a file”) and confirm it can do that but fails when trying to read a file outside its scope. Adjust permissions until the behavior matches your policy.
  9. Document and review periodically. Write down what the agent can and cannot do. Review the permissions every few months—remove anything that’s no longer needed.

Common Mistakes

  • Granting write access to the entire home directory. The agent only needs the project folder. Giving it /home/user lets it modify dotfiles, SSH keys, or other projects.
  • Running the agent with sudo or as root. A single bad command can wipe the system. Always use a non-privileged user.
  • Allowing arbitrary network calls. If the agent can curl anything, it could exfiltrate code or download malware. Restrict network access to known endpoints if possible.
  • Skipping approval for git push. A wrong commit can be pushed to production. Always require human approval for any push to a shared branch.
  • Storing secrets in the repository. Even if the agent can read them, they’re exposed to anyone with repo access. Use a secrets manager.
  • Not testing the restrictions. Permissions might look right but actually be too broad. Always run a test to confirm.

Tips

  • Use a container (Docker) to isolate the agent completely. Run the agent inside a container with a read-only root filesystem and only mount the project directory.
  • For cloud-based agents, use the built-in policy features (e.g., GitHub’s Copilot policy) to restrict suggestions to specific repos or file types.
  • Set up a “human in the loop” for any action that changes state—not just pushes, but also package installs or config edits.
  • Keep the approval process fast: use a simple yes/no prompt rather than a complex ticketing system, so developers don’t bypass it.
  • Regularly rotate the agent’s credentials, especially if it has access to production systems.
  • If the agent is used by multiple developers, consider a shared service account with a policy that tracks which developer triggered which action.

Troubleshooting

The agent can’t read a file it needs. Check the user ownership and permissions. Run ls -la on the file and ensure the agent user has read permission. If the file is in a directory, the agent also needs execute permission on each parent directory.

The agent can still run commands it shouldn’t. Your wrapper might be bypassed if the agent uses a shell built-in or a path that isn’t in the whitelist. Use a strict allowlist of absolute paths (e.g., /usr/bin/git) and disable shell built-ins by using exec in the wrapper.

Approval prompts are not appearing. Check that the agent’s configuration actually calls the approval function. In GitHub, ensure the policy is applied to the correct repository or org. For custom agents, verify the webhook or prompt is not being suppressed by a timeout or a silent mode.

Audit logs are empty. Make sure logging is enabled at the correct level. On Linux, auditd may need rules added. For GitHub, check that the audit log is enabled in the org settings.

The agent is too slow because of approvals. Reduce the number of approval gates by grouping actions. For example, approve a batch of file edits at once, rather than each individual write. Or allow automatic approval for read-only actions.

Secrets are being logged. Add a log filter that redacts patterns like API_KEY=.... In many agents, you can set environment variables to disable verbose logging.

Frequently Asked Questions

Q: Can I use the same permissions for all my coding agents?
A: No—each agent may have different needs. A code completion agent only needs read access to the repo, while a refactoring agent needs write access. Tailor permissions per agent.

Q: How do I approve a single command without pausing the whole session?
A: Most agents support a “require approval” mode that only pauses for specific actions like git push or rm. Configure that list to match your risk tolerance.

Q: What if the agent needs to install packages?
A: Allow it to run npm install or pip install but only in a virtual environment or container. Require approval before it modifies the global system.

Q: Can I set permissions per branch?
A: Yes, in GitHub you can restrict Copilot to certain branches, and for custom agents you can check the current branch in the wrapper script and reject actions on protected branches.

Q: How do I revoke access if the agent is compromised?
A: Immediately rotate the agent’s credentials, remove its SSH keys, and revoke its service account. Then review the audit logs to see what it did.

Q: Is it safe to let the agent use my personal access token?
A: No—use a dedicated token with only the required scopes (e.g., repo read, not admin). Store it in a secrets manager and set an expiration date.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.