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

universal_dev_security/integrations/github.py

@@ -0,0 +1,149 @@
+"""GitHub integration: a pull-request security workflow for user projects.
+
+The generated workflow:
+* runs on pull requests, pushes to the default branch and manual dispatch;
+* uses least-privilege permissions (contents: read; security-events: write only
+  for SARIF upload);
+* installs scanners from official release assets with SHA-256 verification;
+* runs `uds scan` and uploads SARIF (code scanning) and the HTML/JSON reports;
+* never pushes, publishes or comments with write tokens.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.integrations import apply_changes
+
+WORKFLOW_PATH = ".github/workflows/uds-security.yml"
+DEFAULT_GITLEAKS_VERSION = "8.30.1"
+DEFAULT_OSV_VERSION = "2.7.1"
+DEFAULT_TRIVY_VERSION = "0.76.2"
+_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+_SPEC_RE = re.compile(r"^[A-Za-z0-9_.\-\[\]=<>~!@:/+#, ]{1,300}$")
+
+TEMPLATE = """# Generated by Universal Dev Security (UDS). Review before committing.
+# Scanner versions are pinned and release assets are verified with SHA-256.
+name: UDS security scan
+
+on:
+  pull_request:
+  push:
+    branches: [__BRANCH__]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: uds-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  uds-scan:
+    name: UDS security scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      security-events: write  # upload SARIF to GitHub code scanning
+    env:
+      GITLEAKS_VERSION: "__GITLEAKS__"
+      OSV_SCANNER_VERSION: "__OSV__"
+      TRIVY_VERSION: "__TRIVY__"
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install UDS and Semgrep
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "__UDS_SPEC__" semgrep
+
+      - name: Install scanners (official releases, checksum verified)
+        run: |
+          set -euo pipefail
+          mkdir -p "$HOME/.local/bin" /tmp/uds-tools && cd /tmp/uds-tools
+          base="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}"
+          curl -sSfLO "$base/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          curl -sSfLO "$base/gitleaks_${GITLEAKS_VERSION}_checksums.txt"
+          grep " gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz\\$" "gitleaks_${GITLEAKS_VERSION}_checksums.txt" | sha256sum -c -
+          tar -xzf "gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" gitleaks
+          install -m 0755 gitleaks "$HOME/.local/bin/gitleaks"
+          base="https://github.com/google/osv-scanner/releases/download/v${OSV_SCANNER_VERSION}"
+          curl -sSfLO "$base/osv-scanner_linux_amd64"
+          curl -sSfLO "$base/osv-scanner_SHA256SUMS"
+          grep " osv-scanner_linux_amd64\\$" osv-scanner_SHA256SUMS | sha256sum -c -
+          install -m 0755 osv-scanner_linux_amd64 "$HOME/.local/bin/osv-scanner"
+          base="https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}"
+          curl -sSfLO "$base/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz"
+          curl -sSfLO "$base/trivy_${TRIVY_VERSION}_checksums.txt"
+          grep " trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz\\$" "trivy_${TRIVY_VERSION}_checksums.txt" | sha256sum -c -
+          tar -xzf "trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz" trivy
+          install -m 0755 trivy "$HOME/.local/bin/trivy"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Run UDS scan
+        # --allow-network lets OSV-Scanner send package names/versions (not source code) to osv.dev.
+        run: >-
+          uds scan . --no-history --allow-network --require-complete
+          --format json,html,sarif --report-dir uds-reports --fail-on __FAIL_ON__
+
+      - name: Upload SARIF to code scanning
+        if: always() && hashFiles('uds-reports/security-report.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: uds-reports/security-report.sarif
+          category: uds
+
+      - name: Upload UDS reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: uds-security-report
+          path: uds-reports/
+          retention-days: 14
+          if-no-files-found: ignore
+"""
+
+
+def render_workflow(*, branch: str = "main", fail_on: str = "high", uds_spec: str = "universal-dev-security",
+                    gitleaks: str = DEFAULT_GITLEAKS_VERSION, osv: str = DEFAULT_OSV_VERSION,
+                    trivy: str = DEFAULT_TRIVY_VERSION) -> str:
+    if not re.match(r"^[A-Za-z0-9._/-]{1,100}$", branch):
+        raise ValueError("Invalid branch name")
+    if fail_on not in ("none", "unclassified", "low", "medium", "high", "critical"):
+        raise ValueError("Invalid fail-on level")
+    if not _SPEC_RE.match(uds_spec) or '"' in uds_spec:
+        raise ValueError("Invalid UDS install specification")
+    for value in (gitleaks, osv, trivy):
+        if not _VERSION_RE.match(value):
+            raise ValueError(f"Invalid scanner version: {value!r}")
+    return (TEMPLATE.replace("__BRANCH__", branch).replace("__FAIL_ON__", fail_on).replace("__UDS_SPEC__", uds_spec)
+            .replace("__GITLEAKS__", gitleaks).replace("__OSV__", osv).replace("__TRIVY__", trivy))
+
+
+def install(root: Path, *, apply: bool = False, remove: bool = False, **options: Any) -> dict[str, Any]:
+    root = root.expanduser().resolve()
+    path = root / WORKFLOW_PATH
+    if path.is_file() and "Generated by Universal Dev Security" not in path.read_text(encoding="utf-8", errors="replace"):
+        raise ValueError(f"{WORKFLOW_PATH} exists and was not generated by UDS; refusing to overwrite it.")
+    content = None if remove else render_workflow(**options)
+    result = apply_changes(root, {WORKFLOW_PATH: content}, "github workflow " + ("remove" if remove else "install"), apply)
+    result["workflow"] = WORKFLOW_PATH
+    result["notes"] = [
+        "Review the workflow, then commit it yourself — UDS never commits or pushes.",
+        "Until UDS is published on PyPI, set --uds-spec to a pinned Git URL or wheel location.",
+        "Enable GitHub secret scanning and push protection in the repository settings as an independent control.",
+        "Consider pinning third-party actions to full commit SHAs.",
+    ]
+    return result

universal_dev_security/integrations/vscode.py

@@ -0,0 +1,44 @@
+"""VS Code integration: tasks for scanning and opening the dashboard."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.integrations import apply_changes
+
+TASKS_PATH = ".vscode/tasks.json"
+LABEL_PREFIX = "UDS: "
+
+UDS_TASKS = [
+    {"label": "UDS: Security scan", "type": "process", "command": "uds", "args": ["scan", "${workspaceFolder}"],
+     "group": "test", "problemMatcher": []},
+    {"label": "UDS: Open dashboard", "type": "process", "command": "uds",
+     "args": ["dashboard", "${workspaceFolder}", "--open"], "problemMatcher": []},
+    {"label": "UDS: Doctor", "type": "process", "command": "uds", "args": ["doctor", "${workspaceFolder}"],
+     "problemMatcher": []},
+]
+
+
+def install(root: Path, *, apply: bool = False, remove: bool = False) -> dict[str, Any]:
+    root = root.expanduser().resolve()
+    path = root / TASKS_PATH
+    data: dict[str, Any] = {"version": "2.0.0", "tasks": []}
+    if path.is_file():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except ValueError as exc:
+            # tasks.json may contain comments (JSONC); never rewrite what we cannot parse faithfully.
+            raise ValueError(f"{TASKS_PATH} is not plain JSON (it may contain comments); refusing to modify it. "
+                             "Add the UDS tasks manually (see docs/integrations.md).") from exc
+        if not isinstance(data, dict) or not isinstance(data.get("tasks", []), list):
+            raise ValueError(f"{TASKS_PATH} has an unexpected structure; refusing to modify it.")
+    tasks = [t for t in data.get("tasks", []) if not (isinstance(t, dict) and str(t.get("label", "")).startswith(LABEL_PREFIX))]
+    if not remove:
+        tasks.extend(UDS_TASKS)
+    data["tasks"] = tasks
+    data.setdefault("version", "2.0.0")
+    content = json.dumps(data, indent=2) + "\n"
+    result = apply_changes(root, {TASKS_PATH: content}, "vscode tasks " + ("remove" if remove else "install"), apply)
+    result["tasks_file"] = TASKS_PATH
+    return result

universal_dev_security/policy.py

@@ -0,0 +1,384 @@
+"""Central UDS security policy engine.
+
+Every integration (CLI, Git hooks, Claude Code hooks, generic AI agents)
+describes what it is about to do as an :class:`Action`. The engine evaluates it
+against the immutable global rules plus any *additional* restrictions from the
+project configuration and returns a :class:`PolicyDecision`.
+
+Precedence: mandatory global policy > technology profile > project config.
+Project configuration can add deny/approval rules and protected paths, but it
+cannot remove or downgrade a global rule.
+"""
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path, PurePosixPath
+from typing import Any, Callable
+
+from universal_dev_security.config import ProjectConfig
+from universal_dev_security.redaction import find_secrets
+
+
+class Decision(str, Enum):
+    ALLOW = "allow"
+    ASK = "ask"      # explicit user approval required
+    DENY = "deny"
+
+    @property
+    def rank(self) -> int:
+        return {"allow": 0, "ask": 1, "deny": 2}[self.value]
+
+
+class Risk(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @property
+    def rank(self) -> int:
+        return {"low": 0, "medium": 1, "high": 2, "critical": 3}[self.value]
+
+
+class ActionKind(str, Enum):
+    SHELL = "shell"
+    WRITE_FILE = "write_file"
+    EDIT_FILE = "edit_file"
+    READ_FILE = "read_file"
+    DELETE_FILE = "delete_file"
+    GIT_COMMIT = "git_commit"
+    GIT_PUSH = "git_push"
+    PUBLISH = "publish"
+
+
+@dataclass
+class Action:
+    kind: ActionKind
+    command: str = ""
+    path: str = ""
+    content: str = ""
+    actor: str = "ai"            # "ai", "user", "ci", "hook"
+    project_root: str = ""
+
+    def __post_init__(self) -> None:
+        self.kind = ActionKind(self.kind)
+        # Bound the amount of text inspected to keep evaluation fast.
+        self.command = (self.command or "")[:100_000]
+        self.content = (self.content or "")[:2_000_000]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Action":
+        if not isinstance(data, dict):
+            raise ValueError("Action must be a JSON object")
+        kind = data.get("action") or data.get("kind")
+        try:
+            action_kind = ActionKind(kind)
+        except ValueError as exc:
+            raise ValueError(f"Unknown action kind: {kind!r}") from exc
+        return cls(
+            kind=action_kind,
+            command=str(data.get("command", "") or ""),
+            path=str(data.get("path", "") or ""),
+            content=str(data.get("content", "") or ""),
+            actor=str(data.get("actor", "ai") or "ai"),
+            project_root=str(data.get("project_root", "") or ""),
+        )
+
+
+@dataclass
+class RuleMatch:
+    rule_id: str
+    decision: Decision
+    risk: Risk
+    reason: str
+    source: str = "global"   # "global" or "project"
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "rule_id": self.rule_id,
+            "decision": self.decision.value,
+            "risk": self.risk.value,
+            "reason": self.reason,
+            "source": self.source,
+        }
+
+
+@dataclass
+class PolicyDecision:
+    decision: Decision
+    risk: Risk
+    matches: list[RuleMatch] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def reason(self) -> str:
+        if not self.matches:
+            return "No UDS policy rule matched."
+        relevant = [m for m in self.matches if m.decision is self.decision] or self.matches
+        return "; ".join(f"[{m.rule_id}] {m.reason}" for m in relevant)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "decision": self.decision.value,
+            "risk": self.risk.value,
+            "reason": self.reason,
+            "matches": [match.to_dict() for match in self.matches],
+            "warnings": self.warnings,
+        }
+
+
+# --------------------------------------------------------------------------
+# Shell command rules
+# --------------------------------------------------------------------------
+
+MAX_ANALYZED_COMMAND_CHARS = 20_000
+
+_GIT = r"\bgit(?:\.exe)?(?:\s+(?:-C\s+\S+|-c\s+\S+|--[\w-]+(?:=\S+)?))*\s+"
+
+
+@dataclass(frozen=True)
+class CommandRule:
+    rule_id: str
+    pattern: re.Pattern[str]
+    decision: Decision
+    risk: Risk
+    reason: str
+
+
+def _rule(rule_id: str, pattern: str, decision: Decision, risk: Risk, reason: str) -> CommandRule:
+    return CommandRule(rule_id, re.compile(pattern, re.IGNORECASE), decision, risk, reason)
+
+
+GLOBAL_COMMAND_RULES: tuple[CommandRule, ...] = (
+    _rule("git-hook-bypass", _GIT + r"(?:(?:commit|merge|am)\b.{0,1000}(?:--no-verify|\s-[a-z]*n[a-z]*\b(?!\s*=))|(?:push|rebase)\b.{0,1000}--no-verify)",
+          Decision.DENY, Risk.CRITICAL, "Bypassing Git hooks disables UDS protections."),
+    _rule("git-hooks-path-change", _GIT + r"config\b.{0,1000}\bcore\.hooksPath\b",
+          Decision.ASK, Risk.HIGH, "Changing core.hooksPath can disable UDS Git protection."),
+    _rule("git-force-push", _GIT + r"push\b.{0,1000}(?:--force\b|--force-with-lease\b|--force-if-includes\b|\s-f\b|\s\+\S+)",
+          Decision.ASK, Risk.CRITICAL, "Force push rewrites remote history and requires explicit approval."),
+    _rule("git-push", _GIT + r"push\b",
+          Decision.ASK, Risk.HIGH, "Git push always requires explicit user approval."),
+    _rule("git-commit", _GIT + r"commit\b",
+          Decision.ASK, Risk.MEDIUM, "Commits require explicit user approval (staged content should be scanned)."),
+    _rule("git-history-rewrite", _GIT + r"(?:filter-branch|filter-repo|replace)\b|" + _GIT + r"rebase\b|" + _GIT + r"reset\s+--hard\b",
+          Decision.ASK, Risk.HIGH, "History rewrites and hard resets can destroy work."),
+    _rule("git-discard-changes", _GIT + r"(?:clean\s+-[a-z]*f|checkout\s+(?:--\s+)?\.(?:\s|$)|restore\s+(?:--\S+\s+)*\.(?:\s|$)|stash\s+(?:drop|clear)\b|branch\s+-D\b)",
+          Decision.ASK, Risk.HIGH, "This Git command discards uncommitted work or branches."),
+    _rule("git-global-config", _GIT + r"config\s+(?:--global|--system)\b",
+          Decision.ASK, Risk.HIGH, "Global Git configuration changes affect every project on this machine."),
+    _rule("delete-root", r"\brm\s+(?:-[a-z]*\s+)*(?:/|~|\$HOME|/\*|[a-z]:\\?)\s*$|\bRemove-Item\b.{0,1000}\s(?:[a-z]:\\|~)\s*(?:-|$)|\bformat\s+[a-z]:|\bmkfs(?:\.\w+)?\b|\bdd\s+if=",
+          Decision.DENY, Risk.CRITICAL, "Command could destroy a whole drive or home directory."),
+    _rule("recursive-delete", r"\brm\s+(?:-[a-z]*r[a-z]*|-[a-z]*R[a-z]*|--recursive)\b|\bRemove-Item\b.{0,1000}-Recurse|\b(?:rd|rmdir)\s+/s\b|\bdel\s+(?:/[a-z]\s+)*/s\b|\bshutil\.rmtree\b",
+          Decision.ASK, Risk.HIGH, "Recursive deletion requires explicit approval."),
+    _rule("remote-code-execution", r"\b(?:curl|wget|iwr|irm|Invoke-WebRequest|Invoke-RestMethod)\b[^|]{0,1000}\|\s*(?:sudo\s+)?(?:sh|bash|zsh|python\d*|iex|Invoke-Expression|pwsh|powershell)\b|\biex\s*\(.{0,1000}DownloadString|Invoke-Expression\s*\(.{0,1000}(?:DownloadString|Invoke-WebRequest|irm|iwr)",
+          Decision.ASK, Risk.CRITICAL, "Piping downloaded content into an interpreter executes unreviewed code."),
+    _rule("system-security-settings", r"\bSet-MpPreference\b|\bAdd-MpPreference\b.{0,1000}-Exclusion|\bnetsh\s+(?:adv)?firewall\b.{0,1000}\b(?:off|disable)\b|\bSet-NetFirewallProfile\b.{0,1000}-Enabled\s+False|\bSet-ExecutionPolicy\b.{0,1000}\b(?:Unrestricted|Bypass)\b.{0,1000}-Scope\s+LocalMachine|\bbcdedit\b|\bsetenforce\s+0\b|\bufw\s+disable\b|\bspctl\s+--master-disable\b|\bcsrutil\s+disable\b",
+          Decision.DENY, Risk.CRITICAL, "Changing machine security settings is outside the UDS authorization boundary."),
+    _rule("system-wide-install", r"\b(?:npm|pnpm|yarn)\s+(?:install|i|add)\s+(?:.{0,1000}\s)?(?:-g|--global)\b|\b(?:winget|choco|scoop|brew|apt|apt-get|dnf|yum|pacman|zypper|snap)\s+install\b|\bsudo\b|\bpip3?\s+install\b.{0,1000}--user\b|\bmsiexec\b",
+          Decision.ASK, Risk.HIGH, "System-wide or privileged installation requires approval."),
+    _rule("publish", r"\b(?:npm|pnpm|yarn)\s+publish\b|\btwine\s+upload\b|\b(?:poetry|uv|flit|hatch)\s+publish\b|\bcargo\s+publish\b|\bgem\s+push\b|\bdotnet\s+nuget\s+push\b|\bdocker\s+push\b|\bgh\s+release\s+create\b|\bgh\s+repo\s+create\b|\bgh\s+pr\s+(?:create|merge)\b|\bmvn\b.{0,1000}\bdeploy\b|\bcomposer\s+publish\b",
+          Decision.ASK, Risk.HIGH, "Publishing or uploading requires explicit approval."),
+    _rule("secret-file-access", r"(?:^|[\s\"'=<>/\\])(?:\.env(?!\.(?:example|sample|template|dist)\b)(?:\.[\w.-]+)?|id_rsa|id_ed25519|id_ecdsa|[\w.-]+\.pem|[\w.-]+\.p12|[\w.-]+\.pfx|[\w.-]+\.key|credentials(?:\.json)?|\.npmrc|\.pypirc|\.netrc)(?=$|[\s\"'|;&>)])",
+          Decision.ASK, Risk.MEDIUM, "Command touches a file that commonly contains credentials."),
+    _rule("security-control-modification", r"(?:^|[\s\"'=/\\])(?:\.uds[/\\]|\.claude[/\\]settings(?:\.local)?\.json|\.git[/\\]hooks\b|\.gitleaks\.toml|\.gitleaksignore)",
+          Decision.ASK, Risk.HIGH, "Command touches UDS, Claude Code, or Git hook security configuration."),
+    _rule("uds-protection-removal", r"\buds(?:\.exe)?\s+(?:hooks\s+uninstall|integrate\s+\S+\s+--remove|rollback)\b",
+          Decision.ASK, Risk.HIGH, "Removing UDS protections or rolling back requires explicit approval."),
+    _rule("world-writable-permissions", r"\bchmod\s+(?:-R\s+)?(?:0?777|a\+w|o\+w)\b|\bicacls\b.{0,1000}\bEveryone:\(?F",
+          Decision.ASK, Risk.MEDIUM, "Granting world-writable permissions weakens file security."),
+)
+
+# --------------------------------------------------------------------------
+# File rules
+# --------------------------------------------------------------------------
+
+SECRET_FILE_GLOBS = (
+    ".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa", "id_rsa*", "id_ed25519*", "id_ecdsa*",
+    ".npmrc", ".pypirc", ".netrc", "credentials", "credentials.json", "*.keystore", "*.jks",
+)
+SECRET_FILE_ALLOW = (".env.example", ".env.sample", ".env.template", ".env.dist")
+
+SECURITY_CONTROL_GLOBS = (
+    ".uds/*", ".uds/**", ".claude/settings.json", ".claude/settings.local.json", ".git/hooks/*",
+    ".git/config", ".gitleaks.toml", ".gitleaksignore", ".semgrepignore", ".trivyignore",
+)
+CI_GLOBS = (".github/workflows/*", ".github/workflows/**", ".gitlab-ci.yml", "azure-pipelines.yml")
+
+
+def _relative_posix(path: str, project_root: str) -> tuple[str, bool]:
+    """Return (relative posix path, inside_project)."""
+    if not path:
+        return "", True
+    candidate = Path(path)
+    if project_root:
+        root = Path(project_root).expanduser().resolve()
+        absolute = candidate if candidate.is_absolute() else root / candidate
+        try:
+            resolved = absolute.resolve()
+        except (OSError, RuntimeError):
+            return path.replace("\\", "/"), False
+        try:
+            return resolved.relative_to(root).as_posix(), True
+        except ValueError:
+            return resolved.as_posix(), False
+    normalized = path.replace("\\", "/")
+    inside = not candidate.is_absolute() and ".." not in PurePosixPath(normalized).parts
+    return normalized.lstrip("./") if normalized.startswith("./") else normalized, inside
+
+
+def _matches_any(relative: str, globs: tuple[str, ...] | list[str]) -> bool:
+    name = PurePosixPath(relative).name
+    lowered = relative.lower()
+    for glob in globs:
+        glob_l = glob.lower()
+        if fnmatch.fnmatchcase(lowered, glob_l) or fnmatch.fnmatchcase(name.lower(), glob_l):
+            return True
+        if glob_l.endswith("/**") and (lowered + "/").startswith(glob_l[:-2]):
+            return True
+    return False
+
+
+# --------------------------------------------------------------------------
+# Engine
+# --------------------------------------------------------------------------
+
+class PolicyEngine:
+    def __init__(self, config: ProjectConfig | None = None) -> None:
+        self.config = config or ProjectConfig()
+        self._project_command_rules: list[CommandRule] = []
+        self.warnings: list[str] = list(self.config.warnings)
+        for pattern in self.config.deny_command_patterns:
+            self._add_project_rule("project-deny", pattern, Decision.DENY, Risk.HIGH)
+        for pattern in self.config.approval_command_patterns:
+            self._add_project_rule("project-approval", pattern, Decision.ASK, Risk.MEDIUM)
+
+    def _add_project_rule(self, rule_id: str, pattern: str, decision: Decision, risk: Risk) -> None:
+        try:
+            compiled = re.compile(pattern, re.IGNORECASE)
+        except re.error:
+            self.warnings.append(f"Invalid project command pattern ignored: {pattern!r}")
+            return
+        self._project_command_rules.append(
+            CommandRule(rule_id, compiled, decision, risk, f"Project policy matched pattern {pattern!r}.")
+        )
+
+    # -- public API -----------------------------------------------------
+
+    def evaluate(self, action: Action) -> PolicyDecision:
+        handlers: dict[ActionKind, Callable[[Action], list[RuleMatch]]] = {
+            ActionKind.SHELL: self._evaluate_shell,
+            ActionKind.WRITE_FILE: self._evaluate_write,
+            ActionKind.EDIT_FILE: self._evaluate_write,
+            ActionKind.READ_FILE: self._evaluate_read,
+            ActionKind.DELETE_FILE: self._evaluate_delete,
+            ActionKind.GIT_COMMIT: lambda a: [RuleMatch("git-commit", Decision.ASK, Risk.MEDIUM,
+                                                        "Commits require explicit user approval.")],
+            ActionKind.GIT_PUSH: lambda a: [RuleMatch("git-push", Decision.ASK, Risk.HIGH,
+                                                      "Git push always requires explicit user approval.")],
+            ActionKind.PUBLISH: lambda a: [RuleMatch("publish", Decision.ASK, Risk.HIGH,
+                                                     "Publishing requires explicit approval.")],
+        }
+        matches = handlers[action.kind](action)
+        return self._combine(matches)
+
+    def _combine(self, matches: list[RuleMatch]) -> PolicyDecision:
+        if not matches:
+            return PolicyDecision(Decision.ALLOW, Risk.LOW, [], list(self.warnings))
+        if self.config.security_mode == "strict":
+            for match in matches:
+                if match.risk is Risk.CRITICAL and match.decision is Decision.ASK:
+                    match.decision = Decision.DENY
+                    match.reason += " (strict mode: denied)"
+        decision = max((m.decision for m in matches), key=lambda d: d.rank)
+        risk = max((m.risk for m in matches), key=lambda r: r.rank)
+        return PolicyDecision(decision, risk, matches, list(self.warnings))
+
+    # -- shell ----------------------------------------------------------
+
+    def _evaluate_shell(self, action: Action) -> list[RuleMatch]:
+        command = action.command
+        matches: list[RuleMatch] = []
+        seen: set[str] = set()
+        if len(command) > MAX_ANALYZED_COMMAND_CHARS:
+            # Too long to analyze reliably and cheaply: never allow silently.
+            return [RuleMatch("command-too-long", Decision.ASK, Risk.HIGH,
+                              f"Command exceeds {MAX_ANALYZED_COMMAND_CHARS} characters and was not analyzed.")]
+        parts = [s for s in re.split(r"\r?\n|;|&&|\|\||(?<!\|)&(?!&)", command) if s.strip()]
+        segments = parts if len(parts) > 1 else [command]
+        if len(parts) > 1 and "\n" in command:
+            segments.append(command)  # keep cross-line context (e.g. heredocs piped to an interpreter)
+        for segment in segments:
+            normalized = " ".join(segment.split())
+            rules = list(GLOBAL_COMMAND_RULES) + self._project_command_rules
+            for rule in rules:
+                if rule.rule_id in seen:
+                    continue
+                if rule.pattern.search(normalized):
+                    # A force push also matches the generic push rule; keep the stronger one.
+                    if rule.rule_id == "git-push" and "git-force-push" in seen:
+                        continue
+                    seen.add(rule.rule_id)
+                    source = "project" if rule.rule_id.startswith("project-") else "global"
+                    matches.append(RuleMatch(rule.rule_id, rule.decision, rule.risk, rule.reason, source))
+        if find_secrets(command):
+            matches.append(RuleMatch("secret-in-command", Decision.ASK, Risk.HIGH,
+                                     "Command contains a likely credential; it would be stored in shell history and logs."))
+        for protected in self.config.protected_paths:
+            if protected and protected.replace("\\", "/").lower() in command.replace("\\", "/").lower():
+                matches.append(RuleMatch("project-protected-path", Decision.ASK, Risk.HIGH,
+                                         f"Command references protected path {protected!r}.", "project"))
+                break
+        return matches
+
+    # -- files ----------------------------------------------------------
+
+    def _path_matches(self, action: Action, *, write: bool) -> list[RuleMatch]:
+        relative, inside = _relative_posix(action.path, action.project_root)
+        matches: list[RuleMatch] = []
+        if not relative:
+            return matches
+        if not inside:
+            matches.append(RuleMatch("outside-project", Decision.ASK, Risk.HIGH,
+                                     "Path is outside the project directory."))
+        if _matches_any(relative, SECURITY_CONTROL_GLOBS):
+            matches.append(RuleMatch("security-control-modification" if write else "security-control-read",
+                                     Decision.ASK if write else Decision.ALLOW, Risk.HIGH if write else Risk.LOW,
+                                     "File is part of the UDS / Claude Code / Git hook security configuration."))
+        if _matches_any(relative, CI_GLOBS) and write:
+            matches.append(RuleMatch("ci-workflow-modification", Decision.ASK, Risk.MEDIUM,
+                                     "CI workflow changes can alter security checks and secret access."))
+        name = PurePosixPath(relative).name.lower()
+        if _matches_any(relative, SECRET_FILE_GLOBS) and name not in SECRET_FILE_ALLOW:
+            matches.append(RuleMatch("secret-file-access", Decision.ASK, Risk.MEDIUM,
+                                     "File commonly contains credentials."))
+        if self.config.protected_paths and _matches_any(relative, self.config.protected_paths):
+            matches.append(RuleMatch("project-protected-path", Decision.ASK, Risk.HIGH,
+                                     "Path is protected by project policy.", "project"))
+        return [m for m in matches if m.decision is not Decision.ALLOW]
+
+    def _evaluate_write(self, action: Action) -> list[RuleMatch]:
+        matches = self._path_matches(action, write=True)
+        secrets = find_secrets(action.content)
+        if secrets:
+            rules = sorted({s.rule_id for s in secrets})
+            lines = sorted({s.line for s in secrets})[:10]
+            matches.append(RuleMatch("secret-in-file", Decision.DENY, Risk.CRITICAL,
+                                     f"Content contains likely credential(s) ({', '.join(rules)}) at line(s) "
+                                     f"{', '.join(map(str, lines))}. Store secrets in environment variables or a "
+                                     "secret manager instead."))
+        return matches
+
+    def _evaluate_read(self, action: Action) -> list[RuleMatch]:
+        return self._path_matches(action, write=False)
+
+    def _evaluate_delete(self, action: Action) -> list[RuleMatch]:
+        matches = self._path_matches(action, write=True)
+        matches.append(RuleMatch("file-delete", Decision.ASK, Risk.MEDIUM, "Deleting files requires approval."))
+        return matches
+
+
+def evaluate(action: Action, config: ProjectConfig | None = None) -> PolicyDecision:
+    return PolicyEngine(config).evaluate(action)

universal_dev_security/projectfiles.py

@@ -0,0 +1,80 @@
+"""Bounded, symlink-safe project file inventory used by detection and scanners."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Directories that are never project source and are expensive to walk.
+DEFAULT_EXCLUDED_DIRS = frozenset({
+    ".git", ".hg", ".svn", ".uds", ".venv", "venv", "env", ".tox", ".nox", "__pycache__",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", "node_modules", "bower_components",
+    ".next", ".nuxt", ".svelte-kit", "dist", "build", "out", "target", "bin", "obj",
+    ".gradle", ".idea", ".vs", ".vscode", "coverage", "htmlcov", ".terraform", ".cache",
+    "site-packages", ".eggs",
+})
+
+
+@dataclass
+class ProjectInventory:
+    root: Path
+    files: list[str] = field(default_factory=list)   # posix paths relative to root
+    truncated: bool = False
+
+    @property
+    def names(self) -> set[str]:
+        return {path.rsplit("/", 1)[-1] for path in self.files}
+
+    @property
+    def suffixes(self) -> set[str]:
+        result = set()
+        for path in self.files:
+            name = path.rsplit("/", 1)[-1]
+            if "." in name:
+                result.add("." + name.rsplit(".", 1)[-1].lower())
+        return result
+
+    def has_name(self, *names: str) -> bool:
+        wanted = {n.lower() for n in names}
+        return any(name.lower() in wanted for name in self.names)
+
+    def has_suffix(self, *suffixes: str) -> bool:
+        return bool(self.suffixes & {s.lower() for s in suffixes})
+
+    def find(self, name: str) -> list[str]:
+        lowered = name.lower()
+        return [p for p in self.files if p.rsplit("/", 1)[-1].lower() == lowered]
+
+    def has_path_part(self, part: str) -> bool:
+        needle = part.strip("/").lower()
+        return any(f"/{needle}/" in f"/{p.lower()}" for p in self.files)
+
+
+def build_inventory(
+    root: Path,
+    *,
+    max_files: int = 50_000,
+    max_depth: int = 12,
+    extra_excludes: list[str] | None = None,
+) -> ProjectInventory:
+    """Walk ``root`` without following symlinks, skipping heavy directories."""
+    resolved = root.expanduser().resolve()
+    inventory = ProjectInventory(root=resolved)
+    excluded = set(DEFAULT_EXCLUDED_DIRS) | {e.strip("/\\") for e in (extra_excludes or []) if e}
+    base_depth = len(resolved.parts)
+    for current, dirs, files in os.walk(resolved, followlinks=False):
+        current_path = Path(current)
+        depth = len(current_path.parts) - base_depth
+        dirs[:] = sorted(
+            d for d in dirs
+            if d not in excluded and not (current_path / d).is_symlink() and depth < max_depth
+        )
+        for name in sorted(files):
+            relative = (current_path / name).relative_to(resolved).as_posix()
+            if relative in excluded:
+                continue
+            inventory.files.append(relative)
+            if len(inventory.files) >= max_files:
+                inventory.truncated = True
+                return inventory
+    return inventory