@hoanghainh/komagu 2.2.1 → 2.3.0

package/governance/scs/pack.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""METI SCS Evidence Pack Bundler and Gap Report Generator (#271).
+
+Assembles technical audit artifacts into a timestamped, cryptographically
+hashed ZIP archive with evidence-manifest.json and bilingual gap reports.
+
+Standard library only (Python 3.8+) per ADR-0006.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import time
+import zipfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from governance.scs.mapping import (
+    LEGAL_DISCLAIMER_EN,
+    LEGAL_DISCLAIMER_JA,
+    SCS_CONTROLS,
+)
+
+
+def compute_file_sha256(path: Path) -> str:
+    """Compute standard SHA-256 hex digest of a file."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(65536):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+class EvidencePackBuilder:
+    """Evaluates audit directories and packages METI SCS evidence."""
+
+    def __init__(
+        self,
+        audit_dirs: List[Union[str, Path]],
+        project_name: str = "Komagu-Protected-Project",
+        target_system: str = "Production-Environment",
+    ) -> None:
+        self.audit_dirs = [Path(d).resolve() for d in audit_dirs]
+        self.project_name = project_name
+        self.target_system = target_system
+
+    def discover_artifacts(self) -> Dict[str, Path]:
+        """Discover available technical evidence artifacts across provided directories."""
+        discovered: Dict[str, Path] = {}
+        for d in self.audit_dirs:
+            if not d.is_dir():
+                continue
+            for root, _, files in os.walk(d):
+                for f in files:
+                    fp = Path(root) / f
+                    # Key by filename for mapping match
+                    if f not in discovered:
+                        discovered[f] = fp
+        return discovered
+
+    def evaluate_controls(self, artifacts: Dict[str, Path]) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        """Map discovered artifacts against METI SCS controls and compute readiness rating."""
+        evaluated_controls: List[Dict[str, Any]] = []
+        covered_count = 0
+        partial_count = 0
+
+        for ctrl in SCS_CONTROLS:
+            matched_files: List[str] = []
+            for exp in ctrl["expected_artifacts"]:
+                if exp in artifacts:
+                    matched_files.append(exp)
+
+            if ctrl["control_id"] == "SCS-OG-01":
+                # Organizational governance requires manual policy attachment
+                status = "partially_covered" if matched_files else "out_of_scope_organizational"
+            elif matched_files:
+                status = "covered"
+            else:
+                status = "missing_evidence"
+
+            if status == "covered":
+                covered_count += 1
+            elif status == "partially_covered":
+                partial_count += 1
+
+            entry = dict(ctrl)
+            entry["status"] = status
+            entry["evidence_files"] = matched_files
+            evaluated_controls.append(entry)
+
+        total = len(SCS_CONTROLS)
+        compliance_pct = round(((covered_count + (0.5 * partial_count)) / total) * 100.0, 1)
+
+        if compliance_pct >= 85.0 and any(c["tier"] == "★4" and c["status"] == "covered" for c in evaluated_controls):
+            rating = "SCS-★4-READY"
+        elif compliance_pct >= 60.0:
+            rating = "SCS-★3-READY"
+        elif compliance_pct > 0:
+            rating = "GAP-IDENTIFIED"
+        else:
+            rating = "INSUFFICIENT-EVIDENCE"
+
+        readiness = {
+            "rating": rating,
+            "total_controls": total,
+            "covered_controls": covered_count,
+            "partial_controls": partial_count,
+            "compliance_percentage": compliance_pct,
+        }
+
+        return evaluated_controls, readiness
+
+    def generate_manifest(
+        self,
+        evaluated_controls: List[Dict[str, Any]],
+        readiness: Dict[str, Any],
+        artifacts: Dict[str, Path],
+    ) -> Dict[str, Any]:
+        """Generate evidence-manifest.json conforming to evidence-manifest.schema.json."""
+        bundled_records: List[Dict[str, Any]] = []
+
+        # Collect artifacts referenced in controls
+        used_files = set()
+        for ctrl in evaluated_controls:
+            for ef in ctrl["evidence_files"]:
+                used_files.add(ef)
+
+        for fname in sorted(used_files):
+            fp = artifacts.get(fname)
+            if fp and fp.is_file():
+                bundled_records.append({
+                    "filename": fname,
+                    "artifact_type": fp.suffix.lstrip(".") or "txt",
+                    "sha256": compute_file_sha256(fp),
+                    "size_bytes": fp.stat().st_size,
+                    "description": f"Audit artifact: {fname}",
+                })
+
+        manifest = {
+            "$schema": "https://raw.githubusercontent.com/hoanghainh1188/komagu/main/contracts/schemas/evidence-manifest.schema.json",
+            "manifest_version": "1.0.0",
+            "project_name": self.project_name,
+            "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "target_system": self.target_system,
+            "frameworks": [
+                "METI Supply Chain Security Evaluation Scheme (SCS ★3/★4)",
+                "NIST Cybersecurity Framework (NIST CSF 2.0)",
+                "Japan Active Cyber Defense Act (能動的サイバー防御 2025)",
+            ],
+            "overall_readiness": readiness,
+            "controls": evaluated_controls,
+            "bundled_artifacts": bundled_records,
+            "disclaimer": LEGAL_DISCLAIMER_JA + " " + LEGAL_DISCLAIMER_EN,
+        }
+
+        return manifest
+
+    def render_gap_report_ja(self, manifest: Dict[str, Any]) -> str:
+        """Render Japanese METI SCS Gap Analysis Report (gap-report.ja.md)."""
+        r = manifest["overall_readiness"]
+        lines = [
+            "# 経済産業省 サプライチェーン・サイバーセキュリティ (SCS ★3/★4) 適合性ギャップ分析レポート",
+            "",
+            "> **対象プロジェクト / システム:** `" + manifest["project_name"] + " (" + manifest["target_system"] + ")`  ",
+            "> **評価実施日時:** `" + manifest["generated_at"] + "`  ",
+            "> **総合適合性ステータス:** **`" + r["rating"] + "`** (適合率: **" + str(r["compliance_percentage"]) + "%**)  ",
+            "",
+            "## 1. 概要及び評価結果サマリー",
+            "",
+            "本レポートは、2026年10月施行の**能動的サイバー防御法**および経済産業省**サプライチェーン・サイバーセキュリティ評価制度（SCS ★3/★4、NIST CSF 2.0準拠）**に基づき、"
+            "Komaguが検出・収集したセキュリティ監査成果物を自動照合した結果です。",
+            "",
+            "| 評価項目 | 結果 / 指標 |",
+            "|---|---|",
+            f"| **評価対象統制数** | {r['total_controls']} 項目 |",
+            f"| **技術的エビデンス充足 (Covered)** | {r['covered_controls']} 項目 |",
+            f"| **部分的充足 / 組織的対応要 (Partial)** | {r['partial_controls']} 項目 |",
+            f"| **総合適合率** | **{r['compliance_percentage']}%** |",
+            f"| **判定ランク** | **{r['rating']}** |",
+            "",
+            "## 2. METI SCS / NIST CSF 2.0 統制項目別 照合結果マトリクス",
+            "",
+            "| 統制ID | 統制名 / カテゴリ | 要求水準 | NIST CSF 2.0 | ステータス | 添付エビデンス |",
+            "|---|---|---|---|---|---|",
+        ]
+
+        status_ja = {
+            "covered": "✅ 適合 (Covered)",
+            "partially_covered": "⚠️ 部分的充足 (Partial)",
+            "out_of_scope_organizational": "ℹ️ 組織的対応 (Organizational)",
+            "missing_evidence": "❌ 証跡不足 (Missing)",
+        }
+
+        for c in manifest["controls"]:
+            st = status_ja.get(c["status"], c["status"])
+            ev_str = ", ".join(f"`{f}`" for f in c["evidence_files"]) if c["evidence_files"] else "*(なし)*"
+            csf = ", ".join(c["nist_csf_v2"])
+            lines.append(f"| **{c['control_id']}** | {c['name_ja']} | `{c['tier']}` | `{csf}` | {st} | {ev_str} |")
+
+        lines.extend([
+            "",
+            "## 3. 残存ギャップおよび是正アクション (Action Items)",
+            "",
+        ])
+
+        gap_found = False
+        for c in manifest["controls"]:
+            if c["status"] != "covered":
+                gap_found = True
+                lines.append(f"### 【{c['control_id']}】{c['name_ja']} ({c['tier']})")
+                lines.append(f"- **NIST CSF 2.0 カテゴリ:** `{', '.join(c['nist_csf_v2'])}`")
+                lines.append(f"- **現在の状態:** {status_ja.get(c['status'], c['status'])}")
+                lines.append(f"- **推奨是正アクション:** {c.get('action_required_ja', '社内規程の整備')}")
+                lines.append("")
+
+        if not gap_found:
+            lines.append("🎉 すべての統制項目に対して技術的エビデンスが充足しています。元請企業への提出が可能です。\n")
+
+        lines.extend([
+            "## 4. 添付エビデンスファイル一覧 (SHA-256 チェックサム)",
+            "",
+            "| ファイル名 | 種別 | SHA-256 チェックサム | サイズ |",
+            "|---|---|---|---|",
+        ])
+
+        for a in manifest["bundled_artifacts"]:
+            lines.append(f"| `{a['filename']}` | `{a['artifact_type']}` | `{a['sha256'][:16]}...` | {a['size_bytes']} bytes |")
+
+        lines.extend([
+            "",
+            "---",
+            "### 法的免責事項 (Legal Disclaimer)",
+            LEGAL_DISCLAIMER_JA,
+            "",
+            "*Report generated autonomously by Komagu Security-First Modernization Platform.*",
+        ])
+
+        return "\n".join(lines) + "\n"
+
+    def render_gap_report_en(self, manifest: Dict[str, Any]) -> str:
+        """Render English METI SCS Gap Analysis Report (gap-report.md)."""
+        r = manifest["overall_readiness"]
+        lines = [
+            "# METI Supply Chain Security (SCS ★3/★4) & NIST CSF 2.0 Gap Analysis Report",
+            "",
+            "> **Target Project / System:** `" + manifest["project_name"] + " (" + manifest["target_system"] + ")`  ",
+            "> **Evaluation Timestamp:** `" + manifest["generated_at"] + "`  ",
+            "> **Readiness Verdict:** **`" + r["rating"] + "`** (Compliance Score: **" + str(r["compliance_percentage"]) + "%**)  ",
+            "",
+            "## 1. Executive Summary",
+            "",
+            "This report maps automated Komagu technical security audit artifacts against the Japanese Ministry of Economy, "
+            "Trade and Industry (METI) Supply Chain Security Evaluation Scheme (SCS ★3/★4) and NIST Cybersecurity Framework (CSF 2.0).",
+            "",
+            "| Metric | Value |",
+            "|---|---|",
+            f"| **Total Controls Evaluated** | {r['total_controls']} |",
+            f"| **Technically Covered** | {r['covered_controls']} |",
+            f"| **Partially Covered / Organizational** | {r['partial_controls']} |",
+            f"| **Overall Compliance Score** | **{r['compliance_percentage']}%** |",
+            f"| **Readiness Status** | **{r['rating']}** |",
+            "",
+            "## 2. Control Evaluation Matrix",
+            "",
+            "| Control ID | Name | Tier | NIST CSF 2.0 | Status | Evidence Artifacts |",
+            "|---|---|---|---|---|---|",
+        ]
+
+        status_en = {
+            "covered": "PASSED (Covered)",
+            "partially_covered": "PARTIAL (Action Req)",
+            "out_of_scope_organizational": "ORGANIZATIONAL",
+            "missing_evidence": "MISSING",
+        }
+
+        for c in manifest["controls"]:
+            st = status_en.get(c["status"], c["status"])
+            ev_str = ", ".join(f"`{f}`" for f in c["evidence_files"]) if c["evidence_files"] else "*(none)*"
+            csf = ", ".join(c["nist_csf_v2"])
+            lines.append(f"| **{c['control_id']}** | {c['name_en']} | `{c['tier']}` | `{csf}` | `{st}` | {ev_str} |")
+
+        lines.extend([
+            "",
+            "## 3. Gap Analysis & Remediation Action Plan",
+            "",
+        ])
+
+        for c in manifest["controls"]:
+            if c["status"] != "covered":
+                lines.append(f"### [{c['control_id']}] {c['name_en']} ({c['tier']})")
+                lines.append(f"- **NIST CSF 2.0 Category:** `{', '.join(c['nist_csf_v2'])}`")
+                lines.append(f"- **Current Status:** `{status_en.get(c['status'], c['status'])}`")
+                lines.append(f"- **Recommended Action:** {c.get('action_required_en', 'Document internal policy.')}")
+                lines.append("")
+
+        lines.extend([
+            "## 4. Bundled Artifact Manifest & Cryptographic Hashes",
+            "",
+            "| Filename | Type | SHA-256 Digest | Size (Bytes) |",
+            "|---|---|---|---|",
+        ])
+
+        for a in manifest["bundled_artifacts"]:
+            lines.append(f"| `{a['filename']}` | `{a['artifact_type']}` | `{a['sha256']}` | {a['size_bytes']} |")
+
+        lines.extend([
+            "",
+            "---",
+            "### Disclaimer",
+            LEGAL_DISCLAIMER_EN,
+            "",
+            "*Report generated autonomously by Komagu Security-First Modernization Platform.*",
+        ])
+
+        return "\n".join(lines) + "\n"
+
+    def build_pack(self, output_dir: Union[str, Path]) -> Tuple[Path, Path, Path, Path]:
+        """Build evidence pack ZIP, manifest JSON, and bilingual reports.
+        
+        Returns:
+            (zip_path, manifest_path, gap_report_ja_path, gap_report_en_path)
+        """
+        out_p = Path(output_dir).resolve()
+        out_p.mkdir(parents=True, exist_ok=True)
+
+        artifacts = self.discover_artifacts()
+        evaluated_controls, readiness = self.evaluate_controls(artifacts)
+        manifest = self.generate_manifest(evaluated_controls, readiness, artifacts)
+
+        manifest_path = out_p / "evidence-manifest.json"
+        manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8")
+
+        gap_report_ja_path = out_p / "gap-report.ja.md"
+        gap_report_ja_path.write_text(self.render_gap_report_ja(manifest), encoding="utf-8")
+
+        gap_report_en_path = out_p / "gap-report.md"
+        gap_report_en_path.write_text(self.render_gap_report_en(manifest), encoding="utf-8")
+
+        # Create evidence-pack.zip
+        zip_path = out_p / "evidence-pack.zip"
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            zf.write(manifest_path, arcname="evidence-manifest.json")
+            zf.write(gap_report_ja_path, arcname="gap-report.ja.md")
+            zf.write(gap_report_en_path, arcname="gap-report.md")
+
+            for item in manifest["bundled_artifacts"]:
+                fname = item["filename"]
+                if fname in artifacts and artifacts[fname].is_file():
+                    zf.write(artifacts[fname], arcname=f"artifacts/{fname}")
+
+        return zip_path, manifest_path, gap_report_ja_path, gap_report_en_path

package/operate/cli/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "2.2.1"  # x-release-please-version
+__version__ = "2.3.0"  # x-release-please-version

package/operate/cli/commands/evidence.py

@@ -0,0 +1,138 @@
+"""Command: komagu evidence - METI SCS ★3/★4 & NIST CSF 2.0 Evidence Pack Bundler (#271)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List
+
+from governance.scs.pack import EvidencePackBuilder
+from operate.cli.ui import (
+    BOLD,
+    CYAN,
+    GREEN,
+    RED,
+    YELLOW,
+    color,
+    print_summary_table,
+    step,
+    step_fail,
+    step_info,
+    step_ok,
+    step_warn,
+)
+
+
+def register_subcommand(subparsers: argparse._SubParsersAction) -> None:
+    """Register the evidence subcommand parser."""
+    parser = subparsers.add_parser(
+        "evidence",
+        help="Generate METI Supply Chain Security (SCS ★3/★4) evidence pack and gap report",
+        description="Bundles technical audit artifacts into a timestamped, cryptographically hashed evidence pack (ZIP + JSON manifest) with Japanese/English gap reports.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Generate METI SCS evidence pack from default audit output directory (OUT/)
+  komagu evidence --audit-dir OUT --output-dir ./meti-evidence
+
+  # Generate evidence pack specifying project and system names
+  komagu evidence \
+    --audit-dir OUT \
+    --project "FinTech Core Banking" \
+    --system "Staging API Cluster" \
+    --output-dir ./audit-pack
+
+  # Enforce minimum readiness rating (e.g. fail CI if SCS-★3-READY is not met)
+  komagu evidence --audit-dir OUT --require-tier 3
+""",
+    )
+    parser.add_argument(
+        "--audit-dir",
+        "-d",
+        action="append",
+        dest="audit_dirs",
+        metavar="DIR",
+        help="Path to directory containing audit outputs (e.g. OUT/, findings.sarif, sbom.json). Repeatable.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        default="./evidence-pack",
+        help="Directory to save evidence-pack.zip, evidence-manifest.json, and gap reports (default: ./evidence-pack)",
+    )
+    parser.add_argument(
+        "--project",
+        default="Target Modernization System",
+        help="Project or organization name (default: Target Modernization System)",
+    )
+    parser.add_argument(
+        "--system",
+        default="Production Architecture",
+        help="Target system or environment name (default: Production Architecture)",
+    )
+    parser.add_argument(
+        "--require-tier",
+        type=int,
+        choices=[3, 4],
+        help="Fail with exit code 1 if evaluated readiness does not meet the specified star tier (3 or 4)",
+    )
+    parser.set_defaults(func=execute_evidence)
+
+
+def execute_evidence(args: argparse.Namespace) -> int:
+    """Execute evidence pack generation and gap analysis."""
+    audit_dirs = args.audit_dirs or ["OUT", "audit-out", "delivery/pilot/audit-out", "."]
+
+    step(f"Assembling METI SCS Evidence Pack for {color(args.project, BOLD)} ({args.system})")
+    step_info(f"Scanning audit source directories: {', '.join(audit_dirs)}")
+
+    builder = EvidencePackBuilder(
+        audit_dirs=audit_dirs,
+        project_name=args.project,
+        target_system=args.system,
+    )
+
+    artifacts = builder.discover_artifacts()
+    step_info(f"Discovered {len(artifacts)} audit artifacts across directories")
+
+    evaluated_controls, readiness = builder.evaluate_controls(artifacts)
+    rating = readiness["rating"]
+    score = readiness["compliance_percentage"]
+
+    # Build ZIP and reports
+    zip_path, manifest_path, gap_ja, gap_en = builder.build_pack(args.output_dir)
+
+    step_ok(f"Generated Evidence Manifest: {manifest_path}")
+    step_ok(f"Generated Japanese Gap Report: {gap_ja}")
+    step_ok(f"Generated English Gap Report: {gap_en}")
+    step_ok(f"Packaged Signed ZIP Archive: {zip_path}")
+
+    # Display Executive Summary Table
+    rating_color = GREEN if "READY" in rating else (YELLOW if rating == "GAP-IDENTIFIED" else RED)
+    summary_rows = [
+        ("Project Name", args.project),
+        ("Target System", args.system),
+        ("Total SCS Controls Evaluated", str(readiness["total_controls"])),
+        ("Technically Covered Controls", color(str(readiness["covered_controls"]), GREEN, BOLD)),
+        ("Partial / Organizational", color(str(readiness["partial_controls"]), YELLOW)),
+        ("Compliance Score", color(f"{score}%", rating_color, BOLD)),
+        ("METI SCS Readiness Rating", color(rating, rating_color, BOLD)),
+    ]
+
+    print_summary_table(
+        title="METI Supply Chain Security (SCS ★3/★4) Assessment Summary",
+        rows=summary_rows,
+        footer="Evidence pack ready for submission to prime contractor / accredited auditor."
+    )
+
+    # Gating enforcement if requested
+    if args.require_tier:
+        if args.require_tier == 4 and rating != "SCS-★4-READY":
+            step_fail(f"Quality Gate Failed: Required SCS-★4-READY, evaluated as {rating} ({score}%)")
+            return 1
+        elif args.require_tier == 3 and rating not in ("SCS-★3-READY", "SCS-★4-READY"):
+            step_fail(f"Quality Gate Failed: Required SCS-★3-READY, evaluated as {rating} ({score}%)")
+            return 1
+
+    return 0

package/operate/cli/commands/inventory.py

@@ -0,0 +1,187 @@
+"""Inventory subcommand: compare code routes, OpenAPI spec, and gateway traffic to find Shadow/Zombie APIs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from operate.cli.ui import color, print_summary_table, step, step_fail, step_info, step_ok, step_warn
+from operate.inventory.api_inventory import (
+    diff_api_inventory,
+    load_code_routes,
+    load_openapi_spec,
+    load_traffic_log,
+)
+
+
+def register_subcommand(subparsers: argparse._SubParsersAction) -> None:
+    """Register the inventory subcommand parser."""
+    parser = subparsers.add_parser(
+        "inventory",
+        help="Reconcile code routes, OpenAPI spec, and gateway traffic to detect Shadow and Zombie APIs",
+        description="Detects Shadow APIs (undocumented code/traffic) and Zombie APIs (deprecated routes still active).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Reconcile LSA code routes against the published OpenAPI spec
+  komagu inventory --routes OUT/routes.json --openapi openapi.json
+
+  # Include Kong Gateway traffic log to spot Zombie APIs and active Shadow endpoints
+  komagu inventory --routes OUT/routes.json --openapi openapi.json --traffic-log /var/log/kong/access.log
+
+  # CI gate: fail if any undocumented Shadow API is detected
+  komagu inventory --routes OUT/routes.json --openapi openapi.json --fail-on-shadow
+
+  # Output machine-readable JSON diff to a custom path
+  komagu inventory --routes OUT/routes.json --openapi openapi.json --out OUT/api-diff.json
+""",
+    )
+    parser.add_argument(
+        "--routes",
+        "-r",
+        type=Path,
+        required=True,
+        help="Path to code routes JSON (e.g. OUT/routes.json or routes.candidates.json from LSA)",
+    )
+    parser.add_argument(
+        "--openapi",
+        "-s",
+        type=Path,
+        required=True,
+        help="Path to OpenAPI / Swagger JSON or YAML specification",
+    )
+    parser.add_argument(
+        "--traffic-log",
+        "--kong-log",
+        "-t",
+        type=Path,
+        default=None,
+        help="Path to Kong HTTP-Log (JSON lines) or NGINX Combined access log",
+    )
+    parser.add_argument(
+        "--out",
+        "-o",
+        type=Path,
+        default=None,
+        help="Path to write the api-inventory-diff.json output (defaults to OUT/api-inventory-diff.json)",
+    )
+    parser.add_argument(
+        "--fail-on-shadow",
+        action="store_true",
+        help="Exit with non-zero code if any shadow API is detected",
+    )
+    parser.add_argument(
+        "--fail-on-zombie",
+        action="store_true",
+        help="Exit with non-zero code if any zombie API is detected",
+    )
+    parser.set_defaults(func=run_inventory)
+
+
+def run_inventory(args: argparse.Namespace) -> int:
+    """Execute API inventory reconciliation."""
+    routes_file = Path(args.routes).resolve()
+    openapi_file = Path(args.openapi).resolve()
+    traffic_file = Path(args.traffic_log).resolve() if args.traffic_log else None
+
+    if not routes_file.is_file():
+        step_fail(f"Routes file not found: {routes_file}")
+        return 2
+
+    if not openapi_file.is_file():
+        step_fail(f"OpenAPI spec file not found: {openapi_file}")
+        return 2
+
+    step("Parsing routes extracted from source code")
+    code_routes = load_code_routes(routes_file)
+    step_ok(f"Loaded {len(code_routes)} endpoints from code routes")
+
+    step("Parsing OpenAPI specification")
+    spec_endpoints = load_openapi_spec(openapi_file)
+    step_ok(f"Loaded {len(spec_endpoints)} endpoints from OpenAPI specification")
+
+    traffic_data = {}
+    if traffic_file:
+        if not traffic_file.is_file():
+            step_warn(f"Traffic log file not found: {traffic_file} (skipping traffic analysis)")
+        else:
+            step("Analyzing gateway traffic log (Kong / NGINX)")
+            traffic_data = load_traffic_log(traffic_file)
+            total_hits = sum(t["traffic_hits"] for t in traffic_data.values())
+            step_ok(f"Parsed {len(traffic_data)} active endpoints ({total_hits} total requests) from traffic log")
+
+    step("Reconciling API inventories across 3 surfaces")
+    diff_doc = diff_api_inventory(
+        code_routes=code_routes,
+        spec_endpoints=spec_endpoints,
+        traffic_data=traffic_data,
+        routes_file_name=routes_file.name,
+        openapi_file_name=openapi_file.name,
+        traffic_file_name=traffic_file.name if traffic_file else None,
+    )
+
+    s = diff_doc["summary"]
+    shadow_count = s["shadow_count"]
+    zombie_count = s["zombie_count"]
+    missing_count = s["missing_code_count"]
+    dormant_count = s["dormant_count"]
+
+    # Determine output file path
+    out_file = args.out
+    if not out_file:
+        out_dir = routes_file.parent
+        out_file = out_dir / "api-inventory-diff.json"
+
+    out_file.parent.mkdir(parents=True, exist_ok=True)
+    with open(out_file, "w", encoding="utf-8") as fh:
+        json.dump(diff_doc, fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+    step_ok(f"Saved inventory diff to {out_file}")
+
+    # Display summary card
+    c_yellow_bold = "\033[33m\033[1m"
+    c_red_bold = "\033[31m\033[1m"
+    c_green = "\033[32m"
+    c_bold = "\033[1m"
+
+    summary_rows = [
+        ("Code Routes Discovered", str(s["total_code_routes"])),
+        ("OpenAPI Endpoints Documented", str(s["total_spec_endpoints"])),
+        ("Gateway Traffic Endpoints", str(s["total_traffic_endpoints"])),
+        ("Shadow APIs (Undocumented)", color(str(shadow_count), c_yellow_bold if shadow_count > 0 else c_green)),
+        ("Zombie APIs (Deprecated Active)", color(str(zombie_count), c_red_bold if zombie_count > 0 else c_green)),
+        ("Documented Missing in Code", str(missing_count)),
+        ("Dormant Code Endpoints", str(dormant_count)),
+    ]
+    print_summary_table(
+        "API Inventory Reconciliation Summary",
+        summary_rows,
+        footer="Shadow APIs expose undocumented attack surface; Zombie APIs must be retired."
+    )
+
+    if shadow_count > 0:
+        print("  " + color("⚠ Detected Shadow APIs (Top 5):", "\033[33m", c_bold))
+        for sh in diff_doc["shadow_apis"][:5]:
+            hits = f"({sh['traffic_hits']} traffic hits)" if sh["traffic_hits"] > 0 else ""
+            norm_str = color(sh["normalized"], c_bold)
+            disc_str = sh["discovered_in"]
+            print(f"    • {norm_str} [{disc_str}] {hits}")
+
+    if zombie_count > 0:
+        print("  " + color("✖ Detected Zombie APIs (Top 5):", "\033[31m", c_bold))
+        for z in diff_doc["zombie_apis"][:5]:
+            norm_str = color(z["normalized"], c_bold)
+            hits_str = f"{z['traffic_hits']} active traffic hits!"
+            print(f"    • {norm_str} ({hits_str})")
+
+    exit_code = 0
+    if args.fail_on_shadow and shadow_count > 0:
+        step_fail(f"Failing gate: {shadow_count} shadow APIs detected")
+        exit_code = 1
+    if args.fail_on_zombie and zombie_count > 0:
+        step_fail(f"Failing gate: {zombie_count} zombie APIs detected")
+        exit_code = 1
+
+    return exit_code