codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/tools/security_tools.py

@@ -0,0 +1,657 @@
+"""
+보안 스캐너 래퍼 모듈.
+
+bandit, semgrep, pip-audit, detect-secrets 등 보안 도구를 통합하여
+SecurityFinding 데이터 모델로 결과를 반환합니다.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import re
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from codebuff_core.directory_policy import (
+    EXCLUDED_RELATIVE_DIRS,
+    SEARCH_EXCLUDED_DIRS,
+)
+
+
+@dataclass
+class SecurityFinding:
+    """보안 스캔 결과 단일 항목."""
+
+    scanner: str  # "bandit" | "semgrep" | "pip-audit" | "detect-secrets" | "custom"
+    severity: str  # "critical" | "high" | "medium" | "low" | "info"
+    category: str  # "sast" | "dependency" | "secret" | "injection"
+    title: str
+    description: str
+    file: str | None = None
+    line: int | None = None
+    cwe_id: str | None = None
+    owasp_id: str | None = None
+    confidence: str = "medium"  # "high" | "medium" | "low"
+    fix_suggestion: str | None = None
+    raw_id: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Bandit CWE/OWASP 매핑
+# ---------------------------------------------------------------------------
+_BANDIT_CWE_MAP: dict[str, tuple[str, str]] = {
+    # (CWE, OWASP)
+    "B105": ("CWE-798", "A07:2021"),  # hardcoded password
+    "B106": ("CWE-798", "A07:2021"),  # hardcoded password func arg
+    "B107": ("CWE-798", "A07:2021"),  # hardcoded password default
+    "B108": ("CWE-377", "A01:2021"),  # hardcoded tmp dir
+    "B301": ("CWE-502", "A08:2021"),  # pickle
+    "B302": ("CWE-502", "A08:2021"),  # marshal
+    "B303": ("CWE-327", "A02:2021"),  # insecure hash (MD5, SHA1)
+    "B304": ("CWE-327", "A02:2021"),  # insecure cipher
+    "B305": ("CWE-327", "A02:2021"),  # insecure cipher mode
+    "B306": ("CWE-327", "A02:2021"),  # mktemp
+    "B307": ("CWE-78", "A03:2021"),  # eval
+    "B308": ("CWE-95", "A03:2021"),  # mark_safe
+    "B310": ("CWE-918", "A10:2021"),  # urllib open
+    "B311": ("CWE-330", "A02:2021"),  # random
+    "B312": ("CWE-295", "A07:2021"),  # telnetlib
+    "B320": ("CWE-611", "A05:2021"),  # xml parse
+    "B321": ("CWE-319", "A02:2021"),  # FTP
+    "B323": ("CWE-295", "A07:2021"),  # unverified SSL context
+    "B324": ("CWE-327", "A02:2021"),  # insecure hash
+    "B501": ("CWE-295", "A07:2021"),  # verify=False
+    "B502": ("CWE-327", "A02:2021"),  # ssl no version
+    "B506": ("CWE-502", "A08:2021"),  # yaml load
+    "B601": ("CWE-78", "A03:2021"),  # paramiko shell
+    "B602": ("CWE-78", "A03:2021"),  # subprocess shell=True
+    "B603": ("CWE-78", "A03:2021"),  # subprocess without shell
+    "B604": ("CWE-78", "A03:2021"),  # function call shell
+    "B605": ("CWE-78", "A03:2021"),  # os.system
+    "B606": ("CWE-78", "A03:2021"),  # os.popen
+    "B607": ("CWE-78", "A03:2021"),  # partial executable path
+    "B608": ("CWE-89", "A03:2021"),  # SQL injection
+    "B609": ("CWE-78", "A03:2021"),  # wildcard injection
+    "B610": ("CWE-78", "A03:2021"),  # django extra
+    "B611": ("CWE-78", "A03:2021"),  # django raw SQL
+    "B701": ("CWE-94", "A03:2021"),  # jinja2 autoescape
+    "B702": ("CWE-79", "A03:2021"),  # mako template
+    "B703": ("CWE-79", "A03:2021"),  # django mark_safe
+}
+
+_BANDIT_SEVERITY_MAP: dict[str, str] = {
+    "HIGH": "high",
+    "MEDIUM": "medium",
+    "LOW": "low",
+}
+
+_BANDIT_CONFIDENCE_MAP: dict[str, str] = {
+    "HIGH": "high",
+    "MEDIUM": "medium",
+    "LOW": "low",
+}
+
+# ---------------------------------------------------------------------------
+# 커스텀 우회 패턴
+# ---------------------------------------------------------------------------
+_EVASION_PATTERNS: list[dict] = [
+    {
+        "pattern": r"base64\.(b64decode|decodebytes)\s*\(",
+        "title": "Base64 Encoded Credential",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "base64로 인코딩된 비밀번호/키 - 디코딩하면 평문 노출",
+        "confidence": "medium",
+    },
+    {
+        "pattern": r"os\.(?:environ|getenv)\s*\.?\s*(?:get)?\s*\([^)]+,\s*['\"][^'\"]{8,}['\"]",
+        "title": "Hardcoded Fallback in env var",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "환경변수 미설정 시 하드코딩된 기본값 사용 - 프로덕션 유출 위험",
+        "confidence": "medium",
+    },
+    {
+        "pattern": r"(?:\[::-1\]|reversed\(|''.join\(|str\.join)",
+        "title": "String Obfuscation (potential credential hiding)",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "문자열 역순/조합으로 크리덴셜 은닉 시도",
+        "confidence": "low",
+    },
+    {
+        "pattern": r"['\"](?:password|passwd|secret|api_key|token|auth)['\"]:\s*['\"][^'\"]+['\"]",
+        "title": "Credential in dict/config literal",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "딕셔너리/설정 리터럴에 크리덴셜 하드코딩",
+        "confidence": "high",
+    },
+    {
+        "pattern": r"(?:pw|pswd|passwd|tkn|api_k|auth_t|secret_k)\s*=\s*['\"][^'\"]{6,}['\"]",
+        "title": "Obfuscated credential variable name",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "약어 변수명으로 크리덴셜 은닉 (pw, tkn 등)",
+        "confidence": "medium",
+    },
+    {
+        "pattern": r"codecs\.decode\s*\([^)]+['\"]rot",
+        "title": "ROT13/codec-based credential obfuscation",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "ROT13 등 간단한 인코딩으로 크리덴셜 은닉",
+        "confidence": "medium",
+    },
+    {
+        "pattern": r"(?:connect|login|authenticate|create_engine)\s*\([^)]*(?:password|passwd|secret)\s*=\s*['\"][^'\"]+['\"]",
+        "title": "Credential passed as function argument",
+        "cwe": "CWE-798",
+        "owasp": "A07:2021",
+        "description": "DB 연결/인증 함수에 크리덴셜 직접 전달",
+        "confidence": "high",
+    },
+    {
+        "pattern": r"(?:eval|exec)\s*\(\s*(?:\w+\s*\+|f['\"]|['\"].*\+)",
+        "title": "Dynamic code execution with string building",
+        "cwe": "CWE-95",
+        "owasp": "A03:2021",
+        "description": "문자열 조합 후 eval/exec - 코드 인젝션 우회 패턴",
+        "confidence": "high",
+    },
+]
+
+# ---------------------------------------------------------------------------
+# 한국 금융권 개인정보(PII) 패턴
+# ---------------------------------------------------------------------------
+_PII_PATTERNS: list[dict] = [
+    {
+        "pattern": r"\d{6}\s*-?\s*[1-4]\d{6}",
+        "title": "주민등록번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "주민등록번호(YYMMDD-GNNNNNN) 패턴 탐지 - 개인정보보호법 위반 가능",
+        "confidence": "high",
+        "severity": "high",
+    },
+    {
+        "pattern": r"\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}",
+        "title": "신용카드번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "신용카드번호(16자리) 패턴 탐지 - 여신전문금융업법 위반 가능",
+        "confidence": "high",
+        "severity": "high",
+    },
+    {
+        "pattern": r"(?:\d{3,4}[\s-]?\d{2,4}[\s-]?\d{4,6}[\s-]?\d{2,3})",
+        "title": "은행 계좌번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "은행 계좌번호 형식 탐지 (은행별 다양한 형식) - 금융실명법 관련",
+        "confidence": "low",
+        "severity": "medium",
+    },
+    {
+        "pattern": r"01[016789][\s-]?\d{3,4}[\s-]?\d{4}",
+        "title": "휴대전화번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "한국 휴대전화번호(010-XXXX-XXXX) 패턴 탐지 - 개인정보보호법 위반 가능",
+        "confidence": "medium",
+        "severity": "medium",
+    },
+    {
+        "pattern": r"[MSms]\d{8}",
+        "title": "여권번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "한국 여권번호(M12345678) 패턴 탐지 - 개인정보보호법 위반 가능",
+        "confidence": "medium",
+        "severity": "medium",
+    },
+    {
+        "pattern": r"\d{2}[\s-]?\d{2}[\s-]?\d{6}[\s-]?\d{2}",
+        "title": "운전면허번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "운전면허번호(지역-년도-일련번호-검증) 패턴 탐지 - 개인정보보호법 위반 가능",
+        "confidence": "medium",
+        "severity": "medium",
+    },
+    {
+        "pattern": r"\d{10}[\s-]?\d{2}",
+        "title": "건강보험번호 패턴",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "건강보험 자격득실확인서 번호(10+2자리) 패턴 탐지",
+        "confidence": "low",
+        "severity": "medium",
+    },
+    {
+        "pattern": r"(?:log(?:ging)?|logger)\s*[\.(]\s*(?:info|debug|warning|error|critical)\s*\([^)]*(?:주민|resident|ssn|card_?num|카드번호|계좌|account_?num|phone|전화|휴대폰)",
+        "title": "PII 로깅 anti-pattern",
+        "cwe": "CWE-532",
+        "owasp": "A09:2021",
+        "description": "개인정보가 포함된 변수를 로그에 기록 - 로그 유출 시 대량 정보 노출 위험",
+        "confidence": "high",
+        "severity": "high",
+    },
+    {
+        "pattern": r"requests\.(?:post|put|patch)\s*\([^)]*(?:주민|resident|ssn|card_?num|카드번호|계좌|account_?num|phone|전화|휴대폰)",
+        "title": "PII 외부 전송 anti-pattern",
+        "cwe": "CWE-319",
+        "owasp": "A02:2021",
+        "description": "개인정보를 외부 API에 평문 전송 - 전자금융거래법 위반 가능",
+        "confidence": "high",
+        "severity": "high",
+    },
+    {
+        "pattern": r"(?:print|sys\.stdout\.write)\s*\([^)]*(?:주민|resident|ssn|card_?num|카드번호|계좌|account_?num|phone|전화|휴대폰)",
+        "title": "PII 마스킹 없는 출력",
+        "cwe": "CWE-359",
+        "owasp": "A01:2021",
+        "description": "개인정보를 마스킹 없이 표준 출력에 노출 - 화면 캡처/공유 시 유출 위험",
+        "confidence": "medium",
+        "severity": "medium",
+    },
+    {
+        "pattern": r"(?:open|to_csv|to_excel|to_json)\s*\([^)]*(?:주민|resident|ssn|card_?num|카드번호|계좌|account_?num|phone|전화|휴대폰)",
+        "title": "PII 평문 파일 저장",
+        "cwe": "CWE-312",
+        "owasp": "A02:2021",
+        "description": "개인정보를 암호화 없이 파일에 저장 - 신용정보법/개인정보보호법 위반 가능",
+        "confidence": "high",
+        "severity": "high",
+    },
+    {
+        "pattern": r'df\s*\[\s*["\'](?:주민등록번호|주민번호|resident_id|ssn|카드번호|card_number|계좌번호|account_number)["\']',
+        "title": "DataFrame PII 미암호화",
+        "cwe": "CWE-311",
+        "owasp": "A02:2021",
+        "description": "DataFrame에 개인정보 컬럼이 평문으로 존재 - 암호화/마스킹 처리 필요",
+        "confidence": "medium",
+        "severity": "medium",
+    },
+]
+
+_SCANNER_TIMEOUT = 120
+
+
+# ---------------------------------------------------------------------------
+# 스캐너 래퍼 함수
+# ---------------------------------------------------------------------------
+
+
+def run_bandit(
+    target_path: str,
+    workspace_root: str,
+    severity_filter: str = "low",
+) -> list[SecurityFinding]:
+    """bandit SAST 스캐너 실행."""
+    severity_levels = {"low": "l", "medium": "m", "high": "h", "critical": "h"}
+    sev_flag = severity_levels.get(severity_filter, "l")
+
+    cmd = [
+        "bandit",
+        "-r",
+        target_path,
+        "-f",
+        "json",
+        "--exit-zero",
+        f"-{'l' * ('lmh'.index(sev_flag) + 1)}",
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+            timeout=_SCANNER_TIMEOUT,
+        )
+    except FileNotFoundError:
+        return []
+    except subprocess.TimeoutExpired:
+        return []
+
+    findings: list[SecurityFinding] = []
+    try:
+        data = json.loads(result.stdout)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    for issue in data.get("results", []):
+        test_id = issue.get("test_id", "")
+        cwe, owasp = _BANDIT_CWE_MAP.get(test_id, (None, None))
+        sev = _BANDIT_SEVERITY_MAP.get(issue.get("issue_severity", ""), "medium")
+        conf = _BANDIT_CONFIDENCE_MAP.get(issue.get("issue_confidence", ""), "medium")
+
+        findings.append(
+            SecurityFinding(
+                scanner="bandit",
+                severity=sev,
+                category="sast",
+                title=issue.get("test_name", test_id),
+                description=issue.get("issue_text", "")[:200],
+                file=issue.get("filename"),
+                line=issue.get("line_number"),
+                cwe_id=cwe,
+                owasp_id=owasp,
+                confidence=conf,
+                fix_suggestion=issue.get("more_info"),
+                raw_id=test_id,
+            )
+        )
+
+    return findings
+
+
+def run_semgrep(
+    target_path: str,
+    workspace_root: str,
+    ruleset: str = "p/owasp-top-ten",
+) -> list[SecurityFinding]:
+    """semgrep SAST 스캐너 실행."""
+    cmd = [
+        "semgrep",
+        "--config",
+        ruleset,
+        "--json",
+        "--quiet",
+        target_path,
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+            timeout=_SCANNER_TIMEOUT,
+        )
+    except FileNotFoundError:
+        return []
+    except subprocess.TimeoutExpired:
+        return []
+
+    findings: list[SecurityFinding] = []
+    try:
+        data = json.loads(result.stdout)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    _semgrep_severity_map = {
+        "ERROR": "high",
+        "WARNING": "medium",
+        "INFO": "low",
+    }
+
+    for res in data.get("results", []):
+        extra = res.get("extra", {})
+        metadata = extra.get("metadata", {})
+
+        severity = _semgrep_severity_map.get(extra.get("severity", ""), "medium")
+
+        cwe_ids = metadata.get("cwe", [])
+        cwe_id = cwe_ids[0] if cwe_ids else None
+        if cwe_id and not cwe_id.startswith("CWE-"):
+            cwe_id = f"CWE-{cwe_id}"
+
+        owasp_ids = metadata.get("owasp", [])
+        owasp_id = owasp_ids[0] if owasp_ids else None
+
+        findings.append(
+            SecurityFinding(
+                scanner="semgrep",
+                severity=severity,
+                category="sast",
+                title=res.get("check_id", "unknown"),
+                description=extra.get("message", "")[:200],
+                file=res.get("path"),
+                line=res.get("start", {}).get("line"),
+                cwe_id=cwe_id,
+                owasp_id=owasp_id,
+                confidence=metadata.get("confidence", "medium").lower(),
+                fix_suggestion=extra.get("fix"),
+                raw_id=res.get("check_id"),
+            )
+        )
+
+    return findings
+
+
+def run_pip_audit(workspace_root: str) -> list[SecurityFinding]:
+    """pip-audit 의존성 취약점 스캐너 실행."""
+    cmd = ["pip-audit", "--format", "json", "--output", "-"]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+            timeout=_SCANNER_TIMEOUT,
+        )
+    except FileNotFoundError:
+        return []
+    except subprocess.TimeoutExpired:
+        return []
+
+    findings: list[SecurityFinding] = []
+    try:
+        data = json.loads(result.stdout)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    deps = data if isinstance(data, list) else data.get("dependencies", [])
+
+    for dep in deps:
+        for vuln in dep.get("vulns", []):
+            vuln_id = vuln.get("id", "")
+            desc = vuln.get("description", "")[:200]
+            fix_ver = vuln.get("fix_versions", [])
+            fix_str = f"업데이트: {', '.join(fix_ver)}" if fix_ver else None
+
+            findings.append(
+                SecurityFinding(
+                    scanner="pip-audit",
+                    severity="high",
+                    category="dependency",
+                    title=f"{dep.get('name', 'unknown')} - {vuln_id}",
+                    description=desc or f"알려진 취약점: {vuln_id}",
+                    cwe_id=None,
+                    owasp_id="A06:2021",
+                    confidence="high",
+                    fix_suggestion=fix_str,
+                    raw_id=vuln_id,
+                )
+            )
+
+    return findings
+
+
+def run_detect_secrets(
+    target_path: str,
+    workspace_root: str,
+) -> list[SecurityFinding]:
+    """detect-secrets 시크릿 스캐너 실행."""
+    cmd = ["detect-secrets", "scan", target_path]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=workspace_root,
+            timeout=_SCANNER_TIMEOUT,
+        )
+    except FileNotFoundError:
+        return []
+    except subprocess.TimeoutExpired:
+        return []
+
+    findings: list[SecurityFinding] = []
+    try:
+        data = json.loads(result.stdout)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    for filepath, secrets_list in data.get("results", {}).items():
+        for secret in secrets_list:
+            findings.append(
+                SecurityFinding(
+                    scanner="detect-secrets",
+                    severity="high",
+                    category="secret",
+                    title=f"Secret detected: {secret.get('type', 'unknown')}",
+                    description=f"시크릿 탐지 ({secret.get('type', '')}) - 라인 {secret.get('line_number', '?')}",
+                    file=filepath,
+                    line=secret.get("line_number"),
+                    cwe_id="CWE-798",
+                    owasp_id="A07:2021",
+                    confidence="high",
+                    raw_id=secret.get("type"),
+                )
+            )
+
+    return findings
+
+
+_SCAN_TIMEOUT = 10  # seconds per custom scanner
+_SCAN_MAX_FINDINGS = 10_000
+_SCAN_MAX_FILE_SIZE = 1_000_000
+_SCAN_MAX_LINE_SIZE = 10_000
+
+
+class PatternScanResult(list):
+    """List-compatible findings plus completion status for the tool response."""
+
+    def __init__(self):
+        super().__init__()
+        self.truncated = False
+        self.truncation_reason = None
+
+    def mark_partial(self, reason: str) -> None:
+        self.truncated = True
+        self.truncation_reason = reason
+
+
+def _scan_files(target, suffixes, deadline, findings):
+    if time.monotonic() >= deadline:
+        findings.mark_partial("time_budget")
+        return
+    try:
+        if target.is_file():
+            yield target
+            return
+        if not target.is_dir():
+            findings.mark_partial("invalid_target")
+            return
+    except OSError:
+        findings.mark_partial("unreadable_target")
+        return
+
+    def on_error(error):
+        findings.mark_partial("unreadable_directory")
+
+    for directory, dirs, names in os.walk(target, onerror=on_error):
+        if time.monotonic() >= deadline:
+            findings.mark_partial("time_budget")
+            return
+        base = Path(directory)
+        dirs[:] = [
+            name
+            for name in dirs
+            if name not in SEARCH_EXCLUDED_DIRS
+            and (base / name).relative_to(target).parts not in EXCLUDED_RELATIVE_DIRS
+        ]
+        for name in names:
+            if time.monotonic() >= deadline:
+                findings.mark_partial("time_budget")
+                return
+            path = base / name
+            if path.suffix in suffixes:
+                yield path
+
+
+def _run_pattern_scan(target_path, workspace_root, patterns, suffixes, category):
+    findings = PatternScanResult()
+    target = Path(target_path)
+    root = Path(workspace_root)
+    deadline = time.monotonic() + _SCAN_TIMEOUT
+    for fpath in _scan_files(target, suffixes, deadline, findings):
+        try:
+            if time.monotonic() >= deadline:
+                findings.mark_partial("time_budget")
+                break
+            if fpath.stat().st_size > _SCAN_MAX_FILE_SIZE:
+                findings.mark_partial("file_size_limit")
+                continue
+            # Do not follow a file symlink out of the explicitly requested scope.
+            fpath.resolve().relative_to(
+                target.resolve() if target.is_dir() else target.parent.resolve()
+            )
+            try:
+                rel = str(fpath.relative_to(root))
+            except ValueError:
+                rel = str(fpath)
+            with fpath.open(errors="ignore") as source:
+                for number, line in enumerate(source, 1):
+                    if time.monotonic() >= deadline:
+                        findings.mark_partial("time_budget")
+                        return findings
+                    if len(line) > _SCAN_MAX_LINE_SIZE:
+                        findings.mark_partial("line_size_limit")
+                        continue
+                    for pattern in patterns:
+                        if time.monotonic() >= deadline:
+                            findings.mark_partial("time_budget")
+                            return findings
+                        if re.search(pattern["pattern"], line):
+                            if len(findings) >= _SCAN_MAX_FINDINGS:
+                                findings.mark_partial("result_limit")
+                                return findings
+                            findings.append(
+                                SecurityFinding(
+                                    scanner="custom",
+                                    severity=pattern.get("severity", "high")
+                                    if category == "pii"
+                                    else "medium",
+                                    category=category,
+                                    title=pattern["title"],
+                                    description=pattern["description"][:200],
+                                    file=rel,
+                                    line=number,
+                                    cwe_id=pattern.get("cwe"),
+                                    owasp_id=pattern.get("owasp"),
+                                    confidence=pattern.get("confidence", "medium"),
+                                )
+                            )
+        except (OSError, ValueError):
+            findings.mark_partial("unreadable_file")
+    if time.monotonic() >= deadline:
+        findings.mark_partial("time_budget")
+    return findings
+
+
+def run_custom_pattern_scan(target_path: str, workspace_root: str) -> PatternScanResult:
+    """Custom evasion patterns with pruning and cooperative scan budgets."""
+    return _run_pattern_scan(
+        target_path, workspace_root, _EVASION_PATTERNS, {".py"}, "sast"
+    )
+
+
+def run_pii_scan(target_path: str, workspace_root: str) -> PatternScanResult:
+    """PII patterns with pruning and cooperative scan budgets."""
+    return _run_pattern_scan(
+        target_path, workspace_root, _PII_PATTERNS, {".py", ".ipynb"}, "pii"
+    )
+
+
+def finding_to_dict(f: SecurityFinding) -> dict:
+    """SecurityFinding을 직렬화 가능한 dict로 변환."""
+    return asdict(f)