Skarn guard: 에이전트 플러그인

Skarn을 위한 훅 구성, 에이전트 스킬, 로컬 MCP 서버 선언이 포함되어 있으며, 네 개의 호스트용으로 패키징되어 있고 다섯 번째 호스트는 자체 저장소에서 제공됩니다. 이 저장소는 Skarn 릴리스마다 생성됩니다. 바이너리, 탐지 규칙, 엔진 코드는 포함하지 않습니다.

여기에는 다섯 개의 유닛이 있으며, 그중 네 개는 가드 유닛입니다. claude/와 codex/는 이 저장소의 루트 매니페스트가 제공하는 마켓플레이스의 플러그인으로, Claude Code와 Codex CLI용입니다. antigravity/는 Antigravity CLI(agy)용 플러그인 디렉터리입니다. 저장소 루트 자체는 Gemini CLI 확장입니다. Google의 설치 프로그램과 갤러리 크롤러가 루트에서 매니페스트를 읽기 때문입니다. 루트의 파일은 저장소 수준 파일(이 README, LICENSE, SECURITY.md, 마켓플레이스 매니페스트) 또는 Gemini 파일(gemini-extension.json, GEMINI.md, hooks/, skills/)입니다. 다른 모든 호스트는 하위 디렉터리를 갖습니다. 다섯 번째 유닛인 recall/은 같은 마켓플레이스의 스킬 전용 플러그인입니다. 스킬 하나, 훅 없음, MCP 서버 없음. Cursor 유닛은 이 저장소에 전혀 없으며 https://github.com/skarn-security/cursor-plugin에 있습니다.

가드는 사전 실행 훅입니다. 에이전트가 셸 명령을 실행하거나, 패치를 적용하거나, 파일을 쓰거나, URL을 가져오거나, MCP 도구를 호출하거나, 모델 제공자에게 프롬프트를 보내기 전에, 대기 중인 작업이 사용자 머신의 Skarn 탐지 엔진에 의해 스캔되어 판정을 받습니다: 거부(차단), 질문(사용자에게 에스컬레이션), 또는 허용(조용히). 로컬에서 스캔하며 네트워크 호출을 하지 않고 원시 비밀을 출력하지 않습니다. 판정은 규칙 이름과 수정된 미리보기를 명명합니다.

설치

먼저 skarn 바이너리를 설치하세요(플러그인에는 포함되어 있지 않습니다. 훅은 PATH의 skarn guard를 호출합니다):

brew install skarn-security/tap/skarn

Claude Code:

claude plugin marketplace add skarn-security/agent-guard
claude plugin install skarn-guard@skarn

Codex CLI:

codex plugin marketplace add skarn-security/agent-guard
codex plugin add skarn-guard-codex@skarn

두 가드 플러그인은 이름이 다릅니다. 하나의 마켓플레이스는 같은 이름의 두 플러그인을 보유할 수 없고, 각각 호스트의 훅 형태(이벤트 이름, 도구 매처, 가드가 라우팅하는 --agent)를 제공하기 때문입니다. 연결 중인 호스트에 맞는 것을 설치하세요. 둘 다 skarn-audit 스킬을 포함하며, 이 스킬은 이 머신에서 skarn assess와 skarn vet을 실행하고 수정된 결과를 보고합니다. 수정은 Skarn이 감지한 자격 증명 값을 마스킹합니다. 결과의 주변 대화 내용은 여전히 세션에서 파생되므로, 스킬은 전체 결과를 안전한 텍스트가 아닌 세션 데이터로 취급합니다.

Codex는 설치 후 처음 시작할 때 훅을 신뢰하라고 요청합니다. "Hooks need review" 프롬프트에서 "Trust all and continue"를 선택하세요. 그렇게 하기 전까지 훅은 실행되지 않으며 가드가 보호하지 않습니다. 신뢰는 훅별 콘텐츠 해시이므로, 나중에 훅이 변경되면(버전 업 또는 감사에서 강제로 전환) 다시 요청합니다. Claude Code는 신뢰 단계가 필요 없습니다. 훅은 다음 세션에서 활성화됩니다.

skarn-recall은 같은 마켓플레이스의 세 번째 플러그인이며, 위의 마켓플레이스 추가로 이미 접근할 수 있습니다. 스킬 하나, 훅 없음, 호스트별 항목이 없으므로 같은 플러그인이 두 호스트 모두에 제공됩니다:

claude plugin install skarn-recall@skarn

codex plugin add skarn-recall@skarn

이 스킬은 세션 기록에서 작업한 내용을 재구성합니다. 그래서 가드 내부가 아닌 별도로 제공됩니다. 읽는 기록 내용은 에이전트를 제공하는 모델 제공자에게 머신을 떠납니다. 수정은 Skarn이 감지한 자격 증명을 마스킹하며, 민감하다고 생각하는 모든 것을 마스킹하지는 않습니다. 원할 때 설치하고, 프로젝트와 시간 창으로 읽는 범위를 지정하세요.

Gemini CLI는 이 저장소를 확장으로 설치하며, 감사 모드의 동일한 가드 훅, skarn-audit 스킬, GEMINI.md 컨텍스트 파일, 아래의 MCP 서버를 포함합니다:

gemini extensions install https://github.com/skarn-security/agent-guard
gemini extensions list
gemini extensions uninstall skarn

설치 시 동의를 요청합니다. 확장이 훅과 MCP 서버를 모두 선언하고 폴더를 신뢰하라고 요청하기 때문입니다. 둘 다 응답하세요.

Antigravity CLI는 클론의 antigravity/ 디렉터리를 설치합니다:

git clone https://github.com/skarn-security/agent-guard
agy plugin install agent-guard/antigravity
agy plugin list
agy plugin uninstall skarn-guard

agy plugin list는 훅, 스킬, MCP 서버 수와 함께 플러그인을 보고합니다. antigravity/를 ~/.gemini/config/plugins/skarn-guard/에 수동으로 복사해도 같은 효과가 있습니다.

Cursor는 자체 저장소 https://github.com/skarn-security/cursor-plugin를 가지며, 같은 릴리스로 생성됩니다. Cursor의 마켓플레이스와 검토는 저장소별로 이루어지므로 해당 유닛은 여기에 없습니다.

skarn setup은 Claude Code, Codex CLI, Cursor, Copilot CLI, Gemini CLI 및 Grok Build를 위한 대체 설치 경로입니다. 플러그인 시스템 없이 동일한 훅을 각 호스트의 기본 구성에 병합합니다. Antigravity CLI는 알지 못하므로 해당 호스트는 위의 플러그인 디렉터리를 설치하거나 훅 파일을 수동으로 병합합니다.

Related MCP server: netallion-mcp-lite

로컬 MCP 서버

네 개의 가드 유닛(claude/, codex/, antigravity/, 루트의 Gemini 확장)은 모두 동일한 stdio MCP 서버를 선언하며, 호스트는 PATH에서 skarn mcp를 실행하여 시작합니다. Cursor와 VS Code는 한 번의 클릭으로 설치할 수 있습니다:

두 버튼 모두 서버를 skarn으로 등록하고 PATH에서 skarn mcp를 실행하므로 먼저 바이너리를 설치하세요. 설치하지 않으려면, 고정된 런처 형식이 Node만 있어도 작동합니다: Cursor 또는 VS Code - 첫 실행 시 @skarn-security/skarn@0.26.0을 다운로드하고 이후에는 npx 캐시를 재사용합니다. 더 새로운 Skarn은 더 새로운 링크가 필요합니다.

모든 클라이언트에 대한 수동 구성:

{
  "mcpServers": {
    "skarn": {
      "command": "skarn",
      "args": ["mcp"]
    }
  }
}

이 서버는 사용자 머신에서 실행되며 네트워크 호출을 하지 않고 네 개의 읽기 전용 도구를 제공합니다: scan_sessions(과거 세션의 결과, 모든 미리보기 값은 수정됨), vet_configs(어시스턴트 구성 표면에 대한 마스킹된 보고서), list_sessions 및 session_stats(메타데이터와 집계, 메시지 내용은 절대 아님). 쓰기 도구나 메시지 내용을 반환하는 도구는 없습니다.

두 콘텐츠 도구인 search_sessions와 get_session은 서버를 skarn mcp --enable-recall로 시작할 때만 나타납니다. 둘 다 반환 내용을 마스킹하며, 콘텐츠는 여전히 세션을 제공하는 모델 제공자에게 머신을 떠납니다. 따라서 위의 선언은 플래그를 설정하지 않습니다. search_sessions는 hours나 project를 모두 지정하지 않은 호출을 거부합니다. get_session은 정확한 session_id 하나를 받으며, 이는 이미 범위입니다.

바이너리를 직접 설치하지 않으려면 버전이 고정된 npx 형식이 작동합니다:

{
  "mcpServers": {
    "skarn": {
      "command": "npx",
      "args": ["-y", "@skarn-security/skarn@0.26.0", "mcp"]
    }
  }
}

npx는 서버가 처음 시작될 때 패키지를 다운로드하고 이후에는 캐시하므로 첫 시작은 더 느리고 네트워크 액세스가 필요합니다. 버전을 고정하세요. 고정되지 않은 형식은 시작 시 레지스트리가 제공하는 무엇이든 해석하며, skarn vet는 이를 vet-mcp-unpinned로 보고합니다. 사용하지 마세요.

이 저장소 루트의 llms-install.md는 에이전트가 읽을 수 있는 단계로 된 동일한 설치로, 서버를 연결해 주는 클라이언트를 위한 것입니다.

각 호스트는 누락된 바이너리를 각자의 방식으로 보고합니다. claude mcp list는 Executable not found in $PATH: "skarn"과 함께 Failed to connect라고 말합니다. gemini mcp list는 skarn 서버를 Disconnected로 표시합니다. codex mcp list는 상태 확인을 실행하지 않으므로 행이 나열되고 활성화된 상태로 유지되며 세션이 시작할 때 서버가 실패합니다. Cursor는 플러그인의 행을 Error - Show Output으로 표시하고 출력 패널은 spawn skarn ENOENT로 끝납니다. 모든 경우에 터미널에서 skarn --version을 실행하세요. command not found는 바이너리가 설치되지 않았거나 해당 호스트가 상속하는 PATH에 없다는 뜻이며, 이는 셸이 아닌 데스크톱에서 시작된 애플리케이션의 일반적인 답입니다.

먼저 감사, 그다음 강제

두 가드 플러그인은 감사 모드로 제공됩니다(skarn-recall은 훅이 없으므로 모드가 없습니다). 가드는 반환했을 판정을 보고하고 에이전트가 하는 일을 절대 변경하지 않습니다. 먼저 그렇게 실행하고 실제 차단률을 측정하세요. 에이전트가 상속하는 환경에 SKARN_GUARD_LOG=<path>를 설정하면 가드는 플래그된 각 호출에 대해 수정된 JSONL 레코드 하나를 추가합니다(ts, verdict, tool, rule, severity, 수정된 이유, session, cwd, latency_ms). 정상 호출은 기록되지 않습니다.

로그가 깨끗해 보이면 훅 명령의 --guard-mode audit를 --guard-mode enforce로 바꾸거나 skarn setup --update --mode enforce를 실행하세요. 강제에는 Skarn 라이선스가 필요합니다. 없으면 가드는 감사 상태로 유지되어 차단하지 않고 보고하므로, 만료된 라이선스가 편집기를 망가뜨리지 않습니다.

Skarn 릴리스가 호스트의 이벤트 집합을 넓힐 때 훅을 최신 상태로 유지하는 것은 아래의 플러그인 업데이트이지 Skarn 명령이 아닙니다. 이 플러그인은 자체 훅 파일을 가지고 있으며, skarn setup --update는 skarn setup이 직접 쓴 Skarn 소유 항목만 새로 고칩니다. 항목을 쓴 범위(기본적으로 사용자별, 또는 --scope project 아래의 저장소 구성)에서 말입니다. 다른 방식으로 연결된 구성의 경우 --update는 설치된 바이너리가 쓰는 것으로 해당 항목을 다시 쓰며, 각 항목을 통째로 교체합니다. 단, 직접 조정한 훅 호출 시간 초과(timeout, Copilot의 timeoutSec)는 제외됩니다. 이 값은 교체 항목과 명확하게 짝을 이루고 값이 합리적일 때 유지되므로 머신별 예산이 새로 고침 후에도 유지됩니다. 해당 항목에 추가한 다른 필드는 삭제됩니다. 터미널에서 실행하면 skarn guard report와 skarn assess가 릴리스당 한 번, 해당 호스트의 정확한 업데이트 명령과 함께 뒤처진 설정 연결 사용자별 훅을 지목합니다.

업데이트

Claude Code:

claude plugin marketplace update skarn
claude plugin update skarn-guard@skarn

Codex CLI(업데이트 동사가 없습니다. 다시 추가하면 새 버전이 설치됩니다):

codex plugin marketplace upgrade
codex plugin add skarn-guard-codex@skarn

플러그인 업데이트와 바이너리 업데이트는 독립적입니다. 훅 명령은 PATH의 skarn guard를 호출하므로 brew upgrade skarn만으로도 최신 탐지 엔진을 얻을 수 있습니다. 플러그인 자체가 포함하는 것이 변경될 때 플러그인 업데이트가 중요합니다: 훅 형태(새 이벤트, 새 플래그, 새 매처), 스킬 텍스트, 또는 매니페스트 메타데이터.

안전

가드는 결정을 더 엄격하게만 만들 뿐 완화하지 않습니다. 가드 자체가 실패할 때 일어나는 일은 호스트에 따라 다릅니다. 각 호스트가 훅 충돌, 시간 초과, 또는 잘못된 출력이 무엇을 의미하는지 결정하기 때문입니다.

Claude Code, Codex CLI, Gemini CLI는 열린 실패(fail open)입니다. 잘못된 이벤트, 범위를 벗어난 도구, 또는 가드 오류는 허용을 산출하며 가드는 에이전트를 절대 망가뜨리지 않습니다. 이들 호스트에서 유일한 닫힌 실패(fail-closed) 경로는 라이선스가 있는 강제와 함께 --strict이며, 각 호스트 README에 문서화되어 있습니다.

Antigravity CLI는 명시적 허용을 제외한 모든 훅 결과에서 닫힌 실패(fail closed)입니다. 충돌, 시간 초과, 잘못된 JSON, 빈 {}는 모두 감사 모드와 강제 모드에서 일치하는 호출을 차단하며, PATH에 skarn 바이너리가 없는 연결된 훅은 일치하는 모든 호출을 차단합니다. 가드는 수신하는 모든 이벤트에 명시적 결정으로 응답하며, 제공되는 매처는 범위를 지정한 도구만 명명하므로 매처 밖의 단계는 가드 실패로 차단될 수 없습니다. 해당 훅을 연결하기 전에 skarn을 설치하고, skarn을 제거하기 전에 항목을 제거하세요. 문서: https://getskarn.com/?utm_source=agent-guard-readme&utm_medium=referral&utm_campaign=home&utm_content=documentation

라이선스, 개인정보, 지원

이 저장소는 MIT 라이선스입니다. LICENSE를 참조하세요. 구성만 포함하므로 플러그인 매니페스트, 훅, 스킬, MCP 서버 선언이 해당됩니다.

해당 파일들이 호출하는 skarn 바이너리는 별도 다운로드이며 오픈 소스가 아닙니다. 이는 https://getskarn.com/terms/의 Skarn 최종 사용자 라이선스 계약에 따라 라이선스가 부여되며, 실행하면 해당 계약에 동의하는 것으로 간주됩니다. 무엇을 읽고, 무엇을 보관하며, 무엇을 어디에도 전송하지 않는지: https://getskarn.com/privacy/.

지원: hello@getskarn.com. 취약점 보고는 security@getskarn.com으로 보내주세요. 이 저장소의 SECURITY.md를 참조하십시오.