sourcecode 4.7.0__py3-none-any.whl → 4.9.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "4.7.0"
+__version__ = "4.9.0"

sourcecode/audit_report.py

@@ -0,0 +1,147 @@
+"""Signed audit report over existing ASK evidence.
+
+This module packages facts other commands already publish. It does not score ROI,
+choose a fix, or introduce a second judgement layer: the report summary is a
+reader-friendly index over the embedded evidence blocks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode import __version__
+
+AUDIT_REPORT_SCHEMA = "audit-report-v1"
+
+
+def _canonical_json(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _sign(payload: dict[str, Any], key: bytes) -> dict[str, str]:
+    canonical = _canonical_json(payload)
+    return {
+        "algorithm": "hmac-sha256",
+        "payload_sha256": hashlib.sha256(canonical).hexdigest(),
+        "key_id": hashlib.sha256(key).hexdigest()[:12],
+        "signature": hmac.new(key, canonical, hashlib.sha256).hexdigest(),
+    }
+
+
+def build_audit_report(
+    root: Path,
+    *,
+    profiles: Optional[set[str]] = None,
+    sign_key: Optional[bytes] = None,
+    risk_limit: int = 10,
+) -> dict[str, Any]:
+    """Build the buyer-readable audit bundle from existing command payloads."""
+    from sourcecode.posture import build_posture
+    from sourcecode.risk import build_risk
+
+    root = Path(root).resolve()
+    risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+    posture = build_posture(root, profiles or set())
+    top_risks = risk.get("risks", [])[:risk_limit]
+    access = ((posture.get("endpoints") or {}).get("effective_access") or {})
+
+    unsigned: dict[str, Any] = {
+        "schema_version": AUDIT_REPORT_SCHEMA,
+        "tool": {"name": "ask", "version": __version__},
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "repository": {"path": str(root)},
+        **({"profile_set": sorted(profiles)} if profiles else {}),
+        "summary": {
+            "risk_model": risk.get("model"),
+            "total_defects": risk.get("total_defects"),
+            "total_findings": risk.get("total_findings"),
+            "risk_bands": risk.get("by_band", {}),
+            "top_risks_shown": len(top_risks),
+            "endpoint_access": access.get("summary", {}),
+            "unresolved_beans": len(posture.get("unresolved") or []),
+        },
+        "top_risks": top_risks,
+        "evidence": {
+            "risk": risk,
+            "posture": posture,
+        },
+        "limits": {
+            "statement": (
+                "This report packages existing ASK evidence. It does not certify "
+                "compliance, choose fixes, assign ROI, or replace a human audit decision."
+            ),
+            "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
+        },
+    }
+    # Sign and publish the same JSON-normalized material. Some embedded evidence
+    # may contain tuples or other JSON-coercible values; normalizing before signing
+    # avoids a signature over an in-memory shape the user never receives.
+    normalized = json.loads(_canonical_json(unsigned).decode("utf-8"))
+    if sign_key:
+        normalized["signature"] = _sign(normalized, sign_key)
+    return normalized
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    """Human report renderer over the JSON contract."""
+    summary = report.get("summary") or {}
+    repo = (report.get("repository") or {}).get("path", "")
+    profile = ", ".join(report.get("profile_set") or []) or "default"
+    lines = [
+        "# ASK Audit Report",
+        "",
+        f"- Repository: `{repo}`",
+        f"- ASK version: `{(report.get('tool') or {}).get('version', '')}`",
+        f"- Profile set: `{profile}`",
+        f"- Total defects: `{summary.get('total_defects')}`",
+        f"- Risk bands: `{summary.get('risk_bands')}`",
+        f"- Endpoint access: `{summary.get('endpoint_access')}`",
+        "",
+        "## Top Risks",
+        "",
+    ]
+    risks = report.get("top_risks") or []
+    if not risks:
+        lines.append("No composed risks were reported.")
+    else:
+        lines.extend([
+            "| Band | Score | Rules | File | Line | Title |",
+            "|---|---:|---|---|---:|---|",
+        ])
+        for row in risks:
+            rules = ", ".join(str(r) for r in row.get("rule_ids", []))
+            lines.append(
+                "| "
+                + " | ".join([
+                    str(row.get("band", "")),
+                    str(row.get("severity_effective", "")),
+                    rules,
+                    str(row.get("source_file", "")),
+                    str(row.get("first_line", "")),
+                    str(row.get("title", "")).replace("|", "\\|"),
+                ])
+                + " |"
+            )
+    lines.extend([
+        "",
+        "## Limits",
+        "",
+        str((report.get("limits") or {}).get("statement", "")),
+    ])
+    signature = report.get("signature")
+    if isinstance(signature, dict):
+        lines.extend([
+            "",
+            "## Signature",
+            "",
+            f"- Algorithm: `{signature.get('algorithm')}`",
+            f"- Payload SHA-256: `{signature.get('payload_sha256')}`",
+            f"- Key ID: `{signature.get('key_id')}`",
+            f"- Signature: `{signature.get('signature')}`",
+        ])
+    return "\n".join(lines) + "\n"