hashgraph-online/hol-guard

hol-guard를 사용하여 로컬 하네스(harness)를 보호하세요. 플러그인(plugins), 스킬(skills), MCP 서버, 그리고 마켓플레이스 패키지(marketplace packages)에 대한 유지 관리자 및 CI 체크가 필요한 경우 plugin-scanner를 사용하세요.

PyPI 패키지 (hol-guard)
PyPI 패키지 (plugin-scanner)
HOL 플러그인 레지스트리 (HOL Plugin Registry)
HOL GitHub Organization
이슈 보고 (Report an Issue)

| 만약 당신이...
|---|---|---|
| 도구가 실행되기 전에 Codex, Claude Code, Copilot CLI, Hermes, Cursor, Gemini 또는 OpenCode를 보호하고 싶다면 | hol-guard | hol-guard start |
| 릴리스 전 CI에서 패키지를 린트(lint)하고 검증하고 싶다면 | plugin-scanner | plugin-scanner verify . |

pipx install hol-guard
hol-guard init

hol-guard init은 첫 실행 시 안내되는 설정(guided setup)입니다. 먼저 단계별 계획을 보여준 다음, 각 부수 효과(side effect)를 제어합니다: 대시보드 승인, Guard가 완료, 앱 보호 승인, Guard가 완료, 클라우드 연결 및 알림 승인 순으로 진행됩니다. 사용자가 해당 체크포인트를 승인하기 전까지는 아무것도 열리거나 변경되지 않습니다. hol-guard init --yes는 이미 계획을 신뢰하는 자동화 환경에서만 사용하세요.

수동 및 후속 명령:

pipx run hol-guard bootstrap
pipx run hol-guard hermes bootstrap
pipx run hol-guard run codex --dry-run
...

Guard를 통해 얻을 수 있는 것:

• 사용자의 머신에 있는 로컬 하네스(harness) 설정을 감지합니다.
• 도구를 신뢰하기 전 기준점(baseline)을 기록합니다.
• 실행 전 새롭게 생성되거나 변경된 아티팩트(artifacts)에서 깔끔하게 일시 중지합니다.
• 하네스가 인라인(inline)으로 프롬프트를 띄울 수 없는 경우, 차단된 변경 사항을 로컬호스트(localhost) 승인 센터에 대기시킵니다.
• 나중에 결정을 검토할 수 있도록 영수증(receipts)을 로컬에 저장합니다.
• 실제로 공유 기록이 필요한 시점까지 동기화를 선택 사항으로 유지합니다.

전체 로컬 흐름은 docs/guard/get-started.md를 참조하세요.

Guard 명령 요약

hol-guard start

Guard가 발견한 하네스(harness)의 다음 단계를 보여줍니다.

hol-guard init

승인 체크포인트로서 첫 실행 온보딩(onboarding)을 실행합니다: 로컬 대시보드, 하네스 발견 및 설치, 선택 사항인 Guard Cloud 연결, 그리고 데스크톱 알림 설정.

hol-guard bootstrap

최적의 로컬 하네스 (harness)를 감지하고, 승인 센터 (approval center)를 시작하며, 그 앞에 Guard를 설치합니다.

hol-guard hermes bootstrap

Guard가 관리하는 Hermes 오버레이 번들 (overlay bundle)을 직접 설치합니다.

hol-guard status

Guard가 현재 무엇을 모니터링하고 있는지 보여줍니다.

hol-guard install <harness>

해당 하네스에 대한 런처 심 (launcher shim)을 생성합니다.

hol-guard update

현재 환경에 설치된 hol-guard 패키지를 업데이트합니다.

hol-guard run <harness> --dry-run

신뢰하기 전에 현재 상태를 한 번 기록합니다.

hol-guard run <harness>

실행 전 변경 사항을 검토하며, 필요한 경우 차단된 세션을 승인 센터로 전달합니다.

hol-guard approvals

대기 중인 승인 목록을 나열하거나 터미널에서 이를 해결합니다.

hol-guard receipts

로컬 승인 및 차단 이력을 보여줍니다.

하네스 승인 전략 (Harness approval strategy)

claude-code

Guard는 Claude 훅 (hooks)을 우선적으로 선호하며, 셸 (shell)에서 프롬프트를 띄울 수 없는 경우 로컬 승인 센터를 사용합니다.

copilot

Guard는 copilot CLI를 래핑 (wrap)할 수 있으며, ~/.copilot/config.json, ~/.copilot/mcp-config.json, 워크스페이스의 .vscode/mcp.json을 감지하여, 문서화된 preToolUse 및 postToolUse 이벤트에 대해 Guard가 관리하는 Copilot 훅 배선 (hook wiring)을 설치합니다. Guard는 VS Code Copilot의 인라인 권한 시트 (inline permission sheet) 자체를 Guard 가로채기 (interception)의 증거로 간주하지 않습니다. 현재의 증거는 Guard 훅 응답, Guard 영수증 (receipts), 또는 Guard의 유도 (elicitation)에 명시적으로 응답하는 MCP 클라이언트로부터 나와야 합니다.

codex

대화형 CLI 또는 Codex App이 MCP 유도에 응답할 수 있는 경우, Guard는 동일한 Codex 채팅 내에서 인라인으로 질문합니다. codex exec 또는 응답이 없는 다른 세션의 경우에만 로컬 승인 센터로 대체됩니다. Guard가 적절한 Codex 스레드 바인딩 (thread binding)을 가지고 있으면, 브라우저에서의 승인 또는 차단은 HOL Guard 브랜드가 붙은 연속 복사본 (continuation copy)과 함께 동일한 Codex 스레드를 재개합니다. 라이브 앱-서버 세션은 그대로 유지되며, 헤드리스 (headless) codex exec 세션은 codex exec resume을 통해 재개됩니다.

정확히 차단된 명령 컨텍스트와 함께 제공됩니다. 세션을 식별할 수 없는 경우, Guard는 재개된 척하는 대신 상황을 명확히 알리고 대신 수행해야 할 수동 다음 단계를 안내합니다.cursor

Guard는 Cursor의 네이티브 도구 승인 (tool approval) 방식을 존중하며, 실행 전 아티팩트 신뢰성 (artifact trust)에 집중합니다.opencode

Guard는 패키지 수준의 정책 (package-level policy)을 작성하는 반면, OpenCode는 관리형 MCP 도구에 대해 네이티브 방식, 항상 허용, 또는 거부 프롬프트를 유지합니다.hermes

Guard는 관리형 Hermes 오버레이 번들 (overlay bundle)을 설치하고, MCP 서버를 Guard 프록시 (proxies)를 통해 라우팅하며, 차단된 요청에 대해 네이티브 또는 중앙 집중식 전달 (native-or-center delivery) 방식을 선호합니다.gemini

Guard는 확장 프로그램을 스캔하며, 차단된 변경 사항에 대해서는 로컬 승인 센터 (local approval center)로 폴백 (fallback)합니다.

HOL Guard는 AI 하네스 (AI harnesses)를 위한 안티바이러스입니다. 파일이 변경되거나 네트워크에 접속되기 전에 모든 도구 동작을 가로채며, 밀리초 단위로 허용할지 차단할지를 결정합니다.

hol-guard settings set security-level <level> 명령으로 보호 수준을 선택하십시오.

:

수준 (Level)	대상 (Who it's for)	차단 항목 (What it blocks)
Gentle	마찰을 최소화하려는 팀; 숙련된 사용자	신뢰도가 높은 비밀 정보 (secrets) 및 명확한 데이터 유출 (exfil)만 차단
Balanced	대부분의 사용자 (기본값)	비밀 정보, 셸 유출 (shell exfil), 프롬프트 인젝션 (prompt injections), 공급망 후크 (supply-chain hooks)
Strict	보안을 중시하는 팀	위 항목들에 더해 신뢰도가 낮은 신호 및 신뢰할 수 없는 프롬프트 차단
Paranoid	고보안 환경	위 모든 항목에 더해 인식되지 않은 모든 MCP 서버 동작 차단

확신이 서지 않는다면 Balanced로 시작하십시오. 첫 일주일간의 영수증 (receipts)을 검토한 후 Strict로 격상할 수 있습니다.

하나 이상의 탐지기 (detectors)가 작동하여 Guard가 명령을 일시 중지했습니다. 무엇이 정확히 트리거되었는지 확인하려면 다음을 실행하십시오:

hol-guard receipts # 최근 결정 사항 검토
hol-guard doctor # 프로브 (probe)를 실행하여 어떤 탐지기가 활성화되어 있는지 확인
hol-guard doctor --perf # 탐지기별 타이밍 포함

차단이 오탐 (false positive)처럼 보인다면, 영수증 뷰 (receipts view) 또는 http://localhost:6174의 대시보드에서 승인할 수 있습니다.

터미널에서:

hol-guard approvals # 대기 중인 승인 목록 표시
hol-guard approvals clear # 모든 대기 중인 승인 삭제 (확인 프롬프트 표시)

대시보드에서: http://localhost:6174를 열고, **Approval Center (승인 센터)**로 이동하여 Clear all (모두 삭제) 버튼을 사용하십시오. 승인이 제거되기 전에 확인 절차를 거치게 됩니다.

Guard의 권고 데이터베이스 (advisory database) 업데이트는 선택 사항이며 Pull-only (가져오기 전용) 방식입니다. hol-guard advisories sync를 실행하면, Guard는 advisories.hol.org로부터 서명된 권고 목록 (advisory list)을 가져옵니다. 동기화(sync) 과정 중 로컬 파일 경로, 하네스 설정 (harness configs), 영수증 데이터 (receipt data) 또는 워크스페이스 식별자 (workspace identifiers)는 어떤 서버로도 전송되지 않습니다.

권고 동기화 (Advisory sync)를 위해서는 HOL Guard Cloud 계정이 필요합니다. 로그인하지 않은 경우 동기화가 건너뛰어지며, Guard는 로컬에 번들링된 권고 데이터베이스를 계속 사용합니다. 무료 계정을 연결하려면 hol-guard login을 실행하십시오.

pipx install plugin-scanner
plugin-scanner lint .
plugin-scanner verify .

# GitHub Actions PR 게이트 (gate)
- name: AI plugin quality gate
uses: hashgraph-online/ai-plugin-scanner-action@v1
...

plugin-scanner를 추가해야 하는 경우:

• 플러그인 (plugins), 스킬 (skills) 또는 마켓플레이스 패키지 (marketplace packages)를 게시할 때
• 출시 전 CI 게이트 (CI gate)를 원하는 경우
• SARIF, 검증 페이로드 (verification payloads) 또는 제출 아티팩트 (submission artifacts)가 필요한 경우

리포지토리에서 .agents/plugins/marketplace.json과 같은 Codex 마켓플레이스 루트 (marketplace root)를 사용하는 경우, plugin_dir: "."를 유지하십시오. 스캐너는 로컬 ./plugins/... 항목을 자동으로 발견하고, 각 로컬 플러그인 매니페스트 (plugin manifest)를 스캔하며, 리포지토리 루트를 단일 플러그인으로 취급하는 대신 원격 마켓플레이스 항목은 건너뜁니다.

• 기여자 설정 (Contributor setup): Development 섹션으로 이동
• 로컬 Guard 문서: docs/guard/get-started.md
• GitHub Action 문서: hashgraph-online/ai-plugin-scanner-action
• 레지스트리 및 신뢰 참조 (Registry and trust references): 아래 내용을 계속 읽어주세요

스캐너 참조: 신뢰 점수 (trust scoring), 설치, 생태계 및 CLI 명령

스캐너는 이제 품질 등급 (quality grade)과 함께 명시적인 신뢰 출처 (trust provenance)를 출력합니다:

• 번들링된 기술 (bundled skills)은 게시된 HCS-28 베이스라인 어댑터 ID (baseline adapter ids), 가중치 (weights), 분모 규칙 (denominator rules)을 직접 사용합니다.
• MCP 설정 신뢰 (MCP configuration trust)는 동일한 HCS 스타일의 어댑터, 가중치, 기여 모드 (contribution-mode) 패턴을 로컬에서 사용합니다.
• 최상위 Codex 플러그인 신뢰 (top-level Codex plugin trust)는 동일한 HCS 스타일의 어댑터, 가중치, 기여 모드 (contribution-mode) 패턴을 로컬에서 사용합니다.

현재 로컬 사양 (Current local specs):

이를 통해 품질 등급 (quality grade)과 신뢰 점수 (trust score)를 분리하여 유지합니다. SECURITY.md와 같은 시그널 (signals)은 여전히 가시적으로 유지되지만, 해당 시그널의 가중치는 이제 원시 카테고리 점수 (raw category points)의 추론된 부수 효과 (inferred side effect)가 아닌, 명명된 어댑터 가중치 (named adapter weight)로 취급됩니다.

git clone https://github.com/hashgraph-online/hol-guard.git
cd hol-guard
uv sync --extra dev --extra cisco
...

Cisco MCP extra 없이 가벼운 베이스라인 경로 (lean baseline path)가 필요한 경우 uv sync --extra dev --python 3.10을 사용하세요.

Guard 패키지:

pip install hol-guard

Scanner 패키지:

pip install plugin-scanner

가벼운 베이스라인 (lean baseline)은 Python 3.10 지원을 온전하게 유지하며, 배포된 cisco-ai-skill-scanner 통합을 항상 포함합니다.

베이스라인 기술 스캐너 (baseline skill scanner) 외에 정적 MCP 커버리지 (static MCP coverage)를 추가하고 싶다면, Python 3.11 이상 환경에서 Cisco extra를 설치하세요:

pip install "hol-guard[cisco]"

pip install "plugin-scanner[cisco]"

cisco-ai-mcp-scanner는 Python 3.11 이상에서만 작동하며, 가벼운 베이스라인이 요구하는 수준보다 더 무거운 YARA 기반 설치 표면 (install surface)을 추가하기 때문에 선택 사항인 cisco extra에 유지됩니다. Cisco는 현재 스캐너 설치 표면 전반에 걸쳐 패치된 litellm==1.83.10 릴리스를 지원하므로, 이 리포지토리는 완전한 커버리지를 위해 해당 Cisco 호환 고정 버전 (Cisco-compatible pin)을 유지합니다.

Guard 표면 (Guard surfaces)에서 Cisco extra는 hol-guard scan, hol-guard preflight, hol-guard explain <path>에 선택적인 오프라인 증거 (offline evidence)를 추가합니다. 로컬 아티팩트 스캔 (local artifact scans)에 대한 소비자 모드 증거 경로를 제어하려면 --cisco-mode {auto,on,off}를 사용하세요. hol-guard run 및 Guard 런타임 프롬프트/파일 읽기 보호 (runtime prompt/file-read protection)는 이번 패스에서도 네이티브 Guard 동작으로 유지됩니다.

Guard 인벤토리 스냅샷 (inventory snapshots)은 Hermes 또는 OpenClaw 인벤토리 실행 시 해당 스캐너 (scanners)를 명시적으로 활성화하면 Cisco MCP 및 skill-scanner 상태를 포함할 수 있습니다. Cloud 증거 모델 (evidence model)은 로컬 경로(local paths)나 비밀 정보(secrets)를 저장하지 않고 스캐너 소스, 상태, 비식별화된 결과 텍스트 (redacted finding text), 소요 시간, 매핑된 아티팩트 ID (mapped artifact ID), 그리고 리스크 구성 요소 메타데이터 (risk component metadata)를 기록합니다.

이번 패스에서 Guard는 Cisco AIBOM 런타임 통합 (runtime integration)을 추가하지 않습니다. 향후 AIBOM 지원이 다시 도입된다면, Guard의 차단(blocking) 또는 승인(approval) 로직이 아닌 증거(evidence) 또는 내보내기(export) 인터페이스에 머물러야 합니다.

아래 패키지들을 오픈 소스로 공개해 준 Cisco AI Defense에 감사를 표합니다.

패키지 (Package)	이 리포지토리에서의 상태	비고
cisco-ai-skill-scanner	기본 제공 (shipped by default)	경량 베이스라인 설치 (lean baseline install)에 포함됨.
cisco-ai-mcp-scanner	[cisco]를 통해 제공 (shipped via [cisco])	리포지토리 제어 CI 및 Docker를 포함하여 Python 3.11+ 환경에서 전체 Cisco 커버리지를 위해 권장됨.
cisco-ai-a2a-scanner	연기됨 (deferred)	라이브 A2A 엔드포인트가 필요하며 이번 패스에는 추가되지 않음.
cisco-aibom	연기됨 (deferred)	이번 패스에서 Guard 런타임 통합 없음. 향후 증거 또는 내보내기 워크플로우를 위해서만 재검토할 것.

로컬 개발 중에 하나의 셸 (shell)에서 두 도구를 모두 사용하려면:

pipx install hol-guard
pipx install plugin-scanner

컨테이너 우선 (Container-first) 환경에서는 대신 게시된 이미지를 사용할 수 있습니다. 리포지토리 제어 이미지는 Python 3.12 기반의 lock 유도형 Cisco 의존성 세트 (lock-derived Cisco dependency set)를 설치하므로, 컨테이너는 기본적으로 전체 정적 Cisco 커버리지를 갖게 됩니다.

docker run --rm \
-v "$PWD:/workspace" \
ghcr.io/hashgraph-online/hol-guard:<version> \
...

패키지별 명령 이름:

hol-guard start
plugin-scanner verify .

생태계 (Ecosystem)	탐지 영역 (Detection Surfaces)
Codex	.codex-plugin/plugin.json , marketplace.json , .agents/plugins/marketplace.json
...

리포지토리 내에서 탐지된 모든 패키지를 스캔하려면 --ecosystem auto (기본값)를 사용하거나, 단일 생태계를 명시적으로 선택하십시오.

plugin-scanner는 다음과 같은 전체 품질 스위트 (quality suite)를 지원합니다:

scan

전체 표면 보안 및 릴리스 분석 (release analysis)을 위한 scan

규칙 기반 작성 피드백 (rule-oriented authoring feedback)을 위한 lint

런타임 및 설치 표면 준비 상태 점검 (runtime and install-surface readiness checks)을 위한 verify

아티팩트 기반 제출 게이팅 (artifact-backed submission gating)을 위한 submit

대상별 진단 및 트러블슈팅 번들 (targeted diagnostics and troubleshooting bundles)을 위한 doctor

스캐너는 플러그인이 실제로 노출하는 표면(surfaces)만을 평가한 다음, 적용 가능한 점검 항목 전체에 대해 최종 점수를 정규화 (normalize)합니다. 플러그인이 포함하지 않는 선택적 표면에 대해서는 보상이나 불이익을 받지 않습니다.

카테고리	최대 점수	범위
Manifest Validation	31	plugin.json, 필수 필드, semver, kebab-case, 권장 메타데이터, 인터페이스 메타데이터, 인터페이스 링크 및 에셋, 안전하게 선언된 경로
...

# 플러그인 디렉토리 스캔
plugin-scanner scan ./my-plugin
# 리포지토리 내부의 지원되는 모든 에코시스템 자동 감지 (기본값)
...

이전 자동화 도구와의 호환성을 위해서만 단독 형태인 plugin-scanner ./my-plugin 형식을 사용하십시오. 새로운 스크립트와 문서에서는 scan, lint, verify, submit, doctor와 같이 명시적인 서브커맨드 (subcommands)를 사용하는 것을 권장합니다.