agentic-ioc-scanner

에이전틱 AI 코딩 도구를 위한 IOC 스캐너 — Mini Shai-Hulud, Gemini CLI RCE, Cursor CVE-2026-26268, DPRK PromptMink 탐지.

에이전틱 AI 코딩 어시스턴트(Claude Code, Gemini CLI, Cursor)와 이들이 리포지토리로 가져오는 의존성의 손상 탐지 키트입니다. 11가지 검사로 훅 주입, RCE 설정, 악성 의존성, git 훅 백도어, CI 워크플로 변조를 포괄합니다. IOC 목록은 외부화되어 있어 새로운 지표를 추가할 때 코드 변경이 필요하지 않습니다.

관련 블로그 글: 도구가 반격할 때

포함 내용

1. IOC 스캐너 (scanner/ais.sh)

각 검사에는 인라인 What:(목적)과 Fix:(해결 방법)가 섹션 헤더 아래에 출력되어 보고서가 자체 설명 가능합니다. IOC 목록은 scanner/iocs.txt에 있습니다(버전 관리됨, IOC_FILE=/path/to/iocs.txt로 재정의 가능).

사용법:

bash scanner/ais.sh
# 프롬프트가 나타나면 프로젝트 폴더를 입력하세요

# 사용자 정의 IOC 목록:
IOC_FILE=./my-iocs.txt bash scanner/ais.sh

# 사용자 정의 보고서 경로 (기본값: ./agentic-ioc-scan-YYYYMMDD-HHMMSS.log):
REPORT_FILE=/var/log/agentic-scan.log bash scanner/ais.sh

출력

• 발견 사항이 터미널(컬러) 및 일반 텍스트 보고서 파일(agentic-ioc-scan-YYYYMMDD-HHMMSS.log, ANSI 제거됨, tee → sed 사용)로 스트리밍됩니다.
• 심각도 태그: [CRITICAL] (즉시 조치), [WARNING] (악성 가능성 높음 — 확인 필요), [REVIEW] (정상 사용 가능성 있음 — 확인 필요), [OK] (깨끗함).
• 파일 내용 발견 사항에는 지표가 발견된 줄 번호가 포함됩니다(path:line 형식). 줄 번호가 표시되는 섹션: §1 훅, §2 Bun 시그니처, §3 난독화 신호, §5 preinstall 키, §7 Gemini 메타 문자, §8 AGENTS.md git 훅 참조, §9 의심스러운 훅 내용.
• §11 웜 리모트 발견 사항은 추가로 잘못된 .git/config 줄과 일치하는 리모트 URL을 보고하므로 제거해야 할 항목을 바로 찾을 수 있습니다.
• core.hooksPath 리디렉션(§9)은 리포지토리의 .git/config 절대 경로를 보고하여 재할당을 감사 가능하게 합니다.
• 워크트리 인식: .git이 파일인 경우(gitdir: … 포함) 실제 git 디렉터리를 검사 전에 확인합니다.

샘플 발견 사항

[CRITICAL] 리포지토리가 알려진 웜 유출 이름을 가리킴
           리포지토리: /home/dev/projects/myrepo
           설정: /home/dev/projects/myrepo/.git/config:9
           URL:    https://github.com/dhawaldesai/A-Mini-Shai-Hulud-has-Appeared

[CRITICAL] 악성 훅: /home/dev/projects/myrepo/.claude/settings.json:3
[CRITICAL] 의심스러운 git post-checkout 훅: /home/dev/projects/myrepo/.git/hooks/post-checkout:2

IOC 업데이트

scanner/iocs.txt를 편집하고 # version: 헤더를 증가시키십시오. 형식은 TYPE|VALUE|NOTES입니다. 지원되는 유형:

새로운 IOC가 나타날 때 코드 변경이 필요하지 않습니다. 스캐너는 시작 시 이를 읽고 배너에 로드된 버전을 출력합니다.

의존성

필수: bash, find, grep, awk, sed, git. 선택 사항: jq (권장, §1에서 사용 — 없으면 grep 휴리스틱으로 대체), npm (§10 전역 패키지 검사에 필요 — 사용 불가 시 섹션을 자동으로 건너뜁니다).

2. 영향받는 패키지 버전 스캐너 (scanner/pkg_version_check.sh)

IOC 스캐너의 동반 도구입니다. 영향받는 package,version 쌍의 CSV(예: Mini Shai-Hulud IOC 피드 ~/Downloads/Mini Shai-Hulud - Sheet1.csv — 633개 npm 패키지/버전 쌍)를 읽고 다음 위치에 있는지 확인합니다:

1. 사용자가 제공한 로컬 프로젝트 디렉터리 — package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, 설치된 node_modules/<pkg>/package.json을 스캔합니다. PyPI 매니페스트(requirements.txt, poetry.lock, Pipfile.lock)도 CSV에 범위 없는 이름이 포함된 경우 확인됩니다.
2. 사용자의 GitHub 리포지토리 — gh CLI 사용: 잠금 파일 유형에 대한 코드 검색 후, 의존성 그래프 SBOM API(/repos/{owner}/{repo}/dependency-graph/sbom)를 통한 정확한 버전 검증.

심각도 모델: 잠금 파일, node_modules/ 또는 SBOM에서 정확한 pkg@version 일치 → [CRITICAL]. 영향받는 버전을 포함할 수 있는 범위 지정자(^1.2.3, ~1.2.3, >=…) → [REVIEW]. 버전 확인 없이 패키지 이름만 일치 → [REVIEW]. 출력은 터미널과 ./shai-hulud-pkg-scan-YYYYMMDD-HHMMSS.log(ANSI 제거)로 스트리밍되며, 마지막에 심각도 분류 요약이 제공됩니다.

사용법:

# 대화형 — 프로젝트 디렉터리 입력 요청
bash scanner/pkg_version_check.sh

# 완전 스크립트 (환경 변수 재정의)
PROJECT_DIR=/path/to/project \
  IOC_CSV="$HOME/Downloads/Mini Shai-Hulud - Sheet1.csv" \
  REPORT_FILE=/var/log/pkg-scan.log \
  bash scanner/pkg_version_check.sh --skip-node-modules

CSV 형식: 1열 = 패키지 이름 (@scope/pkg와 같은 범위 이름 지원), 2열 = 정확한 영향받는 버전. 헤더 행은 자동 감지되어 건너뜁니다. IOC_CSV=…로 경로를 재정의할 수 있습니다.

의존성: bash, find, grep, awk, sed. 선택 사항: jq (node_modules/<pkg>/package.json 파싱 정확도 향상), gh (GitHub 단계에 필요 — 없거나 인증되지 않은 경우 명확한 메시지와 함께 건너뜁니다).

알려진 제한 사항:

• GitHub 코드 검색은 384KB를 초과하는 잠금 파일을 놓치며 기본 브랜치만 인덱싱합니다. SBOM 경로가 권위 있는 검사입니다.
• GitHub 단계는 속도 제한이 있습니다(인증 시 10 req/min). 약 7초에 5개 패키지로 조절되므로 633행 CSV를 GitHub에 대해 전체 실행하는 데 약 22분이 걸립니다. 로컬 스캔을 먼저 실행하고 GitHub 단계는 별도로 실행하십시오.
• 잠금 파일 파싱은 grep 기반이며 완전히 파싱되지 않습니다. 깊게 중첩되거나 비정상적인 형식은 오탐을 유발할 수 있습니다. 가장 가치 있는 후속 조치는 jq 기반 잠금 파일 파싱입니다.
• SBOM API는 리포지토리의 의존성 그래프가 활성화되고 인덱싱되어야 합니다. 없는 리포지토리는 [REVIEW]로 대체됩니다.

3. Claude Code 보안 정책 (claude-code-policy/)

Claude Code를 위한 예방 계층으로, 위의 탐지 계층을 보완합니다.

• 프로젝트 수준 훅 실행 차단 (allowManagedHooksOnly)
• .claude/settings.json에 쓰기 차단
• 알려진 드로퍼 패턴 실행 차단
• 에이전트 도구 사용에서 curl, wget, bun 명령 차단

설치:

# 관리 설정 복사 (프로젝트가 재정의할 수 없음)
cp claude-code-policy/managed-settings.json ~/.claude/managed-settings.json

# PreToolUse 훅 복사
mkdir -p ~/.claude/hooks
cp claude-code-policy/hooks/block_shai_hulud.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/block_shai_hulud.py

로드맵 / 알려진 격차

• PyPI 전역 스캔(§10과 동등, 현재는 npm ls -g만 연결됨).
• 허용 목록에 없는 작성자가 .claude/settings.json, .vscode/tasks.json, .gemini/ 파일을 추가하는 푸시를 거부하는 서버 측 pre-receive 훅.
• GitHub 푸시 보호 / Advanced Security와의 선택적 통합.

참고 자료

• 도구가 반격할 때 — 동반 분석
• Sophos: SAP npm 패키지 대상 Mini Shai-Hulud 공급망 공격
• Mend.io: Shai-Hulud가 SAP를 강타하다 — 공급망 웜이 Claude Code를 무기화
• Wiz: SAP npm의 Mini Shai-Hulud 공급망
• Novee Security: Google Gemini CLI RCE — CVSS 10.0 권고
• The Hacker News: Google, CVSS 10 Gemini CLI CI/CD RCE 수정 (Cursor CVE-2026-26268도 포함)
• ReversingLabs: PromptMink — DPRK 악성코드, Claude를 통해 코드베이스에 삽입
• Endor Labs: Mini Shai-Hulud 귀환 — @antv 생태계 공격에서 가짜 Sigstore 배지가 포함된 42개의 악성 npm 패키지

기여

이슈 및 PR을 환영합니다. 특히 새로운 IOC 제출(scanner/iocs.txt에 추가하고 버전 헤더 증가), 추가 플랫폼별 스캔 루트, 인접 에이전틱 도구(Continue, Cody, Codex CLI, Aider)에 대한 탐지 패턴 등이 필요합니다.

라이선스

MIT