Security Audit for Agent-Ready Repos

Overview

Giving an AI agent write access to your codebase is a powerful capability -- and a significant trust decision. An agent that can create files, run commands, and open pull requests operates with a level of access that most human contributors earn over weeks or months. This lesson provides a structured security audit for repositories where agents work, covering the specific risks that agent access introduces and the controls that mitigate them. Whether you are preparing for your first agent deployment or hardening an existing setup, this checklist ensures you have not overlooked the threats that are unique to agent-assisted development.

Why Agent Security Is Different

Traditional code security focuses on what humans might do -- accidentally commit secrets, introduce vulnerabilities, or misconfigure access controls. Agent security adds a new dimension: an automated system that reads, writes, and executes at machine speed, often without a human watching every action in real time.

Human developer risks vs additional agent risks: human risks include committing secrets accidentally, introducing vulnerabilities, and misconfiguring access. Agent risks add new dimensions: leaking secrets into generated code or logs, executing arbitrary commands at scale, bypassing review if not properly gated, and reading sensitive files whose content is included in API calls. Both share controls: secret scanning, branch protection, code review, and least privilege.

The key differences are:

• Speed and volume -- an agent can modify dozens of files in seconds. A human reviewer's attention is the bottleneck
• Context leakage -- every file the agent reads may be sent to an API endpoint. Sensitive data in the codebase becomes sensitive data in transit
• Command execution -- agents with shell access can run arbitrary commands. Without sandboxing, this includes network requests, file system modifications outside the project, and process management
• Implicit trust escalation -- if an agent can push to a branch that triggers a deployment pipeline, the agent effectively has deployment access

The Security Audit Checklist

This audit covers six domains. Work through each one systematically.

Domain 1: Secrets Management

Secrets -- API keys, database credentials, tokens, private keys -- are the highest-severity risk. An agent that reads a .env file might include the secret in generated code, reference it in a commit message, or send it to an external API as part of the model context.

Audit steps:

• Verify .env, .env.local, and all secret files are in .gitignore
• Run a secret scanner against the full repository history, not just the current state
• Check that the CLAUDE.md explicitly tells the agent not to read or reference secret files
• Confirm that environment variables are injected at runtime, not stored in configuration files

Domain 2: Branch Protection and Push Controls

An agent that can push directly to main bypasses every review process your team has built. Even if the agent's code is correct, unreviewed pushes violate the principle that all changes go through human review.

Audit steps:

• Confirm that the default branch (main or master) has branch protection rules enabled
• Require pull request reviews before merging -- no direct pushes
• Require status checks (CI) to pass before merging
• Set up a pre-push hook as a local safety net

Domain 3: Agent Permissions and Sandboxing

The principle of least privilege is the foundation of agent security. Every agent should have only the permissions it needs for its specific task -- nothing more.

Overprivileged vs properly scoped agent: an overprivileged agent can read all files, write anywhere, execute any command, and has network access. A properly scoped agent is restricted to reading only src/ and tests/, writing only to src/services/, executing only npm test, and has no network access.

Audit steps:

• Review the agent's permission configuration. Can it run arbitrary bash commands? If so, restrict to a specific allowlist
• Verify file system sandboxing -- the agent should only access the project directory, not the home directory or system files
• Check whether the agent can make network requests. If not needed, disable network access
• For specialized agents (reviewers, linters), confirm they have read-only access -- no write permissions

Domain 4: Hook Coverage

Hooks are your automated safety net -- the controls that run automatically before or after agent actions. Incomplete hook coverage means some agent actions go unchecked.

Audit steps:

• Inventory all hooks (pre-commit, pre-push, CI checks) and map them to agent actions
• Verify that hooks cannot be bypassed with --no-verify flags
• Check that hooks run in the agent's execution environment (not just the developer's local machine)
• Test each hook by intentionally triggering the condition it guards against

Domain 5: MCP Server Security

If your agents use MCP (Model Context Protocol) servers -- for database access, API integrations, or external tool connections -- each server is a potential attack surface.

Audit steps:

• List all MCP servers the agent can access. Is each one necessary?
• Verify authentication on each MCP connection -- no unauthenticated servers
• Check that MCP servers use scoped permissions (read-only database access, not admin)
• Review MCP server logs for unexpected access patterns
• Confirm that MCP server credentials are not stored in the repository

Domain 6: Audit Trail and Monitoring

Security is not just prevention -- it is detection. If something goes wrong, you need to know what happened and when.

Audit steps:

• Verify that all agent sessions are logged with timestamps, actions, and outcomes
• Check that agent-generated commits are identifiable (distinct author or co-author tag)
• Set up alerts for unusual agent activity: large numbers of file changes, changes to sensitive directories, or failed permission checks
• Retain agent transcripts for at least 30 days for forensic review

Audit trail components: Session Logs (timestamps, actions, file changes), Commit Attribution (agent co-author tags in git history), Access Logs (MCP server access, file read/write events), and Alert System (unusual patterns, policy violations). The first three feed into forensic review capability; the alert system triggers immediate response.

The Quick Security Checklist

For teams that want a rapid pass before deeper auditing, here is the essential checklist:

• .env and secret files are in .gitignore and never committed
• CLAUDE.md explicitly forbids reading or referencing secrets
• Branch protection prevents direct pushes to main
• Pre-commit hook scans for secret patterns
• Agent permissions follow least privilege -- no unnecessary write or execute access
• Agent file system access is limited to the project directory
• MCP servers are authenticated and use scoped permissions
• Agent-generated commits are identifiable in git history
• CI runs the same checks on agent PRs as human PRs
• Agent session transcripts are retained for review

Ongoing Security Maintenance

A security audit is not a one-time event. As your codebase evolves and agent capabilities expand, the security posture must evolve with them.

Monthly reviews:

• Review agent access logs for anomalies
• Update the secret scanning patterns to cover new secret types
• Verify that new MCP server integrations follow the security standards
• Check that new team members' agent configurations follow the org-wide security policy

Triggered reviews:

• Any new MCP server integration triggers a security review
• Any change to agent permissions triggers a review
• Any security incident (even minor) triggers a retrospective that updates the checklist

Security is not a gate that blocks adoption -- it is a foundation that enables confident adoption. Teams that address security early adopt agents more aggressively because they trust the guardrails.

Summary

Securing an agent-ready repository requires auditing six domains: secrets management, branch protection, agent permissions, hook coverage, MCP server security, and audit trails. The risks agents introduce -- context leakage, command execution at scale, and implicit trust escalation -- are distinct from traditional developer risks and require specific controls. Use the quick checklist for an initial pass, then work through the detailed audit for each domain. Treat security as an ongoing practice, not a one-time gate. In the next lesson, we shift from safety to efficiency: optimizing agents for speed, accuracy, and cost.