universal-dev-security 1.0.0__py3-none-any.whl

universal_dev_security/history.py

@@ -0,0 +1,149 @@
+"""Local scan history and scan-to-scan comparison."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.findings import SEVERITY_ORDER
+
+SCAN_ID_RE = re.compile(r"^\d{8}T\d{6}(?:\d{6})?Z-[0-9a-f]{6}$")
+UDS_GITIGNORE = "# Generated by UDS.\nreports/\nhistory/\nbackups/\ncache/\n"
+
+
+def ensure_uds_dir(root: Path) -> Path:
+    """Create ``.uds/`` with a protective .gitignore (never overwriting one)."""
+    uds = root / ".uds"
+    uds.mkdir(exist_ok=True)
+    ignore = uds / ".gitignore"
+    if not ignore.exists():
+        try:
+            with ignore.open("x", encoding="utf-8", newline="\n") as handle:
+                handle.write(UDS_GITIGNORE)
+        except FileExistsError:
+            pass
+    return uds
+
+
+def history_dir(root: Path) -> Path:
+    return root.expanduser().resolve() / ".uds" / "history"
+
+
+def save_scan(root: Path, scan: dict[str, Any], limit: int = 50) -> Path:
+    scan_id = str(scan.get("scan_id", ""))
+    if not SCAN_ID_RE.match(scan_id):
+        raise ValueError("Scan has an invalid scan_id")
+    ensure_uds_dir(root.expanduser().resolve())
+    directory = history_dir(root)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{scan_id}.json"
+    path.write_text(json.dumps(scan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8", newline="\n")
+    prune(root, limit)
+    return path
+
+
+def list_scans(root: Path) -> list[str]:
+    directory = history_dir(root)
+    if not directory.is_dir():
+        return []
+    return sorted(p.stem for p in directory.glob("*.json") if SCAN_ID_RE.match(p.stem))
+
+
+def prune(root: Path, limit: int) -> list[str]:
+    scans = list_scans(root)
+    removed = scans[:-limit] if limit > 0 and len(scans) > limit else []
+    for scan_id in removed:
+        (history_dir(root) / f"{scan_id}.json").unlink(missing_ok=True)
+    return removed
+
+
+def resolve_scan_id(root: Path, reference: str) -> str:
+    scans = list_scans(root)
+    if not scans:
+        raise ValueError("No scan history found. Run `uds scan` first.")
+    if reference == "latest":
+        return scans[-1]
+    if reference == "previous":
+        if len(scans) < 2:
+            raise ValueError("Only one scan in history; nothing to compare with.")
+        return scans[-2]
+    if not SCAN_ID_RE.match(reference):  # also prevents path traversal
+        raise ValueError(f"Invalid scan id: {reference!r}")
+    if reference not in scans:
+        raise ValueError(f"Scan not found in history: {reference}")
+    return reference
+
+
+def load_scan(root: Path, reference: str) -> dict[str, Any]:
+    scan_id = resolve_scan_id(root, reference)
+    data = json.loads((history_dir(root) / f"{scan_id}.json").read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("History entry is not a scan object")
+    return data
+
+
+def summarize(scan: dict[str, Any]) -> dict[str, Any]:
+    summary = scan.get("summary", {})
+    return {
+        "scan_id": scan.get("scan_id"),
+        "started_at": scan.get("started_at"),
+        "overall_status": scan.get("overall_status"),
+        "finding_count": summary.get("finding_count", 0),
+        "by_severity": summary.get("by_severity", {}),
+        "executed": scan.get("coverage", {}).get("executed", []),
+    }
+
+
+def history_summaries(root: Path, limit: int = 20) -> list[dict[str, Any]]:
+    result = []
+    for scan_id in list_scans(root)[-limit:]:
+        try:
+            result.append(summarize(load_scan(root, scan_id)))
+        except (OSError, ValueError):
+            continue
+    return result
+
+
+def compare_scans(base: dict[str, Any], current: dict[str, Any]) -> dict[str, Any]:
+    """Compare findings by fingerprint, only across scanners executed in both scans."""
+    base_tools = set(base.get("coverage", {}).get("executed", []))
+    current_tools = set(current.get("coverage", {}).get("executed", []))
+    common = base_tools & current_tools
+    base_findings = {f["fingerprint"]: f for f in base.get("findings", []) if f.get("tool") in common}
+    current_findings = {f["fingerprint"]: f for f in current.get("findings", []) if f.get("tool") in common}
+    not_rescanned = [f for f in base.get("findings", []) if f.get("tool") not in current_tools]
+    newly_covered = [f for f in current.get("findings", []) if f.get("tool") not in base_tools]
+    new = [current_findings[k] for k in current_findings if k not in base_findings]
+    resolved = [base_findings[k] for k in base_findings if k not in current_findings]
+    unchanged = [current_findings[k] for k in current_findings if k in base_findings]
+
+    def by_severity(items: list[dict[str, Any]]) -> dict[str, int]:
+        counts = {s.value: 0 for s in SEVERITY_ORDER}
+        for item in items:
+            counts[item.get("severity", "unclassified")] = counts.get(item.get("severity", "unclassified"), 0) + 1
+        return counts
+
+    base_scope = base.get("options", {}).get("scope_fingerprint")
+    current_scope = current.get("options", {}).get("scope_fingerprint")
+    scope_changed = base_scope is None or base_scope != current_scope
+    warnings = []
+    if scope_changed and resolved:
+        warnings.append("The scan scope changed between these scans (UDS exclusions or configured exclude_paths). "
+                        "Findings listed as resolved may have been excluded rather than fixed.")
+    return {
+        "base_scan_id": base.get("scan_id"),
+        "current_scan_id": current.get("scan_id"),
+        "scope_changed": scope_changed,
+        "warnings": warnings,
+        "compared_tools": sorted(common),
+        "new": new,
+        "resolved": resolved,
+        "unchanged_count": len(unchanged),
+        "not_rescanned": not_rescanned,
+        "newly_covered": newly_covered,
+        "new_by_severity": by_severity(new),
+        "resolved_by_severity": by_severity(resolved),
+        "note": "Findings are compared only for scanners that executed in both scans; findings from scanners "
+                "that did not run again are listed as not re-scanned, never as resolved.",
+    }

universal_dev_security/initializer.py

@@ -0,0 +1,112 @@
+"""Safe, non-destructive project initialization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from universal_dev_security.detector import detect_project
+
+DEFAULT_CONFIG = (
+    "# Universal Dev Security project configuration\n"
+    "# Never store credentials, tokens, or private keys in this file.\n\n"
+    "[project]\n"
+    'name = "my-project"\n'
+    'profile = "auto"\n\n'
+    "[policy]\n"
+    'security_mode = "balanced"\n'
+    "allow_automatic_low_risk_fixes = true\n"
+    "require_user_approval_for_high_risk_changes = true\n"
+    "require_user_approval_for_git_push = true\n"
+    "# Exit non-zero from `uds scan` when findings reach this severity:\n"
+    "# none | unclassified | low | medium | high | critical\n"
+    'fail_on = "none"\n'
+    "# Extra restrictions (regular expressions). Global rules cannot be removed.\n"
+    "deny_command_patterns = []\n"
+    "approval_command_patterns = []\n"
+    "protected_paths = []\n\n"
+    "[scanners]\n"
+    "# gitleaks is mandatory; semgrep, osv-scanner and trivy run when installed and applicable.\n"
+    'enabled = ["gitleaks", "semgrep", "osv-scanner", "trivy"]\n'
+    "# OSV-Scanner sends package names and versions (not source code) to osv.dev.\n"
+    "# It is skipped unless this is true or `uds scan --allow-network` is used.\n"
+    "allow_network = false\n"
+    "# Empty = profile-based Semgrep Registry packs (rules are downloaded; metrics are off).\n"
+    "semgrep_configs = []\n"
+    "timeout_seconds = 600\n"
+    "exclude_paths = []\n\n"
+    "[testing]\n"
+    "# Command run by `uds test` and after automatic fixes, e.g. [\"pytest\", \"-q\"].\n"
+    "# Empty = auto-detect.\n"
+    "command = []\n\n"
+    "[reporting]\n"
+    "terminal = true\n"
+    "file_reports = true\n\n"
+    "[history]\n"
+    "limit = 50\n"
+)
+
+PROJECT_README = (
+    "# UDS project configuration\n\n"
+    "This directory contains local Universal Dev Security configuration.\n\n"
+    "- `config.toml`: project-level preferences.\n"
+    "- Never store passwords, API keys, tokens, private keys, or personal data here.\n"
+    "- Mandatory global policies cannot be weakened by project settings.\n"
+    "- `reports/`, `history/`, `backups/`: generated by UDS; excluded from Git.\n\n"
+    "Run `uds scan` to scan, `uds dashboard` to open the latest report, and\n"
+    "`uds policy show` to see the effective security policy.\n"
+)
+
+UDS_GITIGNORE = (
+    "# Generated by UDS. Reports and backups can reference sensitive file paths.\n"
+    "reports/\n"
+    "history/\n"
+    "backups/\n"
+    "cache/\n"
+)
+
+
+def initialize_project(path: Path) -> dict:
+    target = path.expanduser().resolve()
+    if not target.exists() or not target.is_dir():
+        return {"status": "error", "reason": "target_directory_not_found"}
+
+    uds_dir = target / ".uds"
+    config_path = uds_dir / "config.toml"
+    readme_path = uds_dir / "README.md"
+
+    if config_path.exists() or readme_path.exists():
+        return {
+            "status": "already_initialized",
+            "path": str(target),
+            "message": "Existing UDS files were left unchanged.",
+        }
+
+    detected = detect_project(target)["detected"]
+    created: list[str] = []
+    try:
+        uds_dir.mkdir(exist_ok=True)
+        with config_path.open("x", encoding="utf-8", newline="\n") as handle:
+            handle.write(DEFAULT_CONFIG)
+        created.append(".uds/config.toml")
+        with readme_path.open("x", encoding="utf-8", newline="\n") as handle:
+            handle.write(PROJECT_README)
+        created.append(".uds/README.md")
+        gitignore_path = uds_dir / ".gitignore"
+        if not gitignore_path.exists():
+            with gitignore_path.open("x", encoding="utf-8", newline="\n") as handle:
+                handle.write(UDS_GITIGNORE)
+            created.append(".uds/.gitignore")
+    except FileExistsError:
+        return {
+            "status": "already_initialized",
+            "path": str(target),
+            "message": "An existing file was detected; no overwrite was performed.",
+        }
+
+    return {
+        "status": "initialized",
+        "path": str(target),
+        "detected": detected,
+        "created": created,
+        "message": "Configuration created. No scanners or global settings were changed.",
+    }

universal_dev_security/integrations/__init__.py

@@ -0,0 +1,46 @@
+"""Integrations with AI coding tools, Git hosting and editors.
+
+All integrations follow the same safety contract:
+* dry-run by default — show the planned change and a diff;
+* ``apply=True`` creates a recovery checkpoint first, then writes atomically;
+* existing user configuration is merged, never silently overwritten;
+* removal only deletes UDS-owned entries.
+"""
+from __future__ import annotations
+
+import difflib
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.recovery import RecoveryManager, resolve_inside, safe_write
+
+
+def apply_changes(root: Path, changes: dict[str, str | None], label: str, apply: bool) -> dict[str, Any]:
+    """Plan (and optionally apply) file changes. ``None`` content deletes a file."""
+    root = root.expanduser().resolve()
+    planned = []
+    for relative, new in changes.items():
+        path = resolve_inside(root, relative)
+        old = path.read_text(encoding="utf-8") if path.is_file() else None
+        if old == new:
+            continue
+        diff = "".join(difflib.unified_diff(
+            (old or "").splitlines(keepends=True), (new or "").splitlines(keepends=True),
+            fromfile=f"a/{relative}", tofile=f"b/{relative}"))
+        planned.append({"path": relative, "action": "delete" if new is None else ("update" if old is not None else "create"),
+                        "diff": diff})
+    result: dict[str, Any] = {"applied": False, "changes": planned, "checkpoint": None}
+    if not apply or not planned:
+        result["applied"] = apply and not planned
+        return result
+    manager = RecoveryManager(root)
+    checkpoint = manager.create(label, [c["path"] for c in planned])
+    for change in planned:
+        content = changes[change["path"]]
+        if content is None:
+            resolve_inside(root, change["path"]).unlink(missing_ok=True)
+        else:
+            safe_write(root, change["path"], content)
+    manager.seal(checkpoint)
+    result.update(applied=True, checkpoint=checkpoint)
+    return result

universal_dev_security/integrations/agents.py

@@ -0,0 +1,45 @@
+"""Generic AI-agent integration interface (`uds guard`).
+
+Any coding agent can ask UDS for a decision before acting by piping a JSON
+object to ``uds guard`` (see docs/integrations.md)::
+
+    {"action": "shell", "command": "git push origin main", "project_root": "/repo"}
+    {"action": "write_file", "path": "src/app.py", "content": "...", "project_root": "/repo"}
+
+Response (stdout)::
+
+    {"decision": "allow"|"ask"|"deny", "risk": "...", "reason": "...", "matches": [...]}
+
+Exit codes: 0 allow, 1 ask (obtain explicit user approval), 2 deny, 3 invalid request.
+Agents must treat any non-zero exit or unparsable output as "do not proceed".
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.config import ConfigError, load_config
+from universal_dev_security.policy import Action, PolicyEngine
+
+EXIT_CODES = {"allow": 0, "ask": 1, "deny": 2}
+MAX_REQUEST_BYTES = 5 * 1024 * 1024
+
+
+def guard(request_text: str, default_root: str) -> tuple[int, dict[str, Any]]:
+    if len(request_text.encode("utf-8", errors="replace")) > MAX_REQUEST_BYTES:
+        return 3, {"decision": "deny", "reason": "Request too large."}
+    try:
+        data = json.loads(request_text)
+        if isinstance(data, dict) and not data.get("project_root"):
+            data["project_root"] = default_root
+        action = Action.from_dict(data)
+    except (ValueError, TypeError) as exc:
+        return 3, {"decision": "deny", "reason": f"Invalid request: {exc}"}
+    try:
+        config = load_config(Path(action.project_root))
+    except ConfigError:
+        return 1, {"decision": "ask", "risk": "high", "reason": "UDS configuration could not be parsed; approval required."}
+    decision = PolicyEngine(config).evaluate(action)
+    payload = decision.to_dict()
+    return EXIT_CODES[decision.decision.value], payload

universal_dev_security/integrations/claude_code.py

@@ -0,0 +1,192 @@
+"""Claude Code integration: PreToolUse hooks that enforce the UDS policy.
+
+Installed configuration (merged into ``.claude/settings.json``)::
+
+    {"hooks": {"PreToolUse": [{"matcher": "<tools>", "hooks": [{"type": "command",
+        "command": "uds hook claude-code", "timeout": 30}]}]},
+     "permissions": {"ask": ["Bash(git push:*)"]}}
+
+Hook protocol (Claude Code): the tool call is received as JSON on stdin. To
+require approval or deny, the hook prints
+``{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision":
+"ask"|"deny", "permissionDecisionReason": "..."}}`` and exits 0. When UDS has
+no objection it prints nothing, so Claude Code's normal permission flow still
+applies (UDS never auto-approves anything).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.config import load_config
+from universal_dev_security.integrations import apply_changes
+from universal_dev_security.policy import Action, ActionKind, Decision, PolicyEngine
+
+SETTINGS_PATH = ".claude/settings.json"
+LOCAL_SETTINGS_PATH = ".claude/settings.local.json"
+HOOK_MARKER = "hook claude-code"
+MATCHER = "Bash|PowerShell|Write|Edit|MultiEdit|NotebookEdit|Read"
+ASK_RULES = ["Bash(git push:*)", "PowerShell(git push:*)"]
+_SAFE_PATH_RE = re.compile(r"^[\w\s.:\\/()+-]+$")
+
+
+# ---------------------------------------------------------------------------
+# Hook runtime
+# ---------------------------------------------------------------------------
+
+def _action_from_hook(payload: dict[str, Any], project_root: str) -> Action | None:
+    tool = str(payload.get("tool_name") or "")
+    data = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else {}
+    if tool in ("Bash", "PowerShell"):
+        return Action(ActionKind.SHELL, command=str(data.get("command") or ""), project_root=project_root)
+    if tool == "Write":
+        return Action(ActionKind.WRITE_FILE, path=str(data.get("file_path") or ""),
+                      content=str(data.get("content") or ""), project_root=project_root)
+    if tool == "Edit":
+        return Action(ActionKind.EDIT_FILE, path=str(data.get("file_path") or ""),
+                      content=str(data.get("new_string") or ""), project_root=project_root)
+    if tool == "MultiEdit":
+        edits = data.get("edits") if isinstance(data.get("edits"), list) else []
+        content = "\n".join(str(e.get("new_string") or "") for e in edits if isinstance(e, dict))
+        return Action(ActionKind.EDIT_FILE, path=str(data.get("file_path") or ""), content=content,
+                      project_root=project_root)
+    if tool == "NotebookEdit":
+        return Action(ActionKind.EDIT_FILE, path=str(data.get("notebook_path") or ""),
+                      content=str(data.get("new_source") or ""), project_root=project_root)
+    if tool == "Read":
+        return Action(ActionKind.READ_FILE, path=str(data.get("file_path") or ""), project_root=project_root)
+    return None
+
+
+def _decision_output(decision: str, reason: str) -> dict[str, Any]:
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": decision,
+                                   "permissionDecisionReason": f"UDS: {reason}"[:2000]}}
+
+
+def handle_hook(payload: Any) -> dict[str, Any] | None:
+    """Evaluate a Claude Code PreToolUse payload. Returns hook output or None (no objection)."""
+    if not isinstance(payload, dict):
+        return _decision_output("ask", "Unrecognized hook input; approval required.")
+    if payload.get("hook_event_name") not in (None, "PreToolUse"):
+        return None
+    project_root = os.environ.get("CLAUDE_PROJECT_DIR") or str(payload.get("cwd") or os.getcwd())
+    action = _action_from_hook(payload, project_root)
+    if action is None:
+        return None
+    try:
+        config = load_config(Path(project_root))
+    except ValueError:
+        return _decision_output("ask", "The UDS project configuration could not be parsed; approval required.")
+    decision = PolicyEngine(config).evaluate(action)
+    if decision.decision is Decision.ALLOW:
+        return None
+    return _decision_output(decision.decision.value, decision.reason)
+
+
+def run_hook(stdin_text: str) -> tuple[int, str]:
+    """Entry point used by `uds hook claude-code`. Fails closed (ask) on any error."""
+    try:
+        payload = json.loads(stdin_text or "{}")
+        output = handle_hook(payload)
+    except Exception:  # noqa: BLE001 - a crashing guard must never silently allow
+        output = _decision_output("ask", "Internal UDS hook error; approval required.")
+    return 0, json.dumps(output) if output else ""
+
+
+# ---------------------------------------------------------------------------
+# Installation
+# ---------------------------------------------------------------------------
+
+def hook_command(use_python_path: bool) -> str:
+    if use_python_path:
+        python = sys.executable
+        if not _SAFE_PATH_RE.match(python):
+            raise ValueError("The Python interpreter path contains characters that cannot be embedded safely.")
+        return f'"{python}" -m universal_dev_security {HOOK_MARKER}'
+    return f"uds {HOOK_MARKER}"
+
+
+def _is_uds_hook(entry: Any) -> bool:
+    return isinstance(entry, dict) and any(
+        isinstance(h, dict) and HOOK_MARKER in str(h.get("command", "")) for h in entry.get("hooks", []) or [])
+
+
+def merge_settings(existing: dict[str, Any], command: str) -> dict[str, Any]:
+    settings = json.loads(json.dumps(existing))  # deep copy
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise ValueError("Existing 'hooks' setting is not an object; refusing to modify it.")
+    pre = hooks.setdefault("PreToolUse", [])
+    if not isinstance(pre, list):
+        raise ValueError("Existing 'hooks.PreToolUse' is not a list; refusing to modify it.")
+    pre[:] = [entry for entry in pre if not _is_uds_hook(entry)]
+    pre.append({"matcher": MATCHER, "hooks": [{"type": "command", "command": command, "timeout": 30}]})
+    permissions = settings.setdefault("permissions", {})
+    if not isinstance(permissions, dict):
+        raise ValueError("Existing 'permissions' setting is not an object; refusing to modify it.")
+    ask = permissions.setdefault("ask", [])
+    if not isinstance(ask, list):
+        raise ValueError("Existing 'permissions.ask' is not a list; refusing to modify it.")
+    for rule in ASK_RULES:
+        if rule not in ask:
+            ask.append(rule)
+    return settings
+
+
+def remove_from_settings(existing: dict[str, Any]) -> dict[str, Any]:
+    settings = json.loads(json.dumps(existing))
+    hooks = settings.get("hooks")
+    if isinstance(hooks, dict) and isinstance(hooks.get("PreToolUse"), list):
+        hooks["PreToolUse"] = [e for e in hooks["PreToolUse"] if not _is_uds_hook(e)]
+        if not hooks["PreToolUse"]:
+            del hooks["PreToolUse"]
+        if not hooks:
+            del settings["hooks"]
+    permissions = settings.get("permissions")
+    if isinstance(permissions, dict) and isinstance(permissions.get("ask"), list):
+        permissions["ask"] = [r for r in permissions["ask"] if r not in ASK_RULES]
+        if not permissions["ask"]:
+            del permissions["ask"]
+        if not permissions:
+            del settings["permissions"]
+    return settings
+
+
+def install(root: Path, *, apply: bool = False, remove: bool = False, local: bool = False,
+            use_python_path: bool = False) -> dict[str, Any]:
+    root = root.expanduser().resolve()
+    relative = LOCAL_SETTINGS_PATH if local else SETTINGS_PATH
+    path = root / relative
+    existing: dict[str, Any] = {}
+    if path.is_file():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8") or "{}")
+        except ValueError as exc:
+            raise ValueError(f"{relative} is not valid JSON; refusing to modify it. Fix it manually first.") from exc
+        if not isinstance(existing, dict):
+            raise ValueError(f"{relative} is not a JSON object; refusing to modify it.")
+    if remove:
+        updated = remove_from_settings(existing)
+        new_content: str | None = json.dumps(updated, indent=2) + "\n" if (updated or path.is_file()) else None
+    else:
+        updated = merge_settings(existing, hook_command(use_python_path))
+        new_content = json.dumps(updated, indent=2) + "\n"
+    result = apply_changes(root, {relative: new_content}, f"claude-code integration ({'remove' if remove else 'install'})", apply)
+    result["settings_file"] = relative
+    if not remove:
+        location = (f"The hook runs this Python interpreter directly ({sys.executable}); keep that environment "
+                    "installed, and prefer --local because the path is machine-specific."
+                    if use_python_path else
+                    "The hook runs `uds` from PATH; if it is not on PATH the hook cannot run. Use --python-path to "
+                    "embed this interpreter (recommended together with --local, because absolute paths are "
+                    "machine-specific).")
+        result["notes"] = [
+            location,
+            "The hook only adds 'ask'/'deny' decisions; it never auto-approves tool calls.",
+            "`git push` additionally requires approval through permissions.ask as defense in depth.",
+        ]
+    return result