ecdat 0.2.0__py3-none-any.whl

ecdat_core/cli.py

@@ -0,0 +1,202 @@
+"""Command-line interface and scan orchestrator for ECDAT.
+
+Public API:
+    - :func:`run_scan` — orchestrate a full scan (ingest -> detect -> assess
+      -> recommend -> assemble) and return a :class:`ScanResult`.
+    - :func:`main` — console entrypoint for both the ``ecdat`` command
+      (registered via ``[project.scripts]`` in pyproject.toml as
+      ``ecdat = "ecdat_core.cli:main"``) and the ``python -m ecdat_core.cli``
+      module invocation. Argparse resolves ``argv=None`` to ``sys.argv[1:]``,
+      so the setuptools-generated wrapper calling ``main()`` with no arguments
+      behaves identically to the module form.
+
+The ``scan`` subcommand runs :func:`run_scan` over a local directory or git
+URL, writes ``cbom.json`` and ``summary.json`` to the current working
+directory, and prints a human-readable summary table to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+from ecdat_core.cbom_export import export_cbom, export_summary
+from ecdat_core.detector import scan_file_content
+from ecdat_core.ingestion import ingest_git_url, ingest_local_directory
+from ecdat_core.models import Detection, ScanResult
+from ecdat_core.recommender import recommend
+from ecdat_core.risk_engine import assess_risk
+from ecdat_core.signature_loader import SignatureEntry, get_all_signatures
+
+_RISK_ORDER = ("critical", "high", "medium", "low", "quantum-safe")
+
+
+def run_scan(
+    target: str,
+    is_git_url: bool = False,
+    *,
+    sandboxed: bool = True,
+) -> ScanResult:
+    """Orchestrate a full ECDAT scan and return the assembled result.
+
+    Args:
+        target: A local directory path, or a Git repository URL when
+            ``is_git_url`` is ``True``.
+        is_git_url: When ``True``, treat *target* as a Git URL to shallow
+            clone before scanning.
+        sandboxed: When ``True`` (the default), a user-supplied local path is
+            enforced inside ``SCAN_WORKSPACE_ROOT`` by
+            :func:`~ecdat_core.ingestion.validate_local_path` — this is what
+            the FastAPI backend relies on, so the default must stay ``True``.
+            The pip-installed ``ecdat`` CLI passes ``sandboxed=False`` because
+            there the invoking user is the trust boundary.  Has no effect on
+            git-URL scans: the directory :func:`~ecdat_core.ingestion.ingest_git_url`
+            creates is always scanner-owned and therefore never sandboxed.
+
+    Returns:
+        A fully populated :class:`ScanResult` with detections, risk
+        assessments, and recommendations for every cryptographic artefact
+        discovered, plus a ``files_scanned`` count.
+    """
+    if is_git_url:
+        scan_target = target
+        # The cloned directory below is scanner-created (tempfile.mkdtemp,
+        # mode 0700, ephemeral) — not a user-supplied path — so scanning it is
+        # exempt from the local-path sandbox.  The user-controlled git URL
+        # itself has already passed validate_git_url inside ingest_git_url.
+        local_path = ingest_git_url(target)
+        ingest_sandboxed = False
+    else:
+        scan_target = str(Path(target).resolve())
+        local_path = target
+        # User-supplied path: honour the caller's sandbox policy.  Defaults to
+        # sandboxed so existing callers (including the backend) are unchanged.
+        ingest_sandboxed = sandboxed
+
+    signatures = _signature_lookup()
+
+    detections: list[Detection] = []
+    files_scanned = 0
+
+    for file_path, content, language in ingest_local_directory(
+        local_path, sandboxed=ingest_sandboxed
+    ):
+        files_scanned += 1
+        detections.extend(scan_file_content(file_path, content, language))
+
+    return _assemble(scan_target, detections, signatures, files_scanned)
+
+
+def _signature_lookup() -> dict[str, SignatureEntry]:
+    """Return a map of signature name -> entry for fast lookups."""
+    return {entry.name: entry for entry in get_all_signatures()}
+
+
+def _assemble(
+    target: str,
+    detections: list[Detection],
+    signatures: dict[str, SignatureEntry],
+    files_scanned: int,
+) -> ScanResult:
+    """Assess risk, recommend, and package everything into a ScanResult."""
+    risk_assessments = []
+    recommendations = []
+
+    for detection in detections:
+        entry = signatures.get(detection.algorithm_family)
+        if entry is None:
+            continue
+        risk_assessments.append(assess_risk(detection, entry))
+        recommendations.append(recommend(detection, entry))
+
+    return ScanResult(
+        scan_id=str(uuid4()),
+        target=target,
+        detections=detections,
+        risk_assessments=risk_assessments,
+        recommendations=recommendations,
+        scanned_at=datetime.now(timezone.utc).isoformat(),
+        files_scanned=files_scanned,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the ECDAT CLI; return a process exit code.
+
+    Args:
+        argv: Argument list; defaults to ``sys.argv[1:]``.
+
+    Returns:
+        ``0`` on success, ``2`` on argument misuse, ``1`` on scan failure.
+    """
+    parser = argparse.ArgumentParser(
+        prog="ecdat",
+        description="Cryptographic Discovery & Analysis Tool",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan_parser = subparsers.add_parser(
+        "scan", help="Scan a local directory or git repository"
+    )
+    scan_parser.add_argument(
+        "path", help="Local directory path, or git URL with --git-url"
+    )
+    scan_parser.add_argument(
+        "--git-url",
+        action="store_true",
+        help="Treat PATH as a git repository URL to clone",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command != "scan":
+        parser.error("unknown command")
+
+    try:
+        result = run_scan(args.path, is_git_url=args.git_url)
+    except (OSError, RuntimeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    _write_outputs(result)
+    _print_summary(result)
+    return 0
+
+
+def _write_outputs(result: ScanResult) -> None:
+    """Write cbom.json and summary.json into the current directory."""
+    _write_json("cbom.json", export_cbom(result))
+    _write_json("summary.json", export_summary(result))
+
+
+def _write_json(filename: str, payload: dict) -> None:
+    """Write a dict as pretty-printed JSON to *filename* in the cwd."""
+    with Path(filename).open("w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+    print(f"wrote {filename}")
+
+
+def _print_summary(result: ScanResult) -> None:
+    """Print a human-readable scan summary table to stdout."""
+    counts = {level: 0 for level in _RISK_ORDER}
+    for assessment in result.risk_assessments:
+        counts[assessment.risk_level] = counts.get(assessment.risk_level, 0) + 1
+
+    print()
+    print(f"Scan target : {result.target}")
+    print(f"Files scanned: {result.files_scanned}")
+    print(f"Detections  : {len(result.detections)}")
+    print("-" * 32)
+    print(f"{'Risk level':<16}{'Count':>6}")
+    print("-" * 32)
+    for level in _RISK_ORDER:
+        print(f"{level:<16}{counts[level]:>6}")
+    print("-" * 32)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ecdat_core/detector.py

@@ -0,0 +1,273 @@
+"""Regex-based detection engine for ECDAT.
+
+Scans source file content line-by-line against the cryptographic signature
+knowledge base and emits :class:`Detection` records for every regex match.
+
+Public API:
+    - :func:`detect_language` -> map a file path's extension to an ECDAT
+      language key, or ``None`` if the file type is unsupported.
+    - :func:`scan_file_content` -> run all language signatures against content
+      and return the resulting detections.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ecdat_core.models import Detection
+from ecdat_core.signature_loader import SignatureEntry, get_signatures_for_language
+
+# Extensions -> ECDAT language key. Case is normalised before lookup.
+_EXTENSION_TO_LANGUAGE: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript",
+    ".ts": "javascript",
+    ".java": "java",
+    ".go": "go",
+    ".c": "c_cpp",
+    ".cpp": "c_cpp",
+    ".h": "c_cpp",
+}
+
+# Maximum length of the stored matched_text substring.
+MAX_MATCHED_TEXT_LENGTH = 200
+
+# Deterministic confidence values: an exact API call is a very strong signal,
+# while a looser import-only or bare-keyword match is weaker.
+CONFIDENCE_API_CALL = 1.0
+CONFIDENCE_IMPORT_KEYWORD = 0.6
+
+# Matches a call-like invocation in matched text, e.g. ``RSA.generate(`` or
+# ``hashlib.md5(`` — an identifier immediately followed by an opening paren.
+_API_CALL_RE = re.compile(r"\w+\s*\(")
+
+# Families whose asset type is literally an algorithm. The current knowledge
+# base only defines these families; certificate/protocol families are mapped
+# defensively in case they are added later.
+_ALGORITHM_FAMILIES = frozenset(
+    {
+        "asymmetric-encryption",
+        "signature",
+        "hash",
+        "symmetric-encryption",
+        "pqc-kem",
+        "pqc-signature",
+    }
+)
+
+
+def detect_language(file_path: str) -> str | None:
+    """Map a file path's extension to an ECDAT language key.
+
+    Args:
+        file_path: Path to the source file (only the extension is inspected).
+
+    Returns:
+        The ECDAT language key (e.g. "python", "javascript", "c_cpp") for a
+        supported extension, or ``None`` for an unsupported / missing one so
+        callers can skip such files.
+    """
+    suffix = _extension_of(file_path)
+    return _EXTENSION_TO_LANGUAGE.get(suffix)
+
+
+def _extension_of(file_path: str) -> str:
+    """Return the lowercased file extension including the dot.
+
+    Returns an empty string when the path has no extension.
+    """
+    name = file_path.rsplit("/", 1)[-1]
+    dot = name.rfind(".")
+    if dot <= 0:  # dot at index 0 means a hidden file such as ".gitignore"
+        return ""
+    return name[dot:].lower()
+
+
+def scan_file_content(
+    file_path: str, content: str, language: str
+) -> list[Detection]:
+    """Run the language's signatures against content and collect detections.
+
+    Args:
+        file_path: Path to the file being scanned (stored on each detection).
+        content: Full source file content as a string.
+        language: An ECDAT language key, e.g. "python" or "java".
+
+    Returns:
+        list[Detection]: One detection per regex match found, in a
+        deterministic order derived from line / pattern ordering.
+    """
+    detections: list[Detection] = []
+    lines = content.split("\n")
+
+    for signature in get_signatures_for_language(language):
+        patterns = signature.patterns.get(language, [])
+        asset_type = _asset_type_for_family(signature.family)
+
+        # Collect every raw regex match for this signature, then collapse the
+        # ones that resolved to the same physical line. A signature entry often
+        # carries several pattern strings (import-style, call-site, bare
+        # keyword) that can legitimately co-occur on a single line — e.g. a
+        # one-line usage that matches both an import pattern and a call pattern,
+        # or `\bAES\b` matching inside `AES-256`. Those describe ONE real-world
+        # cryptographic usage, so they must yield exactly one Detection.
+        raw_matches: list[Detection] = []
+        for pattern in patterns:
+            compiled = re.compile(pattern)
+            for line_index, line in enumerate(lines):
+                line_number = line_index + 1
+                key_size_bits = _extract_key_size(
+                    signature.key_size_pattern, line
+                )
+                for match in compiled.finditer(line):
+                    raw_matches.append(
+                        Detection(
+                            file_path=file_path,
+                            line_number=line_number,
+                            matched_text=_trim_match(match.group(0)),
+                            asset_type=asset_type,
+                            algorithm_family=signature.name,
+                            key_size_bits=key_size_bits,
+                            quantum_vulnerable=_resolve_quantum_vulnerable(
+                                signature, key_size_bits
+                            ),
+                            classically_broken=signature.classically_broken,
+                            confidence=_compute_confidence(match.group(0)),
+                            language=language,
+                            detection_method="regex",
+                        )
+                    )
+
+        detections.extend(_dedupe_detections(raw_matches))
+    return detections
+
+
+def _dedupe_detections(detections: list[Detection]) -> list[Detection]:
+    """Collapse same-line duplicates within a single signature's matches.
+
+    When several pattern strings of the same signature entry match the same
+    physical line (e.g. an import-style pattern and a call-site pattern both
+    firing on a one-line usage, or the ``\\bAES\\b`` bare-keyword pattern
+    matching inside ``AES-256``), they all describe the same real-world
+    cryptographic usage and must be collapsed into a single :class:`Detection`.
+
+    The caller passes matches from a *single* signature for a *single* file, so
+    keying on ``line_number`` here is equivalent to the (signature, file_path,
+    line_number) identity that defines one cryptographic usage.
+
+    Tie-break rule, applied deterministically per line:
+        1. Prefer the highest-confidence match — an exact API call scores 1.0
+           vs a looser import/bare-keyword match at 0.6.
+        2. If confidences tie, prefer the most specific pattern, i.e. the one
+           whose matched text is longest (``hashlib.md5(`` over ``md5(``, or
+           ``AES-256`` over a bare ``AES``). A longer match captures a more
+           precisely specified construct and better represents the real usage.
+
+    Each non-collapsed line keeps its first-seen position so the overall output
+    order stays stable and deterministic.
+
+    Args:
+        detections: Raw matches produced by one signature against one file.
+
+    Returns:
+        A deduplicated list with at most one :class:`Detection` per line.
+    """
+    best_by_line: dict[int, Detection] = {}
+    first_seen: list[int] = []
+
+    for detection in detections:
+        line = detection.line_number
+        current = best_by_line.get(line)
+        if current is None:
+            best_by_line[line] = detection
+            first_seen.append(line)
+        elif _is_better_match(detection, current):
+            best_by_line[line] = detection
+
+    return [best_by_line[line] for line in first_seen]
+
+
+def _is_better_match(candidate: Detection, current: Detection) -> bool:
+    """Report whether *candidate* should replace *current* on the same line.
+
+    Higher confidence wins; on a confidence tie, the more specific pattern's
+    longer matched text wins (see :func:`_dedupe_detections`).
+    """
+    if candidate.confidence != current.confidence:
+        return candidate.confidence > current.confidence
+    return len(candidate.matched_text) > len(current.matched_text)
+
+
+def _asset_type_for_family(family: str) -> str:
+    """Map a signature family to a CycloneDX asset type.
+
+    Algorithm families map to ``algorithm``; certificate and protocol families
+    map to their corresponding asset types.
+    """
+    if family in _ALGORITHM_FAMILIES or "algorithm" in family:
+        return "algorithm"
+    if "certificate" in family:
+        return "certificate"
+    if "protocol" in family:
+        return "protocol"
+    return "related-crypto-material"
+
+
+def _trim_match(matched_text: str) -> str:
+    """Trim matched text to at most :data:`MAX_MATCHED_TEXT_LENGTH` chars."""
+    if len(matched_text) <= MAX_MATCHED_TEXT_LENGTH:
+        return matched_text
+    return matched_text[:MAX_MATCHED_TEXT_LENGTH]
+
+
+def _extract_key_size(
+    key_size_pattern: str | None, line: str
+) -> int | None:
+    """Extract a key size in bits from a line, or None when not determinable."""
+    if not key_size_pattern:
+        return None
+    match = re.search(key_size_pattern, line)
+    if not match:
+        return None
+    return _digits_from_groups(match)
+
+
+def _digits_from_groups(match: re.Match[str]) -> int | None:
+    """Return the first all-digit capture group as an int, else None."""
+    for group in match.groups():
+        if group is not None and group.isdigit():
+            return int(group)
+    # Fall back to the whole match if no group holds a pure number.
+    digits = "".join(ch for ch in match.group(0) if ch.isdigit())
+    return int(digits) if digits else None
+
+
+def _compute_confidence(matched_text: str) -> float:
+    """Return a deterministic confidence for a matched substring.
+
+    An exact API-call match (an identifier immediately followed by an opening
+    parenthesis, e.g. ``RSA.generate(``) is scored 1.0. Looser import-only or
+    bare-keyword matches (e.g. ``from ... import RSA`` or a lone ``\bMD5\b``)
+    are scored 0.6.
+    """
+    if _API_CALL_RE.search(matched_text):
+        return CONFIDENCE_API_CALL
+    return CONFIDENCE_IMPORT_KEYWORD
+
+
+def _resolve_quantum_vulnerable(
+    signature: SignatureEntry, key_size_bits: int | None
+) -> bool:
+    """Resolve quantum-vulnerability for a single detection.
+
+    Symmetric ciphers with a ``min_quantum_safe_key_bits`` threshold are
+    evaluated dynamically per-detection: a key size at or above the threshold
+    (e.g. AES-192/256) is quantum-safe, while a smaller extracted size is
+    flagged. When no key size could be extracted the signature's static
+    ``quantum_vulnerable`` applies unchanged — for AES that is the conservative
+    ``True`` default.
+    """
+    threshold = signature.min_quantum_safe_key_bits
+    if threshold is not None and key_size_bits is not None:
+        return key_size_bits < threshold
+    return signature.quantum_vulnerable