Securing AI Coding Agents with Capability-Based Access

AI coding agents can do much more than generate source code. Modern agents can inspect repositories, modify files, execute shell commands, install packages, call APIs, run tests, and interact with development infrastructure.

That flexibility is useful, but it also changes the security model.

A traditional application usually performs predefined operations. An AI coding agent can decide which tools to call and in what sequence based on natural-language instructions and information discovered during execution. If the agent receives broad filesystem, shell, network, or credential access, a compromised instruction or malicious repository can potentially turn that authority into an unintended action.

This is why least privilege should be enforced as an execution boundary, not simply described in a system prompt.

A useful approach is capability-based access: instead of giving an agent broad access to a machine, expose a small set of explicitly scoped capabilities that represent the actions it is allowed to perform.

Microsoft's current guidance for agent security similarly emphasizes dedicated agent identities, least-privilege access, explicit tool scopes, auditing, and revocation. OWASP guidance also recommends giving each agent only the tools required for its task and requiring confirmation for high-impact actions.

What Is Capability-Based Access?

Capability-based security associates authority with a specific capability or permission rather than giving a process unrestricted access to a resource.

For an AI coding agent, a capability might represent:

• Read files inside a particular workspace.

• Write files inside a particular workspace.

• Run approved test commands.

• Read package metadata.

• Access a specific development API.

• Query a development database.

• Execute a predefined build operation.

The important distinction is that the agent does not receive general-purpose authority.

For example, instead of:

Agent
  └── Full access to developer machine

a safer model is:

Agent
  ├── Read: /workspace/project
  ├── Write: /workspace/project/src
  ├── Execute: dotnet test
  └── Network: package registry only

The exact capabilities depend on the task.

A documentation agent might only need read access. A test-fixing agent may need read/write access to a repository and permission to run tests. A deployment agent should have considerably stronger controls and potentially require human approval.

Why Prompt Restrictions Are Not Enough

A common first attempt at securing an AI coding agent is to add instructions such as:

Do not access credentials.
Do not modify files outside the project.
Do not execute destructive commands.

These instructions can influence model behavior, but they should not be treated as the security boundary.

The model is still interpreting instructions and deciding what actions to request. External content can also influence that reasoning. A malicious README, issue description, source file, dependency, or generated instruction could attempt to convince the agent to perform an operation outside its intended task.

Research on coding-agent authorization has found that models can struggle to infer exactly which permissions are necessary while simultaneously avoiding unnecessary or sensitive access.

The stronger architecture is:

User
  |
  v
AI Coding Agent
  |
  | Tool request
  v
Capability Policy Layer
  |
  +---- Allowed ----> Tool
  |
  +---- Denied -----> Audit Log

The policy layer should make the final authorization decision.

Designing Capabilities for a Coding Agent

A practical capability model can start with four dimensions:

Dimension	Example	Security Question
Resource	/workspace/orders	What can the agent access?
Operation	Read / Write / Execute	What can it do?
Scope	Project directory only	How much of the resource?
Condition	Development environment	When is access allowed?

This is more precise than simply assigning a role such as DeveloperAgent.

Consider a coding agent that needs to fix a failing unit test.

It may require:

Read  -> repository
Write -> src/ and tests/
Execute -> dotnet test

It probably does not need:

Read -> ~/.ssh
Read -> browser credentials
Write -> operating-system directories
Execute -> arbitrary shell commands
Access -> production database

The objective is not to make the agent incapable. The objective is to make its authorized capability set match the task.

Implementing a Capability Policy in C#

The following example demonstrates a small authorization layer. It is intentionally framework-neutral so the same concept can be adapted to an existing agent orchestration system.

Define the Capabilities

public enum AgentCapability
{
    ReadWorkspace,
    WriteWorkspace,
    RunTests,
    ReadSecrets,
    Deploy
}

Now define the policy assigned to an agent session:

public sealed class AgentPolicy
{
    private readonly HashSet<AgentCapability> _capabilities;

    public AgentPolicy(IEnumerable<AgentCapability> capabilities)
    {
        _capabilities = capabilities.ToHashSet();
    }

    public bool Allows(AgentCapability capability)
    {
        return _capabilities.Contains(capability);
    }
}

A test-fixing agent could receive:

var policy = new AgentPolicy(
[
    AgentCapability.ReadWorkspace,
    AgentCapability.WriteWorkspace,
    AgentCapability.RunTests
]);

It does not automatically receive deployment or secret-access privileges.

Authorize Before Executing a Tool

The important part is not defining the capability. The important part is checking it before the operation reaches the underlying system.

public sealed class AgentToolBroker
{
    private readonly AgentPolicy _policy;

    public AgentToolBroker(AgentPolicy policy)
    {
        _policy = policy;
    }

    public void Authorize(AgentCapability capability, string operation)
    {
        if (!_policy.Allows(capability))
        {
            throw new UnauthorizedAccessException(
                $"Operation '{operation}' is not permitted.");
        }
    }
}

A file-writing operation can then enforce the policy:

public async Task WriteFileAsync(
    string path,
    string content,
    AgentToolBroker broker)
{
    broker.Authorize(
        AgentCapability.WriteWorkspace,
        "write-file");

    await File.WriteAllTextAsync(path, content);
}

This example is intentionally simple. A production implementation also needs to validate the resource being accessed, not just the operation.

Giving an agent WriteWorkspace does not mean it should be able to write every directory on the machine.

Scope the Filesystem Capability

A safer implementation associates the capability with an allowed root.

public sealed class WorkspacePolicy
{
    private readonly string _workspaceRoot;

    public WorkspacePolicy(string workspaceRoot)
    {
        _workspaceRoot = Path.GetFullPath(workspaceRoot);
    }

    public string ValidatePath(string requestedPath)
    {
        var fullPath = Path.GetFullPath(requestedPath);

        if (!fullPath.StartsWith(
                _workspaceRoot,
                StringComparison.OrdinalIgnoreCase))
        {
            throw new UnauthorizedAccessException(
                "Path is outside the permitted workspace.");
        }

        return fullPath;
    }
}

The tool can use the validated path:

public async Task WriteWorkspaceFileAsync(
    string path,
    string content,
    WorkspacePolicy workspace)
{
    var safePath = workspace.ValidatePath(path);

    await File.WriteAllTextAsync(safePath, content);
}

This creates a second security boundary:

Capability
    |
    +-- Operation: Write
    |
    +-- Resource: Workspace
    |
    +-- Scope: Specific directory

For production systems, path validation should account for symbolic links, junctions, race conditions, filesystem permissions, and the isolation guarantees of the underlying operating system or sandbox. A string-prefix check by itself should not be considered a complete filesystem security mechanism.

Capability-Based Access vs Role-Based Access

Role-based access control remains useful, but agentic systems often need finer-grained controls.

Approach	Strength	Limitation
Role-based access	Easy to understand and manage	Roles can become broad
Prompt-based restrictions	Simple to implement	Not an enforcement boundary
Capability-based access	Fine-grained authority	Requires policy infrastructure
OS/container sandbox	Strong resource isolation	Requires infrastructure
Human approval	Useful for high-impact operations	Adds workflow friction

These mechanisms should not be viewed as mutually exclusive.

A production architecture can combine them:

Agent Identity
      |
      v
Role / Policy
      |
      v
Capability Check
      |
      v
Sandbox / OS Boundary
      |
      v
Tool Execution
      |
      v
Audit Log

High-Risk Capabilities Should Require Additional Controls

Not every operation deserves the same authorization process.

Reading a source file is normally lower risk than deploying an application.

A useful classification is:

Risk	Example	Typical Control
Low	Read source code	Capability check
Medium	Modify source code	Scoped capability + audit
High	Install packages	Allowlist + approval
High	Modify infrastructure	Approval + restricted identity
Critical	Production deployment	Human approval + short-lived credentials

Microsoft recommends least-privilege identities and explicitly scoped access for agents, while its security guidance also emphasizes logging agent identity, effective scope, actions, resources, and correlation information.

Audit Every Capability Decision

Authorization without observability makes security investigations difficult.

A capability broker should record events such as:

public sealed record AgentAuditEvent(
    string AgentId,
    string Capability,
    string Operation,
    string Resource,
    bool Allowed,
    DateTimeOffset Timestamp);

A denied request should be recorded as carefully as an allowed request.

For example:

AgentId: coding-agent-42
Capability: ReadSecrets
Operation: read-file
Resource: ~/.ssh/config
Allowed: false

This provides useful evidence when investigating unexpected agent behavior.

It also makes it possible to identify agents that repeatedly request permissions outside their intended task.

Common Mistakes

Giving the Agent the Developer's Full Permissions

Running an agent under a developer's unrestricted account defeats much of the purpose of least privilege.

Use a dedicated identity, restricted workspace, and narrowly scoped credentials where possible.

Treating the System Prompt as Authorization

A prompt can provide behavioral guidance, but authorization should be enforced outside the model.

Using One Permission for Everything

A capability such as FileAccess is usually too broad.

Prefer separate operations such as:

ReadWorkspace
WriteWorkspace
RunTests
InstallPackages
Deploy

Then scope each operation further.

Forgetting Network Access

Filesystem restrictions do not prevent an agent from sending information elsewhere.

Network egress should therefore be considered part of the capability model.

Giving Long-Lived Credentials to Agents

If an operation requires credentials, prefer short-lived, narrowly scoped credentials and make revocation possible.

Troubleshooting Capability Policies

The Agent Cannot Complete a Valid Task

Do not immediately grant unrestricted access.

Instead:

1. Review the denied capability.

2. Determine whether the operation is genuinely required.

3. Add the smallest necessary capability.

4. Restrict its resource scope.

5. Retest the workflow.

6. Record the policy change.

This turns authorization failures into useful feedback for improving the policy.

The Agent Requests Too Many Permissions

Treat excessive permission requests as a design signal.

Review the task and identify the minimum execution chain. If the agent needs ten capabilities to perform a simple operation, the tool abstraction may be too broad.

A Capability Is Technically Allowed but Still Dangerous

Capabilities should be evaluated based on their effective impact.

For example, RunCommand is substantially broader than RunTests, even if both eventually execute a process.

Prefer domain-specific tools where practical:

RunTests
BuildProject
FormatCode
CreatePatch

instead of exposing:

ExecuteAnything

Best Practices Checklist

Before allowing an AI coding agent to operate in a development environment:

• Use a dedicated agent identity.

• Start with deny-by-default permissions.

• Give the agent only the capabilities required for its task.

• Scope filesystem access to specific directories.

• Restrict network destinations where possible.

• Prefer specific tools over unrestricted shell access.

• Separate development and production capabilities.

• Use short-lived credentials for sensitive operations.

• Require human approval for irreversible or high-impact actions.

• Log capability decisions and tool execution.

• Test revocation and policy changes.

• Review permissions whenever the agent's tools or workflow change.

• Treat third-party tools, plugins, and dependencies as part of the security boundary.

Conclusion

AI coding agents change the security problem from simply protecting an application to controlling what an autonomous software process is authorized to do.

Capability-based access provides a useful foundation because it separates what the model requests from what the environment actually permits.

The strongest architecture is not a single security mechanism. It combines agent identity, least privilege, scoped capabilities, filesystem and network isolation, approval gates, short-lived credentials, and comprehensive auditing.

The key principle is straightforward:

Let the agent reason broadly, but execute narrowly.

That distinction allows development teams to benefit from autonomous coding workflows without giving an AI process unrestricted authority over the environments it operates in.

Research into agent security increasingly frames the problem in similar terms: agents should be treated as security principals with explicit boundaries around resources, tools, identities, and execution environments.