claude-code-templates 1.22.0 → 1.22.2

package/src/validation/ARCHITECTURE.md

@@ -0,0 +1,309 @@
+# Security Audit System Architecture
+
+## Overview
+This document outlines the security validation system for Claude Code Templates components (agents, commands, MCPs, settings, hooks).
+
+## Industry Standards Reference
+
+### Implemented Standards
+- **NPM 2025**: SHA256 hashing, provenance metadata, trusted publishing principles
+- **SLSA Framework**: Level 2 compliance (build integrity, tamper resistance)
+- **PyPI Security**: Content validation, typo-squatting detection
+- **GitHub Security**: Secret scanning patterns, malicious pattern detection
+
+## System Architecture
+
+```
+cli-tool/src/validation/
+├── validators/
+│   ├── StructuralValidator.js      # Frontmatter, size, encoding
+│   ├── SemanticValidator.js        # Prompt injection, jailbreaks
+│   ├── ReferenceValidator.js       # URLs, HTML, Safe Browsing
+│   ├── IntegrityValidator.js       # SHA256, version tracking
+│   └── ProvenanceValidator.js      # Author, repo, commit metadata
+├── ValidationOrchestrator.js       # Coordinates all validators
+├── security-audit.js               # CLI command implementation
+└── ARCHITECTURE.md                 # This file
+
+.github/workflows/
+└── component-validation.yml        # PR validation workflow
+```
+
+## Validation Tiers
+
+### Tier 1: Structural Validation (CRITICAL)
+**Validators**: `StructuralValidator.js`
+- ✅ YAML frontmatter validation (name, description, tools, model)
+- ✅ File size limits (max 100KB for agents/commands)
+- ✅ UTF-8 encoding validation
+- ✅ Section count limits (prevent context overflow)
+- ✅ Required fields presence check
+
+**Error Codes**: `STRUCT_*`
+
+### Tier 2: Semantic Validation (HIGH PRIORITY)
+**Validators**: `SemanticValidator.js`
+- ✅ Prompt injection detection
+- ✅ Jailbreak pattern detection
+- ✅ Instruction override attempts
+- ✅ Self-modification requests
+- ✅ Credential harvesting patterns
+
+**Patterns to Detect**:
+```javascript
+const DANGEROUS_PATTERNS = [
+  /ignore\s+(previous|all)\s+instructions?/i,
+  /system\s+prompt|developer\s+instructions?/i,
+  /you\s+are\s+now\s+(a|an)\s+/i,
+  /execute\s+the\s+following\s+(code|command)/i,
+  /fetch.*?(token|key|password|credential)/i,
+  /open\s+a?\s?shell/i,
+  /<script|<iframe|javascript:/i
+];
+```
+
+**Error Codes**: `SEM_*`
+
+### Tier 3: Reference Validation (MEDIUM PRIORITY)
+**Validators**: `ReferenceValidator.js`
+- ✅ URL validation (HTTPS only)
+- ✅ Private IP blocking (127.0.0.1, 10.0.0.0/8, 192.168.0.0/16)
+- ✅ file:// protocol blocking
+- ✅ HTML tag sanitization
+- ✅ Google Safe Browsing API integration (optional)
+
+**Error Codes**: `REF_*`
+
+### Tier 4: Integrity (HIGH PRIORITY)
+**Validators**: `IntegrityValidator.js`
+- ✅ SHA256 hash generation
+- ✅ Hash verification on install
+- ✅ Version tracking
+- ✅ Signature validation (future)
+
+**Error Codes**: `INT_*`
+
+### Tier 5: Provenance (MEDIUM PRIORITY)
+**Validators**: `ProvenanceValidator.js`
+- ✅ Author metadata extraction
+- ✅ Source repository tracking
+- ✅ Git commit SHA tracking
+- ✅ Timestamp tracking
+- ⏳ Digital signatures (future)
+
+**Error Codes**: `PROV_*`
+
+## CLI Usage
+
+### Command: `--security-audit`
+
+```bash
+# Validate all components in the repository
+npx create-claude-config --security-audit
+
+# Validate specific component type
+npx create-claude-config --security-audit --agent frontend-developer
+
+# Validate specific file
+npx create-claude-config --security-audit --file ./components/agents/frontend-developer.md
+
+# Validate with verbose output
+npx create-claude-config --security-audit --verbose
+
+# Generate security report (JSON)
+npx create-claude-config --security-audit --output report.json
+
+# Validate in CI/CD mode (exit 1 on errors)
+npx create-claude-config --security-audit --ci
+```
+
+### Output Format
+
+```
+🔒 Security Audit Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📁 Scanning: cli-tool/components/agents/
+
+✅ frontend-developer.md
+   ├─ Structural: PASS
+   ├─ Semantic: PASS
+   ├─ References: PASS
+   ├─ Integrity: PASS (sha256: a3f2...)
+   └─ Provenance: PASS (author: claude-code-templates)
+
+⚠️  backend-api-specialist.md
+   ├─ Structural: PASS
+   ├─ Semantic: WARNING (SEM_W001: Potential instruction override)
+   ├─ References: PASS
+   ├─ Integrity: PASS (sha256: b4e1...)
+   └─ Provenance: PASS
+
+❌ malicious-agent.md
+   ├─ Structural: PASS
+   ├─ Semantic: FAIL (SEM_E001: Jailbreak pattern detected)
+   ├─ References: FAIL (REF_E001: file:// protocol detected)
+   └─ Integrity: PASS (sha256: c5d2...)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary:
+  Total: 3 components
+  ✅ Passed: 1
+  ⚠️  Warnings: 1
+  ❌ Failed: 1
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## GitHub Actions Integration
+
+### Workflow: `.github/workflows/component-validation.yml`
+
+```yaml
+name: Component Security Validation
+
+on:
+  pull_request:
+    paths:
+      - 'cli-tool/components/**/*.md'
+  push:
+    branches:
+      - main
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: |
+          cd cli-tool
+          npm install
+
+      - name: Run Security Audit
+        run: |
+          cd cli-tool
+          npm run security-audit -- --ci --verbose
+
+      - name: Upload Security Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-audit-report
+          path: cli-tool/security-report.json
+```
+
+### PR Checks
+- ✅ All validators must pass
+- ⚠️  Warnings are allowed but reported
+- ❌ Any errors block the PR
+
+## Component Metadata Schema
+
+### Enhanced components.json
+```json
+{
+  "agents": [
+    {
+      "name": "frontend-developer",
+      "path": "agents/development-team/frontend-developer.md",
+      "description": "...",
+      "security": {
+        "validated": true,
+        "validatedAt": "2025-10-15T15:30:00Z",
+        "hash": "sha256:a3f2e1d4...",
+        "version": "1.0.0",
+        "provenance": {
+          "author": "claude-code-templates",
+          "repository": "https://github.com/danimesq/claude-code-templates",
+          "commit": "43dd5f9",
+          "verifiedAuthor": false
+        },
+        "audit": {
+          "structural": { "passed": true, "score": 100 },
+          "semantic": { "passed": true, "score": 100 },
+          "references": { "passed": true, "score": 100 },
+          "integrity": { "passed": true, "score": 100 },
+          "provenance": { "passed": true, "score": 95 }
+        }
+      }
+    }
+  ]
+}
+```
+
+## Error Code Reference
+
+### Structural (STRUCT_*)
+- `STRUCT_E001`: Missing required frontmatter
+- `STRUCT_E002`: Invalid YAML syntax
+- `STRUCT_E003`: File size exceeds limit
+- `STRUCT_E004`: Invalid UTF-8 encoding
+- `STRUCT_W001`: Missing optional field
+
+### Semantic (SEM_*)
+- `SEM_E001`: Jailbreak pattern detected
+- `SEM_E002`: Prompt injection detected
+- `SEM_E003`: Instruction override attempt
+- `SEM_E004`: Self-modification request
+- `SEM_E005`: Credential harvesting pattern
+- `SEM_W001`: Suspicious instruction wording
+
+### References (REF_*)
+- `REF_E001`: Insecure protocol (file://, http://)
+- `REF_E002`: Private IP address detected
+- `REF_E003`: Malicious URL (Safe Browsing)
+- `REF_E004`: Dangerous HTML tag
+- `REF_W001`: Missing HTTPS
+
+### Integrity (INT_*)
+- `INT_E001`: Hash mismatch
+- `INT_E002`: Missing version
+- `INT_E003`: Invalid signature
+- `INT_W001`: No signature provided
+
+### Provenance (PROV_*)
+- `PROV_E001`: Missing author
+- `PROV_E002`: Invalid repository URL
+- `PROV_W001`: Unverified author
+- `PROV_W002`: Missing commit SHA
+
+## Testing Strategy
+
+### Unit Tests
+```bash
+npm test -- --testPathPattern=validation
+```
+
+### Integration Tests
+```bash
+npm run test:integration -- validation
+```
+
+### Test Coverage
+- Target: 90%+ for validators
+- Mocking: GitHub API, Safe Browsing API
+- Fixtures: Malicious and benign component examples
+
+## Future Enhancements
+
+### Phase 2
+- [ ] LLM-based semantic analysis (lightweight model)
+- [ ] Community reporting system
+- [ ] Automated revocation mechanism
+- [ ] Digital signatures with PGP/GPG
+
+### Phase 3
+- [ ] Real-time validation API endpoint
+- [ ] Browser extension for component preview
+- [ ] Trust score system (0-100)
+- [ ] Historical vulnerability tracking
+
+## Security Contact
+For security concerns, please open an issue at:
+https://github.com/danimesq/claude-code-templates/security

package/src/validation/BaseValidator.js

@@ -0,0 +1,152 @@
+/**
+ * BaseValidator - Abstract base class for component validation
+ *
+ * Provides common validation infrastructure and result formatting
+ * All validators extend this class and implement the validate() method
+ */
+class BaseValidator {
+  constructor() {
+    this.errors = [];
+    this.warnings = [];
+    this.info = [];
+  }
+
+  /**
+   * Add an error to the validation results
+   * @param {string} code - Error code for identification (e.g., STRUCT_E001)
+   * @param {string} message - Human-readable error message
+   * @param {object} metadata - Additional context about the error
+   */
+  addError(code, message, metadata = {}) {
+    this.errors.push({
+      level: 'error',
+      code,
+      message,
+      metadata,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Add a warning to the validation results
+   * @param {string} code - Warning code for identification
+   * @param {string} message - Human-readable warning message
+   * @param {object} metadata - Additional context about the warning
+   */
+  addWarning(code, message, metadata = {}) {
+    this.warnings.push({
+      level: 'warning',
+      code,
+      message,
+      metadata,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Add an info message to the validation results
+   * @param {string} code - Info code for identification
+   * @param {string} message - Human-readable info message
+   * @param {object} metadata - Additional context
+   */
+  addInfo(code, message, metadata = {}) {
+    this.info.push({
+      level: 'info',
+      code,
+      message,
+      metadata,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  /**
+   * Check if validation passed (no errors)
+   * @returns {boolean}
+   */
+  isValid() {
+    return this.errors.length === 0;
+  }
+
+  /**
+   * Calculate validation score (0-100)
+   * Errors reduce score more than warnings
+   * @returns {number}
+   */
+  getScore() {
+    const errorPenalty = this.errors.length * 25;
+    const warningPenalty = this.warnings.length * 5;
+    return Math.max(0, 100 - errorPenalty - warningPenalty);
+  }
+
+  /**
+   * Get all validation results
+   * @returns {object}
+   */
+  getResults() {
+    return {
+      valid: this.isValid(),
+      score: this.getScore(),
+      errorCount: this.errors.length,
+      warningCount: this.warnings.length,
+      infoCount: this.info.length,
+      errors: this.errors,
+      warnings: this.warnings,
+      info: this.info
+    };
+  }
+
+  /**
+   * Reset validation state
+   */
+  reset() {
+    this.errors = [];
+    this.warnings = [];
+    this.info = [];
+  }
+
+  /**
+   * Calculate line number from character index in content
+   * @param {string} content - Full content
+   * @param {number} index - Character index
+   * @returns {object} Line information (line number, column, line text)
+   */
+  getLineFromIndex(content, index) {
+    // Count newlines before the index to get line number
+    const beforeIndex = content.substring(0, index);
+    const lineNumber = (beforeIndex.match(/\n/g) || []).length + 1;
+
+    // Find the start of the current line
+    const lineStart = beforeIndex.lastIndexOf('\n') + 1;
+
+    // Find the end of the current line
+    const afterIndex = content.substring(index);
+    const nextNewline = afterIndex.indexOf('\n');
+    const lineEnd = nextNewline === -1 ? content.length : index + nextNewline;
+
+    // Extract the full line text
+    const lineText = content.substring(lineStart, lineEnd);
+
+    // Calculate column (position in the line)
+    const column = index - lineStart + 1;
+
+    return {
+      line: lineNumber,
+      column: column,
+      lineText: lineText.trim(),
+      position: `${lineNumber}:${column}`
+    };
+  }
+
+  /**
+   * Abstract method - must be implemented by subclasses
+   * @param {object} component - Component to validate
+   * @param {object} options - Validation options
+   * @returns {Promise<object>} Validation results
+   * @throws {Error} If not implemented
+   */
+  async validate(component, options = {}) {
+    throw new Error('validate() must be implemented by subclass');
+  }
+}
+
+module.exports = BaseValidator;