project-shield 1.1.5 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShovelMaker91
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,11 +2,23 @@
 
 **Security scanner for AI coders and MCP users.**
 
-Detects leaked API keys, PII, insecure MCP configs, and prompt injection — in one command.
+Detects leaked API keys, PII, insecure MCP configs, and prompt injection. Audits your Claude Code environment for misconfigurations and malicious hooks.
 
 [![npm version](https://img.shields.io/npm/v/project-shield)](https://www.npmjs.com/package/project-shield)
 [![license](https://img.shields.io/npm/l/project-shield)](LICENSE)
 
+### 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
+
 ```bash
 npx project-shield scan ./my-project
 ```
@@ -14,7 +26,7 @@ npx project-shield scan ./my-project
 ```
 Tier: Free (0/5 scans)
 
-Project Shield v1.0.0
+Project Shield v2.0.0
 Ruleset: v1.0.0 (SHA-256: f408a4fd...)
 Scanning: 47 files (3 excluded)
 
@@ -46,6 +58,43 @@ Scanning: 47 files (3 excluded)
   Badge generation LOCKED — Fix all critical findings first.
 ```
 
+### Audit Demo
+
+```bash
+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?
@@ -123,6 +172,22 @@ project-shield scan ./my-project --badge shield-badge.svg
 project-shield scan ./my-project --ignore .shieldignore
 ```
 
+### Audit (v2.0)
+
+```bash
+# 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
 
 ```
@@ -133,6 +198,11 @@ project-shield scan <path>
   -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)
 ```
 
 ---
@@ -142,6 +212,10 @@ project-shield scan <path>
 | 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 |
@@ -233,6 +307,40 @@ project-shield deactivate
 
 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
@@ -303,6 +411,7 @@ The `--evidence` flag generates a compliance-ready report (Pro only):
 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
@@ -310,6 +419,14 @@ src/
     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
@@ -322,12 +439,19 @@ src/
     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 usage tracking (monthly)
+    usage.ts            Scan + audit usage tracking (monthly)
     gate.ts             Feature gating (Free/Pro)
     commands.ts         activate / deactivate / status
 rules/
@@ -360,7 +484,19 @@ MIT
 
 **AI 코더/MCP 사용자를 위한 보안 스캐너 CLI.**
 
-API 키 유출, 개인정보, MCP 설정 보안 취약점, 프롬프트 인젝션을 한 번에 탐지합니다.
+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 즉시 연동
 
 ```bash
 npx project-shield scan ./my-project
@@ -424,6 +560,22 @@ project-shield scan ./my-project --evidence ./report
 project-shield scan ./my-project --badge shield-badge.svg
 ```
 
+### 환경 감사 (v2.0)
+
+```bash
+# 기본 환경 감사
+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
@@ -431,6 +583,10 @@ project-shield scan ./my-project --badge shield-badge.svg
 | 기능 | Free | Pro |
 |------|------|-----|
 | 월간 스캔 | 5회 | 50회 |
+| 월간 감사 | 3회 | 20회 |
+| 환경 검사 (F008) | Critical 3개만 | 전체 9개 |
+| 훅 분석 (F009) | — | 전체 7개 |
+| 감사 Evidence | — | JSON Evidence Pack |
 | 시크릿 / MCP / 인젝션 상세 | 전체 표시 | 전체 표시 |
 | PII 상세 | 건수만 표시 | 파일:라인 상세 |
 | Fix-it 가이드 | 상위 3개, 요약만 | 전체, 코드 + 참조 포함 |
@@ -489,6 +645,40 @@ Base64/URL 인코딩된 우회 시도 감지 시 **자동 critical**
 
 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)

package/dist/auditor/checks/environment.d.ts

@@ -0,0 +1,7 @@
+import type { AuditFinding } from '../../types/audit.js';
+import type { ToolSettings, EnvFileInfo, InstructionFileInfo } from '../providers/types.js';
+/**
+ * Run all F008 environment checks and return findings.
+ */
+export declare function checkEnvironment(settings: ToolSettings[], envFiles: EnvFileInfo[], instructionFiles: InstructionFileInfo[], projectDir: string): AuditFinding[];
+//# sourceMappingURL=environment.d.ts.map

package/dist/auditor/checks/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../src/auditor/checks/environment.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AA6C5F;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,QAAQ,EAAE,WAAW,EAAE,EACvB,gBAAgB,EAAE,mBAAmB,EAAE,EACvC,UAAU,EAAE,MAAM,GACjB,YAAY,EAAE,CAchB"}