6.2 Least-Privilege Permissions & Policy Enforcement

6.2 Least-Privilege Permissions & Policy Enforcement

Introduction to Identity & Access Management for AI Agents

Autonomous AI developer agents act as non-human identities within modern software engineering ecosystems. When an agent interacts with GitHub REST/GraphQL APIs, clones repositories, executes CI/CD workflows, or creates pull requests, its authorization boundaries are dictated entirely by the access tokens granted to it. Providing over-privileged access tokens—such as Classic Personal Access Tokens (PATs) with full repo or admin scopes—exposes enterprise organizations to severe security risks. If an AI model experiences prompt injection, context contamination, or supply chain poisoning, an over-privileged token can be exploited to exfiltrate private source code, wipe repositories, or compromise organization credentials.

Enforcing the Principle of Least Privilege (PoLP) requires authenticating AI agents through short-lived, fine-grained, repository-scoped identities with strict cryptographic attribution and branch protection controls.

---

GitHub App Installation Tokens vs Classic Personal Access Tokens (PATs)

GitHub provides two primary mechanisms for authenticating automated identities: Classic PATs and GitHub Apps. For enterprise AI agents, GitHub Apps are mandatory.

Risks of Classic PATs in AI Workflows

Using Classic PATs for AI agents introduces three critical vulnerabilities:

1. Over-Privilege: A Classic PAT with repo scope grants full read/write access to every public and private repository accessible by the token owner. An AI agent working on a minor documentation fix effectively holds keys to the enterprise's entire intellectual property portfolio.
2. Lack of Non-Repudiation: Because actions performed via Classic PATs appear under the human owner's identity, security audit logs cannot differentiate between actions taken intentionally by the engineer and actions executed autonomously by the AI agent.
3. Credential Stolen Persistence: If a long-lived PAT is leaked via agent stdout logging or LLM context leakage, attackers gain persistent, unrestricted access until manual revocation.

---

JWT Token Exchange & Authentication Architecture

GitHub Apps authenticate using a two-tier token exchange protocol based on JSON Web Tokens (JWT) and short-lived installation access tokens.

+------------------+             +-----------------------+             +----------------------+
|  AI Agent Host   |             |   GitHub Auth Server  |             |  GitHub REST/GraphQL |
+------------------+             +-----------------------+             +----------------------+
         │                                   │                                   │
         │ 1. Sign JWT with Private Key      │                                   │
         │    (RS256 algorithm, 10m exp)     │                                   │
         │                                   │                                   │
         │ 2. POST /app/installations/       │                                   │
         │    {install_id}/access_tokens     │                                   │
         │ --------------------------------> │                                   │
         │    (Header: Bearer <JWT>)         │                                   │
         │    (Body: permissions & repos)    │                                   │
         │                                   │                                   │
         │ 3. Return Installation Token      │                                   │
         │ <-------------------------------- │                                   │
         │    (Token: ghs_xxxx, 1h exp)      │                                   │
         │                                   │                                   │
         │ 4. Execute API Request            │                                   │
         │ --------------------------------------------------------------------> │
         │    (Header: Authorization Bearer ghs_xxxx)                            │

The Authentication Steps

1. Private Key Storage: The AI App's RSA private key (.pem) is securely stored in a cloud Hardware Security Module (HSM) or secret store (e.g., HashiCorp Vault or AWS KMS).
2. JWT Generation: When an AI agent initializes, it generates a JWT signed with RS256 algorithm. The JWT payload includes:
   • iss (Issuer): The GitHub App's unique ID (App ID).
   • iat (Issued At): Current UTC timestamp minus 60 seconds (to account for clock skew).
   • exp (Expiration): Current UTC timestamp plus maximum 10 minutes.
3. Token Exchange Call: The agent issues an HTTP POST request to GitHub's authentication endpoint: POST /app/installations/{installation_id}/access_tokens The request body specifies requested fine-grained permissions and exact target repositories:

   {
     "repositories": ["service-core"],
     "permissions": {
       "contents": "read",
       "pull_requests": "write",
       "issues": "write"
     }
   }
   

4. Scoped Access Token Delivery: GitHub validates the JWT signature and returns an installation access token (prefixed with ghs_). This token expires automatically after exactly 60 minutes and is strictly constrained to the requested permissions and repository list.

---

Least-Privilege REST & GraphQL Permission Matrices

To prevent privilege escalation, enterprise security policy engines enforce strict permission matrices tailored to the agent's assigned task role:

Defending Against workflows: write Vulnerabilities

A common attack vector in automated GitHub workflows is modifying .github/workflows/ files. If an AI agent possesses workflows: write permission, a prompt injection attack could trick the model into adding malicious steps (such as exfiltrating repository secrets or running crypto-miners) to GitHub Actions workflows. Enterprise policy requires stripping workflows: write permission from all AI agent installation tokens by default.

---

Cryptographic Commit Signing (GPG, SSH & Cloud KMS)

Code integrity requires non-repudiable proof that commits were generated by an authorized AI identity and have not been altered in transit.

KMS-Backed Commit Signing Architecture

Rather than storing static GPG private keys inside containerized AI agent runners (where they could be leaked), enterprise architectures utilize cloud KMS/HSM endpoints:

1. Git Commit Creation: The AI agent builds a Git commit object locally in its workspace.
2. Payload Hash Extraction: The raw commit header and content buffer are hashed (SHA-256).
3. KMS Signing Request: The commit hash is sent to a cloud KMS service (e.g., AWS KMS or Google Cloud KMS) holding an isolated RSA or SSH private key.
4. Signature Insertion: KMS returns an asymmetric signature block, which is embedded into the Git commit object header before pushing to remote.
5. GitHub Verification: GitHub checks the signature against the App's registered public key, displaying a "Verified" badge next to the bot's commit in the PR UI.

+-------------------------+             +------------------------+             +------------------------+
|  AI Agent Local Runner  |             | Cloud KMS / HSM Module |             | GitHub Remote Repo     |
+-------------------------+             +------------------------+             +------------------------+
             │                                       │                                      │
             │ 1. Assemble Commit Object             │                                      │
             │ 2. Compute Commit Hash                │                                      │
             │ 3. Send Sign Request (Hash)           │                                      │
             │ ------------------------------------> │                                      │
             │                                       │                                      │
             │ 4. Return Asymmetric Signature        │                                      │
             │ <------------------------------------ │                                      │
             │                                       │                                      │
             │ 5. Embed Signature into Git Commit    │                                      │
             │ 6. git push origin feature-branch     │                                      │
             │ ---------------------------------------------------------------------------> │
             │                                                                              │ (Validates & Displays
             │                                                                              │  "Verified" Bot Badge)

---

CODEOWNERS & Branch Protection Ruleset Integration

Even with fine-grained tokens, AI agents must be bound by repository governance rules. Enterprise repositories implement GitHub Rulesets and CODEOWNERS enforcement:

CODEOWNERS Integration

The CODEOWNERS file defines individual developers or teams responsible for specific directory paths:

# Critical Security and Infrastructure CODEOWNERS
/src/auth/              @org-security-team
/.github/workflows/     @org-devops-lead
/infrastructure/        @org-infra-team

When an AI agent opens a Pull Request modifying /src/auth/login.ts, GitHub automatically assigns @org-security-team as mandatory approvers. The PR cannot be merged until human code owners review and approve the diff.

Essential Branch Protection Rulesets for AI Agents

1. Require Signed Commits: Rejects un-signed pushes to protected branches, ensuring all code originates from authenticated KMS bot signatures or verified developer keys.
2. Require Linear History: Prevents merge commits that obscure commit origin tracing.
3. Require Status Checks to Pass: Ensures CI build, linter, and unit test suites pass prior to merge.
4. Block AI Bot Bypass Permissions: Enterprise admin policies must explicitly uncheck "Allow specified actors to bypass pull request requirements" for all AI bot service accounts. AI agents must satisfy identical governance standards as human developers.