musubix 3.4.1 → 3.4.3

package/docs/overview/MUSUBIX-Security-v2.1.md

@@ -1,668 +0,0 @@
-# MUSUBIX Security v2.1.0 - セキュリティ強化リリース
-
-**パッケージ名**: `@nahisaho/musubix-security`  
-**バージョン**: 2.1.0  
-**最終更新**: 2026-01-08
-
----
-
-## 1. 概要
-
-MUSUBIX v2.1.0は、**4つのEPIC**で**30タスク**を実装したセキュリティ強化リリースです。**3400+テスト**が全て合格しており、エンタープライズグレードのセキュリティ分析を提供します。
-
-### 1.1 v2.1.0 新機能サマリー
-
-| EPIC | 機能 | タスク数 | テスト数 |
-|------|------|---------|---------|
-| **EPIC-1** | テイント分析強化 | 8 | 200+ |
-| **EPIC-2** | CVEデータベース連携 | 7 | 150+ |
-| **EPIC-3** | OWASP/CWE Top 25 ルール | 6 | 700+ |
-| **EPIC-4** | 自動修正パイプライン | 9 | 200+ |
-
-### 1.2 アーキテクチャ
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Security Analysis Engine                  │
-├─────────────────────────────────────────────────────────────┤
-│  EPIC-1: Enhanced Taint Analysis                            │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
-│  │ 50+ Sources │──│ Propagation │──│ 40+ Sinks           │ │
-│  │ (HTTP,ENV)  │  │ (DFG/CFG)   │  │ (SQL,CMD,XSS)       │ │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
-├─────────────────────────────────────────────────────────────┤
-│  EPIC-2: CVE Database Integration                           │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
-│  │ NVD API 2.0 │──│ CVE Cache   │──│ Vuln Matching       │ │
-│  │ (Real-time) │  │ (SQLite)    │  │ (Semver/Regex)      │ │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
-├─────────────────────────────────────────────────────────────┤
-│  EPIC-3: OWASP/CWE Rules                                    │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
-│  │ OWASP Top10 │──│ CWE Top 25  │──│ Rule Engine         │ │
-│  │ (10 Rules)  │  │ (25 Rules)  │  │ (Registry/Config)   │ │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
-├─────────────────────────────────────────────────────────────┤
-│  EPIC-4: Auto-Fix Pipeline                                  │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
-│  │ Fix Gen     │──│ Validation  │──│ CI/CD Integration   │ │
-│  │ (Template)  │  │ (Sandbox)   │  │ (GitHub/GitLab)     │ │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 2. EPIC-1: テイント分析強化
-
-### 2.1 概要
-
-高度なテイント追跡システムにより、ユーザー入力から危険なシンクへのデータフローを正確に追跡します。
-
-### 2.2 ソース定義（50+）
-
-```typescript
-import {
-  ALL_BUILTIN_SOURCES,
-  SourceCategory,
-} from '@nahisaho/musubix-security';
-
-// カテゴリ別ソース
-const categories: SourceCategory[] = [
-  'user-input',    // req.body, req.query, req.params, document.getElementById
-  'network',       // fetch, axios.get, http.request
-  'environment',   // process.env, Deno.env
-  'file',          // fs.readFile, fs.readFileSync
-  'database',      // query result, findOne, findMany
-  'external-api',  // response.json(), response.text()
-];
-
-// 例: user-input ソース
-// req.body, req.query, req.params, req.headers
-// document.getElementById, document.querySelector
-// window.location, URLSearchParams
-```
-
-### 2.3 シンク定義（40+）
-
-```typescript
-import {
-  ALL_BUILTIN_SINKS,
-  SinkCategory,
-} from '@nahisaho/musubix-security';
-
-// カテゴリ別シンク
-const sinkCategories: SinkCategory[] = [
-  'sql-query',     // query(), execute(), raw()
-  'command-exec',  // exec(), spawn(), execSync()
-  'html-output',   // innerHTML, document.write()
-  'file-path',     // fs.readFile(), fs.writeFile()
-  'code-exec',     // eval(), Function(), vm.runInContext()
-  'redirect',      // res.redirect(), window.location
-];
-```
-
-### 2.4 サニタイザ定義（30+）
-
-```typescript
-import {
-  ALL_BUILTIN_SANITIZERS,
-  SanitizerMapping,
-} from '@nahisaho/musubix-security';
-
-// シンクタイプ別サニタイザ
-const sanitizers: SanitizerMapping = {
-  'sql-query': ['parameterizedQuery', 'escapeSQL', 'preparedStatement'],
-  'html-output': ['escapeHTML', 'sanitizeHTML', 'DOMPurify.sanitize'],
-  'command-exec': ['escapeShell', 'shellEscape'],
-  'file-path': ['path.normalize', 'path.resolve', 'validatePath'],
-  'redirect': ['validateURL', 'isAllowedDomain'],
-};
-```
-
-### 2.5 手続き間テイント伝播
-
-```typescript
-import {
-  CallGraphBuilder,
-  TaintPropagator,
-  InterproceduralAnalyzer,
-} from '@nahisaho/musubix-security';
-
-// コールグラフ構築
-const callGraph = new CallGraphBuilder();
-callGraph.buildFromProject('./src');
-
-// 手続き間テイント伝播
-const propagator = new TaintPropagator(callGraph);
-const taintFlows = propagator.analyze(code);
-
-// DFG統合解析
-const analyzer = new InterproceduralAnalyzer({
-  maxDepth: 10,
-  trackImplicitFlows: true,
-});
-const result = await analyzer.analyze(project);
-```
-
-### 2.6 使用例
-
-```typescript
-import { createEnhancedTaintAnalyzer } from '@nahisaho/musubix-security';
-
-const analyzer = createEnhancedTaintAnalyzer({
-  maxDepth: 10,
-  sources: ALL_BUILTIN_SOURCES,
-  sinks: ALL_BUILTIN_SINKS,
-  sanitizers: ALL_BUILTIN_SANITIZERS,
-});
-
-const result = await analyzer.analyze(`
-  const userInput = req.body.name;
-  const query = "SELECT * FROM users WHERE name = '" + userInput + "'";
-  db.query(query);  // 🚨 SQL Injection detected!
-`, 'app.ts');
-
-console.log(result.taintFlows);
-// [{
-//   source: { type: 'user-input', location: 'req.body.name' },
-//   sink: { type: 'sql-query', location: 'db.query()' },
-//   path: ['userInput', 'query', 'db.query'],
-//   sanitized: false
-// }]
-```
-
----
-
-## 3. EPIC-2: CVEデータベース連携
-
-### 3.1 概要
-
-NVD（National Vulnerability Database）API 2.0と連携し、リアルタイムでCVE情報を取得・照合します。
-
-### 3.2 NVDClient
-
-```typescript
-import { NVDClient, NVDConfig } from '@nahisaho/musubix-security';
-
-const client = new NVDClient({
-  apiKey: process.env.NVD_API_KEY,  // オプション（レートリミット緩和）
-  cacheEnabled: true,
-  cacheTTL: 86400,  // 24時間
-});
-
-// CVE検索
-const cves = await client.searchCVEs({
-  keywordSearch: 'lodash',
-  resultsPerPage: 20,
-});
-
-// 特定CVE取得
-const cve = await client.getCVE('CVE-2021-23337');
-console.log(cve.cvssV3Score);  // 7.2
-console.log(cve.description);
-```
-
-### 3.3 CVEマッチング
-
-```typescript
-import { CVEMatcher, DependencyScanner } from '@nahisaho/musubix-security';
-
-const matcher = new CVEMatcher(nvdClient);
-const scanner = new DependencyScanner();
-
-// package.json解析
-const deps = await scanner.scanPackageJson('./package.json');
-
-// CVEマッチング
-const matches = await matcher.matchDependencies(deps);
-
-for (const match of matches) {
-  console.log(`${match.package}@${match.version}`);
-  console.log(`  CVE: ${match.cve.id}`);
-  console.log(`  CVSS: ${match.cve.cvssV3Score}`);
-  console.log(`  Fix: ${match.fixedVersion || 'No fix available'}`);
-}
-```
-
-### 3.4 ローカルキャッシュ
-
-```typescript
-import { CVECache, CVEDatabase } from '@nahisaho/musubix-security';
-
-// SQLiteベースのローカルキャッシュ
-const cache = new CVECache({
-  dbPath: './.musubix/cve-cache.db',
-  ttl: 86400 * 7,  // 7日間
-});
-
-// バッチ更新
-await cache.updateFromNVD({
-  startDate: '2024-01-01',
-  modifiedSince: lastUpdateDate,
-});
-
-// ローカル検索（高速）
-const results = cache.search({
-  package: 'express',
-  versionRange: '>=4.0.0 <4.18.2',
-});
-```
-
----
-
-## 4. EPIC-3: OWASP/CWE Top 25 ルール
-
-### 4.1 概要
-
-OWASP Top 10（2021）とCWE Top 25（2023）に完全対応したルールエンジンを実装しました。
-
-### 4.2 OWASP Top 10 ルール
-
-```typescript
-import { OWASPRules } from '@nahisaho/musubix-security';
-
-// A01: Broken Access Control
-// A02: Cryptographic Failures  
-// A03: Injection
-// A04: Insecure Design
-// A05: Security Misconfiguration
-// A06: Vulnerable Components
-// A07: Authentication Failures
-// A08: Integrity Failures
-// A09: Logging Failures
-// A10: SSRF
-
-const rules = OWASPRules.getAll();
-console.log(rules.length);  // 10
-```
-
-### 4.3 CWE Top 25 ルール
-
-```typescript
-import { CWERules } from '@nahisaho/musubix-security';
-
-// CWE-79: XSS
-// CWE-89: SQL Injection
-// CWE-78: OS Command Injection
-// CWE-20: Improper Input Validation
-// CWE-22: Path Traversal
-// CWE-352: CSRF
-// CWE-434: Unrestricted File Upload
-// CWE-502: Deserialization
-// CWE-798: Hardcoded Credentials
-// CWE-862: Missing Authorization
-// ... (25 rules total)
-
-const rules = CWERules.getAll();
-console.log(rules.length);  // 25
-```
-
-### 4.4 ルールエンジン
-
-```typescript
-import {
-  RuleEngine,
-  RuleRegistry,
-  RuleContext,
-} from '@nahisaho/musubix-security';
-
-// ルール登録
-const registry = new RuleRegistry();
-registry.registerAll(OWASPRules.getAll());
-registry.registerAll(CWERules.getAll());
-
-// エンジン初期化
-const engine = new RuleEngine(registry, {
-  severity: ['critical', 'high', 'medium'],
-  categories: ['injection', 'authentication'],
-});
-
-// 解析実行
-const context = new RuleContext(sourceFile, project);
-const violations = await engine.analyze(context);
-
-for (const v of violations) {
-  console.log(`[${v.rule.id}] ${v.message}`);
-  console.log(`  File: ${v.location.file}:${v.location.line}`);
-  console.log(`  Severity: ${v.severity}`);
-  console.log(`  Fix: ${v.suggestedFix}`);
-}
-```
-
-### 4.5 設定プロファイル
-
-```typescript
-import { SecurityProfiles } from '@nahisaho/musubix-security';
-
-// 組み込みプロファイル
-const profiles = {
-  'default': SecurityProfiles.DEFAULT,      // バランス
-  'strict': SecurityProfiles.STRICT,        // 厳格
-  'minimal': SecurityProfiles.MINIMAL,      // 最小
-  'owasp-top10': SecurityProfiles.OWASP,    // OWASPのみ
-  'cwe-top25': SecurityProfiles.CWE,        // CWEのみ
-};
-
-// カスタムプロファイル
-const custom = SecurityProfiles.create({
-  extends: 'strict',
-  rules: {
-    'CWE-79': 'error',
-    'CWE-89': 'error',
-    'CWE-352': 'warn',
-  },
-  exclude: ['**/test/**', '**/node_modules/**'],
-});
-```
-
----
-
-## 5. EPIC-4: 自動修正パイプライン
-
-### 5.1 概要
-
-検出された脆弱性に対して、安全な修正コードを自動生成し、CI/CDパイプラインに統合します。
-
-### 5.2 AutoFixer
-
-```typescript
-import { AutoFixer, FixTemplate } from '@nahisaho/musubix-security';
-
-const fixer = new AutoFixer({
-  templates: FixTemplate.loadBuiltins(),
-  validateFix: true,
-  preserveSemantics: true,
-});
-
-// 脆弱性に対する修正生成
-const fix = await fixer.generateFix(vulnerability);
-
-console.log(fix.original);
-// const query = "SELECT * FROM users WHERE id = " + userId;
-
-console.log(fix.fixed);
-// const query = "SELECT * FROM users WHERE id = ?";
-// db.query(query, [userId]);
-
-console.log(fix.explanation);
-// "パラメータ化クエリを使用してSQLインジェクションを防止"
-```
-
-### 5.3 修正検証
-
-```typescript
-import { FixValidator, SandboxRunner } from '@nahisaho/musubix-security';
-
-const validator = new FixValidator({
-  sandbox: new SandboxRunner(),
-  timeout: 5000,
-});
-
-// 修正の検証
-const result = await validator.validate(fix, {
-  syntaxCheck: true,        // 構文チェック
-  typeCheck: true,          // 型チェック
-  semanticCheck: true,      // セマンティクス保持
-  securityCheck: true,      // 脆弱性再発防止
-  testExecution: true,      // テスト実行
-});
-
-if (result.valid) {
-  await fix.apply();
-} else {
-  console.error(result.errors);
-}
-```
-
-### 5.4 パッチ生成
-
-```typescript
-import { PatchGenerator, UnifiedDiff } from '@nahisaho/musubix-security';
-
-const generator = new PatchGenerator();
-
-// 単一ファイルパッチ
-const patch = generator.generatePatch(fix);
-console.log(patch.diff);
-// --- a/src/api.ts
-// +++ b/src/api.ts
-// @@ -10,3 +10,4 @@
-// -const query = "SELECT * FROM users WHERE id = " + userId;
-// +const query = "SELECT * FROM users WHERE id = ?";
-// +db.query(query, [userId]);
-
-// 複数修正のバッチパッチ
-const batchPatch = generator.generateBatchPatch(fixes);
-await batchPatch.writeToFile('./security-fixes.patch');
-```
-
-### 5.5 CI/CD統合
-
-```typescript
-import { CIIntegration, GitHubActions, GitLabCI } from '@nahisaho/musubix-security';
-
-// GitHub Actions統合
-const github = new GitHubActions({
-  token: process.env.GITHUB_TOKEN,
-  repo: 'owner/repo',
-});
-
-// セキュリティスキャン結果をPRコメント
-await github.commentOnPR(prNumber, {
-  violations: scanResult.violations,
-  fixes: generatedFixes,
-  summary: true,
-});
-
-// 自動修正PR作成
-await github.createFixPR({
-  fixes: generatedFixes,
-  branch: 'security/auto-fix',
-  title: 'Security: Auto-fix vulnerabilities',
-  labels: ['security', 'auto-generated'],
-});
-```
-
-### 5.6 パイプラインオーケストレーション
-
-```typescript
-import {
-  SecurityPipeline,
-  PipelineStage,
-  PipelineConfig,
-} from '@nahisaho/musubix-security';
-
-const pipeline = new SecurityPipeline({
-  stages: [
-    PipelineStage.SCAN,           // 脆弱性スキャン
-    PipelineStage.TAINT_ANALYSIS, // テイント解析
-    PipelineStage.CVE_CHECK,      // CVEチェック
-    PipelineStage.RULE_CHECK,     // ルールチェック
-    PipelineStage.FIX_GENERATION, // 修正生成
-    PipelineStage.VALIDATION,     // 検証
-    PipelineStage.REPORT,         // レポート生成
-  ],
-  parallel: true,
-  failFast: false,
-});
-
-const result = await pipeline.run('./src');
-
-console.log(result.summary);
-// {
-//   totalVulnerabilities: 15,
-//   fixable: 12,
-//   fixed: 10,
-//   manualReviewRequired: 5,
-//   duration: '45s'
-// }
-```
-
----
-
-## 6. 使用例
-
-### 6.1 基本的なセキュリティスキャン
-
-```typescript
-import { SecurityService } from '@nahisaho/musubix-security';
-
-const service = new SecurityService({
-  profile: 'strict',
-  enableTaintAnalysis: true,
-  enableCVECheck: true,
-});
-
-const result = await service.scan('./src');
-
-console.log(`Found ${result.vulnerabilities.length} vulnerabilities`);
-console.log(`Critical: ${result.summary.critical}`);
-console.log(`High: ${result.summary.high}`);
-```
-
-### 6.2 自動修正ワークフロー
-
-```typescript
-import {
-  SecurityService,
-  AutoFixer,
-  ReportGenerator,
-} from '@nahisaho/musubix-security';
-
-// スキャン
-const service = new SecurityService({ profile: 'strict' });
-const scanResult = await service.scan('./src');
-
-// 修正生成
-const fixer = new AutoFixer();
-const fixes = await fixer.generateFixes(scanResult.vulnerabilities);
-
-// 修正適用（ドライラン）
-const dryRun = await fixer.applyFixes(fixes, { dryRun: true });
-console.log(`${dryRun.applied} fixes would be applied`);
-
-// レポート生成
-const reporter = new ReportGenerator();
-await reporter.generate(scanResult, {
-  format: 'html',
-  output: './security-report.html',
-  includeFixes: true,
-});
-```
-
-### 6.3 CI/CDパイプライン統合
-
-```yaml
-# .github/workflows/security.yml
-name: Security Scan
-
-on: [push, pull_request]
-
-jobs:
-  security:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      
-      - name: Run MUSUBIX Security
-        run: |
-          npx musubix security scan ./src \
-            --profile strict \
-            --format sarif \
-            --output security-results.sarif
-      
-      - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: security-results.sarif
-```
-
----
-
-## 7. 設定
-
-### 7.1 設定ファイル
-
-```json
-// musubix.security.json
-{
-  "profile": "strict",
-  "rules": {
-    "CWE-79": "error",
-    "CWE-89": "error",
-    "CWE-78": "error"
-  },
-  "taintAnalysis": {
-    "enabled": true,
-    "maxDepth": 10,
-    "trackImplicitFlows": true
-  },
-  "cveCheck": {
-    "enabled": true,
-    "apiKey": "${NVD_API_KEY}",
-    "cacheTTL": 86400
-  },
-  "autoFix": {
-    "enabled": true,
-    "validateFix": true,
-    "preserveSemantics": true
-  },
-  "exclude": [
-    "**/node_modules/**",
-    "**/dist/**",
-    "**/*.test.ts"
-  ]
-}
-```
-
-### 7.2 環境変数
-
-| 変数名 | 説明 | デフォルト |
-|--------|------|-----------|
-| `NVD_API_KEY` | NVD APIキー（オプション） | - |
-| `MUSUBIX_SECURITY_PROFILE` | デフォルトプロファイル | `default` |
-| `MUSUBIX_SECURITY_CACHE_DIR` | キャッシュディレクトリ | `.musubix/cache` |
-
----
-
-## 8. テスト
-
-### 8.1 テスト統計
-
-| カテゴリ | テスト数 | 合格率 |
-|---------|---------|--------|
-| テイント分析 | 200+ | 100% |
-| CVE連携 | 150+ | 100% |
-| OWASP/CWE | 700+ | 100% |
-| 自動修正 | 200+ | 100% |
-| 統合テスト | 150+ | 100% |
-| **合計** | **1400+** | **100%** |
-
-### 8.2 テスト実行
-
-```bash
-# 全テスト
-npm run test
-
-# セキュリティパッケージのみ
-npm run test -- --filter @nahisaho/musubix-security
-
-# カバレッジ
-npm run test:coverage
-```
-
----
-
-## 9. 関連ドキュメント
-
-- [MUSUBIX-Security.md](./MUSUBIX-Security.md) - 基本機能ドキュメント
-- [MUSUBIX-Security-Plan.md](./MUSUBIX-Security-Plan.md) - セキュリティ実装計画
-- [API-REFERENCE.md](../API-REFERENCE.md) - APIリファレンス
-- [CHANGELOG.md](../../CHANGELOG.md) - 変更履歴
-
----
-
-**作成日**: 2026-01-08  
-**バージョン**: 2.1.0  
-**作成者**: MUSUBIX Development Team