Project Shield

Security scanner for AI coders and MCP users.

Detects leaked API keys, PII, insecure MCP configs, and prompt injection — in one command.

npx project-shield scan ./my-project

Tier: Free (0/5 scans)

Project Shield v1.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.

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

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)

Free vs Pro

| Feature | Free | Pro | |---------|------|-----| | Scans per month | 5 | 50 | | 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 | <!-- inject -->, \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.

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
  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
  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)
  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 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 설정 보안 취약점, 프롬프트 인젝션을 한 번에 탐지합니다.

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

Free vs Pro

| 기능 | Free | Pro | |------|------|-----| | 월간 스캔 | 5회 | 50회 | | 시크릿 / 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. 점수, 등급, 발견, 수정 가이드, 무결성 해시, 면책조항 포함.

라인 무시 (shield-ignore)

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

.shieldignore 파일:

tests/fixtures/
*.test.ts

무결성

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

라이선스

MIT