GoPlusSecurity/agentguard

GoPlus AgentGuard – AI 에이전트를 위한 보안 가드

무엇인가요 – AI 코드 에이전트(Claude Code, OpenClaw, Hermes, Codex 등)와 호스트 시스템 사이에 위치하는 Node 기반 명령줄 도구(및 플러그인)입니다. 에이전트가 실행하려는 모든 명령어, 파일 쓰기, 네트워크 요청, 스킬/플러그인을 감시하며, 정적 분석 및 런타임 규칙을 적용하여 위험한 작업을 차단하거나 경고합니다.

왜 중요한가요 – 현대의 AI 에이전트는 완전한 터미널 접근 권한을 부여받을 수 있습니다. 악의적인 스킬이나 프롬프트 인젝션 공격은 침묵하게 비밀 정보를 도난당하거나, 암호화폐 지갑을 비우거나, 디스크를 삭제할 수 있습니다. AgentGuard는 다음과 같은 실시간 보안 계층을 제공합니다:

• 에이전트의 실행 파이프라인에 훅을 걸어 알려진 파괴적 명령어(예: rm -rf /, 포크 폭탄, curl|bash)를 차단합니다.
• .env 및 ~/.ssh와 같은 자격 증명 파일에 쓰기 작업을 방지합니다.
• 일반적인 웹훅 엔드포인트(Discord, Telegram, Slack)로의 정보 유출 시도를 탐지합니다.
• 각 작업을 수행한 스킬을 추적하여 악용의 원인을 확인할 수 있습니다.
• 하루에 한 번의 "패트롤"을 수행하여 전체 환경의 변조 여부, 비밀 정보 유출, 열린 포트, 의심스러운 크론 작업, 신뢰 레지스트리의 건강 상태를 감사합니다.

어떻게 얻을 수 있나요 – npm을 통해 전역으로 설치하고, agentguard init 명령어를 한 번 실행하면 지원되는 에이전트를 자동 감지하고 적절한 훅/플러그인을 설치합니다.

npm install -g @goplus/agentguard
agentguard init   # Claude, OpenClaw, Hermes 등을 자동 감지

로컬 가드에는 클라우드 계정이 필요하지 않으며, 옵션으로 클라우드 연결을 통해 위협 인텔리전스 피드 및 중앙 집중식 감사 동기화를 사용할 수 있습니다.

주요 기능 (README에 기술됨)

계층	기능
자동 가드 (훅)	파괴적 쉘 명령어, 비밀 파일 쓰기, 알려진 정보 유출 URL의 실시간 차단. 스킬 출처 추적.
딥 스캔 (스킬)	스킬/플러그인의 온디맨드 정적 분석 (24개 검출 규칙). 비밀 정보, 백도어, 가시화, 프롬프트 인젝션 패턴, Web3 전용 지갑 공격을 탐지. 기능 기반 권한을 가진 신뢰 레지스트리 항목 생성.
데일리 패트롤 (OpenClaw)	스케줄된 작업(기본값: 03:00 UTC)으로 8가지 포괄적인 검사를 수행: 무결성, 비밀 정보 노출, 네트워크 노출, 크론 작업 안전성, 파일 시스템 변경, 감사 로그 분석, 구성 건강 상태, 신뢰 레지스트리 건강 상태. 간결한 PASS/WARN/FAIL 보고서 생성 및 ~/.agentguard/audit.jsonl에 로깅.
헬스 체크업	1클릭으로 HTML 보고서 생성, "로브스터" 시각적 점수로 코드 안전성, 신뢰 위생, 런타임 방어, 비밀 보호, Web3 실드, 구성 상태 요약.
보호 수준	strict (모든 위험 작업 차단), balanced (위험한 것은 차단, 위험한 것은 확인 – 기본값), permissive (중요한 위협만 차단).
클라우드 / 위협 인텔리전스 (옵션)	agentguard connect로 로컬 JWT 등록, 조치 피드 다운로드, 암호화된 감사 로그를 GoPlus 클라우드에 동기화 가능.

일반적인 워크플로우

1. 설치 및 초기화 – npm i -g @goplus/agentguard && agentguard init.
2. 새 스킬 스캔 – agentguard scan ./my-skill (또는 DSH 플러그인용 agentguard dsh-scan …). CLI는 인간이 읽을 수 있거나 JSON 형식의 위험 보고서를 반환.
3. 단일 작업 평가 – 도구 호출의 JSON 설명을 agentguard protect로 파이프하여 차단 여부 확인.
4. 데일리 패트롤 실행 – agentguard patrol run 또는 agentguard patrol setup으로 크론 작업으로 설정.
5. 보고서 검토 – agentguard report로 감사 로그, agentguard checkup으로 시각적 건강 페이지, agentguard trust list로 현재 신뢰된 스킬 확인.

지원되는 에이전트 / 통합

• Claude Code – claude plugin add …를 통한 네이티브 플러그인.
• OpenClaw – OpenClaw 플러그인으로 등록 (registerOpenClawPlugin). before_tool_call / after_tool_call 이벤트에 훅.
• Hermes, Codex, QClaw, DSH – 각각 고유의 초기화 플래그(agentguard init --agent <name>)를 통해 적절한 훅 번들 설치.

제한 사항 / 범위 (README에 기술됨)

• 딥 스캔 규칙은 정적입니다. 소스 코드에 반영되지 않은 런타임 전용 동작은 탐지할 수 없습니다.
• 패트롤 기능은 OpenClaw 환경에 종속됩니다. OpenClaw 외 사용자는 수동 스캔 필요.
• 원격 코드 실행 탐지는 히ュ리스틱(예: npx, npm exec, curl|bash)에 의존합니다. 경고를 줄이기 위해 핀 정확한 커밋 사용 권장.
• 도구는 클라우드 연결을 필요로 하지 않지만, 고급 위협 인텔리전스 및 중앙 집중식 감사 기능은 옵션 API 키 필요.
• 특정 DSH 기능(런타임 모드, 소유자 할당)은 DSH 런타임이 필요한 계약을 노출할 때만 사용 가능.

결론 – AgentGuard는 AI 코드 에이전트를 위한 목적에 맞게 설계된 보안 계층으로, 개발자가 최소 권한 실행을 쉽게 강제하고, 새로운 플러그인을 자동 스캔하며, 전체 에이전트 생태계의 일일 건강 상태를 유지할 수 있도록 도와줍니다. AI 기반 자동화의 새로운 위험 표면을 겨냥한 진정한, 활발히 유지 관리되는 오픈소스 프로젝트입니다.