project-shield 1.1.2 → 1.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +518 -518
  2. package/dist/index.js +27 -0
  3. package/dist/index.js.map +1 -1
  4. package/dist/output/badge.js +24 -24
  5. package/dist/output/fixit.js +44 -44
  6. package/package.json +52 -52
  7. package/rules/v1.0.0.json +248 -248
package/README.md CHANGED
@@ -1,518 +1,518 @@
1
- # Project Shield
2
-
3
- **Security scanner for AI coders and MCP users.**
4
-
5
- Detects leaked API keys, PII, insecure MCP configs, and prompt injection — in one command.
6
-
7
- [![npm version](https://img.shields.io/npm/v/project-shield)](https://www.npmjs.com/package/project-shield)
8
- [![license](https://img.shields.io/npm/l/project-shield)](LICENSE)
9
-
10
- ```bash
11
- npx project-shield scan ./my-project
12
- ```
13
-
14
- ```
15
- Tier: Free (0/5 scans)
16
-
17
- Project Shield v1.0.0
18
- Ruleset: v1.0.0 (SHA-256: f408a4fd...)
19
- Scanning: 47 files (3 excluded)
20
-
21
- ━━━ Secrets ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
22
- CRITICAL src/config.ts:12
23
- AWS Access Key detected (AKIA****)
24
- Layers: regex ✓ entropy ✓ context ✓
25
-
26
- ━━━ PII ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
27
- CONFIRMED data/users.csv:5
28
- Korean Resident Registration Number detected (900*****)
29
- Layers: regex ✓ checksum ✓
30
-
31
- ━━━ MCP Config ━━━━━━━━━━━━━━━━━━━━━━━━━━━
32
- CRITICAL mcp.json (3/5 failed)
33
- ✗ Auth: No authentication configured
34
- ✗ Secrets: Hardcoded API key found
35
- ✓ Tool Meta: OK
36
- ✗ Permissions: Root filesystem access
37
- ✓ Logging: OK
38
-
39
- ━━━ Injection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
40
- CRITICAL prompts/system.txt:3
41
- Hidden injection in comment [structural]
42
- Pattern: inj_ignore_prev | Layers: keyword ✓ structure ✓
43
-
44
- ━━━ Score ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
45
- Grade: F (0/100) — Locked
46
- Badge generation LOCKED — Fix all critical findings first.
47
- ```
48
-
49
- ---
50
-
51
- ## Why Project Shield?
52
-
53
- | Problem | Project Shield |
54
- |---------|---------------|
55
- | API key leaked in commit | 3-layer detection (regex + entropy + context) |
56
- | PII in test data | Korean RRN checksum validation, credit card Luhn check |
57
- | MCP config wide open | 5-point check (auth, secrets, tools, permissions, logging) |
58
- | Prompt injection in tool descriptions | 2-layer detection (keyword + structural analysis) |
59
- | "What do I fix first?" | Fix-it guides with code examples |
60
- | Compliance evidence needed | PDF + JSON evidence pack |
61
-
62
- ---
63
-
64
- ## Install
65
-
66
- ```bash
67
- # Global
68
- npm install -g project-shield
69
-
70
- # npx (no install)
71
- npx project-shield scan ./my-project
72
-
73
- # Dev dependency
74
- npm install -D project-shield
75
- ```
76
-
77
- ---
78
-
79
- ## Usage
80
-
81
- ### Basic scan
82
-
83
- ```bash
84
- project-shield scan ./my-project
85
- ```
86
-
87
- ### JSON output
88
-
89
- ```bash
90
- project-shield scan ./my-project --format json
91
- ```
92
-
93
- ### Fix-it guides
94
-
95
- ```bash
96
- # Free: top 3 guides (summary only)
97
- project-shield scan ./my-project --fix
98
-
99
- # Pro: all guides with code examples + references
100
- project-shield scan ./my-project --fix
101
- ```
102
-
103
- ### Evidence pack (Pro — JSON + PDF)
104
-
105
- ```bash
106
- project-shield scan ./my-project --evidence ./report
107
- # Creates: report.json + report.pdf
108
- ```
109
-
110
- ### Badge generation
111
-
112
- ```bash
113
- # Free badge (with watermark)
114
- project-shield scan ./my-project --badge shield-badge.svg
115
-
116
- # Pro badge (no watermark, with UUID + verify URL)
117
- project-shield scan ./my-project --badge shield-badge.svg
118
- ```
119
-
120
- ### Custom ignore
121
-
122
- ```bash
123
- project-shield scan ./my-project --ignore .shieldignore
124
- ```
125
-
126
- ### All options
127
-
128
- ```
129
- project-shield scan <path>
130
- -f, --format <format> Output format: terminal | json (default: terminal)
131
- -i, --ignore <path> Path to .shieldignore file
132
- -r, --ruleset <path> Path to custom ruleset JSON
133
- -b, --badge <path> Output path for SVG badge
134
- --fix Show fix-it remediation guides
135
- --evidence <path> Output path for evidence pack (JSON + PDF)
136
- ```
137
-
138
- ---
139
-
140
- ## Free vs Pro
141
-
142
- | Feature | Free | Pro |
143
- |---------|------|-----|
144
- | Scans per month | 5 | 50 |
145
- | Secrets / MCP / Injection details | Full | Full |
146
- | PII details | Count only | File:line details |
147
- | Fix-it guides | Top 3, summary | All, with code + references |
148
- | Badge | Watermark | Clean + UUID + verify URL |
149
- | Evidence Pack | Blocked | JSON + PDF |
150
- | Seal UUID | No | Yes |
151
-
152
- ### License Management
153
-
154
- ```bash
155
- # Check current status
156
- project-shield status
157
-
158
- # Activate Pro license
159
- project-shield activate PSH-XXXX-XXXX-XXXX-XXXX
160
-
161
- # Deactivate license
162
- project-shield deactivate
163
- ```
164
-
165
- **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.
166
-
167
- ---
168
-
169
- ## What It Detects
170
-
171
- ### F001: Secrets (3-layer detection)
172
-
173
- | Layer | Method | Example |
174
- |-------|--------|---------|
175
- | Regex | Pattern matching | `AKIA...`, `sk_live_...`, `ghp_...` |
176
- | Entropy | Shannon entropy > 4.5 | High-randomness strings in secret context |
177
- | Context | Variable name analysis | `API_KEY=`, `secret:`, `.env` files |
178
-
179
- **10 built-in patterns**: AWS, Stripe, OpenAI, GitHub PAT/OAuth, Slack, Google, Private Keys + high-entropy catch-all.
180
-
181
- **Severity rules**:
182
- - 2+ layers hit = **critical**
183
- - 1 layer hit = **warning**
184
- - Pattern override (e.g., `sk_live_` always critical)
185
-
186
- ### F002: MCP Config (5-point check)
187
-
188
- | Check | What | Critical When |
189
- |-------|------|---------------|
190
- | Auth | Authentication configured? | No auth field found |
191
- | Secrets | Hardcoded keys in config? | Literal API key (not `${ENV_VAR}`) |
192
- | Tool Meta | Dangerous tool keywords? | `exec`, `eval`, `shell`, `rm` in tools |
193
- | Permissions | Overly broad access? | Root `/`, wildcard `*`, `--privileged` |
194
- | Logging | Audit logging enabled? | No logging/audit field |
195
-
196
- ### F003: Prompt Injection (2-layer detection)
197
-
198
- | Layer | Method | Example |
199
- |-------|--------|---------|
200
- | Keyword | 11 patterns (6 direct + 5 indirect) | "ignore previous instructions", "secretly" |
201
- | Structure | Comment hiding, zero-width chars, tool length | `<!-- inject -->`, `\u200B` |
202
-
203
- **Cross-judgment**:
204
- - Keyword + Structure = **critical**
205
- - Keyword only = **warning**
206
- - Structure only (with hidden keyword) = **critical**
207
- - Encoded bypass (Base64/URL) = **automatic critical**
208
-
209
- ### F004: PII (2-layer detection)
210
-
211
- | Pattern | Locale | Checksum |
212
- |---------|--------|----------|
213
- | Korean RRN (주민등록번호) | KR | Yes |
214
- | Korean Phone | KR | No |
215
- | Korean Business Number | KR | Yes |
216
- | Korean Passport | KR | No |
217
- | Email | Global | No |
218
- | US SSN | Global | No |
219
- | Credit Card | Global | Luhn |
220
-
221
- ### F005: Scoring (0-100)
222
-
223
- | Grade | Score | Status |
224
- |-------|-------|--------|
225
- | A | 90-100 | Excellent |
226
- | B | 75-89 | Good |
227
- | C | 60-74 | Pass |
228
- | D | 40-59 | Warning |
229
- | E | 20-39 | Warning |
230
- | F | 0-19 | Locked |
231
-
232
- **Any critical finding = automatic F + badge locked.**
233
-
234
- Deductions: critical -25, warning -10, possible -5, info -2.
235
-
236
- ---
237
-
238
- ## Inline Suppression
239
-
240
- Add `shield-ignore` to suppress a specific line:
241
-
242
- ```javascript
243
- const API_KEY = "sk_test_abc123"; // shield-ignore
244
- ```
245
-
246
- ```python
247
- API_KEY = "sk_test_abc123" # shield-ignore
248
- ```
249
-
250
- Or use `.shieldignore` (gitignore syntax):
251
-
252
- ```
253
- # .shieldignore
254
- tests/fixtures/
255
- *.test.ts
256
- docs/examples/
257
- ```
258
-
259
- ---
260
-
261
- ## Evidence Pack
262
-
263
- The `--evidence` flag generates a compliance-ready report (Pro only):
264
-
265
- **JSON** (`report.json`):
266
- - Full findings (secrets, PII, MCP, injection)
267
- - Score + lock status
268
- - Fix-it summary
269
- - Integrity hashes (result SHA-256 + ruleset SHA-256)
270
- - Disclaimer
271
-
272
- **PDF** (`report.pdf`):
273
- - Cover page with grade
274
- - Executive summary
275
- - Findings detail by category
276
- - Integrity verification
277
- - Disclaimer
278
-
279
- ---
280
-
281
- ## CI Integration
282
-
283
- ```yaml
284
- # GitHub Actions
285
- - name: Security Scan
286
- run: npx project-shield scan . --format json
287
- # Exit code 1 if any critical finding
288
- ```
289
-
290
- ```yaml
291
- # With badge
292
- - name: Security Scan + Badge
293
- run: |
294
- npx project-shield scan . --badge shield-badge.svg
295
- # Commit badge to repo
296
- ```
297
-
298
- ---
299
-
300
- ## Architecture
301
-
302
- ```
303
- src/
304
- index.ts CLI entry (commander)
305
- types/index.ts All TypeScript interfaces
306
- scanner/
307
- engine.ts Scan orchestrator (glob, binary skip, ignore)
308
- secrets.ts 3-layer secret detection
309
- pii.ts 2-layer PII detection
310
- mcp.ts 5-point MCP config check
311
- injection.ts 2-layer injection detection
312
- ignore.ts shield-ignore + .shieldignore
313
- scoring/
314
- score.ts 0-100 scoring + A-F grading
315
- lock.ts Badge lock logic
316
- integrity/
317
- ruleset.ts Ruleset loader + SHA-256 verification
318
- failsafe.ts Crash = fail, no ruleset = reject
319
- seal.ts Result hash sealing (SHA-256 + UUID)
320
- output/
321
- terminal.ts Terminal + JSON formatter
322
- badge.ts SVG badge generator (shields.io style)
323
- fixit.ts 10-type fix-it guide system
324
- evidence.ts Evidence pack (JSON + PDF)
325
- license/
326
- types.ts License type definitions
327
- storage.ts Local file I/O (~/.project-shield/)
328
- http.ts HTTPS request wrapper
329
- validator.ts Key validation + 7-day cache + 3-day grace
330
- usage.ts Scan usage tracking (monthly)
331
- gate.ts Feature gating (Free/Pro)
332
- commands.ts activate / deactivate / status
333
- rules/
334
- v1.0.0.json Ruleset (secrets + PII + MCP + injection patterns)
335
- ```
336
-
337
- ---
338
-
339
- ## Integrity
340
-
341
- - Ruleset is SHA-256 verified on every load. Tampered ruleset = scan rejected.
342
- - Scan results are hash-sealed. Same input = same hash.
343
- - Fail-safe: crash during scan = `SCAN_FAILED` (never false PASS).
344
-
345
- ---
346
-
347
- ## License
348
-
349
- MIT
350
-
351
- ---
352
-
353
- <p align="center">
354
- <sub>Built for developers who ship AI-powered apps and want to sleep at night.</sub>
355
- </p>
356
-
357
- ---
358
-
359
- # Project Shield (한국어)
360
-
361
- **AI 코더/MCP 사용자를 위한 보안 스캐너 CLI.**
362
-
363
- API 키 유출, 개인정보, MCP 설정 보안 취약점, 프롬프트 인젝션을 한 번에 탐지합니다.
364
-
365
- ```bash
366
- npx project-shield scan ./my-project
367
- ```
368
-
369
- ---
370
-
371
- ## 왜 Project Shield?
372
-
373
- | 문제 | Project Shield |
374
- |------|---------------|
375
- | 커밋에서 API 키 유출 | 3중 탐지 (정규식 + 엔트로피 + 컨텍스트) |
376
- | 테스트 데이터에서 개인정보 노출 | 주민등록번호 체크섬 검증, 신용카드 Luhn 검증 |
377
- | MCP 설정 보안 허점 | 5항목 점검 (인증, 시크릿, 툴, 권한, 로깅) |
378
- | 툴 설명에 숨겨진 프롬프트 인젝션 | 2중 탐지 (키워드 + 구조 분석) |
379
- | "뭐부터 고쳐야 하지?" | Fix-it 가이드 (코드 예제 포함) |
380
- | 컴플라이언스 증빙 필요 | PDF + JSON Evidence Pack |
381
-
382
- ---
383
-
384
- ## 설치
385
-
386
- ```bash
387
- # 글로벌
388
- npm install -g project-shield
389
-
390
- # npx (설치 없이)
391
- npx project-shield scan ./my-project
392
- ```
393
-
394
- ---
395
-
396
- ## 사용법
397
-
398
- ### 기본 스캔
399
-
400
- ```bash
401
- project-shield scan ./my-project
402
- ```
403
-
404
- ### Fix-it 가이드 포함
405
-
406
- ```bash
407
- # Free: 상위 3개 (요약만)
408
- project-shield scan ./my-project --fix
409
-
410
- # Pro: 전체 가이드 + 코드 예제 + 참조
411
- project-shield scan ./my-project --fix
412
- ```
413
-
414
- ### Evidence Pack (Pro 전용 — JSON + PDF)
415
-
416
- ```bash
417
- project-shield scan ./my-project --evidence ./report
418
- # 생성: report.json + report.pdf
419
- ```
420
-
421
- ### 뱃지 생성
422
-
423
- ```bash
424
- project-shield scan ./my-project --badge shield-badge.svg
425
- ```
426
-
427
- ---
428
-
429
- ## Free vs Pro
430
-
431
- | 기능 | Free | Pro |
432
- |------|------|-----|
433
- | 월간 스캔 | 5회 | 50회 |
434
- | 시크릿 / MCP / 인젝션 상세 | 전체 표시 | 전체 표시 |
435
- | PII 상세 | 건수만 표시 | 파일:라인 상세 |
436
- | Fix-it 가이드 | 상위 3개, 요약만 | 전체, 코드 + 참조 포함 |
437
- | 뱃지 | 워터마크 | 클린 + UUID + 검증 URL |
438
- | Evidence Pack | 차단 | JSON + PDF 생성 |
439
- | Seal UUID | 미포함 | 포함 |
440
-
441
- ### 라이선스 관리
442
-
443
- ```bash
444
- # 현재 상태 확인
445
- project-shield status
446
-
447
- # Pro 라이선스 활성화
448
- project-shield activate PSH-XXXX-XXXX-XXXX-XXXX
449
-
450
- # 라이선스 비활성화
451
- project-shield deactivate
452
- ```
453
-
454
- **라이선스 검증**: 서버 검증 후 7일간 로컬 캐시. 서버 불통 시 3일 유예 기간. 유예 이후 Free로 자동 다운그레이드.
455
-
456
- ---
457
-
458
- ## 탐지 항목
459
-
460
- ### F001: 시크릿(Secret) 탐지
461
-
462
- 3중 탐지: 정규식 매칭 + 섀넌 엔트로피 + 컨텍스트 분석 (변수명, `.env` 파일 등)
463
-
464
- 10종 패턴: AWS, Stripe, OpenAI, GitHub PAT/OAuth, Slack, Google, Private Key
465
-
466
- ### F002: MCP 설정 점검
467
-
468
- 5항목 점검: 인증(auth), 시크릿(secrets), 툴(tools), 권한(permissions), 로깅(logging)
469
-
470
- ### F003: 프롬프트 인젝션 탐지
471
-
472
- 2중 탐지: 키워드 매칭 (11종 패턴) + 구조 분석 (HTML 주석, zero-width 유니코드, 툴 설명 길이)
473
-
474
- Base64/URL 인코딩된 우회 시도 감지 시 **자동 critical**
475
-
476
- ### F004: PII 탐지
477
-
478
- 주민등록번호 (체크섬 검증), 전화번호, 사업자등록번호, 여권번호, 이메일, US SSN, 신용카드 (Luhn 검증)
479
-
480
- ### F005: 스코어
481
-
482
- 0-100점 방식, A-F 등급. **Critical 발견이 1개라도 있으면 자동 F + 뱃지 잠금.**
483
-
484
- ### F006: Fix-it 가이드
485
-
486
- 10종 맞춤형 가이드: AWS 키 로테이션, Stripe 키 로테이션, Private Key 제거, RRN 마스킹, 신용카드 제거, MCP 설정 수정 3종, 프롬프트 인젝션 제거
487
-
488
- ### F007: Evidence Pack
489
-
490
- JSON + PDF. 점수, 등급, 발견, 수정 가이드, 무결성 해시, 면책조항 포함.
491
-
492
- ---
493
-
494
- ## 라인 무시 (shield-ignore)
495
-
496
- ```javascript
497
- const key = "sk_test_abc"; // shield-ignore
498
- ```
499
-
500
- `.shieldignore` 파일:
501
- ```
502
- tests/fixtures/
503
- *.test.ts
504
- ```
505
-
506
- ---
507
-
508
- ## 무결성
509
-
510
- - 룰셋은 매 로드마다 SHA-256 검증. 변조된 룰셋 = 스캔 거부.
511
- - 스캔 결과는 해시 봉인. 동일 입력 = 동일 해시.
512
- - Fail-safe: 스캔 중 크래시 = `SCAN_FAILED` (거짓 통과 없음).
513
-
514
- ---
515
-
516
- ## 라이선스
517
-
518
- MIT
1
+ # Project Shield
2
+
3
+ **Security scanner for AI coders and MCP users.**
4
+
5
+ Detects leaked API keys, PII, insecure MCP configs, and prompt injection — in one command.
6
+
7
+ [![npm version](https://img.shields.io/npm/v/project-shield)](https://www.npmjs.com/package/project-shield)
8
+ [![license](https://img.shields.io/npm/l/project-shield)](LICENSE)
9
+
10
+ ```bash
11
+ npx project-shield scan ./my-project
12
+ ```
13
+
14
+ ```
15
+ Tier: Free (0/5 scans)
16
+
17
+ Project Shield v1.0.0
18
+ Ruleset: v1.0.0 (SHA-256: f408a4fd...)
19
+ Scanning: 47 files (3 excluded)
20
+
21
+ ━━━ Secrets ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
22
+ CRITICAL src/config.ts:12
23
+ AWS Access Key detected (AKIA****)
24
+ Layers: regex ✓ entropy ✓ context ✓
25
+
26
+ ━━━ PII ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
27
+ CONFIRMED data/users.csv:5
28
+ Korean Resident Registration Number detected (900*****)
29
+ Layers: regex ✓ checksum ✓
30
+
31
+ ━━━ MCP Config ━━━━━━━━━━━━━━━━━━━━━━━━━━━
32
+ CRITICAL mcp.json (3/5 failed)
33
+ ✗ Auth: No authentication configured
34
+ ✗ Secrets: Hardcoded API key found
35
+ ✓ Tool Meta: OK
36
+ ✗ Permissions: Root filesystem access
37
+ ✓ Logging: OK
38
+
39
+ ━━━ Injection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
40
+ CRITICAL prompts/system.txt:3
41
+ Hidden injection in comment [structural]
42
+ Pattern: inj_ignore_prev | Layers: keyword ✓ structure ✓
43
+
44
+ ━━━ Score ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
45
+ Grade: F (0/100) — Locked
46
+ Badge generation LOCKED — Fix all critical findings first.
47
+ ```
48
+
49
+ ---
50
+
51
+ ## Why Project Shield?
52
+
53
+ | Problem | Project Shield |
54
+ |---------|---------------|
55
+ | API key leaked in commit | 3-layer detection (regex + entropy + context) |
56
+ | PII in test data | Korean RRN checksum validation, credit card Luhn check |
57
+ | MCP config wide open | 5-point check (auth, secrets, tools, permissions, logging) |
58
+ | Prompt injection in tool descriptions | 2-layer detection (keyword + structural analysis) |
59
+ | "What do I fix first?" | Fix-it guides with code examples |
60
+ | Compliance evidence needed | PDF + JSON evidence pack |
61
+
62
+ ---
63
+
64
+ ## Install
65
+
66
+ ```bash
67
+ # Global
68
+ npm install -g project-shield
69
+
70
+ # npx (no install)
71
+ npx project-shield scan ./my-project
72
+
73
+ # Dev dependency
74
+ npm install -D project-shield
75
+ ```
76
+
77
+ ---
78
+
79
+ ## Usage
80
+
81
+ ### Basic scan
82
+
83
+ ```bash
84
+ project-shield scan ./my-project
85
+ ```
86
+
87
+ ### JSON output
88
+
89
+ ```bash
90
+ project-shield scan ./my-project --format json
91
+ ```
92
+
93
+ ### Fix-it guides
94
+
95
+ ```bash
96
+ # Free: top 3 guides (summary only)
97
+ project-shield scan ./my-project --fix
98
+
99
+ # Pro: all guides with code examples + references
100
+ project-shield scan ./my-project --fix
101
+ ```
102
+
103
+ ### Evidence pack (Pro — JSON + PDF)
104
+
105
+ ```bash
106
+ project-shield scan ./my-project --evidence ./report
107
+ # Creates: report.json + report.pdf
108
+ ```
109
+
110
+ ### Badge generation
111
+
112
+ ```bash
113
+ # Free badge (with watermark)
114
+ project-shield scan ./my-project --badge shield-badge.svg
115
+
116
+ # Pro badge (no watermark, with UUID + verify URL)
117
+ project-shield scan ./my-project --badge shield-badge.svg
118
+ ```
119
+
120
+ ### Custom ignore
121
+
122
+ ```bash
123
+ project-shield scan ./my-project --ignore .shieldignore
124
+ ```
125
+
126
+ ### All options
127
+
128
+ ```
129
+ project-shield scan <path>
130
+ -f, --format <format> Output format: terminal | json (default: terminal)
131
+ -i, --ignore <path> Path to .shieldignore file
132
+ -r, --ruleset <path> Path to custom ruleset JSON
133
+ -b, --badge <path> Output path for SVG badge
134
+ --fix Show fix-it remediation guides
135
+ --evidence <path> Output path for evidence pack (JSON + PDF)
136
+ ```
137
+
138
+ ---
139
+
140
+ ## Free vs Pro
141
+
142
+ | Feature | Free | Pro |
143
+ |---------|------|-----|
144
+ | Scans per month | 5 | 50 |
145
+ | Secrets / MCP / Injection details | Full | Full |
146
+ | PII details | Count only | File:line details |
147
+ | Fix-it guides | Top 3, summary | All, with code + references |
148
+ | Badge | Watermark | Clean + UUID + verify URL |
149
+ | Evidence Pack | Blocked | JSON + PDF |
150
+ | Seal UUID | No | Yes |
151
+
152
+ ### License Management
153
+
154
+ ```bash
155
+ # Check current status
156
+ project-shield status
157
+
158
+ # Activate Pro license
159
+ project-shield activate PSH-XXXX-XXXX-XXXX-XXXX
160
+
161
+ # Deactivate license
162
+ project-shield deactivate
163
+ ```
164
+
165
+ **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.
166
+
167
+ ---
168
+
169
+ ## What It Detects
170
+
171
+ ### F001: Secrets (3-layer detection)
172
+
173
+ | Layer | Method | Example |
174
+ |-------|--------|---------|
175
+ | Regex | Pattern matching | `AKIA...`, `sk_live_...`, `ghp_...` |
176
+ | Entropy | Shannon entropy > 4.5 | High-randomness strings in secret context |
177
+ | Context | Variable name analysis | `API_KEY=`, `secret:`, `.env` files |
178
+
179
+ **10 built-in patterns**: AWS, Stripe, OpenAI, GitHub PAT/OAuth, Slack, Google, Private Keys + high-entropy catch-all.
180
+
181
+ **Severity rules**:
182
+ - 2+ layers hit = **critical**
183
+ - 1 layer hit = **warning**
184
+ - Pattern override (e.g., `sk_live_` always critical)
185
+
186
+ ### F002: MCP Config (5-point check)
187
+
188
+ | Check | What | Critical When |
189
+ |-------|------|---------------|
190
+ | Auth | Authentication configured? | No auth field found |
191
+ | Secrets | Hardcoded keys in config? | Literal API key (not `${ENV_VAR}`) |
192
+ | Tool Meta | Dangerous tool keywords? | `exec`, `eval`, `shell`, `rm` in tools |
193
+ | Permissions | Overly broad access? | Root `/`, wildcard `*`, `--privileged` |
194
+ | Logging | Audit logging enabled? | No logging/audit field |
195
+
196
+ ### F003: Prompt Injection (2-layer detection)
197
+
198
+ | Layer | Method | Example |
199
+ |-------|--------|---------|
200
+ | Keyword | 11 patterns (6 direct + 5 indirect) | "ignore previous instructions", "secretly" |
201
+ | Structure | Comment hiding, zero-width chars, tool length | `<!-- inject -->`, `\u200B` |
202
+
203
+ **Cross-judgment**:
204
+ - Keyword + Structure = **critical**
205
+ - Keyword only = **warning**
206
+ - Structure only (with hidden keyword) = **critical**
207
+ - Encoded bypass (Base64/URL) = **automatic critical**
208
+
209
+ ### F004: PII (2-layer detection)
210
+
211
+ | Pattern | Locale | Checksum |
212
+ |---------|--------|----------|
213
+ | Korean RRN (주민등록번호) | KR | Yes |
214
+ | Korean Phone | KR | No |
215
+ | Korean Business Number | KR | Yes |
216
+ | Korean Passport | KR | No |
217
+ | Email | Global | No |
218
+ | US SSN | Global | No |
219
+ | Credit Card | Global | Luhn |
220
+
221
+ ### F005: Scoring (0-100)
222
+
223
+ | Grade | Score | Status |
224
+ |-------|-------|--------|
225
+ | A | 90-100 | Excellent |
226
+ | B | 75-89 | Good |
227
+ | C | 60-74 | Pass |
228
+ | D | 40-59 | Warning |
229
+ | E | 20-39 | Warning |
230
+ | F | 0-19 | Locked |
231
+
232
+ **Any critical finding = automatic F + badge locked.**
233
+
234
+ Deductions: critical -25, warning -10, possible -5, info -2.
235
+
236
+ ---
237
+
238
+ ## Inline Suppression
239
+
240
+ Add `shield-ignore` to suppress a specific line:
241
+
242
+ ```javascript
243
+ const API_KEY = "sk_test_abc123"; // shield-ignore
244
+ ```
245
+
246
+ ```python
247
+ API_KEY = "sk_test_abc123" # shield-ignore
248
+ ```
249
+
250
+ Or use `.shieldignore` (gitignore syntax):
251
+
252
+ ```
253
+ # .shieldignore
254
+ tests/fixtures/
255
+ *.test.ts
256
+ docs/examples/
257
+ ```
258
+
259
+ ---
260
+
261
+ ## Evidence Pack
262
+
263
+ The `--evidence` flag generates a compliance-ready report (Pro only):
264
+
265
+ **JSON** (`report.json`):
266
+ - Full findings (secrets, PII, MCP, injection)
267
+ - Score + lock status
268
+ - Fix-it summary
269
+ - Integrity hashes (result SHA-256 + ruleset SHA-256)
270
+ - Disclaimer
271
+
272
+ **PDF** (`report.pdf`):
273
+ - Cover page with grade
274
+ - Executive summary
275
+ - Findings detail by category
276
+ - Integrity verification
277
+ - Disclaimer
278
+
279
+ ---
280
+
281
+ ## CI Integration
282
+
283
+ ```yaml
284
+ # GitHub Actions
285
+ - name: Security Scan
286
+ run: npx project-shield scan . --format json
287
+ # Exit code 1 if any critical finding
288
+ ```
289
+
290
+ ```yaml
291
+ # With badge
292
+ - name: Security Scan + Badge
293
+ run: |
294
+ npx project-shield scan . --badge shield-badge.svg
295
+ # Commit badge to repo
296
+ ```
297
+
298
+ ---
299
+
300
+ ## Architecture
301
+
302
+ ```
303
+ src/
304
+ index.ts CLI entry (commander)
305
+ types/index.ts All TypeScript interfaces
306
+ scanner/
307
+ engine.ts Scan orchestrator (glob, binary skip, ignore)
308
+ secrets.ts 3-layer secret detection
309
+ pii.ts 2-layer PII detection
310
+ mcp.ts 5-point MCP config check
311
+ injection.ts 2-layer injection detection
312
+ ignore.ts shield-ignore + .shieldignore
313
+ scoring/
314
+ score.ts 0-100 scoring + A-F grading
315
+ lock.ts Badge lock logic
316
+ integrity/
317
+ ruleset.ts Ruleset loader + SHA-256 verification
318
+ failsafe.ts Crash = fail, no ruleset = reject
319
+ seal.ts Result hash sealing (SHA-256 + UUID)
320
+ output/
321
+ terminal.ts Terminal + JSON formatter
322
+ badge.ts SVG badge generator (shields.io style)
323
+ fixit.ts 10-type fix-it guide system
324
+ evidence.ts Evidence pack (JSON + PDF)
325
+ license/
326
+ types.ts License type definitions
327
+ storage.ts Local file I/O (~/.project-shield/)
328
+ http.ts HTTPS request wrapper
329
+ validator.ts Key validation + 7-day cache + 3-day grace
330
+ usage.ts Scan usage tracking (monthly)
331
+ gate.ts Feature gating (Free/Pro)
332
+ commands.ts activate / deactivate / status
333
+ rules/
334
+ v1.0.0.json Ruleset (secrets + PII + MCP + injection patterns)
335
+ ```
336
+
337
+ ---
338
+
339
+ ## Integrity
340
+
341
+ - Ruleset is SHA-256 verified on every load. Tampered ruleset = scan rejected.
342
+ - Scan results are hash-sealed. Same input = same hash.
343
+ - Fail-safe: crash during scan = `SCAN_FAILED` (never false PASS).
344
+
345
+ ---
346
+
347
+ ## License
348
+
349
+ MIT
350
+
351
+ ---
352
+
353
+ <p align="center">
354
+ <sub>Built for developers who ship AI-powered apps and want to sleep at night.</sub>
355
+ </p>
356
+
357
+ ---
358
+
359
+ # Project Shield (한국어)
360
+
361
+ **AI 코더/MCP 사용자를 위한 보안 스캐너 CLI.**
362
+
363
+ API 키 유출, 개인정보, MCP 설정 보안 취약점, 프롬프트 인젝션을 한 번에 탐지합니다.
364
+
365
+ ```bash
366
+ npx project-shield scan ./my-project
367
+ ```
368
+
369
+ ---
370
+
371
+ ## 왜 Project Shield?
372
+
373
+ | 문제 | Project Shield |
374
+ |------|---------------|
375
+ | 커밋에서 API 키 유출 | 3중 탐지 (정규식 + 엔트로피 + 컨텍스트) |
376
+ | 테스트 데이터에서 개인정보 노출 | 주민등록번호 체크섬 검증, 신용카드 Luhn 검증 |
377
+ | MCP 설정 보안 허점 | 5항목 점검 (인증, 시크릿, 툴, 권한, 로깅) |
378
+ | 툴 설명에 숨겨진 프롬프트 인젝션 | 2중 탐지 (키워드 + 구조 분석) |
379
+ | "뭐부터 고쳐야 하지?" | Fix-it 가이드 (코드 예제 포함) |
380
+ | 컴플라이언스 증빙 필요 | PDF + JSON Evidence Pack |
381
+
382
+ ---
383
+
384
+ ## 설치
385
+
386
+ ```bash
387
+ # 글로벌
388
+ npm install -g project-shield
389
+
390
+ # npx (설치 없이)
391
+ npx project-shield scan ./my-project
392
+ ```
393
+
394
+ ---
395
+
396
+ ## 사용법
397
+
398
+ ### 기본 스캔
399
+
400
+ ```bash
401
+ project-shield scan ./my-project
402
+ ```
403
+
404
+ ### Fix-it 가이드 포함
405
+
406
+ ```bash
407
+ # Free: 상위 3개 (요약만)
408
+ project-shield scan ./my-project --fix
409
+
410
+ # Pro: 전체 가이드 + 코드 예제 + 참조
411
+ project-shield scan ./my-project --fix
412
+ ```
413
+
414
+ ### Evidence Pack (Pro 전용 — JSON + PDF)
415
+
416
+ ```bash
417
+ project-shield scan ./my-project --evidence ./report
418
+ # 생성: report.json + report.pdf
419
+ ```
420
+
421
+ ### 뱃지 생성
422
+
423
+ ```bash
424
+ project-shield scan ./my-project --badge shield-badge.svg
425
+ ```
426
+
427
+ ---
428
+
429
+ ## Free vs Pro
430
+
431
+ | 기능 | Free | Pro |
432
+ |------|------|-----|
433
+ | 월간 스캔 | 5회 | 50회 |
434
+ | 시크릿 / MCP / 인젝션 상세 | 전체 표시 | 전체 표시 |
435
+ | PII 상세 | 건수만 표시 | 파일:라인 상세 |
436
+ | Fix-it 가이드 | 상위 3개, 요약만 | 전체, 코드 + 참조 포함 |
437
+ | 뱃지 | 워터마크 | 클린 + UUID + 검증 URL |
438
+ | Evidence Pack | 차단 | JSON + PDF 생성 |
439
+ | Seal UUID | 미포함 | 포함 |
440
+
441
+ ### 라이선스 관리
442
+
443
+ ```bash
444
+ # 현재 상태 확인
445
+ project-shield status
446
+
447
+ # Pro 라이선스 활성화
448
+ project-shield activate PSH-XXXX-XXXX-XXXX-XXXX
449
+
450
+ # 라이선스 비활성화
451
+ project-shield deactivate
452
+ ```
453
+
454
+ **라이선스 검증**: 서버 검증 후 7일간 로컬 캐시. 서버 불통 시 3일 유예 기간. 유예 이후 Free로 자동 다운그레이드.
455
+
456
+ ---
457
+
458
+ ## 탐지 항목
459
+
460
+ ### F001: 시크릿(Secret) 탐지
461
+
462
+ 3중 탐지: 정규식 매칭 + 섀넌 엔트로피 + 컨텍스트 분석 (변수명, `.env` 파일 등)
463
+
464
+ 10종 패턴: AWS, Stripe, OpenAI, GitHub PAT/OAuth, Slack, Google, Private Key
465
+
466
+ ### F002: MCP 설정 점검
467
+
468
+ 5항목 점검: 인증(auth), 시크릿(secrets), 툴(tools), 권한(permissions), 로깅(logging)
469
+
470
+ ### F003: 프롬프트 인젝션 탐지
471
+
472
+ 2중 탐지: 키워드 매칭 (11종 패턴) + 구조 분석 (HTML 주석, zero-width 유니코드, 툴 설명 길이)
473
+
474
+ Base64/URL 인코딩된 우회 시도 감지 시 **자동 critical**
475
+
476
+ ### F004: PII 탐지
477
+
478
+ 주민등록번호 (체크섬 검증), 전화번호, 사업자등록번호, 여권번호, 이메일, US SSN, 신용카드 (Luhn 검증)
479
+
480
+ ### F005: 스코어
481
+
482
+ 0-100점 방식, A-F 등급. **Critical 발견이 1개라도 있으면 자동 F + 뱃지 잠금.**
483
+
484
+ ### F006: Fix-it 가이드
485
+
486
+ 10종 맞춤형 가이드: AWS 키 로테이션, Stripe 키 로테이션, Private Key 제거, RRN 마스킹, 신용카드 제거, MCP 설정 수정 3종, 프롬프트 인젝션 제거
487
+
488
+ ### F007: Evidence Pack
489
+
490
+ JSON + PDF. 점수, 등급, 발견, 수정 가이드, 무결성 해시, 면책조항 포함.
491
+
492
+ ---
493
+
494
+ ## 라인 무시 (shield-ignore)
495
+
496
+ ```javascript
497
+ const key = "sk_test_abc"; // shield-ignore
498
+ ```
499
+
500
+ `.shieldignore` 파일:
501
+ ```
502
+ tests/fixtures/
503
+ *.test.ts
504
+ ```
505
+
506
+ ---
507
+
508
+ ## 무결성
509
+
510
+ - 룰셋은 매 로드마다 SHA-256 검증. 변조된 룰셋 = 스캔 거부.
511
+ - 스캔 결과는 해시 봉인. 동일 입력 = 동일 해시.
512
+ - Fail-safe: 스캔 중 크래시 = `SCAN_FAILED` (거짓 통과 없음).
513
+
514
+ ---
515
+
516
+ ## 라이선스
517
+
518
+ MIT