project-shield

v2.0.0

Published

a month ago

Security scanner for AI coders and MCP users — secrets, PII, injection, and Claude Code environment audit

0High
0Medium
0Low

shovelmaker91

security scanner secrets pii mcp injection prompt-injection ai-security claude llm audit environment-security hooks

Project Shield

Security scanner for AI coders and MCP users.

Detects leaked API keys, PII, insecure MCP configs, and prompt injection. Audits your Claude Code environment for misconfigurations and malicious hooks.

Key Features

9 detection engines in one CLI — secrets, PII, MCP config, prompt injection, environment audit, hooks analysis, scoring, fix-it, evidence
Multi-layer detection — 3-layer secrets (regex + entropy + context), 2-layer PII (regex + checksum), 2-layer injection (keyword + structural)
Environment Audit — Claude Code settings, CLAUDE.md injection, hooks malicious command detection (16 checks)
Retention System — 7-day audit expiry warning, settings hash change detection
Security grade scoring (A-F) with automatic badge lock on critical findings
Fix-it guides — actionable remediation with code examples, not just warnings
Evidence Pack — compliance-ready PDF + JSON reports with integrity seals (SHA-256 + UUID)
MCP-native — purpose-built for AI agent configs (Claude, Cursor, Windsurf)
Lightweight — 4 dependencies, runs offline, CI/CD ready

npx project-shield scan ./my-project

Tier: Free (0/5 scans)

Project Shield v2.0.0
Ruleset: v1.0.0 (SHA-256: f408a4fd...)
Scanning: 47 files (3 excluded)

━━━ Secrets ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CRITICAL  src/config.ts:12
   AWS Access Key detected (AKIA****)
   Layers: regex ✓ entropy ✓ context ✓

━━━ PII ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CONFIRMED  data/users.csv:5
   Korean Resident Registration Number detected (900*****)
   Layers: regex ✓ checksum ✓

━━━ MCP Config ━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CRITICAL  mcp.json  (3/5 failed)
   ✗ Auth: No authentication configured
   ✗ Secrets: Hardcoded API key found
   ✓ Tool Meta: OK
   ✗ Permissions: Root filesystem access
   ✓ Logging: OK

━━━ Injection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CRITICAL  prompts/system.txt:3
   Hidden injection in comment [structural]
   Pattern: inj_ignore_prev  |  Layers: keyword ✓ structure ✓

━━━ Score ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Grade: F (0/100) — Locked
  Badge generation LOCKED — Fix all critical findings first.

Audit Demo

npx project-shield audit

Project Shield v2.0.0 — Environment Audit
Target: Claude Code

╔══════════════════════════════════════════════════╗
║  F008: Environment Security                      ║
╠══════════════════════════════════════════════════╣
║  🔴 CRITICAL  Unrestricted MCP servers           ║
║     allowedTools: ["*"] permits all tools         ║
║  🔴 CRITICAL  CLAUDE.md prompt injection          ║
║     Hidden instruction detected in CLAUDE.md      ║
║  ⚠  WARNING   Permissions too broad               ║
║     AllowedDirectories includes root path         ║
║  ✅ PASS      API key not exposed in settings     ║
║  ✅ PASS      No disabled security features       ║
╠══════════════════════════════════════════════════╣
║  F009: Hooks Analysis                             ║
╠══════════════════════════════════════════════════╣
║  🔴 CRITICAL  Malicious command in PreToolUse     ║
║     curl | sh detected in hook command            ║
║  ✅ PASS      No data exfiltration patterns       ║
║  ✅ PASS      No file system destruction          ║
╠══════════════════════════════════════════════════╣
║  Score: 35/100 (D)  |  3 Critical · 1 Warning    ║
║  ⚠ 3 additional issues — upgrade to Pro           ║
╚══════════════════════════════════════════════════╝

Retention: Last audit 8 days ago (expired)
Settings hash: changed since last audit

Why Project Shield?

| Problem | Project Shield | |---------|---------------| | API key leaked in commit | 3-layer detection (regex + entropy + context) | | PII in test data | Korean RRN checksum validation, credit card Luhn check | | MCP config wide open | 5-point check (auth, secrets, tools, permissions, logging) | | Prompt injection in tool descriptions | 2-layer detection (keyword + structural analysis) | | "What do I fix first?" | Fix-it guides with code examples | | Compliance evidence needed | PDF + JSON evidence pack |

Install

# Global
npm install -g project-shield

# npx (no install)
npx project-shield scan ./my-project

# Dev dependency
npm install -D project-shield

Usage

Basic scan

project-shield scan ./my-project

JSON output

project-shield scan ./my-project --format json

Fix-it guides

# Free: top 3 guides (summary only)
project-shield scan ./my-project --fix

# Pro: all guides with code examples + references
project-shield scan ./my-project --fix

Evidence pack (Pro — JSON + PDF)

project-shield scan ./my-project --evidence ./report
# Creates: report.json + report.pdf

Badge generation

# Free badge (with watermark)
project-shield scan ./my-project --badge shield-badge.svg

# Pro badge (no watermark, with UUID + verify URL)
project-shield scan ./my-project --badge shield-badge.svg

Custom ignore

project-shield scan ./my-project --ignore .shieldignore

Audit (v2.0)

# Basic environment audit
project-shield audit

# Auto-fix safe issues
project-shield audit --fix

# JSON output
project-shield audit --format json

# Audit evidence pack (Pro)
project-shield audit --evidence ./audit-report

All options

project-shield scan <path>
  -f, --format <format>    Output format: terminal | json (default: terminal)
  -i, --ignore <path>      Path to .shieldignore file
  -r, --ruleset <path>     Path to custom ruleset JSON
  -b, --badge <path>       Output path for SVG badge
  --fix                    Show fix-it remediation guides
  --evidence <path>        Output path for evidence pack (JSON + PDF)

project-shield audit
  -f, --format <format>    Output format: terminal | json (default: terminal)
  --fix                    Auto-fix safe issues
  --evidence <path>        Output path for audit evidence pack (Pro)

Free vs Pro

| Feature | Free | Pro | |---------|------|-----| | Scans per month | 5 | 50 | | Audits per month | 3 | 20 | | Audit checks (F008) | 3 critical only | All 9 checks | | Hooks analysis (F009) | — | Full 7 checks | | Audit evidence | — | JSON Evidence Pack | | Secrets / MCP / Injection details | Full | Full | | PII details | Count only | File:line details | | Fix-it guides | Top 3, summary | All, with code + references | | Badge | Watermark | Clean + UUID + verify URL | | Evidence Pack | Blocked | JSON + PDF | | Seal UUID | No | Yes |

License Management

# Check current status
project-shield status

# Activate Pro license
project-shield activate PSH-XXXX-XXXX-XXXX-XXXX

# Deactivate license
project-shield deactivate

License validation: Server-validated with 7-day local cache. If the server is unreachable, a 3-day grace period keeps Pro active. After that, it gracefully downgrades to Free.

What It Detects

F001: Secrets (3-layer detection)

| Layer | Method | Example | |-------|--------|---------| | Regex | Pattern matching | AKIA..., sk_live_..., ghp_... | | Entropy | Shannon entropy > 4.5 | High-randomness strings in secret context | | Context | Variable name analysis | API_KEY=, secret:, .env files |

10 built-in patterns: AWS, Stripe, OpenAI, GitHub PAT/OAuth, Slack, Google, Private Keys + high-entropy catch-all.

Severity rules:

2+ layers hit = critical
1 layer hit = warning
Pattern override (e.g., sk_live_ always critical)

F002: MCP Config (5-point check)

| Check | What | Critical When | |-------|------|---------------| | Auth | Authentication configured? | No auth field found | | Secrets | Hardcoded keys in config? | Literal API key (not ${ENV_VAR}) | | Tool Meta | Dangerous tool keywords? | exec, eval, shell, rm in tools | | Permissions | Overly broad access? | Root /, wildcard *, --privileged | | Logging | Audit logging enabled? | No logging/audit field |

F003: Prompt Injection (2-layer detection)

| Layer | Method | Example | |-------|--------|---------| | Keyword | 11 patterns (6 direct + 5 indirect) | "ignore previous instructions", "secretly" | | Structure | Comment hiding, zero-width chars, tool length | , \u200B |

Cross-judgment:

Keyword + Structure = critical
Keyword only = warning
Structure only (with hidden keyword) = critical
Encoded bypass (Base64/URL) = automatic critical

F004: PII (2-layer detection)

| Pattern | Locale | Checksum | |---------|--------|----------| | Korean RRN (주민등록번호) | KR | Yes | | Korean Phone | KR | No | | Korean Business Number | KR | Yes | | Korean Passport | KR | No | | Email | Global | No | | US SSN | Global | No | | Credit Card | Global | Luhn |

F005: Scoring (0-100)

| Grade | Score | Status | |-------|-------|--------| | A | 90-100 | Excellent | | B | 75-89 | Good | | C | 60-74 | Pass | | D | 40-59 | Warning | | E | 20-39 | Warning | | F | 0-19 | Locked |

Any critical finding = automatic F + badge locked.

Deductions: critical -25, warning -10, possible -5, info -2.

F008: Environment Security (9 checks)

| ID | Check | Severity | Tier | Description | |----|-------|----------|------|-------------| | F008-01 | MCP Server Allowlist | Critical | Free | Unrestricted MCP servers (allowedTools: ["*"]) | | F008-02 | CLAUDE.md Injection | Critical | Free | Hidden instructions or prompt injection in CLAUDE.md | | F008-03 | API Key Exposure | Critical | Free | API keys hardcoded in settings files | | F008-04 | Permission Scope | Warning | Pro | Overly broad directory/file permissions | | F008-05 | Disabled Security | Warning | Pro | Security features explicitly disabled | | F008-06 | Telemetry Settings | Info | Pro | Telemetry misconfiguration | | F008-07 | Extension Trust | Warning | Pro | Untrusted extensions enabled | | F008-08 | Network Exposure | Warning | Pro | Insecure network configurations | | F008-09 | Update Policy | Info | Pro | Auto-update disabled or misconfigured |

F009: Hooks Analysis (7 checks)

| ID | Check | Severity | Description | |----|-------|----------|-------------| | F009-01 | Malicious Commands | Critical | curl\|sh, wget\|bash, reverse shells in hooks | | F009-02 | Data Exfiltration | Critical | Sending data to external endpoints | | F009-03 | File Destruction | Critical | rm -rf, file system wipes | | F009-04 | Privilege Escalation | Critical | sudo, chmod 777, permission changes | | F009-05 | Environment Tampering | Warning | Modifying PATH, env variables | | F009-06 | Obfuscated Commands | Warning | Base64-encoded or obfuscated payloads | | F009-07 | Unauthorized Network | Warning | Unexpected outbound connections |

Retention

Audit results expire after 7 days to ensure ongoing security monitoring.

Expiry warning: "Your last audit expired N days ago. Re-run project-shield audit."
Hash change detection: If .claude/settings.json changes, Shield detects the hash mismatch and recommends re-audit.
State storage: .claude/.shield/audit-state.json

Inline Suppression

Add shield-ignore to suppress a specific line:

const API_KEY = "sk_test_abc123"; // shield-ignore

API_KEY = "sk_test_abc123"  # shield-ignore

Or use .shieldignore (gitignore syntax):

# .shieldignore
tests/fixtures/
*.test.ts
docs/examples/

Evidence Pack

The --evidence flag generates a compliance-ready report (Pro only):

JSON (report.json):

Full findings (secrets, PII, MCP, injection)
Score + lock status
Fix-it summary
Integrity hashes (result SHA-256 + ruleset SHA-256)
Disclaimer

PDF (report.pdf):

Cover page with grade
Executive summary
Findings detail by category
Integrity verification
Disclaimer

CI Integration

# GitHub Actions
- name: Security Scan
  run: npx project-shield scan . --format json
  # Exit code 1 if any critical finding

# With badge
- name: Security Scan + Badge
  run: |
    npx project-shield scan . --badge shield-badge.svg
    # Commit badge to repo

Architecture

src/
  index.ts              CLI entry (commander)
  types/index.ts        All TypeScript interfaces
  types/audit.ts        Audit type definitions
  scanner/
    engine.ts           Scan orchestrator (glob, binary skip, ignore)
    secrets.ts          3-layer secret detection
    pii.ts              2-layer PII detection
    mcp.ts              5-point MCP config check
    injection.ts        2-layer injection detection
    ignore.ts           shield-ignore + .shieldignore
  auditor/
    engine.ts           Audit orchestrator (providers, checks, scoring)
    providers/
      types.ts          AuditProvider interface
      claude-code.ts    Claude Code environment provider
    checks/
      environment.ts    F008: 9 environment security checks
      hooks.ts          F009: 7 hooks malicious command checks
  scoring/
    score.ts            0-100 scoring + A-F grading
    lock.ts             Badge lock logic
  integrity/
    ruleset.ts          Ruleset loader + SHA-256 verification
    failsafe.ts         Crash = fail, no ruleset = reject
    seal.ts             Result hash sealing (SHA-256 + UUID)
  output/
    terminal.ts         Terminal + JSON formatter
    badge.ts            SVG badge generator (shields.io style)
    fixit.ts            10-type fix-it guide system
    evidence.ts         Evidence pack (JSON + PDF)
    audit-terminal.ts   Audit PRD box format terminal output
    audit-evidence.ts   Audit evidence pack JSON
    audit-fixit.ts      Audit fix-it guides (16 checks)
  retention/
    storage.ts          Audit state storage (.claude/.shield/audit-state.json)
    expiry.ts           7-day audit expiry detection
    hash-detect.ts      Settings hash change detection
  license/
    types.ts            License type definitions
    storage.ts          Local file I/O (~/.project-shield/)
    http.ts             HTTPS request wrapper
    validator.ts        Key validation + 7-day cache + 3-day grace
    usage.ts            Scan + audit usage tracking (monthly)
    gate.ts             Feature gating (Free/Pro)
    commands.ts         activate / deactivate / status
rules/
  v1.0.0.json           Ruleset (secrets + PII + MCP + injection patterns)

Integrity

Ruleset is SHA-256 verified on every load. Tampered ruleset = scan rejected.
Scan results are hash-sealed. Same input = same hash.
Fail-safe: crash during scan = SCAN_FAILED (never false PASS).

License

MIT

Project Shield (한국어)

AI 코더/MCP 사용자를 위한 보안 스캐너 CLI.

API 키 유출, 개인정보, MCP 설정 보안 취약점, 프롬프트 인젝션을 탐지합니다. Claude Code 환경 설정 오류와 악성 훅도 감사합니다.

주요 특징

9개 탐지 엔진 올인원 — 시크릿, PII, MCP 설정, 프롬프트 인젝션, 환경 감사, 훅 분석, 스코어링, Fix-it, Evidence
다중 레이어 탐지 — 시크릿 3중 (정규식 + 엔트로피 + 컨텍스트), PII 2중 (정규식 + 체크섬), 인젝션 2중 (키워드 + 구조)
환경 감사 — Claude Code 설정, CLAUDE.md 인젝션, 훅 악성 명령 탐지 (16개 검사)
리텐션 시스템 — 7일 감사 만료 경고, 설정 해시 변경 감지
보안 등급 스코어 (A-F) — Critical 발견 시 자동 뱃지 잠금
Fix-it 가이드 — 경고만 하지 않고, 코드 예제와 함께 수정 방법 제시
Evidence Pack — 컴플라이언스용 PDF + JSON 리포트, 무결성 봉인 (SHA-256 + UUID)
MCP 네이티브 — AI 에이전트 설정 전용 (Claude, Cursor, Windsurf)
경량 — 의존성 4개, 오프라인 실행 가능, CI/CD 즉시 연동

npx project-shield scan ./my-project

왜 Project Shield?

| 문제 | Project Shield | |------|---------------| | 커밋에서 API 키 유출 | 3중 탐지 (정규식 + 엔트로피 + 컨텍스트) | | 테스트 데이터에서 개인정보 노출 | 주민등록번호 체크섬 검증, 신용카드 Luhn 검증 | | MCP 설정 보안 허점 | 5항목 점검 (인증, 시크릿, 툴, 권한, 로깅) | | 툴 설명에 숨겨진 프롬프트 인젝션 | 2중 탐지 (키워드 + 구조 분석) | | "뭐부터 고쳐야 하지?" | Fix-it 가이드 (코드 예제 포함) | | 컴플라이언스 증빙 필요 | PDF + JSON Evidence Pack |

설치

# 글로벌
npm install -g project-shield

# npx (설치 없이)
npx project-shield scan ./my-project

사용법

기본 스캔

project-shield scan ./my-project

Fix-it 가이드 포함

# Free: 상위 3개 (요약만)
project-shield scan ./my-project --fix

# Pro: 전체 가이드 + 코드 예제 + 참조
project-shield scan ./my-project --fix

Evidence Pack (Pro 전용 — JSON + PDF)

project-shield scan ./my-project --evidence ./report
# 생성: report.json + report.pdf

뱃지 생성

project-shield scan ./my-project --badge shield-badge.svg

환경 감사 (v2.0)

# 기본 환경 감사
project-shield audit

# 안전한 이슈 자동 수정
project-shield audit --fix

# JSON 출력
project-shield audit --format json

# 감사 Evidence Pack (Pro)
project-shield audit --evidence ./audit-report

Free vs Pro

| 기능 | Free | Pro | |------|------|-----| | 월간 스캔 | 5회 | 50회 | | 월간 감사 | 3회 | 20회 | | 환경 검사 (F008) | Critical 3개만 | 전체 9개 | | 훅 분석 (F009) | — | 전체 7개 | | 감사 Evidence | — | JSON Evidence Pack | | 시크릿 / MCP / 인젝션 상세 | 전체 표시 | 전체 표시 | | PII 상세 | 건수만 표시 | 파일:라인 상세 | | Fix-it 가이드 | 상위 3개, 요약만 | 전체, 코드 + 참조 포함 | | 뱃지 | 워터마크 | 클린 + UUID + 검증 URL | | Evidence Pack | 차단 | JSON + PDF 생성 | | Seal UUID | 미포함 | 포함 |

라이선스 관리

# 현재 상태 확인
project-shield status

# Pro 라이선스 활성화
project-shield activate PSH-XXXX-XXXX-XXXX-XXXX

# 라이선스 비활성화
project-shield deactivate

라이선스 검증: 서버 검증 후 7일간 로컬 캐시. 서버 불통 시 3일 유예 기간. 유예 이후 Free로 자동 다운그레이드.

탐지 항목

F001: 시크릿(Secret) 탐지

3중 탐지: 정규식 매칭 + 섀넌 엔트로피 + 컨텍스트 분석 (변수명, .env 파일 등)

10종 패턴: AWS, Stripe, OpenAI, GitHub PAT/OAuth, Slack, Google, Private Key

F002: MCP 설정 점검

5항목 점검: 인증(auth), 시크릿(secrets), 툴(tools), 권한(permissions), 로깅(logging)

F003: 프롬프트 인젝션 탐지

2중 탐지: 키워드 매칭 (11종 패턴) + 구조 분석 (HTML 주석, zero-width 유니코드, 툴 설명 길이)

Base64/URL 인코딩된 우회 시도 감지 시 자동 critical

F004: PII 탐지

주민등록번호 (체크섬 검증), 전화번호, 사업자등록번호, 여권번호, 이메일, US SSN, 신용카드 (Luhn 검증)

F005: 스코어

0-100점 방식, A-F 등급. Critical 발견이 1개라도 있으면 자동 F + 뱃지 잠금.

F006: Fix-it 가이드

10종 맞춤형 가이드: AWS 키 로테이션, Stripe 키 로테이션, Private Key 제거, RRN 마스킹, 신용카드 제거, MCP 설정 수정 3종, 프롬프트 인젝션 제거

F007: Evidence Pack

JSON + PDF. 점수, 등급, 발견, 수정 가이드, 무결성 해시, 면책조항 포함.

F008: 환경 보안 검사 (9개)

| ID | 검사 | 심각도 | 티어 | 설명 | |----|------|--------|------|------| | F008-01 | MCP 서버 허용 목록 | Critical | Free | 무제한 MCP 서버 (allowedTools: ["*"]) | | F008-02 | CLAUDE.md 인젝션 | Critical | Free | CLAUDE.md에 숨겨진 명령어/프롬프트 인젝션 | | F008-03 | API 키 노출 | Critical | Free | 설정 파일에 하드코딩된 API 키 | | F008-04 | 권한 범위 | Warning | Pro | 과도하게 넓은 디렉토리/파일 권한 | | F008-05 | 보안 기능 비활성화 | Warning | Pro | 보안 기능이 명시적으로 꺼져 있음 | | F008-06 | 텔레메트리 설정 | Info | Pro | 텔레메트리 설정 오류 | | F008-07 | 확장 프로그램 신뢰 | Warning | Pro | 신뢰할 수 없는 확장 프로그램 활성화 | | F008-08 | 네트워크 노출 | Warning | Pro | 안전하지 않은 네트워크 설정 | | F008-09 | 업데이트 정책 | Info | Pro | 자동 업데이트 비활성화/설정 오류 |

F009: 훅 분석 (7개)

| ID | 검사 | 심각도 | 설명 | |----|------|--------|------| | F009-01 | 악성 명령 | Critical | curl\|sh, wget\|bash, 리버스 셸 | | F009-02 | 데이터 유출 | Critical | 외부 엔드포인트로 데이터 전송 | | F009-03 | 파일 파괴 | Critical | rm -rf, 파일 시스템 삭제 | | F009-04 | 권한 상승 | Critical | sudo, chmod 777, 권한 변경 | | F009-05 | 환경 변수 변조 | Warning | PATH, 환경 변수 수정 | | F009-06 | 난독화 명령 | Warning | Base64 인코딩 등 난독화된 페이로드 | | F009-07 | 비인가 네트워크 | Warning | 예상치 못한 외부 연결 |

리텐션

감사 결과는 7일 후 만료되어 지속적 보안 모니터링을 보장합니다.

만료 경고: "마지막 감사가 N일 전에 만료되었습니다. project-shield audit를 다시 실행하세요."
해시 변경 감지: .claude/settings.json이 변경되면 해시 불일치를 감지하고 재감사를 권장합니다.
상태 저장: .claude/.shield/audit-state.json

라인 무시 (shield-ignore)

const key = "sk_test_abc"; // shield-ignore

.shieldignore 파일:

tests/fixtures/
*.test.ts

무결성

룰셋은 매 로드마다 SHA-256 검증. 변조된 룰셋 = 스캔 거부.
스캔 결과는 해시 봉인. 동일 입력 = 동일 해시.
Fail-safe: 스캔 중 크래시 = SCAN_FAILED (거짓 통과 없음).

라이선스

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Project Shield

Key Features

Audit Demo

Why Project Shield?

Install

Usage

Basic scan

JSON output

Fix-it guides

Evidence pack (Pro — JSON + PDF)

Badge generation

Custom ignore

Audit (v2.0)

All options

Free vs Pro

License Management

What It Detects

F001: Secrets (3-layer detection)

F002: MCP Config (5-point check)

F003: Prompt Injection (2-layer detection)

F004: PII (2-layer detection)

F005: Scoring (0-100)

F008: Environment Security (9 checks)

F009: Hooks Analysis (7 checks)

Retention

Inline Suppression

Evidence Pack

CI Integration

Architecture

Integrity

License

Project Shield (한국어)

주요 특징

왜 Project Shield?

설치

사용법

기본 스캔

Fix-it 가이드 포함

Evidence Pack (Pro 전용 — JSON + PDF)

뱃지 생성

환경 감사 (v2.0)

Free vs Pro

라이선스 관리

탐지 항목

F001: 시크릿(Secret) 탐지

F002: MCP 설정 점검

F003: 프롬프트 인젝션 탐지

F004: PII 탐지

F005: 스코어

F006: Fix-it 가이드

F007: Evidence Pack

F008: 환경 보안 검사 (9개)

F009: 훅 분석 (7개)

리텐션

라인 무시 (shield-ignore)

무결성

라이선스