ai-coding-agent-guardrails
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAI Coding Agent Guardrails
AI编码代理安全防护规则
Secure the use of AI coding agents across engineering teams. This skill covers permission boundaries, secret protection, sandbox isolation, code review gates, and audit trails for Claude Code, Cursor, Copilot, and Codex.
为工程团队安全使用AI编码代理提供保障。本技能涵盖针对Claude Code、Cursor、Copilot和Codex的权限边界、秘密保护、沙箱隔离、代码审查关卡以及审计追踪。
When to Use
适用场景
Apply these guardrails when:
- Onboarding AI coding agents into an engineering team for the first time
- Developers are using Claude Code, Cursor, Copilot, or Codex to generate production code
- Agents have access to repositories containing secrets, infrastructure configs, or sensitive business logic
- Your compliance framework (SOC 2, ISO 27001, FedRAMP) requires controls around automated code generation
- Autonomous or semi-autonomous agents are creating pull requests without direct human typing
- You need to enforce consistent security policies across multiple agents and team members
Signs you need tighter guardrails:
- Agents have committed secrets or credentials to version control
- Agent-generated code has introduced vulnerabilities caught late in the pipeline
- No clear audit trail distinguishes human-written from AI-generated code
- Developers are bypassing code review for "simple" agent changes
- Agents are executing arbitrary shell commands in production-connected environments
在以下场景中应用这些防护规则:
- 首次为工程团队引入AI编码代理时
- 开发人员使用Claude Code、Cursor、Copilot或Codex生成生产代码时
- 代理可访问包含机密信息、基础设施配置或敏感业务逻辑的代码仓库时
- 你的合规框架(SOC 2、ISO 27001、FedRAMP)要求对自动化代码生成实施管控时
- 自主或半自主代理无需人工直接输入即可创建拉取请求时
- 你需要在多个代理和团队成员间强制执行一致的安全策略时
需要加强防护规则的迹象:
- 代理曾将机密或凭证提交至版本控制系统
- 代理生成的代码在流水线后期才被发现存在漏洞
- 没有清晰的审计轨迹区分人工编写与AI生成的代码
- 开发人员为“简单”的代理更改绕过代码审查
- 代理在连接生产环境的环境中执行任意Shell命令
Permission Boundaries
权限边界
CLAUDE.md Configuration
CLAUDE.md 配置
Create a at the repository root to restrict Claude Code behavior:
CLAUDE.mdmarkdown
undefined在仓库根目录创建文件以限制Claude Code的行为:
CLAUDE.mdmarkdown
undefinedCLAUDE.md
CLAUDE.md
Restrictions
Restrictions
- NEVER read or output contents of .env, .env.*, secrets.yaml, or any file matching *.pem, *.key
- NEVER execute ,
rm -rf,DROP TABLE, orkubectl deletecommandsterraform destroy - NEVER push directly to main or master branches
- NEVER modify files in the infrastructure/, terraform/, or .github/workflows/ directories without explicit user approval
- NEVER install new dependencies without listing them first for review
- NEVER access or display API keys, tokens, passwords, or connection strings
- NEVER read or output contents of .env, .env.*, secrets.yaml, or any file matching *.pem, *.key
- NEVER execute ,
rm -rf,DROP TABLE, orkubectl deletecommandsterraform destroy - NEVER push directly to main or master branches
- NEVER modify files in the infrastructure/, terraform/, or .github/workflows/ directories without explicit user approval
- NEVER install new dependencies without listing them first for review
- NEVER access or display API keys, tokens, passwords, or connection strings
Allowed Operations
Allowed Operations
- Read and modify application source code in src/, lib/, and tests/
- Run test suites with ,
npm test,pytestgo test - Run linters with ,
eslint,ruffgolangci-lint - Create new branches with prefix or
ai/agent/ - Create and modify files in docs/ directory
- Read and modify application source code in src/, lib/, and tests/
- Run test suites with ,
npm test,pytestgo test - Run linters with ,
eslint,ruffgolangci-lint - Create new branches with prefix or
ai/agent/ - Create and modify files in docs/ directory
Code Standards
Code Standards
- All new functions must include docstrings or JSDoc comments
- All new code must have corresponding unit tests
- Follow existing code style and patterns in the repository
- Maximum file length: 500 lines. Suggest splitting if exceeded.
undefined- All new functions must include docstrings or JSDoc comments
- All new code must have corresponding unit tests
- Follow existing code style and patterns in the repository
- Maximum file length: 500 lines. Suggest splitting if exceeded.
undefinedCommand Allowlists
命令允许列表
For agents that execute shell commands, define an explicit allowlist:
yaml
undefined对于可执行Shell命令的代理,定义明确的允许列表:
yaml
undefined.agent-permissions.yaml
.agent-permissions.yaml
agent_permissions:
allowed_commands:
- "npm test"
- "npm run lint"
- "npm run build"
- "pytest"
- "ruff check"
- "go test ./..."
- "git status"
- "git diff"
- "git log"
- "git checkout -b"
- "git add"
- "git commit"
- "ls"
- "cat"
- "head"
- "tail"
blocked_commands:
- "rm -rf"
- "curl"
- "wget"
- "ssh"
- "scp"
- "kubectl"
- "terraform"
- "aws"
- "gcloud"
- "az"
- "docker push"
- "npm publish"
blocked_paths:
- ".env*"
- "/*.pem"
- "/*.key"
- "/secrets/"
- "infrastructure/"
- ".github/workflows/"
allowed_paths:
- "src/"
- "lib/"
- "tests/"
- "docs/"
- "package.json"
- "pyproject.toml"
undefinedagent_permissions:
allowed_commands:
- "npm test"
- "npm run lint"
- "npm run build"
- "pytest"
- "ruff check"
- "go test ./..."
- "git status"
- "git diff"
- "git log"
- "git checkout -b"
- "git add"
- "git commit"
- "ls"
- "cat"
- "head"
- "tail"
blocked_commands:
- "rm -rf"
- "curl"
- "wget"
- "ssh"
- "scp"
- "kubectl"
- "terraform"
- "aws"
- "gcloud"
- "az"
- "docker push"
- "npm publish"
blocked_paths:
- ".env*"
- "/*.pem"
- "/*.key"
- "/secrets/"
- "infrastructure/"
- ".github/workflows/"
allowed_paths:
- "src/"
- "lib/"
- "tests/"
- "docs/"
- "package.json"
- "pyproject.toml"
undefinedFile System Access Controls
文件系统访问控制
Use filesystem permissions to enforce boundaries at the OS level:
bash
#!/bin/bash使用文件系统权限在操作系统层面强制执行边界:
bash
#!/bin/bashsetup-agent-workspace.sh
setup-agent-workspace.sh
Create a restricted workspace for agent execution
Create a restricted workspace for agent execution
AGENT_USER="ai-agent"
REPO_DIR="/workspace/repo"
AGENT_USER="ai-agent"
REPO_DIR="/workspace/repo"
Create agent user with limited permissions
Create agent user with limited permissions
useradd --system --shell /bin/bash --no-create-home "$AGENT_USER"
useradd --system --shell /bin/bash --no-create-home "$AGENT_USER"
Set ownership: developers own everything, agent gets read on most
Set ownership: developers own everything, agent gets read on most
chown -R root:developers "$REPO_DIR"
chmod -R 750 "$REPO_DIR"
chown -R root:developers "$REPO_DIR"
chmod -R 750 "$REPO_DIR"
Grant agent write access only to safe directories
Grant agent write access only to safe directories
setfacl -R -m u:${AGENT_USER}:rwx "${REPO_DIR}/src"
setfacl -R -m u:${AGENT_USER}:rwx "${REPO_DIR}/tests"
setfacl -R -m u:${AGENT_USER}:rwx "${REPO_DIR}/docs"
setfacl -R -m u:${AGENT_USER}:rwx "${REPO_DIR}/src"
setfacl -R -m u:${AGENT_USER}:rwx "${REPO_DIR}/tests"
setfacl -R -m u:${AGENT_USER}:rwx "${REPO_DIR}/docs"
Deny agent access to sensitive files
Deny agent access to sensitive files
setfacl -m u:${AGENT_USER}:--- "${REPO_DIR}/.env"
setfacl -R -m u:${AGENT_USER}:--- "${REPO_DIR}/infrastructure"
setfacl -R -m u:${AGENT_USER}:--- "${REPO_DIR}/.github/workflows"
echo "Agent workspace permissions configured."
---setfacl -m u:${AGENT_USER}:--- "${REPO_DIR}/.env"
setfacl -R -m u:${AGENT_USER}:--- "${REPO_DIR}/infrastructure"
setfacl -R -m u:${AGENT_USER}:--- "${REPO_DIR}/.github/workflows"
echo "Agent workspace permissions configured."
---Secret Protection
秘密保护
Pre-commit Hooks with git-secrets
结合git-secrets的预提交钩子
bash
#!/bin/bashbash
#!/bin/bashinstall-secret-scanning.sh
install-secret-scanning.sh
Install git-secrets
Install git-secrets
git clone https://github.com/awslabs/git-secrets.git /tmp/git-secrets
cd /tmp/git-secrets && make install
git clone https://github.com/awslabs/git-secrets.git /tmp/git-secrets
cd /tmp/git-secrets && make install
Initialize in repository
Initialize in repository
cd /path/to/repo
git secrets --install
cd /path/to/repo
git secrets --install
Register common secret patterns
Register common secret patterns
git secrets --register-aws
git secrets --register-aws
Add custom patterns for common credential formats
Add custom patterns for common credential formats
git secrets --add '-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----'
git secrets --add 'AKIA[0-9A-Z]{16}'
git secrets --add 'ghp_[a-zA-Z0-9]{36}'
git secrets --add 'sk-[a-zA-Z0-9]{48}'
git secrets --add 'xox[baprs]-[0-9a-zA-Z-]{10,}'
git secrets --add 'password\s*[:=]\s*["\x27][^\s]{8,}'
git secrets --add 'api[_-]?key\s*[:=]\s*["\x27][^\s]{8,}'
git secrets --add '-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----'
git secrets --add 'AKIA[0-9A-Z]{16}'
git secrets --add 'ghp_[a-zA-Z0-9]{36}'
git secrets --add 'sk-[a-zA-Z0-9]{48}'
git secrets --add 'xox[baprs]-[0-9a-zA-Z-]{10,}'
git secrets --add 'password\s*[:=]\s*["\x27][^\s]{8,}'
git secrets --add 'api[_-]?key\s*[:=]\s*["\x27][^\s]{8,}'
Add allowed patterns (false positive exclusions)
Add allowed patterns (false positive exclusions)
git secrets --add --allowed 'EXAMPLE_KEY'
git secrets --add --allowed 'your-api-key-here'
undefinedgit secrets --add --allowed 'EXAMPLE_KEY'
git secrets --add --allowed 'your-api-key-here'
undefinedAgent Output Scanning
代理输出扫描
Scan agent-generated output before it reaches version control:
python
#!/usr/bin/env python3
"""scan_agent_output.py - Scan AI agent output for leaked secrets."""
import re
import sys
from pathlib import Path
SECRET_PATTERNS = [
(r'AKIA[0-9A-Z]{16}', 'AWS Access Key'),
(r'(?i)aws_secret_access_key\s*[:=]\s*\S+', 'AWS Secret Key'),
(r'ghp_[a-zA-Z0-9]{36}', 'GitHub Personal Access Token'),
(r'gho_[a-zA-Z0-9]{36}', 'GitHub OAuth Token'),
(r'sk-[a-zA-Z0-9]{48,}', 'OpenAI/Anthropic API Key'),
(r'xox[baprs]-[0-9a-zA-Z\-]{10,}', 'Slack Token'),
(r'-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----', 'Private Key'),
(r'(?i)(password|passwd|pwd)\s*[:=]\s*["\x27][^\s]{4,}', 'Hardcoded Password'),
(r'(?i)(api[_-]?key|apikey)\s*[:=]\s*["\x27][^\s]{8,}', 'API Key'),
(r'eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}', 'JWT Token'),
(r'(?i)database_url\s*[:=]\s*\S+', 'Database Connection String'),
]
def scan_file(filepath: str) -> list[dict]:
findings = []
content = Path(filepath).read_text(errors="ignore")
for line_num, line in enumerate(content.splitlines(), 1):
for pattern, label in SECRET_PATTERNS:
if re.search(pattern, line):
findings.append({
"file": filepath,
"line": line_num,
"type": label,
"content": line.strip()[:120],
})
return findings
def main():
files = sys.argv[1:]
if not files:
print("Usage: scan_agent_output.py <file1> [file2] ...")
sys.exit(1)
all_findings = []
for f in files:
all_findings.extend(scan_file(f))
if all_findings:
print(f"BLOCKED: {len(all_findings)} potential secret(s) detected:\n")
for finding in all_findings:
print(f" [{finding['type']}] {finding['file']}:{finding['line']}")
print(f" {finding['content']}\n")
sys.exit(1)
print("OK: No secrets detected in agent output.")
sys.exit(0)
if __name__ == "__main__":
main()在代理输出进入版本控制系统前进行扫描:
python
#!/usr/bin/env python3
"""scan_agent_output.py - Scan AI agent output for leaked secrets."""
import re
import sys
from pathlib import Path
SECRET_PATTERNS = [
(r'AKIA[0-9A-Z]{16}', 'AWS Access Key'),
(r'(?i)aws_secret_access_key\s*[:=]\s*\S+', 'AWS Secret Key'),
(r'ghp_[a-zA-Z0-9]{36}', 'GitHub Personal Access Token'),
(r'gho_[a-zA-Z0-9]{36}', 'GitHub OAuth Token'),
(r'sk-[a-zA-Z0-9]{48,}', 'OpenAI/Anthropic API Key'),
(r'xox[baprs]-[0-9a-zA-Z\-]{10,}', 'Slack Token'),
(r'-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----', 'Private Key'),
(r'(?i)(password|passwd|pwd)\s*[:=]\s*["\x27][^\s]{4,}', 'Hardcoded Password'),
(r'(?i)(api[_-]?key|apikey)\s*[:=]\s*["\x27][^\s]{8,}', 'API Key'),
(r'eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}', 'JWT Token'),
(r'(?i)database_url\s*[:=]\s*\S+', 'Database Connection String'),
]
def scan_file(filepath: str) -> list[dict]:
findings = []
content = Path(filepath).read_text(errors="ignore")
for line_num, line in enumerate(content.splitlines(), 1):
for pattern, label in SECRET_PATTERNS:
if re.search(pattern, line):
findings.append({
"file": filepath,
"line": line_num,
"type": label,
"content": line.strip()[:120],
})
return findings
def main():
files = sys.argv[1:]
if not files:
print("Usage: scan_agent_output.py <file1> [file2] ...")
sys.exit(1)
all_findings = []
for f in files:
all_findings.extend(scan_file(f))
if all_findings:
print(f"BLOCKED: {len(all_findings)} potential secret(s) detected:\n")
for finding in all_findings:
print(f" [{finding['type']}] {finding['file']}:{finding['line']}")
print(f" {finding['content']}\n")
sys.exit(1)
print("OK: No secrets detected in agent output.")
sys.exit(0)
if __name__ == "__main__":
main()Git Pre-commit Hook Integration
Git预提交钩子集成
bash
#!/bin/bashbash
#!/bin/bash.git/hooks/pre-commit
.git/hooks/pre-commit
Block commits containing secrets from AI agents
Block commits containing secrets from AI agents
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
if [ -z "$STAGED_FILES" ]; then
exit 0
fi
echo "Scanning staged files for secrets..."
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
if [ -z "$STAGED_FILES" ]; then
exit 0
fi
echo "Scanning staged files for secrets..."
Run git-secrets
Run git-secrets
git secrets --pre_commit_hook -- "$@"
GIT_SECRETS_EXIT=$?
git secrets --pre_commit_hook -- "$@"
GIT_SECRETS_EXIT=$?
Run custom scanner on staged files
Run custom scanner on staged files
python3 .tools/scan_agent_output.py $STAGED_FILES
SCANNER_EXIT=$?
if [ $GIT_SECRETS_EXIT -ne 0 ] || [ $SCANNER_EXIT -ne 0 ]; then
echo ""
echo "COMMIT BLOCKED: Secrets detected in staged files."
echo "If this is a false positive, use: git commit --no-verify"
exit 1
fi
---python3 .tools/scan_agent_output.py $STAGED_FILES
SCANNER_EXIT=$?
if [ $GIT_SECRETS_EXIT -ne 0 ] || [ $SCANNER_EXIT -ne 0 ]; then
echo ""
echo "COMMIT BLOCKED: Secrets detected in staged files."
echo "If this is a false positive, use: git commit --no-verify"
exit 1
fi
---Sandbox Configuration
沙箱配置
Docker Sandbox for Agent Execution
用于代理执行的Docker沙箱
dockerfile
undefineddockerfile
undefinedDockerfile.agent-sandbox
Dockerfile.agent-sandbox
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y
git
nodejs
npm
python3
python3-pip
&& rm -rf /var/lib/apt/lists/*
git
nodejs
npm
python3
python3-pip
&& rm -rf /var/lib/apt/lists/*
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y
git
nodejs
npm
python3
python3-pip
&& rm -rf /var/lib/apt/lists/*
git
nodejs
npm
python3
python3-pip
&& rm -rf /var/lib/apt/lists/*
Create non-root agent user
Create non-root agent user
RUN useradd -m -s /bin/bash agent &&
mkdir -p /workspace &&
chown agent:agent /workspace
mkdir -p /workspace &&
chown agent:agent /workspace
RUN useradd -m -s /bin/bash agent &&
mkdir -p /workspace &&
chown agent:agent /workspace
mkdir -p /workspace &&
chown agent:agent /workspace
Drop capabilities
Drop capabilities
USER agent
WORKDIR /workspace
USER agent
WORKDIR /workspace
No network by default - override at runtime if needed
No network by default - override at runtime if needed
No access to Docker socket
No access to Docker socket
No access to host filesystem beyond mounted volume
No access to host filesystem beyond mounted volume
```bash
#!/bin/bash
```bash
#!/bin/bashrun-agent-sandbox.sh
run-agent-sandbox.sh
Launch an AI coding agent inside a locked-down container
Launch an AI coding agent inside a locked-down container
REPO_DIR="$(pwd)"
CONTAINER_NAME="agent-sandbox-$$"
docker run
--name "$CONTAINER_NAME"
--rm
--network none
--read-only
--tmpfs /tmp:size=512m
--tmpfs /home/agent:size=256m
--memory 4g
--cpus 2
--pids-limit 256
--security-opt no-new-privileges:true
--security-opt seccomp=seccomp-agent.json
--cap-drop ALL
--cap-add DAC_OVERRIDE
-v "${REPO_DIR}/src:/workspace/src"
-v "${REPO_DIR}/tests:/workspace/tests:rw"
-v "${REPO_DIR}/docs:/workspace/docs:rw"
-v "${REPO_DIR}/package.json:/workspace/package.json:ro"
-e "NO_COLOR=1"
agent-sandbox:latest
"$@"
--name "$CONTAINER_NAME"
--rm
--network none
--read-only
--tmpfs /tmp:size=512m
--tmpfs /home/agent:size=256m
--memory 4g
--cpus 2
--pids-limit 256
--security-opt no-new-privileges:true
--security-opt seccomp=seccomp-agent.json
--cap-drop ALL
--cap-add DAC_OVERRIDE
-v "${REPO_DIR}/src:/workspace/src"
-v "${REPO_DIR}/tests:/workspace/tests:rw"
-v "${REPO_DIR}/docs:/workspace/docs:rw"
-v "${REPO_DIR}/package.json:/workspace/package.json:ro"
-e "NO_COLOR=1"
agent-sandbox:latest
"$@"
undefinedREPO_DIR="$(pwd)"
CONTAINER_NAME="agent-sandbox-$$"
docker run
--name "$CONTAINER_NAME"
--rm
--network none
--read-only
--tmpfs /tmp:size=512m
--tmpfs /home/agent:size=256m
--memory 4g
--cpus 2
--pids-limit 256
--security-opt no-new-privileges:true
--security-opt seccomp=seccomp-agent.json
--cap-drop ALL
--cap-add DAC_OVERRIDE
-v "${REPO_DIR}/src:/workspace/src"
-v "${REPO_DIR}/tests:/workspace/tests:rw"
-v "${REPO_DIR}/docs:/workspace/docs:rw"
-v "${REPO_DIR}/package.json:/workspace/package.json:ro"
-e "NO_COLOR=1"
agent-sandbox:latest
"$@"
--name "$CONTAINER_NAME"
--rm
--network none
--read-only
--tmpfs /tmp:size=512m
--tmpfs /home/agent:size=256m
--memory 4g
--cpus 2
--pids-limit 256
--security-opt no-new-privileges:true
--security-opt seccomp=seccomp-agent.json
--cap-drop ALL
--cap-add DAC_OVERRIDE
-v "${REPO_DIR}/src:/workspace/src"
-v "${REPO_DIR}/tests:/workspace/tests:rw"
-v "${REPO_DIR}/docs:/workspace/docs:rw"
-v "${REPO_DIR}/package.json:/workspace/package.json:ro"
-e "NO_COLOR=1"
agent-sandbox:latest
"$@"
undefinedSeccomp Profile for Agent Containers
代理容器的Seccomp配置文件
json
{
"defaultAction": "SCMP_ACT_ERRNO",
"comment": "seccomp-agent.json - Restrictive profile for AI coding agents",
"syscalls": [
{
"names": [
"read", "write", "open", "close", "stat", "fstat", "lstat",
"poll", "lseek", "mmap", "mprotect", "munmap", "brk",
"access", "pipe", "select", "sched_yield", "mremap",
"dup", "dup2", "nanosleep", "getpid", "getuid", "getgid",
"geteuid", "getegid", "getppid", "getpgrp", "setsid",
"getgroups", "uname", "fcntl", "flock", "fsync",
"getcwd", "chdir", "readlink", "chmod", "mkdir",
"rmdir", "unlink", "rename", "symlink", "readlinkat",
"openat", "mkdirat", "newfstatat", "unlinkat", "renameat",
"faccessat", "pselect6", "ppoll", "set_robust_list",
"get_robust_list", "epoll_create1", "epoll_ctl", "epoll_wait",
"eventfd2", "pipe2", "dup3", "pread64", "pwrite64",
"futex", "clock_gettime", "clock_getres", "exit_group",
"wait4", "clone", "execve", "arch_prctl", "set_tid_address",
"exit", "getdents64", "rt_sigaction", "rt_sigprocmask",
"rt_sigreturn", "ioctl", "writev", "madvise", "getrandom"
],
"action": "SCMP_ACT_ALLOW"
},
{
"names": [
"socket", "connect", "bind", "listen", "accept",
"sendto", "recvfrom", "sendmsg", "recvmsg"
],
"action": "SCMP_ACT_ERRNO",
"comment": "Block all network syscalls"
},
{
"names": ["ptrace", "process_vm_readv", "process_vm_writev"],
"action": "SCMP_ACT_ERRNO",
"comment": "Block debugging and process inspection"
}
]
}json
{
"defaultAction": "SCMP_ACT_ERRNO",
"comment": "seccomp-agent.json - Restrictive profile for AI coding agents",
"syscalls": [
{
"names": [
"read", "write", "open", "close", "stat", "fstat", "lstat",
"poll", "lseek", "mmap", "mprotect", "munmap", "brk",
"access", "pipe", "select", "sched_yield", "mremap",
"dup", "dup2", "nanosleep", "getpid", "getuid", "getgid",
"geteuid", "getegid", "getppid", "getpgrp", "setsid",
"getgroups", "uname", "fcntl", "flock", "fsync",
"getcwd", "chdir", "readlink", "chmod", "mkdir",
"rmdir", "unlink", "rename", "symlink", "readlinkat",
"openat", "mkdirat", "newfstatat", "unlinkat", "renameat",
"faccessat", "pselect6", "ppoll", "set_robust_list",
"get_robust_list", "epoll_create1", "epoll_ctl", "epoll_wait",
"eventfd2", "pipe2", "dup3", "pread64", "pwrite64",
"futex", "clock_gettime", "clock_getres", "exit_group",
"wait4", "clone", "execve", "arch_prctl", "set_tid_address",
"exit", "getdents64", "rt_sigaction", "rt_sigprocmask",
"rt_sigreturn", "ioctl", "writev", "madvise", "getrandom"
],
"action": "SCMP_ACT_ALLOW"
},
{
"names": [
"socket", "connect", "bind", "listen", "accept",
"sendto", "recvfrom", "sendmsg", "recvmsg"
],
"action": "SCMP_ACT_ERRNO",
"comment": "Block all network syscalls"
},
{
"names": ["ptrace", "process_vm_readv", "process_vm_writev"],
"action": "SCMP_ACT_ERRNO",
"comment": "Block debugging and process inspection"
}
]
}Code Review Gates
代码审查关卡
GitHub Actions Workflow for Agent PRs
针对代理PR的GitHub Actions工作流
yaml
undefinedyaml
undefined.github/workflows/agent-pr-review.yaml
.github/workflows/agent-pr-review.yaml
name: Agent PR Security Review
on:
pull_request:
types: [opened, synchronize]
jobs:
detect-agent-pr:
runs-on: ubuntu-latest
outputs:
is_agent: ${{ steps.check.outputs.is_agent }}
steps:
- name: Check if PR is from an AI agent
id: check
run: |
BRANCH="${{ github.head_ref }}"
AUTHOR="${{ github.event.pull_request.user.login }}"
BODY="${{ github.event.pull_request.body }}"
IS_AGENT="false"
if [[ "$BRANCH" == ai/* ]] || [[ "$BRANCH" == agent/* ]]; then
IS_AGENT="true"
fi
if echo "$BODY" | grep -qi "generated with.*claude\|generated by.*copilot\|generated by.*cursor\|generated by.*codex"; then
IS_AGENT="true"
fi
if [[ "$AUTHOR" == *"bot"* ]] || [[ "$AUTHOR" == *"agent"* ]]; then
IS_AGENT="true"
fi
echo "is_agent=$IS_AGENT" >> "$GITHUB_OUTPUT"security-scan:
needs: detect-agent-pr
if: needs.detect-agent-pr.outputs.is_agent == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Semgrep security scan
uses: semgrep/semgrep-action@v1
with:
config: >-
p/default
p/owasp-top-ten
p/command-injection
p/sql-injection
p/xss
- name: Scan for secrets with Trufflehog
uses: trufflesecurity/trufflehog@main
with:
extra_args: --only-verified
- name: Check for dependency changes
run: |
CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
DEP_FILES="package.json package-lock.json requirements.txt Pipfile.lock go.sum Cargo.lock"
for dep_file in $DEP_FILES; do
if echo "$CHANGED_FILES" | grep -q "$dep_file"; then
echo "::warning::Agent modified dependency file: $dep_file"
echo "DEPENDENCY_CHANGED=true" >> "$GITHUB_ENV"
fi
done
- name: Require extra review for dependency changes
if: env.DEPENDENCY_CHANGED == 'true'
run: |
gh pr edit "${{ github.event.pull_request.number }}" \
--add-label "agent-dependency-change" \
--add-label "requires-security-review"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}enforce-review:
needs: detect-agent-pr
if: needs.detect-agent-pr.outputs.is_agent == 'true'
runs-on: ubuntu-latest
steps:
- name: Label as agent-generated
run: |
gh pr edit "${{ github.event.pull_request.number }}"
--add-label "ai-generated" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
--add-label "ai-generated" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Enforce minimum reviewers
run: |
echo "Agent-generated PR detected."
echo "This PR requires at least 2 human approvals before merge."undefinedname: Agent PR Security Review
on:
pull_request:
types: [opened, synchronize]
jobs:
detect-agent-pr:
runs-on: ubuntu-latest
outputs:
is_agent: ${{ steps.check.outputs.is_agent }}
steps:
- name: Check if PR is from an AI agent
id: check
run: |
BRANCH="${{ github.head_ref }}"
AUTHOR="${{ github.event.pull_request.user.login }}"
BODY="${{ github.event.pull_request.body }}"
IS_AGENT="false"
if [[ "$BRANCH" == ai/* ]] || [[ "$BRANCH" == agent/* ]]; then
IS_AGENT="true"
fi
if echo "$BODY" | grep -qi "generated with.*claude\|generated by.*copilot\|generated by.*cursor\|generated by.*codex"; then
IS_AGENT="true"
fi
if [[ "$AUTHOR" == *"bot"* ]] || [[ "$AUTHOR" == *"agent"* ]]; then
IS_AGENT="true"
fi
echo "is_agent=$IS_AGENT" >> "$GITHUB_OUTPUT"security-scan:
needs: detect-agent-pr
if: needs.detect-agent-pr.outputs.is_agent == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Semgrep security scan
uses: semgrep/semgrep-action@v1
with:
config: >-
p/default
p/owasp-top-ten
p/command-injection
p/sql-injection
p/xss
- name: Scan for secrets with Trufflehog
uses: trufflesecurity/trufflehog@main
with:
extra_args: --only-verified
- name: Check for dependency changes
run: |
CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
DEP_FILES="package.json package-lock.json requirements.txt Pipfile.lock go.sum Cargo.lock"
for dep_file in $DEP_FILES; do
if echo "$CHANGED_FILES" | grep -q "$dep_file"; then
echo "::warning::Agent modified dependency file: $dep_file"
echo "DEPENDENCY_CHANGED=true" >> "$GITHUB_ENV"
fi
done
- name: Require extra review for dependency changes
if: env.DEPENDENCY_CHANGED == 'true'
run: |
gh pr edit "${{ github.event.pull_request.number }}" \
--add-label "agent-dependency-change" \
--add-label "requires-security-review"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}enforce-review:
needs: detect-agent-pr
if: needs.detect-agent-pr.outputs.is_agent == 'true'
runs-on: ubuntu-latest
steps:
- name: Label as agent-generated
run: |
gh pr edit "${{ github.event.pull_request.number }}"
--add-label "ai-generated" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
--add-label "ai-generated" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Enforce minimum reviewers
run: |
echo "Agent-generated PR detected."
echo "This PR requires at least 2 human approvals before merge."undefinedBranch Protection for Agent Branches
代理分支的分支保护
bash
#!/bin/bashbash
#!/bin/bashconfigure-branch-protection.sh
configure-branch-protection.sh
Set up branch protection rules for agent-generated PRs via GitHub API
Set up branch protection rules for agent-generated PRs via GitHub API
OWNER="your-org"
REPO="your-repo"
gh api repos/${OWNER}/${REPO}/rulesets
--method POST
--input - <<'EOF' { "name": "Agent Branch Protection", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["refs/heads/ai/", "refs/heads/agent/"], "exclude": [] } }, "rules": [ { "type": "pull_request", "parameters": { "required_approving_review_count": 2, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": true, "require_last_push_approval": true } }, { "type": "required_status_checks", "parameters": { "required_status_checks": [ { "context": "security-scan" }, { "context": "test-suite" }, { "context": "secret-detection" } ], "strict_required_status_checks_policy": true } } ] } EOF
--method POST
--input - <<'EOF' { "name": "Agent Branch Protection", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["refs/heads/ai/", "refs/heads/agent/"], "exclude": [] } }, "rules": [ { "type": "pull_request", "parameters": { "required_approving_review_count": 2, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": true, "require_last_push_approval": true } }, { "type": "required_status_checks", "parameters": { "required_status_checks": [ { "context": "security-scan" }, { "context": "test-suite" }, { "context": "secret-detection" } ], "strict_required_status_checks_policy": true } } ] } EOF
---OWNER="your-org"
REPO="your-repo"
gh api repos/${OWNER}/${REPO}/rulesets
--method POST
--input - <<'EOF' { "name": "Agent Branch Protection", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["refs/heads/ai/", "refs/heads/agent/"], "exclude": [] } }, "rules": [ { "type": "pull_request", "parameters": { "required_approving_review_count": 2, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": true, "require_last_push_approval": true } }, { "type": "required_status_checks", "parameters": { "required_status_checks": [ { "context": "security-scan" }, { "context": "test-suite" }, { "context": "secret-detection" } ], "strict_required_status_checks_policy": true } } ] } EOF
--method POST
--input - <<'EOF' { "name": "Agent Branch Protection", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["refs/heads/ai/", "refs/heads/agent/"], "exclude": [] } }, "rules": [ { "type": "pull_request", "parameters": { "required_approving_review_count": 2, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": true, "require_last_push_approval": true } }, { "type": "required_status_checks", "parameters": { "required_status_checks": [ { "context": "security-scan" }, { "context": "test-suite" }, { "context": "secret-detection" } ], "strict_required_status_checks_policy": true } } ] } EOF
---Repository Configuration
仓库配置
Cursor Rules (.cursorrules)
Cursor规则(.cursorrules)
text
undefinedtext
undefined.cursorrules
.cursorrules
You are working in a production codebase. Follow these rules strictly:
You are working in a production codebase. Follow these rules strictly:
Security Rules
Security Rules
- Never hardcode secrets, API keys, tokens, or passwords in source code.
- Never read or display the contents of .env files or secret configuration files.
- Never disable SSL verification, CSRF protection, or authentication middleware.
- Never use eval(), exec(), or similar dynamic code execution functions.
- Never introduce SQL string concatenation; always use parameterized queries.
- Never hardcode secrets, API keys, tokens, or passwords in source code.
- Never read or display the contents of .env files or secret configuration files.
- Never disable SSL verification, CSRF protection, or authentication middleware.
- Never use eval(), exec(), or similar dynamic code execution functions.
- Never introduce SQL string concatenation; always use parameterized queries.
File Restrictions
File Restrictions
- Do not modify any files in: infrastructure/, terraform/, .github/workflows/, deploy/
- Do not create or modify Dockerfiles without explicit approval.
- Do not modify CI/CD configuration files.
- Do not modify any files in: infrastructure/, terraform/, .github/workflows/, deploy/
- Do not create or modify Dockerfiles without explicit approval.
- Do not modify CI/CD configuration files.
Code Quality
Code Quality
- Every new function must have a corresponding unit test.
- All error handling must be explicit; never silently swallow exceptions.
- Follow existing patterns for logging, error handling, and API responses.
- Maximum function length: 50 lines. Refactor if exceeded.
- Every new function must have a corresponding unit test.
- All error handling must be explicit; never silently swallow exceptions.
- Follow existing patterns for logging, error handling, and API responses.
- Maximum function length: 50 lines. Refactor if exceeded.
Git Behavior
Git Behavior
- Create branches with the prefix: ai/
- Write descriptive commit messages referencing the task or issue.
- Never force push or rebase shared branches.
undefined- Create branches with the prefix: ai/
- Write descriptive commit messages referencing the task or issue.
- Never force push or rebase shared branches.
undefinedGitHub Copilot Configuration
GitHub Copilot配置
yaml
undefinedyaml
undefined.github/copilot-config.yml
.github/copilot-config.yml
Note: Copilot content exclusion is configured at the org/repo level
Note: Copilot content exclusion is configured at the org/repo level
via GitHub settings. This file documents intended exclusions and
via GitHub settings. This file documents intended exclusions and
can be referenced by org admins when configuring the settings at
can be referenced by org admins when configuring the settings at
github.com > Org Settings > Copilot > Content Exclusions.
github.com > Org Settings > Copilot > Content Exclusions.
content_exclusions:
paths:
- "/.env*"
- "/secrets/"
- "/.pem"
- "**/.key"
- "/infrastructure/"
- "/terraform/"
- "/.aws/"
- "**/credentials*"
content_exclusions:
paths:
- "/.env*"
- "/secrets/"
- "/.pem"
- "**/.key"
- "/infrastructure/"
- "/terraform/"
- "/.aws/"
- "**/credentials*"
Copilot content exclusion via organization settings (recommended):
Copilot content exclusion via organization settings (recommended):
1. Go to Organization Settings > Copilot > Content exclusion
1. Go to Organization Settings > Copilot > Content exclusion
2. Add repository paths:
2. Add repository paths:
- ".env*"
- ".env*"
- "secrets/**"
- "secrets/**"
- "infrastructure/**"
- "infrastructure/**"
- "*.pem"
- "*.pem"
- "*.key"
- "*.key"
undefinedundefinedOpenAI Codex Configuration
OpenAI Codex配置
markdown
<!-- codex.md or AGENTS.md for Codex CLI -->markdown
<!-- codex.md or AGENTS.md for Codex CLI -->Rules
Rules
- Do not modify files outside of src/ and tests/ directories.
- Do not install packages or modify dependency files without listing changes first.
- Run after every code change to verify nothing is broken.
npm test - Never access network resources or make HTTP requests during code generation.
- All generated code must include error handling.
- Prefix all branch names with .
agent/codex/
---- Do not modify files outside of src/ and tests/ directories.
- Do not install packages or modify dependency files without listing changes first.
- Run after every code change to verify nothing is broken.
npm test - Never access network resources or make HTTP requests during code generation.
- All generated code must include error handling.
- Prefix all branch names with .
agent/codex/
---Network Controls
网络控制
Firewall Rules for Agent Environments
代理环境的防火墙规则
bash
#!/bin/bashbash
#!/bin/bashagent-network-controls.sh
agent-network-controls.sh
Restrict network access for agent execution environments
Restrict network access for agent execution environments
Create a dedicated chain for agent traffic
Create a dedicated chain for agent traffic
iptables -N AGENT_CHAIN
iptables -N AGENT_CHAIN
Allow DNS resolution
Allow DNS resolution
iptables -A AGENT_CHAIN -p udp --dport 53 -j ACCEPT
iptables -A AGENT_CHAIN -p tcp --dport 53 -j ACCEPT
iptables -A AGENT_CHAIN -p udp --dport 53 -j ACCEPT
iptables -A AGENT_CHAIN -p tcp --dport 53 -j ACCEPT
Allow package registries
Allow package registries
iptables -A AGENT_CHAIN -d registry.npmjs.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d pypi.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d files.pythonhosted.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d proxy.golang.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d registry.npmjs.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d pypi.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d files.pythonhosted.org -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d proxy.golang.org -p tcp --dport 443 -j ACCEPT
Allow GitHub for git operations
Allow GitHub for git operations
iptables -A AGENT_CHAIN -d github.com -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d github.com -p tcp --dport 22 -j ACCEPT
iptables -A AGENT_CHAIN -d github.com -p tcp --dport 443 -j ACCEPT
iptables -A AGENT_CHAIN -d github.com -p tcp --dport 22 -j ACCEPT
Block everything else
Block everything else
iptables -A AGENT_CHAIN -j DROP
iptables -A AGENT_CHAIN -j DROP
Apply to agent user
Apply to agent user
iptables -A OUTPUT -m owner --uid-owner ai-agent -j AGENT_CHAIN
undefinediptables -A OUTPUT -m owner --uid-owner ai-agent -j AGENT_CHAIN
undefinedSquid Proxy for Agent Traffic
用于代理流量的Squid代理
conf
undefinedconf
undefined/etc/squid/squid-agent.conf
/etc/squid/squid-agent.conf
Transparent proxy for AI agent network requests
Transparent proxy for AI agent network requests
acl agent_user proxy_auth ai-agent
acl allowed_domains dstdomain .npmjs.org .pypi.org .github.com .golang.org
acl agent_user proxy_auth ai-agent
acl allowed_domains dstdomain .npmjs.org .pypi.org .github.com .golang.org
Allow only specific domains
Allow only specific domains
http_access allow agent_user allowed_domains
http_access deny agent_user
http_access allow agent_user allowed_domains
http_access deny agent_user
Log all agent requests for auditing
Log all agent requests for auditing
access_log /var/log/squid/agent-access.log squid
log_mime_hdrs on
access_log /var/log/squid/agent-access.log squid
log_mime_hdrs on
Request size limits
Request size limits
request_body_max_size 10 MB
reply_body_max_size 50 MB
http_port 3128
undefinedrequest_body_max_size 10 MB
reply_body_max_size 50 MB
http_port 3128
undefinedDocker Compose with Network Isolation
带网络隔离的Docker Compose
yaml
undefinedyaml
undefineddocker-compose.agent.yaml
docker-compose.agent.yaml
version: "3.8"
services:
agent-sandbox:
build:
context: .
dockerfile: Dockerfile.agent-sandbox
networks:
- agent-restricted
volumes:
- ./src:/workspace/src
- ./tests:/workspace/tests:rw
mem_limit: 4g
cpus: 2
pids_limit: 256
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp:size=512m
agent-proxy:
image: ubuntu/squid:latest
networks:
- agent-restricted
- external
volumes:
- ./squid-agent.conf:/etc/squid/squid.conf:ro
ports:
- "3128:3128"
networks:
agent-restricted:
internal: true # No external access from this network
external:
driver: bridge
---version: "3.8"
services:
agent-sandbox:
build:
context: .
dockerfile: Dockerfile.agent-sandbox
networks:
- agent-restricted
volumes:
- ./src:/workspace/src
- ./tests:/workspace/tests:rw
mem_limit: 4g
cpus: 2
pids_limit: 256
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp:size=512m
agent-proxy:
image: ubuntu/squid:latest
networks:
- agent-restricted
- external
volumes:
- ./squid-agent.conf:/etc/squid/squid.conf:ro
ports:
- "3128:3128"
networks:
agent-restricted:
internal: true # No external access from this network
external:
driver: bridge
---Audit Trail
审计追踪
Git Trailers for AI-Generated Code
AI生成代码的Git追踪标记
bash
#!/bin/bashbash
#!/bin/bashgit-ai-commit.sh
git-ai-commit.sh
Wrapper for committing agent-generated code with proper attribution
Wrapper for committing agent-generated code with proper attribution
AGENT_NAME="${AI_AGENT_NAME:-unknown-agent}"
AGENT_VERSION="${AI_AGENT_VERSION:-unknown}"
TASK_ID="${AI_TASK_ID:-none}"
git commit -m "$(cat <<EOF
$1
AI-Generated-By: ${AGENT_NAME} ${AGENT_VERSION}
AI-Task-ID: ${TASK_ID}
AI-Reviewed-By: pending
Co-Authored-By: ${AGENT_NAME} <noreply@${AGENT_NAME}.ai>
EOF
)"
undefinedAGENT_NAME="${AI_AGENT_NAME:-unknown-agent}"
AGENT_VERSION="${AI_AGENT_VERSION:-unknown}"
TASK_ID="${AI_TASK_ID:-none}"
git commit -m "$(cat <<EOF
$1
AI-Generated-By: ${AGENT_NAME} ${AGENT_VERSION}
AI-Task-ID: ${TASK_ID}
AI-Reviewed-By: pending
Co-Authored-By: ${AGENT_NAME} <noreply@${AGENT_NAME}.ai>
EOF
)"
undefinedAgent Action Logger
代理操作日志记录器
python
#!/usr/bin/env python3
"""agent_audit_logger.py - Log all AI agent actions for compliance."""
import json
import logging
import os
import time
from datetime import datetime, timezone
from pathlib import Path
LOG_DIR = Path(os.environ.get("AGENT_LOG_DIR", "/var/log/ai-agents"))
LOG_DIR.mkdir(parents=True, exist_ok=True)
logger = logging.getLogger("agent_audit")
handler = logging.FileHandler(LOG_DIR / "agent-actions.jsonl")
handler.setFormatter(logging.Formatter("%(message)s"))
logger.addHandler(handler)
logger.setLevel(logging.INFO)
def log_action(
agent: str,
action: str,
target: str,
details: dict | None = None,
user: str = "system",
) -> None:
entry = {
"timestamp": datetime.now(timezone.utc).isoformat(),
"agent": agent,
"user": user,
"action": action,
"target": target,
"details": details or {},
"session_id": os.environ.get("AGENT_SESSION_ID", "unknown"),
}
logger.info(json.dumps(entry))
def log_file_read(agent: str, filepath: str) -> None:
log_action(agent, "file_read", filepath)
def log_file_write(agent: str, filepath: str, lines_changed: int) -> None:
log_action(agent, "file_write", filepath, {"lines_changed": lines_changed})
def log_command(agent: str, command: str, exit_code: int) -> None:
log_action(agent, "command_exec", command, {"exit_code": exit_code})
def log_pr_created(agent: str, pr_url: str, files_changed: list[str]) -> None:
log_action(agent, "pr_created", pr_url, {"files_changed": files_changed})python
#!/usr/bin/env python3
"""agent_audit_logger.py - Log all AI agent actions for compliance."""
import json
import logging
import os
import time
from datetime import datetime, timezone
from pathlib import Path
LOG_DIR = Path(os.environ.get("AGENT_LOG_DIR", "/var/log/ai-agents"))
LOG_DIR.mkdir(parents=True, exist_ok=True)
logger = logging.getLogger("agent_audit")
handler = logging.FileHandler(LOG_DIR / "agent-actions.jsonl")
handler.setFormatter(logging.Formatter("%(message)s"))
logger.addHandler(handler)
logger.setLevel(logging.INFO)
def log_action(
agent: str,
action: str,
target: str,
details: dict | None = None,
user: str = "system",
) -> None:
entry = {
"timestamp": datetime.now(timezone.utc).isoformat(),
"agent": agent,
"user": user,
"action": action,
"target": target,
"details": details or {},
"session_id": os.environ.get("AGENT_SESSION_ID", "unknown"),
}
logger.info(json.dumps(entry))
def log_file_read(agent: str, filepath: str) -> None:
log_action(agent, "file_read", filepath)
def log_file_write(agent: str, filepath: str, lines_changed: int) -> None:
log_action(agent, "file_write", filepath, {"lines_changed": lines_changed})
def log_command(agent: str, command: str, exit_code: int) -> None:
log_action(agent, "command_exec", command, {"exit_code": exit_code})
def log_pr_created(agent: str, pr_url: str, files_changed: list[str]) -> None:
log_action(agent, "pr_created", pr_url, {"files_changed": files_changed})Usage example:
Usage example:
log_file_write("claude-code", "src/api/handler.py", 42)
log_file_write("claude-code", "src/api/handler.py", 42)
log_command("claude-code", "npm test", 0)
log_command("claude-code", "npm test", 0)
log_pr_created("claude-code", "https://github.com/org/repo/pull/99", ["src/main.py"])
log_pr_created("claude-code", "https://github.com/org/repo/pull/99", ["src/main.py"])
undefinedundefinedQuerying the Audit Log
查询审计日志
bash
#!/bin/bashbash
#!/bin/bashquery-agent-audit.sh
query-agent-audit.sh
Query agent audit logs for compliance reporting
Query agent audit logs for compliance reporting
LOG_FILE="/var/log/ai-agents/agent-actions.jsonl"
echo "=== Agent Activity Summary ==="
echo ""
echo "Actions by agent (last 24h):"
jq -r 'select(.timestamp > (now - 86400 | todate)) | .agent' "$LOG_FILE"
| sort | uniq -c | sort -rn
| sort | uniq -c | sort -rn
echo ""
echo "File writes by agent:"
jq -r 'select(.action == "file_write") | "(.agent) -> (.target)"' "$LOG_FILE"
| sort | uniq -c | sort -rn
| sort | uniq -c | sort -rn
echo ""
echo "Commands executed:"
jq -r 'select(.action == "command_exec") | "(.agent): (.target) (exit: (.details.exit_code))"' "$LOG_FILE"
| tail -20
| tail -20
echo ""
echo "PRs created by agents:"
jq -r 'select(.action == "pr_created") | "(.agent): (.target)"' "$LOG_FILE"
---LOG_FILE="/var/log/ai-agents/agent-actions.jsonl"
echo "=== Agent Activity Summary ==="
echo ""
echo "Actions by agent (last 24h):"
jq -r 'select(.timestamp > (now - 86400 | todate)) | .agent' "$LOG_FILE"
| sort | uniq -c | sort -rn
| sort | uniq -c | sort -rn
echo ""
echo "File writes by agent:"
jq -r 'select(.action == "file_write") | "(.agent) -> (.target)"' "$LOG_FILE"
| sort | uniq -c | sort -rn
| sort | uniq -c | sort -rn
echo ""
echo "Commands executed:"
jq -r 'select(.action == "command_exec") | "(.agent): (.target) (exit: (.details.exit_code))"' "$LOG_FILE"
| tail -20
| tail -20
echo ""
echo "PRs created by agents:"
jq -r 'select(.action == "pr_created") | "(.agent): (.target)"' "$LOG_FILE"
---Team Policies
团队政策
Agent Usage Policy Template
代理使用政策模板
yaml
undefinedyaml
undefined.github/agent-policy.yaml
.github/agent-policy.yaml
Team policy for AI coding agent usage
Team policy for AI coding agent usage
policy:
version: "1.0"
last_updated: "2025-06-01"
general:
- All developers may use AI coding agents for code generation
- Agent-generated code has the same quality and security bar as human code
- Developers are responsible for all code they submit, regardless of origin
required_review:
standard_code:
min_reviewers: 1
agent_generated: 2
infrastructure_changes:
min_reviewers: 2
agent_generated: "blocked" # Agents may not modify infra
security_sensitive:
min_reviewers: 2
requires: ["security-team-member"]
agent_generated: 2
additional_requires: ["security-team-lead"]
escalation:
- type: "dependency_addition"
action: "require security review"
- type: "auth_or_crypto_changes"
action: "require security team approval"
- type: "ci_cd_changes"
action: "blocked for agents"
- type: "database_migration"
action: "require DBA review"
- type: "api_contract_change"
action: "require API owner approval"
allowed_use_cases:
- "Writing unit and integration tests"
- "Implementing well-specified features with clear requirements"
- "Refactoring code with existing test coverage"
- "Writing documentation and code comments"
- "Fixing linter warnings and code style issues"
- "Generating boilerplate code from templates"
prohibited_use_cases:
- "Modifying authentication or authorization logic"
- "Writing or changing cryptographic implementations"
- "Modifying CI/CD pipelines or deployment configs"
- "Changing infrastructure-as-code without human authorship"
- "Accessing production databases or systems"
- "Modifying security controls or audit logging"
undefinedpolicy:
version: "1.0"
last_updated: "2025-06-01"
general:
- All developers may use AI coding agents for code generation
- Agent-generated code has the same quality and security bar as human code
- Developers are responsible for all code they submit, regardless of origin
required_review:
standard_code:
min_reviewers: 1
agent_generated: 2
infrastructure_changes:
min_reviewers: 2
agent_generated: "blocked" # Agents may not modify infra
security_sensitive:
min_reviewers: 2
requires: ["security-team-member"]
agent_generated: 2
additional_requires: ["security-team-lead"]
escalation:
- type: "dependency_addition"
action: "require security review"
- type: "auth_or_crypto_changes"
action: "require security team approval"
- type: "ci_cd_changes"
action: "blocked for agents"
- type: "database_migration"
action: "require DBA review"
- type: "api_contract_change"
action: "require API owner approval"
allowed_use_cases:
- "Writing unit and integration tests"
- "Implementing well-specified features with clear requirements"
- "Refactoring code with existing test coverage"
- "Writing documentation and code comments"
- "Fixing linter warnings and code style issues"
- "Generating boilerplate code from templates"
prohibited_use_cases:
- "Modifying authentication or authorization logic"
- "Writing or changing cryptographic implementations"
- "Modifying CI/CD pipelines or deployment configs"
- "Changing infrastructure-as-code without human authorship"
- "Accessing production databases or systems"
- "Modifying security controls or audit logging"
undefinedCODEOWNERS for Agent Oversight
用于代理监管的CODEOWNERS
text
undefinedtext
undefined.github/CODEOWNERS
.github/CODEOWNERS
Require specific reviewers for agent-sensitive areas
Require specific reviewers for agent-sensitive areas
All agent-generated branches require security team review
All agent-generated branches require security team review
(enforced via branch protection rules for ai/* and agent/* branches)
(enforced via branch protection rules for ai/* and agent/* branches)
Infrastructure is off-limits to agents and requires platform team
Infrastructure is off-limits to agents and requires platform team
/infrastructure/ @platform-team
/terraform/ @platform-team
/.github/workflows/ @platform-team @security-team
/infrastructure/ @platform-team
/terraform/ @platform-team
/.github/workflows/ @platform-team @security-team
Security-sensitive code requires security team
Security-sensitive code requires security team
/src/auth/ @security-team
/src/crypto/ @security-team
/src/middleware/auth* @security-team
/src/auth/ @security-team
/src/crypto/ @security-team
/src/middleware/auth* @security-team
Dependency files require security review
Dependency files require security review
package.json @security-team @tech-leads
package-lock.json @security-team
requirements.txt @security-team @tech-leads
go.sum @security-team
---package.json @security-team @tech-leads
package-lock.json @security-team
requirements.txt @security-team @tech-leads
go.sum @security-team
---Testing Agent Output
测试代理输出
Mandatory Test Coverage for Agent Code
代理代码的强制测试覆盖率
yaml
undefinedyaml
undefined.github/workflows/agent-test-gate.yaml
.github/workflows/agent-test-gate.yaml
name: Agent Code Test Gate
on:
pull_request:
types: [opened, synchronize]
jobs:
test-coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Detect changed files
id: changes
run: |
FILES=$(git diff --name-only origin/main...HEAD -- '*.py' '*.js' '*.ts' '*.go')
echo "changed_files=$FILES" >> "$GITHUB_OUTPUT"
- name: Run tests with coverage
run: |
# Python
if ls tests/*.py &>/dev/null; then
pip install pytest pytest-cov
pytest --cov=src --cov-report=json --cov-fail-under=80
fi
# Node.js
if [ -f package.json ]; then
npm ci
npm test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
fi
- name: Verify new code has tests
run: |
NEW_FILES=$(git diff --name-only --diff-filter=A origin/main...HEAD -- 'src/**')
for file in $NEW_FILES; do
base=$(basename "$file" | sed 's/\.[^.]*$//')
if ! find tests/ -name "*${base}*" | grep -q .; then
echo "::error::New file $file has no corresponding test file"
exit 1
fi
donesecurity-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Bandit (Python)
if: hashFiles('**/*.py') != ''
run: |
pip install bandit
bandit -r src/ -f json -o bandit-report.json || true
ISSUES=$(jq '.results | length' bandit-report.json)
if [ "$ISSUES" -gt 0 ]; then
echo "::warning::Bandit found $ISSUES security issue(s) in agent-generated code"
jq -r '.results[] | " \(.severity): \(.issue_text) in \(.filename):\(.line_number)"' bandit-report.json
fi
- name: Run ESLint security plugin (JavaScript/TypeScript)
if: hashFiles('**/*.js') != '' || hashFiles('**/*.ts') != ''
run: |
npm ci
npx eslint --no-eslintrc \
--plugin security \
--rule '{"security/detect-eval-with-expression": "error"}' \
--rule '{"security/detect-non-literal-fs-filename": "warn"}' \
--rule '{"security/detect-possible-timing-attacks": "error"}' \
--rule '{"security/detect-no-csrf-before-method-override": "error"}' \
src/ || truemutation-testing:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run mutation testing on agent-changed files
run: |
CHANGED=$(git diff --name-only origin/main...HEAD -- 'src/**/*.py')
if [ -n "$CHANGED" ]; then
pip install mutmut
for file in $CHANGED; do
echo "Mutation testing: $file"
mutmut run --paths-to-mutate="$file" --no-progress || true
done
mutmut results
fiundefinedname: Agent Code Test Gate
on:
pull_request:
types: [opened, synchronize]
jobs:
test-coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Detect changed files
id: changes
run: |
FILES=$(git diff --name-only origin/main...HEAD -- '*.py' '*.js' '*.ts' '*.go')
echo "changed_files=$FILES" >> "$GITHUB_OUTPUT"
- name: Run tests with coverage
run: |
# Python
if ls tests/*.py &>/dev/null; then
pip install pytest pytest-cov
pytest --cov=src --cov-report=json --cov-fail-under=80
fi
# Node.js
if [ -f package.json ]; then
npm ci
npm test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
fi
- name: Verify new code has tests
run: |
NEW_FILES=$(git diff --name-only --diff-filter=A origin/main...HEAD -- 'src/**')
for file in $NEW_FILES; do
base=$(basename "$file" | sed 's/\.[^.]*$//')
if ! find tests/ -name "*${base}*" | grep -q .; then
echo "::error::New file $file has no corresponding test file"
exit 1
fi
donesecurity-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Bandit (Python)
if: hashFiles('**/*.py') != ''
run: |
pip install bandit
bandit -r src/ -f json -o bandit-report.json || true
ISSUES=$(jq '.results | length' bandit-report.json)
if [ "$ISSUES" -gt 0 ]; then
echo "::warning::Bandit found $ISSUES security issue(s) in agent-generated code"
jq -r '.results[] | " \(.severity): \(.issue_text) in \(.filename):\(.line_number)"' bandit-report.json
fi
- name: Run ESLint security plugin (JavaScript/TypeScript)
if: hashFiles('**/*.js') != '' || hashFiles('**/*.ts') != ''
run: |
npm ci
npx eslint --no-eslintrc \
--plugin security \
--rule '{"security/detect-eval-with-expression": "error"}' \
--rule '{"security/detect-non-literal-fs-filename": "warn"}' \
--rule '{"security/detect-possible-timing-attacks": "error"}' \
--rule '{"security/detect-no-csrf-before-method-override": "error"}' \
src/ || truemutation-testing:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run mutation testing on agent-changed files
run: |
CHANGED=$(git diff --name-only origin/main...HEAD -- 'src/**/*.py')
if [ -n "$CHANGED" ]; then
pip install mutmut
for file in $CHANGED; do
echo "Mutation testing: $file"
mutmut run --paths-to-mutate="$file" --no-progress || true
done
mutmut results
fiundefinedPre-merge Validation Script
预合并验证脚本
bash
#!/bin/bashbash
#!/bin/bashvalidate-agent-pr.sh
validate-agent-pr.sh
Run all validation checks before merging an agent-generated PR
Run all validation checks before merging an agent-generated PR
set -euo pipefail
PR_BRANCH="${1:?Usage: validate-agent-pr.sh <branch-name>}"
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PASS=0
FAIL=0
WARN=0
check() {
local name="$1"
shift
if "$@" >/dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: $name"
((PASS++))
else
echo -e "${RED}FAIL${NC}: $name"
((FAIL++))
fi
}
warn_check() {
local name="$1"
shift
if "$@" >/dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: $name"
((PASS++))
else
echo -e "${YELLOW}WARN${NC}: $name"
((WARN++))
fi
}
echo "Validating agent PR: $PR_BRANCH"
echo "=============================="
set -euo pipefail
PR_BRANCH="${1:?Usage: validate-agent-pr.sh <branch-name>}"
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PASS=0
FAIL=0
WARN=0
check() {
local name="$1"
shift
if "$@" >/dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: $name"
((PASS++))
else
echo -e "${RED}FAIL${NC}: $name"
((FAIL++))
fi
}
warn_check() {
local name="$1"
shift
if "$@" >/dev/null 2>&1; then
echo -e "${GREEN}PASS${NC}: $name"
((PASS++))
else
echo -e "${YELLOW}WARN${NC}: $name"
((WARN++))
fi
}
echo "Validating agent PR: $PR_BRANCH"
echo "=============================="
Check that branch follows naming convention
Check that branch follows naming convention
check "Branch naming convention" [[ "$PR_BRANCH" == ai/* || "$PR_BRANCH" == agent/* ]]
check "Branch naming convention" [[ "$PR_BRANCH" == ai/* || "$PR_BRANCH" == agent/* ]]
Check for secrets in diff
Check for secrets in diff
check "No secrets in diff" git secrets --scan
check "No secrets in diff" git secrets --scan
Check that tests pass
Check that tests pass
check "Test suite passes" npm test
check "Test suite passes" npm test
Check test coverage threshold
Check test coverage threshold
warn_check "Coverage above 80%" npm test -- --coverage --coverageThreshold='{"global":{"lines":80}}'
warn_check "Coverage above 80%" npm test -- --coverage --coverageThreshold='{"global":{"lines":80}}'
Check for forbidden file modifications
Check for forbidden file modifications
FORBIDDEN_CHANGES=$(git diff --name-only origin/main..."$PR_BRANCH" --
'infrastructure/' 'terraform/' '.github/workflows/' '.env*' '.pem' '.key') check "No forbidden file changes" [ -z "$FORBIDDEN_CHANGES" ]
'infrastructure/' 'terraform/' '.github/workflows/' '.env*' '.pem' '.key') check "No forbidden file changes" [ -z "$FORBIDDEN_CHANGES" ]
FORBIDDEN_CHANGES=$(git diff --name-only origin/main..."$PR_BRANCH" --
'infrastructure/' 'terraform/' '.github/workflows/' '.env*' '.pem' '.key') check "No forbidden file changes" [ -z "$FORBIDDEN_CHANGES" ]
'infrastructure/' 'terraform/' '.github/workflows/' '.env*' '.pem' '.key') check "No forbidden file changes" [ -z "$FORBIDDEN_CHANGES" ]
Check for new dependencies
Check for new dependencies
DEP_CHANGES=$(git diff --name-only origin/main..."$PR_BRANCH" --
'package.json' 'requirements.txt' 'go.mod' 'Cargo.toml') warn_check "No dependency changes" [ -z "$DEP_CHANGES" ]
'package.json' 'requirements.txt' 'go.mod' 'Cargo.toml') warn_check "No dependency changes" [ -z "$DEP_CHANGES" ]
DEP_CHANGES=$(git diff --name-only origin/main..."$PR_BRANCH" --
'package.json' 'requirements.txt' 'go.mod' 'Cargo.toml') warn_check "No dependency changes" [ -z "$DEP_CHANGES" ]
'package.json' 'requirements.txt' 'go.mod' 'Cargo.toml') warn_check "No dependency changes" [ -z "$DEP_CHANGES" ]
Check commit messages have AI trailers
Check commit messages have AI trailers
MISSING_TRAILERS=$(git log origin/main.."$PR_BRANCH" --format='%B'
| grep -cL "AI-Generated-By:" || true) warn_check "All commits have AI attribution trailers" [ "$MISSING_TRAILERS" -eq 0 ]
| grep -cL "AI-Generated-By:" || true) warn_check "All commits have AI attribution trailers" [ "$MISSING_TRAILERS" -eq 0 ]
echo ""
echo "=============================="
echo -e "Results: ${GREEN}${PASS} passed${NC}, ${RED}${FAIL} failed${NC}, ${YELLOW}${WARN} warnings${NC}"
if [ "$FAIL" -gt 0 ]; then
echo -e "${RED}PR validation FAILED. Address issues before merging.${NC}"
exit 1
fi
echo -e "${GREEN}PR validation passed.${NC}"
---MISSING_TRAILERS=$(git log origin/main.."$PR_BRANCH" --format='%B'
| grep -cL "AI-Generated-By:" || true) warn_check "All commits have AI attribution trailers" [ "$MISSING_TRAILERS" -eq 0 ]
| grep -cL "AI-Generated-By:" || true) warn_check "All commits have AI attribution trailers" [ "$MISSING_TRAILERS" -eq 0 ]
echo ""
echo "=============================="
echo -e "Results: ${GREEN}${PASS} passed${NC}, ${RED}${FAIL} failed${NC}, ${YELLOW}${WARN} warnings${NC}"
if [ "$FAIL" -gt 0 ]; then
echo -e "${RED}PR validation FAILED. Address issues before merging.${NC}"
exit 1
fi
echo -e "${GREEN}PR validation passed.${NC}"
---Quick Reference
快速参考
| Control | Tool | Purpose |
|---|---|---|
| Permission boundaries | CLAUDE.md, .cursorrules, codex.md | Restrict agent behavior per-repo |
| Secret scanning | git-secrets, pre-commit hooks | Block credential leaks |
| Sandbox isolation | Docker, seccomp, network=none | Contain agent execution |
| Code review gates | GitHub Actions, branch protection | Enforce human review |
| Network controls | iptables, Squid proxy | Limit agent internet access |
| Audit trail | Git trailers, JSONL logger | Track AI-generated code |
| Test requirements | Coverage gates, mutation testing | Validate agent output quality |
| Team policies | agent-policy.yaml, CODEOWNERS | Govern agent usage org-wide |
| 管控措施 | 工具 | 用途 |
|---|---|---|
| 权限边界 | CLAUDE.md, .cursorrules, codex.md | 按仓库限制代理行为 |
| 秘密扫描 | git-secrets, 预提交钩子 | 阻止凭证泄露 |
| 沙箱隔离 | Docker, seccomp, network=none | 限制代理执行范围 |
| 代码审查关卡 | GitHub Actions, 分支保护 | 强制执行人工审查 |
| 网络控制 | iptables, Squid代理 | 限制代理互联网访问 |
| 审计追踪 | Git追踪标记, JSONL日志记录器 | 追踪AI生成代码 |
| 测试要求 | 覆盖率关卡, 变异测试 | 验证代理输出质量 |
| 团队政策 | agent-policy.yaml, CODEOWNERS | 在组织层面管控代理使用 |