codevanta 0.1.0__py3-none-any.whl

codevanta/core/report.py

@@ -0,0 +1,306 @@
+"""Shared analysis helpers used by the CLI and the MCP server."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from codevanta.evidence.confidence import Confidence
+from codevanta.evidence.models import Evidence
+from codevanta.evidence.provenance import Provenance
+
+from .disassembler import Disassembler, DisassemblyError, DisassemblyResult
+from .functions import discover_functions
+from .loader import BinaryInfo, BinaryLoader
+from .strings import StringExtractor
+
+
+class AnalysisError(Exception):
+    """Raised when an analysis request cannot be satisfied."""
+
+
+MAX_DISASSEMBLY_COUNT = 100_000
+MAX_STRING_LIMIT = 200_000
+#: Hard ceiling for ``xref_limit`` (mirrors ``MAX_STRING_LIMIT``).
+MAX_XREF_LIMIT = 200_000
+#: Cross references kept in the report by default (the scan budget stays at
+#: :data:`codevanta.analysis.xrefs.DEFAULT_MAX_BYTES`).
+DEFAULT_XREF_LIMIT = 2_000
+
+#: Ceiling on call-graph nodes embedded in a report (bounded work).
+REPORT_MAX_CALLGRAPH_FUNCTIONS = 1000
+
+#: Ceiling on call-graph edges embedded in a report (bounded work).
+REPORT_MAX_CALLGRAPH_EDGES = 5000
+
+#: Instruction budget for the entry-point CFG embedded in a report (bounded
+#: work; the :func:`codevanta.analysis.cfg.build_cfg` default, made explicit so
+#: the report cap is visible next to the other section caps).
+REPORT_MAX_CFG_INSTRUCTIONS = 2000
+
+#: Block budget for the entry-point CFG embedded in a report (bounded work;
+#: likewise the analyzer default).
+REPORT_MAX_CFG_BLOCKS = 500
+
+
+def load_binary(path: str | Path) -> BinaryInfo:
+    """Load a binary and return normalized metadata."""
+    return BinaryLoader().load(path)
+
+
+def read_code(path: str | Path, info: BinaryInfo, address: int, want_bytes: int) -> bytes:
+    """Read bytes for ``address``; raise when the address is unmapped."""
+    offset = info.va_to_offset(address)
+    section = info.section_for_va(address)
+    if offset is None or section is None:
+        raise AnalysisError(f"address 0x{address:x} is not mapped to file bytes")
+    remaining = (section.offset + (section.raw_size or section.size)) - offset
+    if remaining <= 0:
+        raise AnalysisError(f"address 0x{address:x} has no file bytes")
+    with open(path, "rb") as handle:
+        handle.seek(offset)
+        return handle.read(min(want_bytes, remaining))
+
+
+def resolve_target(info: BinaryInfo, address: int | None, function: str | None) -> int:
+    """Resolve the disassembly start from an address, a function name, or the entry point."""
+    if address is not None:
+        return address
+    if function:
+        match = next((c for c in discover_functions(info) if c.name == function), None)
+        if match is None:
+            raise AnalysisError(f"function {function!r} not found")
+        return match.address
+    if info.entry_point is not None:
+        return info.entry_point
+    raise AnalysisError("no address supplied and binary has no entry point")
+
+
+def disassemble_region(
+    path: str | Path,
+    info: BinaryInfo,
+    start: int,
+    count: int = 50,
+) -> DisassemblyResult:
+    """Disassemble ``count`` instructions at ``start`` inside an executable section."""
+    if count < 1:
+        raise AnalysisError("count must be >= 1")
+    if count > MAX_DISASSEMBLY_COUNT:
+        raise AnalysisError(f"count too large (limit {MAX_DISASSEMBLY_COUNT})")
+    section = info.section_for_va(start)
+    if section is None or not section.is_executable:
+        raise AnalysisError(f"address 0x{start:x} is not inside an executable section")
+    code = read_code(path, info, start, count * 16)
+    disassembler = Disassembler(info.architecture, info.bitness, info.endianness)
+    return disassembler.disassemble(code, base_address=start, max_instructions=count)
+
+
+def _empty_cfg(address: int | None, warnings: list[str]) -> dict[str, Any]:
+    """Build the degraded ``cfg`` payload used when no graph could be produced.
+
+    Mirrors :meth:`codevanta.analysis.cfg.FunctionCFG.to_dict` key for key so
+    consumers of the report can rely on one shape; ``warnings`` carries the
+    reason the sweep produced nothing.
+    """
+    evidence = Evidence(
+        source="cfg.linear_sweep",
+        method="linear_sweep",
+        confidence=Confidence.UNKNOWN,
+        address=address,
+        detail="no blocks; the control-flow graph was not built",
+    )
+    return {
+        "function_address": f"0x{address:x}" if address is not None else None,
+        "function_name": None,
+        "block_count": 0,
+        "instruction_count": 0,
+        "truncated": False,
+        "warnings": list(warnings),
+        "blocks": [],
+        "evidence": evidence.to_dict(),
+    }
+
+
+def build_report(
+    path: str | Path,
+    string_limit: int = 5000,
+    xref_limit: int = DEFAULT_XREF_LIMIT,
+    include_callgraph: bool = False,
+    include_xrefs: bool = False,
+    include_cfg: bool = False,
+) -> dict[str, Any]:
+    """Build the phase 1 JSON report for ``path``.
+
+    The report always contains ``provenance``, ``binary``, ``functions``,
+    ``strings`` and ``disassembly``. Nothing more than the file bytes is read and
+    nothing is executed.
+
+    The phase 2 engines are additive and opt-in, one section each:
+    ``include_xrefs`` adds ``report["xrefs"]``, ``include_cfg`` adds
+    ``report["cfg"]`` and ``include_callgraph`` adds ``report["callgraph"]``.
+    Without those arguments the payload is exactly the phase 1 report, so no
+    existing consumer sees a new key. A requested section whose engine has
+    nothing to decode still appears, as a warning-carrying empty result: the
+    phase 2 sections never fail the report.
+
+    Args:
+        path: Binary to analyse.
+        string_limit: Maximum strings kept under ``report["strings"]``
+            (``0 .. MAX_STRING_LIMIT``).
+        xref_limit: Maximum cross references kept under
+            ``report["xrefs"]["items"]`` (``0 .. MAX_XREF_LIMIT``); ``count``
+            still reports the true total found by the scan.
+        include_callgraph: When true, a ``"callgraph"`` section holding
+            :meth:`~codevanta.analysis.callgraph.CallGraph.to_dict` is added.
+            When false the key is omitted entirely, so the payload is unchanged
+            for callers that do not ask for a graph.
+        include_xrefs: When true, an ``"xrefs"`` section with the scan result and
+            its evidence is added.
+        include_cfg: When true, a ``"cfg"`` section with the entry-point
+            control-flow graph is added.
+
+    Returns:
+        The JSON-serializable report.
+
+    Raises:
+        AnalysisError: If ``string_limit`` or ``xref_limit`` is out of range, or
+            -- when ``include_callgraph`` is true -- if the graph cannot be
+            built. The phase 2 sections never raise: an engine failure degrades
+            to a warning inside that section instead of failing the report.
+
+    Note:
+        **Layering.** :mod:`codevanta.core.report` is a *core* module and must not
+        import :mod:`codevanta.analysis` at import time: that package imports
+        :class:`AnalysisError` from here, so a module-level import would create a
+        cycle and would also drag the analysis layer into every core consumer.
+        The dependency is therefore resolved with a **lazy import inside this
+        function**, executed only when the corresponding section is requested:
+        :func:`~codevanta.analysis.callgraph.build_call_graph` for
+        ``include_callgraph``, :func:`~codevanta.analysis.xrefs.find_xrefs` for
+        ``include_xrefs`` and :func:`~codevanta.analysis.cfg.build_cfg` for
+        ``include_cfg``.
+
+    Note:
+        **Bounded work.** The embedded graph is capped at
+        ``REPORT_MAX_CALLGRAPH_FUNCTIONS`` (1000) nodes and
+        ``REPORT_MAX_CALLGRAPH_EDGES`` (5000) edges, which are well below the
+        call-graph defaults (:data:`~codevanta.analysis.callgraph.DEFAULT_MAX_FUNCTIONS`
+        / ``DEFAULT_MAX_EDGES``) so a report stays a bounded payload. When either
+        cap cuts the result short, ``report["callgraph"]["truncated"]`` is true.
+        The pre-computed function candidates are reused instead of rediscovering
+        them, so the report never scans the binary twice for candidates.
+
+        The requested phase 2 sections are bounded too, and say so in their own
+        payloads. The xref scan decodes at most
+        :data:`~codevanta.analysis.xrefs.DEFAULT_MAX_BYTES` (4 MB) of executable
+        bytes -- a budget cut sets ``report["xrefs"]["scan_truncated"]`` -- and
+        only ``xref_limit`` items are embedded, which sets
+        ``report["xrefs"]["truncated"]`` the same way the strings section
+        reports truncation. The CFG runs with
+        ``REPORT_MAX_CFG_INSTRUCTIONS`` (2000) instructions and
+        ``REPORT_MAX_CFG_BLOCKS`` (500) blocks, the analyzer's own defaults made
+        explicit, and marks ``report["cfg"]["truncated"]`` when either limit cut
+        the sweep.
+    """
+    if string_limit < 0:
+        raise AnalysisError("string_limit must be >= 0")
+    if string_limit > MAX_STRING_LIMIT:
+        raise AnalysisError(f"string_limit too large (limit {MAX_STRING_LIMIT})")
+    if xref_limit < 0:
+        raise AnalysisError("xref_limit must be >= 0")
+    if xref_limit > MAX_XREF_LIMIT:
+        raise AnalysisError(f"xref_limit too large (limit {MAX_XREF_LIMIT})")
+
+    info = load_binary(path)
+    provenance = (
+        Provenance()
+        .add_step("load_binary")
+        .add_step("discover_functions")
+        .add_step("extract_strings")
+    )
+    candidates = discover_functions(info)
+    all_strings = StringExtractor(min_length=4).extract(path, info=info)
+    kept = all_strings[:string_limit]
+    disassembly: dict[str, Any] | None = None
+    if info.entry_point is not None:
+        try:
+            disassembly = disassemble_region(path, info, info.entry_point, count=32).to_dict()
+        except (AnalysisError, DisassemblyError):
+            disassembly = None
+    xrefs_payload: dict[str, Any] | None = None
+    cfg_payload: dict[str, Any] | None = None
+    if include_xrefs:
+        # Lazy import on purpose: core must not import the analysis package at
+        # module import time (analysis imports AnalysisError from this module),
+        # and a caller that does not want the section pays nothing for it.
+        from codevanta.analysis.xrefs import DEFAULT_MAX_BYTES, find_xrefs
+
+        provenance.add_step("find_xrefs")
+        # find_xrefs never raises for undecodable input: it reports degraded
+        # coverage through warnings (no executable sections, unsupported
+        # architecture, unreadable sections) that are passed straight through.
+        xref_scan = find_xrefs(path, info, functions=candidates, max_bytes=DEFAULT_MAX_BYTES)
+        kept_xrefs = xref_scan.xrefs[:xref_limit]
+        xrefs_payload = {
+            "count": len(xref_scan.xrefs),
+            "returned": len(kept_xrefs),
+            "truncated": len(kept_xrefs) < len(xref_scan.xrefs),
+            "items": [xref.to_dict() for xref in kept_xrefs],
+            "scanned_sections": list(xref_scan.scanned_sections),
+            "scanned_bytes": xref_scan.scanned_bytes,
+            "scan_truncated": xref_scan.truncated,
+            "indirect_skipped": xref_scan.indirect_skipped,
+            "warnings": list(xref_scan.warnings),
+            "evidence": xref_scan.evidence.to_dict(),
+        }
+    if include_cfg:
+        # Lazy import, same reason as find_xrefs above.
+        from codevanta.analysis.cfg import build_cfg
+
+        provenance.add_step("build_cfg")
+        if info.entry_point is None:
+            cfg_payload = _empty_cfg(None, ["no entry point; control-flow graph not built"])
+        else:
+            try:
+                cfg_payload = build_cfg(
+                    path,
+                    info,
+                    info.entry_point,
+                    max_instructions=REPORT_MAX_CFG_INSTRUCTIONS,
+                    max_blocks=REPORT_MAX_CFG_BLOCKS,
+                ).to_dict()
+            except (AnalysisError, DisassemblyError) as exc:
+                cfg_payload = _empty_cfg(
+                    info.entry_point, [f"control-flow graph not built: {exc}"]
+                )
+
+    report: dict[str, Any] = {
+        "provenance": provenance.to_dict(),
+        "binary": info.to_dict(),
+        "functions": [c.to_dict() for c in candidates],
+        "strings": {
+            "count": len(all_strings),
+            "returned": len(kept),
+            "truncated": len(kept) < len(all_strings),
+            "items": [s.to_dict() for s in kept],
+        },
+        "disassembly": disassembly,
+    }
+    if include_callgraph:
+        # Lazy import on purpose: core must not import the analysis package at
+        # module import time (analysis imports AnalysisError from this module).
+        from codevanta.analysis.callgraph import build_call_graph
+
+        graph = build_call_graph(
+            path,
+            info,
+            functions=candidates,
+            max_functions=REPORT_MAX_CALLGRAPH_FUNCTIONS,
+            max_edges=REPORT_MAX_CALLGRAPH_EDGES,
+        )
+        report["callgraph"] = graph.to_dict()
+    if xrefs_payload is not None:
+        report["xrefs"] = xrefs_payload
+    if cfg_payload is not None:
+        report["cfg"] = cfg_payload
+    return report

codevanta/core/strings.py

@@ -0,0 +1,109 @@
+"""ASCII and UTF-16 string extraction with location mapping.
+
+The UTF-16 byte order follows the binary's endianness when metadata is
+available: little-endian targets are scanned as UTF-16LE, big-endian targets
+as UTF-16BE. Without metadata the scan defaults to UTF-16LE and never guesses
+a byte swap, so little-endian results cannot be fabricated from shifted
+matches inside big-endian data (and vice versa).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from codevanta.evidence.confidence import Confidence
+from codevanta.evidence.models import Evidence
+
+from .loader import BinaryInfo
+
+
+@dataclass(frozen=True)
+class StringResult:
+    """A string found in the file with its offset and mapped address."""
+
+    offset: int
+    address: int | None
+    text: str
+    encoding: str
+    length: int
+    evidence: Evidence
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "offset": f"0x{self.offset:x}",
+            "text": self.text,
+            "encoding": self.encoding,
+            "length": self.length,
+        }
+        if self.address is not None:
+            data["address"] = f"0x{self.address:x}"
+        return data
+
+
+class StringExtractor:
+    """Extracts printable ASCII and UTF-16 strings from a file.
+
+    UTF-16 output uses the byte order of ``BinaryInfo.endianness`` when
+    metadata is supplied; see the module docstring for the no-metadata rule.
+    """
+
+    def __init__(self, min_length: int = 4) -> None:
+        if min_length < 1:
+            raise ValueError("min_length must be >= 1")
+        self.min_length = min_length
+
+    def extract(
+        self,
+        path: str | Path,
+        info: BinaryInfo | None = None,
+        limit: int = 0,
+    ) -> list[StringResult]:
+        """Extract strings from ``path``; ``limit`` caps the result count.
+
+        ASCII strings are always scanned. UTF-16 strings are scanned in the
+        byte order of the binary when ``info`` is given (little-endian targets
+        as UTF-16LE, big-endian targets as UTF-16BE); without ``info`` the
+        scan stays at UTF-16LE rather than guessing a byte swap.
+        """
+        data = Path(path).read_bytes()
+        results: list[StringResult] = []
+        ascii_pattern = re.compile(rb"[\x20-\x7e]{%d,}" % self.min_length)
+        for match in ascii_pattern.finditer(data):
+            text = match.group().decode("ascii", errors="replace")
+            results.append(self._result(match.start(), text, "ascii", info))
+        if info is not None and info.endianness == "big":
+            utf16_pattern = re.compile(rb"(?:\x00[\x20-\x7e]){%d,}" % self.min_length)
+            codec, label = "utf-16-be", "utf-16be"
+        else:
+            utf16_pattern = re.compile(rb"(?:[\x20-\x7e]\x00){%d,}" % self.min_length)
+            codec, label = "utf-16-le", "utf-16le"
+        results.extend(
+            self._result(match.start(), match.group().decode(codec, errors="replace"), label, info)
+            for match in utf16_pattern.finditer(data)
+        )
+        results.sort(key=lambda r: (r.offset, r.encoding))
+        if limit and len(results) > limit:
+            return results[:limit]
+        return results
+
+    @staticmethod
+    def _result(offset: int, text: str, encoding: str, info: BinaryInfo | None) -> StringResult:
+        address = info.offset_to_va(offset) if info is not None else None
+        evidence = Evidence(
+            source="string_scanner",
+            method=f"{encoding}_scan",
+            confidence=Confidence.HIGH if address is not None else Confidence.MEDIUM,
+            address=address,
+            detail=f"{encoding} string, {len(text)} chars",
+        )
+        return StringResult(
+            offset=offset,
+            address=address,
+            text=text,
+            encoding=encoding,
+            length=len(text),
+            evidence=evidence,
+        )

codevanta/evidence/__init__.py

@@ -0,0 +1,7 @@
+"""Evidence, provenance, and confidence primitives for CODEVANTA."""
+
+from .confidence import Confidence
+from .models import Evidence
+from .provenance import Provenance, utc_now_iso
+
+__all__ = ["Confidence", "Evidence", "Provenance", "utc_now_iso"]

codevanta/evidence/confidence.py

@@ -0,0 +1,36 @@
+"""Confidence levels for analysis findings.
+
+The engine never presents a guess as a certainty. Every finding carries one of
+these levels and, where useful, the numeric ``score`` for ordering.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Confidence(str, Enum):
+    """How strongly a finding is supported by evidence."""
+
+    CERTAIN = "certain"  # direct, unambiguous data from the file format
+    HIGH = "high"        # strong structural evidence (e.g. export table)
+    MEDIUM = "medium"    # indirect evidence (e.g. entry point)
+    LOW = "low"          # weak or inferred evidence
+    UNKNOWN = "unknown"  # no confidence can be established
+
+    def __str__(self) -> str:
+        return self.value
+
+    @property
+    def score(self) -> float:
+        """Normalized weight in [0.0, 1.0] used for ordering and merging."""
+        return _SCORES[self]
+
+
+_SCORES: dict[Confidence, float] = {
+    Confidence.CERTAIN: 1.0,
+    Confidence.HIGH: 0.8,
+    Confidence.MEDIUM: 0.5,
+    Confidence.LOW: 0.2,
+    Confidence.UNKNOWN: 0.0,
+}

codevanta/evidence/models.py

@@ -0,0 +1,43 @@
+"""Evidence records that justify every analysis finding."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .confidence import Confidence
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """A traceable justification for a single analysis finding.
+
+    Attributes:
+        source: Where the finding came from, e.g. ``"pe.export_table"``.
+        method: How it was obtained, e.g. ``"export_directory"``.
+        confidence: How reliable the finding is.
+        address: Optional virtual address the evidence refers to.
+        detail: Optional human-readable note.
+        extra: Optional structured metadata for the report.
+    """
+
+    source: str
+    method: str
+    confidence: Confidence = Confidence.UNKNOWN
+    address: int | None = None
+    detail: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "source": self.source,
+            "method": self.method,
+            "confidence": self.confidence.value,
+        }
+        if self.address is not None:
+            data["address"] = f"0x{self.address:x}"
+        if self.detail:
+            data["detail"] = self.detail
+        if self.extra:
+            data["extra"] = dict(self.extra)
+        return data

codevanta/evidence/provenance.py

@@ -0,0 +1,37 @@
+"""Provenance tracking for analysis runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+def utc_now_iso() -> str:
+    """Return the current UTC time as an ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class Provenance:
+    """Records how a report or finding was produced."""
+
+    tool: str = "codevanta"
+    tool_version: str = "0.1.0"
+    created_at: str = field(default_factory=utc_now_iso)
+    steps: list[str] = field(default_factory=list)
+
+    def add_step(self, step: str) -> Provenance:
+        """Append a processing step and return ``self`` for chaining."""
+        if not step:
+            raise ValueError("step must not be empty")
+        self.steps.append(step)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tool": self.tool,
+            "tool_version": self.tool_version,
+            "created_at": self.created_at,
+            "steps": list(self.steps),
+        }

codevanta/gui/__init__.py

@@ -0,0 +1,46 @@
+"""Local, dependency-free web dashboard for CODEVANTA.
+
+The GUI is a standard-library-only HTTP server bound to loopback. It exposes the
+existing analysis engines over a small JSON API and serves one self-contained
+HTML page, so a single command is enough to try CODEVANTA in a browser::
+
+    from codevanta.gui import serve
+
+    serve()                      # http://127.0.0.1:8765/
+
+Nothing here reimplements analysis: every route delegates to the CLI/MCP engine
+of the same name, keeps its bounds and returns its evidence payload. The server
+is read-only (it parses bytes, never executes or writes them) and refuses to bind
+anything but a loopback address.
+
+Public API:
+
+* :func:`~codevanta.gui.layout.render_dashboard_html` -- the dashboard page.
+* :func:`~codevanta.gui.server.create_server` -- a bound, unstarted server.
+* :func:`~codevanta.gui.server.create_handler` -- the request-handler class.
+* :func:`~codevanta.gui.server.serve` -- bind, print the URL, serve until Ctrl+C.
+"""
+
+from __future__ import annotations
+
+from .layout import render_dashboard_html
+from .server import (
+    MAX_RESPONSE_BYTES,
+    ROUTES,
+    VERSION,
+    create_handler,
+    create_server,
+    normalize_host,
+    serve,
+)
+
+__all__ = [
+    "MAX_RESPONSE_BYTES",
+    "ROUTES",
+    "VERSION",
+    "create_handler",
+    "create_server",
+    "normalize_host",
+    "render_dashboard_html",
+    "serve",
+]