최초 실행 마법사는 지원되는 에이전트를 탐지하고 보호 설정 과정을 안내합니다. 대시보드 열기, 에이전트 통합 설치, 선택적 클라우드 서비스 연결 등 각 설정 변경 전에 확인을 요청합니다.

설치 상태를 확인하세요:```bash
hol-guard --version
hol-guard status

수동 설정은 [설치 가이드](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/get-started.md)를 참조하세요. 릴리스 세부 정보와 사전 릴리스는 [릴리스 페이지](https://github.com/hashgraph-online/hol-guard/releases)에서 확인할 수 있습니다.

## HOL Guard가 보호하는 대상

| 표면 | 보호 |
| :--- | :--- |
| **셸 명령 및 파일 접근** | 파괴적인 작업, 민감한 파일 접근, 자격 증명 노출, 의심스러운 아웃바운드 명령을 검토합니다. |
| **패키지 설치** | 설치 전에 지원되는 패키지 관리자 작업을 공급망 인텔리전스와 대조하여 평가합니다. |
| **플러그인, 스킬, 에이전트 구성** | 로컬 아티팩트를 인벤토리화하고 실행 전에 새로 추가되거나 변경된 도구를 검토합니다. |
| **MCP 서버 및 도구** | 서버 구성을 검사하고 지원되는 훅과 관리형 프록시를 통해 도구 호출을 검토합니다. |
| **프롬프트 및 도구 결과** | 지원되는 이벤트에서 프롬프트 인젝션과 민감한 콘텐츠를 검사합니다. |
| **승인 및 증거** | 결정을 네이티브 프롬프트 또는 승인 센터로 라우팅하고, 검토를 위해 로컬 영수증을 기록합니다. |

Guard는 네이티브 에이전트 훅, 관리형 MCP 프록시, 실행 통합을 통해 연결됩니다. 적용 범위는 각 에이전트가 노출하는 이벤트에 따라 달라지며, [지원 매트릭스](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/harness-support.md)는 통합별 적용, 승인 전달, 실패 동작을 문서화합니다.

## 지원되는 AI 에이전트

Codex, Claude Code, GitHub Copilot CLI, Cursor, Cline, Gemini CLI, Grok, Hermes, Kimi Code, Pi, oh-my-pi, OpenClaw, OpenCode, Antigravity, ZCode. [Paseo](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/paseo.md)는 이러한 네이티브 제공자 통합을 통해 지원되며, 제공자별 적용 범위가 있습니다.

예를 들어, Codex를 명시적으로 설정하려면:```bash
hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex

`command test`와 `command explain`은 명령을 실행하거나 승인을 생성하지 않고 검사합니다. `hol-guard approvals`를 사용하여 대기 중인 요청을 해결하고, `hol-guard receipts`를 사용하여 기록된 결정을 검토하세요.

[Extension directory](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/extensions/README.md)는 런타임 레지스트리에서 생성된 명령 커버리지를 나열합니다. 외부 기여는 명시적 옵트인이 필요하며, 필수 핵심 보호 기능은 계속 활성화됩니다. 커버리지를 추가하려면 [Extension contribution guide](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/extensions/contributing.md)를 따르세요.

### 패키지 확인```bash
hol-guard supply-chain sync
hol-guard supply-chain scan
hol-guard supply-chain explain [email protected] --ecosystem npm

| Command | Purpose |
| :--- | :--- |
| `scan` | 감지된 패키지 표면 전반에 걸친 보안 발견 사항 및 품질 보고서. |
| `lint` | 규칙 수준의 작성 피드백. |
| `verify` | 설치 표면 및 런타임 준비 상태 검사. |
| `submit` | 단일 플러그인 패키지에 대한 제출 아티팩트. |
| `doctor` | 컴포넌트 진단 및 문제 해결 번들. |

스캐너는 Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code, OpenCode 패키지 형식을 감지합니다. `plugin-scanner --list-ecosystems`를 사용하여 목록을 나열하거나 `--ecosystem`으로 하나를 선택하세요. Codex 마켓플레이스 루트에서는 로컬 플러그인 항목을 자동으로 검색합니다.

검사는 매니페스트, 시크릿, MCP 전송 및 명령 구성, 승인 기본값, 스킬, 의존성 잠금 파일, GitHub Actions 권한을 포함합니다. 선택적 Cisco 통합은 스킬 및 MCP 분석을 추가합니다. 보고서는 텍스트, JSON, Markdown, SARIF를 지원합니다.```bash
plugin-scanner scan . --format sarif --output plugin-scanner.sarif
plugin-scanner scan . --fail-on-severity high

[action 문서](https://github.com/hashgraph-online/ai-plugin-scanner-action)에서 SARIF 업로드, 제출 워크플로, 기계 판독 가능 출력에 대해 확인하세요. 액션 소스는 [`action/`](https://github.com/hashgraph-online/hol-guard/blob/main/action)에서 유지 관리됩니다.

<a id="install-the-package-you-need"></a>
<a id="resolver-safe-cisco-extra"></a>

### 선택적 Cisco 분석

기본 패키지는 Cisco 종속성 없이 작동합니다. Cisco 스킬 스캐닝을 추가하려면 Python 3.11부터 3.14까지 사용하고 격리된 환경에 extra를 설치하세요:```bash
pipx install 'plugin-scanner[cisco]'

게시된 `cisco` extra는 스킬 스캐닝을 제공하며, 별도의 `cisco-mcp` 그룹은 MCP 스캐너를 제공합니다. 의존성 버전과 Python 제약 조건은 [`pyproject.toml`](https://github.com/hashgraph-online/hol-guard/blob/main/pyproject.toml)에서 관리됩니다.

## 에코시스템 지원

| 에코시스템 | 감지 대상 |
| :--- | :--- |
| Codex | `.codex-plugin/plugin.json`, `marketplace.json`, `.agents/plugins/marketplace.json` |
| Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` |
| DeepSeek Harness | `dsh.bundle`이 있는 `package.json`, 선언된 패치, Cordis `apply(ctx)` 내보내기, 또는 패치 전용 번들의 경우 `dsh.bundle.mode`가 `"patch"`로 설정된 경우 |
| Gemini CLI | `gemini-extension.json`, `commands/**/*.toml` |
| Kimi Code | `kimi.plugin.json`, `.kimi-plugin/plugin.json`, 선언된 스킬, 에이전트, 명령, 프롬프트, MCP 서버 |
| OpenCode | `opencode.json`, `opencode.jsonc`, `.opencode/commands`, `.opencode/plugins` |

저장소에서 지원되는 패키지를 감지하려면 `--ecosystem auto`를 사용하거나, 에코시스템을 명시적으로 선택하세요:```bash
plugin-scanner scan ./plugins-repo --ecosystem claude
plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness

리포지토리 마켓플레이스의 경우 `scan`, `lint`, `verify`, `doctor`는 루트를 대상으로 할 수 있습니다. `submit`은 하나의 플러그인 패키지를 대상으로 합니다.

## Codex 사양 정렬

스캐너는 Codex 플러그인 매니페스트, 인터페이스 메타데이터, 선언된 자산, 마켓플레이스 패키지를 인식합니다:

- 로컬 매니페스트 경로는 `./` 접두사를 사용하며, `lint --fix`는 이를 유지하거나 추가합니다.
- `.agents/plugins/marketplace.json`이 선호되는 마켓플레이스 위치이며, 호환성을 위해 루트 `marketplace.json`도 지원됩니다.
- 인터페이스 검증은 문서화되지 않은 `type` 필드를 요구하지 않고 선언된 링크와 자산을 확인합니다.
- `verify --online`은 HTTP 원격 도달 가능성을 확인합니다. Stdio 서버 실행은 수동 검토를 위해 건너뜁니다.

업스트림 형식은 [Codex 플러그인 문서](https://developers.openai.com/codex/plugins)와 [Model Context Protocol 사양](https://modelcontextprotocol.io)을 참조하세요.

## 구성 + 기준 예시

`.plugin-scanner.toml`에서 스캐너를 구성하세요:```toml
[scanner]
profile = "public-marketplace"
baseline_file = "baseline.txt"
ignore_paths = ["tests/*", "fixtures/*"]

[rules]
disabled = ["README_MISSING"]
severity_overrides = { CODEXIGNORE_MISSING = "low" }

출력 디렉터리는 새로 생성되어야 하며, 상위 디렉터리가 이미 존재해야 합니다. 키트에는 `discovery.json`, `review.json`, `report.json`, 기여 메타데이터, 네이티브 탐지기, 생성된 테스트, 파일 매니페스트가 포함됩니다.

기타 입력: `--from help`는 저장된 명령 도움말을 읽고, `--from click`은 Click `Context.to_info_dict()` 내보내기를 읽으며, `--from oclif`는 `oclif.manifest.json`을 읽고, `--from mcp`는 완전히 내보낸 `tools/list` 결과를 읽으며, `--from snapshot`은 `discovery.json`을 재생합니다. 위의 `cli` 예제는 정규화된 `guard.cli-surface.v1` JSON을 사용합니다.

MCP 기여의 경우, 생성기는 `--executable` 대신 `--launcher`와 `--package`를 사용합니다. 전체 명령과 페이지네이션 요구 사항은 [MCP 키트 예제](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/extension-builder/README.md#generate-an-mcp-kit)를 참조하세요.

**3. 작업을 검토하고 재생성합니다.** `report.json`을 읽고 발견된 작업을 업스트림 구현과 비교합니다. 편집하기 전에 검토 파일을 복사하세요:```bash
cp samplectl-kit/review.json samplectl-review.json

`diff`는 동일한 kit에 대해 `0`을, 유효한 kit가 다를 때 `1`을 반환합니다. 업스트림 내보내기가 변경되면 새 스냅샷을 생성하고 검토하세요.

**4. 통합을 미리 보고 적용합니다.** 기여 브랜치에서 현재 체크아웃에 대한 변경 사항을 미리 봅니다:```bash
uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo .

작성 단계는 검토된 계획을 기여 파일, 외부 신뢰 맵, 카탈로그 등록, 패키징, 작성 소유권 기록에 적용합니다. 기존 ID나 충돌하는 파일이 있으면 통합을 중단하고 검토를 진행합니다.

**5. 테스트하고 풀 리퀘스트를 제출합니다.** `samplectl` 예시의 경우:```bash
uv run --no-sync python scripts/release/stage_guard_cloud_review_artifacts.py
uv run --no-sync pytest -q tests/test_generated_cli_samplectl_extension.py
uv run --no-sync pytest -q \
  tests/test_guard_extension_contribution.py \
  tests/test_guard_extension_trust.py \
  tests/test_guard_command_extension_registry.py
uv run --no-sync python scripts/render_command_extension_directory.py
uv run --no-sync python scripts/render_command_extension_directory.py --check
git diff --check

선택적 Cisco 커버리지를 사용하려면 위의 dependency group 명령을 사용하세요. 기여 요건은 [CONTRIBUTING.md](https://github.com/hashgraph-online/hol-guard/blob/main/CONTRIBUTING.md)를, 통합 테스트는 [testing matrix](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/testing-matrix.md)를 참조하세요.

## 리소스

- [HOL Plugin Registry](https://hol.org/registry/plugins)
- [HOL Plugin Security dataset on Hugging Face](https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security)
- [HOL Standards Documentation](https://hol.org/docs/standards)
- [OpenAI Codex Plugin Documentation](https://developers.openai.com/codex/plugins)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [Cisco AI Skill Scanner](https://pypi.org/project/cisco-ai-skill-scanner/)
- [Cisco AI MCP Scanner](https://pypi.org/project/cisco-ai-mcp-scanner/)
- [HOL GitHub Organization](https://github.com/hashgraph-online)

## 커뮤니티

[Hashgraph Online](https://github.com/hashgraph-online)에서 유지관리합니다.

- [버그 신고 또는 기능 요청](https://github.com/hashgraph-online/hol-guard/issues)
- [릴리스 살펴보기](https://github.com/hashgraph-online/hol-guard/releases)
- [플러그인 보안 데이터셋 살펴보기](https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security)

## 라이선스

[Apache-2.0](https://github.com/hashgraph-online/hol-guard/blob/main/LICENSE)에 따라 라이선스가 부여됩니다.