mobileguard 1.0.0__py3-none-any.whl

mobileguard/__init__.py

@@ -0,0 +1,52 @@
+# Copyright 2026 Jaspreet Singh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+"""MobileGuard — AI governance for consumer mobile platforms.
+
+Reference implementation of the MobileGuard governance framework described in:
+  "MobileGuard: A Stack-Agnostic Governance Framework for Agentic AI
+   Across Consumer Mobile Delivery Platforms"
+  Jaspreet Singh · arXiv:XXXX.XXXXX · 2026
+
+Four governance pillars:
+  PDQC  — Pre-Deployment Quality Contracting   (mobileguard contract)
+  TAC-M — Tiered Autonomy Calibration for Mobile (mobileguard tier)
+  PGSG  — Platform Gatekeeper Simulation Gates  (mobileguard scan)
+  AABE  — Ambient Agent Boundary Enforcement    (mobileguard scan)
+
+MobileGuard does not collect telemetry, send analytics, or phone home.
+All analysis is performed locally. The only outbound network calls are to
+the Anthropic API when --llm is passed to `scan` or when running `contract`.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Jaspreet Singh"
+__license__ = "Apache-2.0"
+
+from mobileguard.models import (
+    AuditReport,
+    ContractVerdict,
+    Finding,
+    Platform,
+    RuleCategory,
+    Severity,
+    ScanResult,
+    TierResult,
+)
+
+__all__ = [
+    "__version__",
+    "AuditReport",
+    "ContractVerdict",
+    "Finding",
+    "Platform",
+    "RuleCategory",
+    "Severity",
+    "ScanResult",
+    "TierResult",
+]

mobileguard/audit.py

@@ -0,0 +1,297 @@
+# Copyright 2026 Jaspreet Singh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+"""PGSG — Platform Gatekeeper Simulation.
+
+Generates structured compliance audit reports for mobileguard audit.
+Maps to EU AI Act Article 50, Apple Guideline 5.1.2(i), and Google Play AI policy.
+Supports markdown, JSON, and HTML output formats.
+PDF export is planned for v1.1 — convert HTML output using your browser's print-to-PDF.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mobileguard import __version__
+from mobileguard.models import AuditReport, Finding, Platform, RuleCategory, Severity, ScanResult
+
+_AI_DOMAIN_RE = re.compile(
+    r"https?://(?:api\.openai\.com|api\.anthropic\.com|"
+    r"generativelanguage\.googleapis\.com|[\w\-]+\.openai\.azure\.com|"
+    r"api\.cohere\.ai|api\.mistral\.ai|api\.groq\.com)",
+    re.IGNORECASE,
+)
+
+_AI_FEATURE_PATTERNS = [
+    (re.compile(r"api\.anthropic\.com", re.I), "Anthropic Claude API (external)"),
+    (re.compile(r"api\.openai\.com", re.I), "OpenAI API (external)"),
+    (re.compile(r"generativelanguage\.googleapis\.com", re.I), "Google Gemini API (external)"),
+    (re.compile(r"openai\.azure\.com", re.I), "Azure OpenAI (external)"),
+    (re.compile(r"api\.cohere\.ai", re.I), "Cohere API (external)"),
+    (re.compile(r"MLKit|ml_kit", re.I), "Google ML Kit (on-device)"),
+    (re.compile(r"CoreML|\.mlmodel", re.I), "Core ML (on-device)"),
+    (re.compile(r"CreateML", re.I), "Create ML (on-device)"),
+    (re.compile(r"Vision\b", re.I), "Vision Framework (on-device)"),
+    (re.compile(r"NaturalLanguage\b", re.I), "Natural Language Framework (on-device)"),
+    (re.compile(r"GeminiNano|gemini[\-_]nano", re.I), "Gemini Nano (on-device)"),
+]
+
+_FRAMEWORK_LABELS = {
+    RuleCategory.APP_STORE: "Apple Guideline 5.1.2(i)",
+    RuleCategory.GOOGLE_PLAY: "Google Play AI Policy",
+    RuleCategory.EU_AI_ACT: "EU AI Act Article 50",
+    RuleCategory.OWASP: "OWASP Mobile AI Top 5",
+}
+
+
+def generate_report(
+    scan_result: ScanResult,
+    *,
+    app_name: str,
+    version: str,
+    platforms: list[Platform],
+    include_evidence: bool = False,
+) -> AuditReport:
+    """Build an AuditReport from a ScanResult."""
+    ai_features = _detect_ai_features(scan_result)
+    compliance_status = _build_compliance_status(scan_result.findings)
+    attestation = (
+        f"This report was generated automatically by MobileGuard v{__version__} "
+        f"on {datetime.now(tz=timezone.utc).strftime('%Y-%m-%d')}. "
+        "It documents governance practices as detected in the codebase at the time of scan. "
+        "This report does not constitute legal advice."
+    )
+
+    findings = scan_result.findings
+    if not include_evidence:
+        findings = [f.model_copy(update={"evidence": None}) for f in findings]
+
+    return AuditReport(
+        app_name=app_name,
+        version=version,
+        platforms=platforms,
+        generated_at=datetime.now(tz=timezone.utc),
+        tool_version=__version__,
+        compliance_status=compliance_status,
+        ai_features=ai_features,
+        findings=findings,
+        attestation=attestation,
+    )
+
+
+def render_markdown(report: AuditReport) -> str:
+    """Render an AuditReport as a Markdown document."""
+    lines: list[str] = []
+    platforms_str = ", ".join(p.value.title() for p in report.platforms)
+    lines += [
+        "# MobileGuard Governance Audit Report",
+        f"**App:** {report.app_name} · "
+        f"**Version:** {report.version} · "
+        f"**Date:** {report.generated_at.strftime('%Y-%m-%d')}",
+        f"**Platforms:** {platforms_str} · "
+        f"**Generated by:** MobileGuard v{report.tool_version}",
+        "",
+        "## Compliance Status",
+        "",
+        "| Framework | Status | Issues |",
+        "|---|---|---|",
+    ]
+
+    for category, status_info in report.compliance_status.items():
+        icon = status_info["icon"]
+        status = status_info["status"]
+        issues = status_info["issues"]
+        lines.append(f"| {category} | {icon} {status} | {issues} |")
+
+    lines += ["", "## AI Features Inventory", ""]
+    if report.ai_features:
+        for feature in report.ai_features:
+            lines.append(f"- {feature['name']} — detected in `{feature['file']}`")
+    else:
+        lines.append("- No AI integrations detected.")
+
+    # Findings by severity
+    criticals = [f for f in report.findings if f.severity == Severity.CRITICAL]
+    errors = [f for f in report.findings if f.severity == Severity.ERROR]
+    warnings = [f for f in report.findings if f.severity == Severity.WARNING]
+
+    lines += ["", "## Critical Issues Requiring Remediation", ""]
+    if criticals:
+        for f in criticals:
+            lines += [
+                f"### {f.rule_id}: {f.description}",
+                f"- **File:** `{f.file_path}`" + (f":{f.line_number}" if f.line_number else ""),
+                f"- **Fix:** {f.fix}",
+                f"- **Pillar:** {f.pillar}",
+                f"- **Reference:** {f.reference}" if f.reference else "",
+                "",
+            ]
+    else:
+        lines.append("No critical issues found.")
+
+    if errors:
+        lines += ["## Errors", ""]
+        for f in errors:
+            lines += [
+                f"### {f.rule_id}: {f.description}",
+                f"- **File:** `{f.file_path}`" + (f":{f.line_number}" if f.line_number else ""),
+                f"- **Fix:** {f.fix}",
+                "",
+            ]
+
+    if warnings:
+        lines += ["## Warnings", ""]
+        for f in warnings:
+            lines += [
+                f"- **{f.rule_id}** `{f.file_path}`"
+                + (f":{f.line_number}" if f.line_number else "")
+                + f" — {f.description}",
+            ]
+
+    lines += [
+        "",
+        "## Attestation",
+        "",
+        report.attestation,
+    ]
+
+    return "\n".join(lines)
+
+
+def render_html(report: AuditReport) -> str:
+    """Render an AuditReport as an HTML document."""
+    md = render_markdown(report)
+    # Simple conversion: escape HTML in markdown and wrap in styled page
+    escaped = md.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    rows = []
+    for category, info in report.compliance_status.items():
+        rows.append(
+            f"<tr><td>{category}</td>"
+            f"<td>{info['icon']} {info['status']}</td>"
+            f"<td>{info['issues']}</td></tr>"
+        )
+
+    findings_html = ""
+    for f in report.findings:
+        sev_class = f.severity.value
+        loc = f"`{f.file_path}`" + (f":{f.line_number}" if f.line_number else "")
+        findings_html += (
+            f'<div class="finding {sev_class}">'
+            f"<strong>{f.rule_id}</strong> [{f.severity.value.upper()}] {f.description}<br>"
+            f"<small>File: {loc} · Fix: {f.fix}</small></div>\n"
+        )
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>MobileGuard Audit Report — {report.app_name}</title>
+<style>
+  body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+         max-width: 900px; margin: 40px auto; padding: 0 20px; color: #1a1a1a; }}
+  h1 {{ color: #0052cc; }}
+  h2 {{ border-bottom: 2px solid #eee; padding-bottom: 8px; }}
+  table {{ border-collapse: collapse; width: 100%; }}
+  th, td {{ border: 1px solid #ddd; padding: 8px 12px; text-align: left; }}
+  th {{ background: #f5f5f5; }}
+  .finding {{ border-left: 4px solid #ccc; padding: 8px 12px; margin: 8px 0; border-radius: 4px; }}
+  .critical {{ border-color: #d32f2f; background: #ffebee; }}
+  .error {{ border-color: #f57c00; background: #fff3e0; }}
+  .warning {{ border-color: #f9a825; background: #fffde7; }}
+  .info {{ border-color: #1976d2; background: #e3f2fd; }}
+  .attestation {{ font-style: italic; color: #666; border-top: 1px solid #eee; padding-top: 16px; }}
+</style>
+</head>
+<body>
+<h1>MobileGuard Governance Audit Report</h1>
+<p><strong>App:</strong> {report.app_name} &nbsp;|&nbsp;
+   <strong>Version:</strong> {report.version} &nbsp;|&nbsp;
+   <strong>Date:</strong> {report.generated_at.strftime('%Y-%m-%d')}<br>
+   <strong>Platforms:</strong> {', '.join(p.value.title() for p in report.platforms)} &nbsp;|&nbsp;
+   <strong>Generated by:</strong> MobileGuard v{report.tool_version}</p>
+
+<h2>Compliance Status</h2>
+<table>
+<tr><th>Framework</th><th>Status</th><th>Issues</th></tr>
+{''.join(rows)}
+</table>
+
+<h2>AI Features Inventory</h2>
+<ul>
+{''.join(f"<li>{feat['name']} — <code>{feat['file']}</code></li>" for feat in report.ai_features) or '<li>No AI integrations detected.</li>'}
+</ul>
+
+<h2>Findings</h2>
+{findings_html or '<p>No findings.</p>'}
+
+<div class="attestation"><h2>Attestation</h2><p>{report.attestation}</p></div>
+</body>
+</html>"""
+
+
+def render_json(report: AuditReport) -> str:
+    """Render an AuditReport as JSON."""
+    return report.model_dump_json(indent=2)
+
+
+def _detect_ai_features(scan_result: ScanResult) -> list[dict[str, str]]:
+    """Infer AI feature inventory from the scan result's project path."""
+    seen: set[str] = set()
+    features: list[dict[str, str]] = []
+    root = Path(scan_result.project_path)
+
+    for file_path in root.rglob("*"):
+        if not file_path.is_file():
+            continue
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        for pattern, label in _AI_FEATURE_PATTERNS:
+            if pattern.search(content) and label not in seen:
+                seen.add(label)
+                rel = str(file_path.relative_to(root))
+                features.append({"name": label, "file": rel})
+
+    return features
+
+
+def _build_compliance_status(findings: list[Finding]) -> dict[str, dict[str, object]]:
+    """Build per-framework compliance status from findings."""
+    category_findings: dict[RuleCategory, list[Finding]] = {cat: [] for cat in RuleCategory}
+    for f in findings:
+        category_findings[f.category].append(f)
+
+    status: dict[str, dict[str, object]] = {}
+    for category, label in _FRAMEWORK_LABELS.items():
+        cat_findings = category_findings[category]
+        critical_count = sum(1 for f in cat_findings if f.severity == Severity.CRITICAL)
+        error_count = sum(1 for f in cat_findings if f.severity == Severity.ERROR)
+        warning_count = sum(1 for f in cat_findings if f.severity == Severity.WARNING)
+
+        if critical_count > 0:
+            icon, compliance = "❌", "Non-compliant"
+            issues = f"{critical_count} critical"
+        elif error_count > 0:
+            icon, compliance = "⚠", "Partial"
+            issues = f"{error_count} error{'s' if error_count > 1 else ''}"
+        elif warning_count > 0:
+            icon, compliance = "⚠", "Partial"
+            issues = f"{warning_count} warning{'s' if warning_count > 1 else ''}"
+        else:
+            icon, compliance = "✅", "Compliant"
+            issues = "0"
+
+        status[label] = {"icon": icon, "status": compliance, "issues": issues}
+
+    return status