AI AgentGuard

](https://github.com/imdlan/AIAgentGuard/releases/latest) ![License](LICENSE) ![Go Report](https://goreportcard.com/report/github.com/imdlan/AIAgentGuard) ](https://github.com/imdlan/AIAgentGuard/releases) ![Homebrew](https://github.com/imdlan/homebrew-AIAgentGuard)

截图

AI AgentGuard is a security tool for AI agents, CLI tools, and MCP servers.It scans for permission risks, evaluates security threats, and providessandboxed execution environments.

English | 简体中文

特性

v1.4.2功能（最新）⭐

IPv6兼容性修复 -主机检查中支持IPv6的固定网络地址格式
代码质量改进 -删除了重复的代码块并修复了恐慌误用
依赖关系清理 -删除了30多个未使用的依赖项，以实现更小的二进制大小

v1.4.1功能

版本命令 -显示已安装的版本 agent-guard version
安装脚本改进 -GitHub API速率限制的回退方法，具有更好的错误消息
版本命令 -显示已安装的版本 agent-guard version
安装脚本改进 -GitHub API速率限制的回退方法，具有更好的错误消息

v1.4.0功能

多语言支持（i18n） -自动检测系统语言，支持中英文输出
嵌入式翻译文件 -40+可翻译字符串，无外部依赖
macOS语言检测 -从AppleLocale和AppleLanguages首选项自动检测

v1.3.0功能

详细安全报告 -显示导致安全风险的特定文件、进程和命令

- 进程扫描详细信息，包括PID、命令行和风险原因 - 显示开放端口和活动连接的网络连接分析 - 通过可操作的补救措施增强风险评估

自动修复向导 -自动修复安全问题或提供手动修复命令

- 新 agent-guard fix CLI命令 --auto 和 --dry-run 选项 - 特定类别的修复（文件系统、shell、网络、secrets）

风险趋势分析 -比较扫描结果随时间的变化，以跟踪安全态势的变化

- 新 agent-guard trend 带历史数据分析的CLI命令

Web UI仪表板 -完整的视觉安全监控界面

- 带有React+Go RESTful API的实时仪表板 - 进程、网络、修复向导和趋势历史面板

v1.2.0功能

多语言依赖性扫描 -扫描npm、pip、cargo和Go依赖项以查找漏洞
普罗米修斯监控 -导出用于监控和警报的指标 /metrics 端点
Grafana仪表板 -带有实时可视化功能的预构建监控仪表板
增强测试覆盖率 -针对多语言扫描器（npm、pip、cargo）的全面单元测试

v1.1.0功能

Go依赖漏洞扫描 -使用golang.org/x/vuln检查已知CVE的Go依赖关系
容器运行时检测 -检测Docker、Kubernetes、Podman、LXC、Wasm环境
真正的沙盒隔离 -基于容器的容器隔离与Linux命名空间（仅限Linux）
绩效基准测试 -对所有主要组件进行12次基准测试

v1.0.0功能（核心）

权限扫描 -检测文件系统、shell、网络和秘密访问权限
文件内容分析 -扫描文件以查找已公开的API密钥、令牌和机密（15+个模式）
过程安全监控 -检测反向shell、可疑进程和高CPU使用率
SUID/SGID扫描 -识别特权可执行文件和潜在的特权升级向量
审计日志 -JSON格式和SIEM集成的全面安全事件记录
智能命令解析 -高级标志解析，防止绕过尝试
沙盒执行 -在隔离环境中安全运行命令
政策管理 -通过YAML配置控制访问权限
快速注射保护 -检测并阻止恶意提示注入攻击
插件扫描 -检测不安全的插件和扩展

更新

要更新到最新版本：

家酿:

brew upgrade agent-guard

安装脚本:

curl -sSL https://raw.githubusercontent.com/imdlan/AIAgentGuard/main/scripts/install.sh | bash

手册：从下载发布.

安装

方法1:自制（推荐用于macOS/Linux）

brew tap imdlan/AIAgentGuard
brew install agent-guard

方法2：从GitHub版本下载

访问发布页面下载适用于您平台的二进制文件。

# macOS / Linux
curl -LO https://github.com/imdlan/AIAgentGuard/releases/latest/download/agent-guard_darwin_arm64.tar.gz
tar -xzf agent-guard_darwin_arm64.tar.gz
chmod +x agent-guard
sudo mv agent-guard /usr/local/bin/

方法3：去安装（适用于开发人员）

go install github.com/imdlan/AIAgentGuard@latest

确保 $GOPATH/bin 在你的 PATH:

export PATH=$PATH:$(go env GOPATH)/bin

方法4：安装脚本

curl -sSL https://raw.githubusercontent.com/imdlan/AIAgentGuard/main/scripts/install.sh | bash

方法5：从源代码构建

git clone https://github.com/imdlan/AIAgentGuard.git
cd agent-guard
go build -o agent-guard
sudo mv agent-guard /usr/local/bin/

快速开始

1.扫描安全风险

# Scan current environment
agent-guard scan

# JSON format output
agent-guard scan --json

# Use custom policy
agent-guard scan --config ./my-policy.yaml

2.在沙盒中运行

# Run command in isolated environment
agent-guard run "curl https://api.example.com"

# Disable network access
agent-guard run --disable-network "npm install"

# Restrict filesystem access
agent-guard run --allow-dirs /tmp,/data "node script.js"

3.生成报告

# Generate detailed report
agent-guard report

# Save to file
agent-guard report --json > security-report.json

4.普罗米修斯监视器（新）

# Run scan with Prometheus metrics
agent-guard scan --metrics-addr :9090

# Metrics available at http://localhost:9090/metrics
# curl http://localhost:9090/metrics

有关详细的监控设置，请参阅监控指南.

5.初始化配置

# Generate default configuration file
agent-guard init

# Configuration file locations:
# - .agent-guard.yaml (current directory)
# - ~/.agent-guard.yaml (user directory)
# - /etc/agent-guard/config.yaml (system directory)

配置示例

创建 .agent-guard.yaml:

# Block dangerous commands
blocked_commands:
  - "rm -rf /"
  - "dd if=/dev/zero"
  - "mkfs"
  - ":(){ :|:& };:"  # fork bomb

# Restrict filesystem access
allowed_paths:
  - /tmp
  - /home/user/project
  - /var/log/app

denied_paths:
  - /etc/passwd
  - /etc/shadow
  - ~/.ssh

# Environment variable protection
blocked_env_vars:
  - API_KEY
  - SECRET_TOKEN
  - DATABASE_URL

# Network access control
network:
  allowed_domains:
    - api.github.com
    - cdn.jsdelivr.net
  denied_domains:
    - "*.malicious.com"

输出示例

  █████╗ ██╗     █████╗  ██████╗ ███████╗███╗   ██╗████████╗ ██████╗ ██╗   ██╗ █████╗ ██████╗ ██████╗
 ██╔══██╗██║    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝ ██║   ██║██╔══██╗██╔══██╗██╔══██╗
 ███████║██║    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██║  ███╗██║   ██║███████║██████╔╝██║  ██║
 ██╔══██╗██║    ██╔══██╗██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██║   ██║██║   ██║██╔══██╗██╔══██╗██║  ██║
 ██║  ██║██║    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ╚██████╔╝╚██████╔╝██║  ██║██║  ██║██████╔╝
 ╚═╝  ╚═╝╚═╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝    ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝

                             🛡️  Security Scan Report v1.4.2

Overall Risk: 🔶 HIGH

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Permission Breakdown:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Filesystem Access: LOW
  🛑 Shell Execution: CRITICAL
  ⚠️ Network Access: MEDIUM
  🔶 Secrets Access: HIGH

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Detailed Findings:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. [SHELL] Root/admin shell access detected [/bin/bash, /bin/zsh] [SYSTEM]
2. [NETWORK] External network connectivity available [NETWORK]
3. [SECRETS] Environment variable API_KEY exposed [ENVIRONMENT]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Recommendations:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  • Consider running AI agents in a sandboxed environment
  • Use 'agent-guard run ' for safe execution
  • Use environment variable blocking in policy config
  • Consider using secret management tools

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

命令参考

全局选项

-c, --config string   Path to policy configuration file
-j, --json            JSON output format
-v, --verbose         Verbose output
-h, --help            Show help information

扫描-安全扫描

扫描当前环境以查找安全风险和权限。

agent-guard scan [flags]

run-沙盒执行

在隔离环境中执行命令。

agent-guard run [command] [flags]

Options:
  --disable-network    Disable network access
  --allow-dirs paths   Allow access to directories (comma-separated)
  --block-dirs paths   Block access to directories (comma-separated)

report-生成报告

生成并显示安全报告。

agent-guard report [flags]

init-初始化配置

生成默认配置文件。

agent-guard init [flags]

Options:
  --force    Overwrite existing configuration file
  --path     Specify configuration file path

fix-安全修复向导

自动修复安全问题或提供补救指导。

agent-guard fix [flags]

Options:
  --auto       Automatically execute fix commands
  --dry-run    Preview changes without executing
  --category   Fix specific category only (filesystem, shell, network, secrets)

趋势-风险趋势分析

通过比较扫描结果随时间的变化来分析安全趋势。

agent-guard trend [flags]

Options:
  --days N    Analyze last N days (default: 7)
  --json      Output in JSON format
  --category  Show trend for specific category

完整使用指南

有关详细的使用指南和最佳实践，请参阅：用法.md

涵盖的主题：

所有用例的详细解释
完整的CLI命令参考
Web UI使用说明
监控和警报设置
部署和维护指南
故障排除解决方案

常见问题解答

Q：如何禁用特定扫描？

A：编辑配置文件并将相应选项设置为 false:

scanner:
  filesystem: false
  shell: true
  network: true
  secrets: true

Q：沙盒模式是如何工作的？

A：沙盒模式使用以下技术：

环境变量隔离
文件系统访问限制
网络访问控制（可选）
命令白名单/黑名单

Q：如何与CI/CD集成？

A：将安全扫描步骤添加到CI/CD管道中：

# GitHub Actions example
- name: Security Scan
  run: |
    go install github.com/imdlan/AIAgentGuard@latest
    agent-guard scan --json > security-report.json
    # Check risk level
    if grep -q "CRITICAL" security-report.json; then
      echo "Critical security issues found!"
      exit 1
    fi

发展

从源代码构建

# Clone repository
git clone https://github.com/imdlan/AIAgentGuard.git
cd agent-guard

# Build
go build -o agent-guard

# Run tests
go test ./...

# Install locally
go install

项目结构

agent-guard/
├── cmd/              # CLI commands
├── internal/         # Internal implementation
│   ├── scanner/     # Scanning engines
│   ├── risk/        # Risk analysis
│   ├── sandbox/     # Sandbox execution
│   ├── policy/      # Policy management
│   ├── security/    # Security protection
│   └── report/      # Report generation
├── pkg/model/       # Data models
├── configs/         # Default configuration
└── scripts/         # Installation scripts

发布过程

此项目使用Goreleaser进行自动发布。当你推送版本标签时，GitHub Actions会自动触发：

构建多平台二进制文件（macOS/Linux、AMD64/ARM64）
创建GitHub版本
生成文件校验和（checksums.txt）
自动更新自制配方

发布新版本:

git tag v1.0.1
git push origin v1.0.1

有关详细文档，请参阅：发布流程指南

本地测试

# Install goreleaser
brew install goreleaser

# Test build (no release)
goreleaser build --clean --snapshot

# Test full workflow (dry-run)
goreleaser release --clean --snapshot --skip-publish

许可证

MIT许可证-请参阅许可证详细信息文件

贡献

欢迎投稿！请参阅贡献.md

联系

github：https://github.com/imdlan/AIAgentGuard
问题：https://github.com/imdlan/AIAgentGuard/issues
讨论：https://github.com/imdlan/AIAgentGuard/discussions

______________________________________________________________________

保护您的AI代理，从安全扫描开始！

AI Agent Guard

快速接入

详细介绍