vmware-policy 1.4.0__tar.gz

vmware_policy-1.4.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: vmware-policy
+Version: 1.4.0
+Summary: Unified audit logging, policy enforcement, and sanitization for VMware MCP skills
+Author: Wei Zhou / 周崴
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: rich<15.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov<8.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<10.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# VMware Policy
+
+Unified audit logging, policy enforcement, and sanitization for the VMware MCP skill family.
+
+## Install
+
+```bash
+pip install vmware-policy
+```
+
+## Usage
+
+```python
+from vmware_policy import vmware_tool
+
+@vmware_tool(risk_level="high", sensitive_params=["password"])
+def delete_segment(name: str, env: str = "") -> dict:
+    ...
+```
+
+## CLI
+
+```bash
+vmware-audit log --last 20
+vmware-audit log --status denied --since 2026-03-28
+vmware-audit stats --days 7
+```

vmware_policy-1.4.0/README.md

@@ -0,0 +1,27 @@
+# VMware Policy
+
+Unified audit logging, policy enforcement, and sanitization for the VMware MCP skill family.
+
+## Install
+
+```bash
+pip install vmware-policy
+```
+
+## Usage
+
+```python
+from vmware_policy import vmware_tool
+
+@vmware_tool(risk_level="high", sensitive_params=["password"])
+def delete_segment(name: str, env: str = "") -> dict:
+    ...
+```
+
+## CLI
+
+```bash
+vmware-audit log --last 20
+vmware-audit log --status denied --since 2026-03-28
+vmware-audit stats --days 7
+```

vmware_policy-1.4.0/docs/version-strategy.md

@@ -0,0 +1,54 @@
+# VMware Policy — Version Strategy
+
+## Independent Versioning
+
+vmware-policy uses its own version number, independent of the VMware skill family (currently v1.3.5).
+
+**Rationale:** Policy is infrastructure-layer software with a different iteration cadence than business skills. Binding versions would force all 7 skills to release whenever policy gets a patch.
+
+## Semantic Versioning (semver)
+
+| Version bump | When | Example |
+|---|---|---|
+| Patch (1.0.x) | Bug fixes, logging improvements, rule additions | 1.0.0 -> 1.0.1 |
+| Minor (1.x.0) | New features (backward compatible): new decorator params, new CLI commands | 1.0.0 -> 1.1.0 |
+| Major (x.0.0) | Breaking changes to decorator signature or audit.db schema | 1.0.0 -> 2.0.0 |
+
+## Stability Guarantees (v1.x)
+
+The following are **public API** and will NOT change in v1.x:
+
+1. `@vmware_tool` decorator signature (all params remain optional, keyword-only)
+2. `_is_vmware_tool` attribute on decorated functions
+3. `_risk_level`, `_idempotent`, `_timeout_seconds`, `_sensitive_params` metadata attributes
+4. `sanitize(text, max_len)` function signature
+5. `audit.db` table schema (columns may be added, never removed or renamed)
+6. `PolicyDenied` exception class
+7. `vmware-audit` CLI command names (log, export, stats)
+
+## Dependency Declaration
+
+All skills should declare:
+
+```toml
+"vmware-policy>=1.0.0,<2.0"
+```
+
+This allows any 1.x patch/minor update without requiring skill changes.
+
+## Release Checklist
+
+1. Update `vmware_policy/__init__.py` version
+2. Update `pyproject.toml` version
+3. Run `pytest tests/ -v` (all must pass)
+4. Build: `python -m build`
+5. Tag: `git tag v1.x.x`
+6. Publish to PyPI: `uv publish`
+
+## vmware-harness Versioning
+
+vmware-harness also has its own version (starting at v0.1.0, pre-stable).
+
+- v0.x: API may change without major version bump
+- v1.0: First stable release (after production validation)
+- Same semver rules as vmware-policy after v1.0

vmware_policy-1.4.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vmware-policy"
+version = "1.4.0"
+description = "Unified audit logging, policy enforcement, and sanitization for VMware MCP skills"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Wei Zhou / 周崴" }]
+dependencies = [
+    "typer>=0.12,<1.0",
+    "rich>=13.0,<15.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<10.0",
+    "pytest-cov>=5.0,<8.0",
+    "ruff>=0.5,<1.0",
+]
+
+[project.scripts]
+vmware-audit = "vmware_policy.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vmware_policy"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "unit: Unit tests",
+]

vmware_policy-1.4.0/tests/test_audit.py

@@ -0,0 +1,107 @@
+"""Tests for vmware_policy.audit."""
+
+import sqlite3
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from vmware_policy.audit import AuditEngine, detect_agent
+
+
+@pytest.mark.unit
+class TestAuditEngine:
+    def setup_method(self):
+        self._tmp = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+        self._tmp.close()
+        self.db_path = Path(self._tmp.name)
+        self.engine = AuditEngine(self.db_path)
+
+    def teardown_method(self):
+        self.db_path.unlink(missing_ok=True)
+
+    def test_creates_db_and_table(self):
+        conn = sqlite3.connect(str(self.db_path))
+        tables = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table'"
+        ).fetchall()
+        conn.close()
+        assert ("audit_log",) in tables
+
+    def test_wal_mode_enabled(self):
+        conn = sqlite3.connect(str(self.db_path))
+        mode = conn.execute("PRAGMA journal_mode").fetchone()[0]
+        conn.close()
+        assert mode == "wal"
+
+    def test_log_writes_record(self):
+        self.engine.log(skill="aiops", tool="vm_power_on", status="ok")
+        rows = self.engine.query(limit=10)
+        assert len(rows) == 1
+        assert rows[0]["skill"] == "aiops"
+        assert rows[0]["tool"] == "vm_power_on"
+        assert rows[0]["status"] == "ok"
+
+    def test_log_denied_writes_record(self):
+        self.engine.log(skill="nsx", tool="delete_segment", status="denied")
+        rows = self.engine.query(status="denied")
+        assert len(rows) == 1
+        assert rows[0]["status"] == "denied"
+
+    def test_query_filters(self):
+        self.engine.log(skill="aiops", tool="vm_power_on", status="ok")
+        self.engine.log(skill="nsx", tool="delete_segment", status="denied")
+        self.engine.log(skill="aiops", tool="vm_power_off", status="error")
+
+        assert len(self.engine.query(skill="aiops")) == 2
+        assert len(self.engine.query(status="denied")) == 1
+        assert len(self.engine.query(tool="vm_power_on")) == 1
+
+    def test_stats(self):
+        self.engine.log(skill="aiops", tool="a", status="ok")
+        self.engine.log(skill="aiops", tool="b", status="ok")
+        self.engine.log(skill="nsx", tool="c", status="denied")
+        data = self.engine.stats(days=1)
+        assert data["total"] == 3
+        assert data["by_skill"]["aiops"] == 2
+        assert data["by_status"]["denied"] == 1
+
+    def test_log_never_raises(self):
+        """Audit logging should swallow errors, not crash the tool."""
+        # Use an invalid path that can't be written
+        bad_engine = AuditEngine("/nonexistent/path/audit.db")
+        bad_engine.log(skill="test", tool="test")  # should not raise
+
+    def test_sensitive_params_stored(self):
+        self.engine.log(
+            skill="aiops",
+            tool="guest_exec",
+            params={"command": "ls", "password": "***"},
+            status="ok",
+        )
+        rows = self.engine.query(limit=1)
+        assert "***" in rows[0]["params"]
+
+
+@pytest.mark.unit
+class TestDetectAgent:
+    def test_default_unknown(self, monkeypatch):
+        monkeypatch.delenv("CLAUDE_SESSION_ID", raising=False)
+        monkeypatch.delenv("CLAUDE_CODE", raising=False)
+        monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+        monkeypatch.delenv("OLLAMA_HOST", raising=False)
+        monkeypatch.delenv("DEERFLOW_SESSION", raising=False)
+        monkeypatch.delenv("CODEX_SESSION", raising=False)
+        assert detect_agent() == "unknown"
+
+    def test_detect_claude(self, monkeypatch):
+        monkeypatch.setenv("CLAUDE_CODE", "1")
+        assert detect_agent() == "claude"
+
+    def test_detect_local(self, monkeypatch):
+        monkeypatch.delenv("CLAUDE_SESSION_ID", raising=False)
+        monkeypatch.delenv("CLAUDE_CODE", raising=False)
+        monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+        monkeypatch.delenv("CODEX_SESSION", raising=False)
+        monkeypatch.setenv("OLLAMA_HOST", "http://localhost:11434")
+        assert detect_agent() == "local"

vmware_policy-1.4.0/tests/test_decorators.py

@@ -0,0 +1,147 @@
+"""Tests for vmware_policy.decorators — the @vmware_tool decorator."""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from vmware_policy.audit import AuditEngine, _engine
+from vmware_policy.decorators import PolicyDenied, vmware_tool
+import vmware_policy.audit as audit_mod
+import vmware_policy.policy as policy_mod
+
+
+@pytest.fixture(autouse=True)
+def _fresh_singletons(tmp_path):
+    """Reset audit and policy singletons for each test."""
+    db_path = tmp_path / "test_audit.db"
+    engine = AuditEngine(db_path)
+    audit_mod._engine = engine
+    policy_mod._engine = None
+    yield engine
+    audit_mod._engine = None
+    policy_mod._engine = None
+
+
+@pytest.mark.unit
+class TestVmwareTool:
+    def test_bare_decorator(self, _fresh_singletons):
+        """@vmware_tool without arguments."""
+        @vmware_tool
+        def list_segments(target: str = "") -> list:
+            return ["seg1", "seg2"]
+
+        result = list_segments()
+        assert result == ["seg1", "seg2"]
+
+    def test_decorator_with_args(self, _fresh_singletons):
+        """@vmware_tool(risk_level='high')."""
+        @vmware_tool(risk_level="high", sensitive_params=["password"])
+        def delete_vm(name: str, password: str = "") -> str:
+            return f"deleted {name}"
+
+        result = delete_vm(name="test-vm", password="secret123")
+        assert result == "deleted test-vm"
+
+    def test_metadata_attached(self):
+        @vmware_tool(risk_level="critical", idempotent=True, timeout_seconds=60)
+        def my_tool() -> None:
+            pass
+
+        assert my_tool._is_vmware_tool is True
+        assert my_tool._risk_level == "critical"
+        assert my_tool._idempotent is True
+        assert my_tool._timeout_seconds == 60
+
+    def test_audit_log_written(self, _fresh_singletons):
+        engine = _fresh_singletons
+
+        @vmware_tool
+        def my_op(target: str = "") -> str:
+            return "done"
+
+        my_op(target="vcenter1")
+        rows = engine.query(limit=10)
+        assert len(rows) == 1
+        assert rows[0]["tool"] == "my_op"
+        assert rows[0]["status"] == "ok"
+
+    def test_error_logged(self, _fresh_singletons):
+        engine = _fresh_singletons
+
+        @vmware_tool
+        def failing_op() -> None:
+            raise RuntimeError("boom")
+
+        with pytest.raises(RuntimeError, match="boom"):
+            failing_op()
+
+        rows = engine.query(limit=10)
+        assert len(rows) == 1
+        assert rows[0]["status"] == "error"
+
+    def test_sensitive_params_redacted(self, _fresh_singletons):
+        engine = _fresh_singletons
+
+        @vmware_tool(sensitive_params=["password", "token"])
+        def login(user: str, password: str, token: str = "") -> str:
+            return "ok"
+
+        login(user="admin", password="secret", token="abc123")
+        rows = engine.query(limit=1)
+        params = rows[0]["params"]
+        assert "secret" not in params
+        assert "abc123" not in params
+        assert "***" in params
+        assert "admin" in params
+
+    def test_preserves_function_name(self):
+        @vmware_tool
+        def original_name() -> None:
+            """Original docstring."""
+            pass
+
+        assert original_name.__name__ == "original_name"
+        assert original_name.__doc__ == "Original docstring."
+
+    def test_duration_recorded(self, _fresh_singletons):
+        import time
+
+        engine = _fresh_singletons
+
+        @vmware_tool
+        def slow_op() -> str:
+            time.sleep(0.05)
+            return "done"
+
+        slow_op()
+        rows = engine.query(limit=1)
+        assert rows[0]["duration_ms"] >= 40
+
+
+@pytest.mark.unit
+class TestPolicyDenied:
+    def test_denied_logged_with_status(self, _fresh_singletons, tmp_path):
+        engine = _fresh_singletons
+
+        # Create a policy with deny rule
+        rules_path = tmp_path / "rules.yaml"
+        rules_path.write_text(
+            "deny:\n"
+            "  - name: no-delete\n"
+            '    operations: ["delete_*"]\n'
+            "    reason: Deletion not allowed\n"
+        )
+        policy_mod._engine = None
+        import vmware_policy.policy as pm
+        pm._engine = pm.PolicyEngine(rules_path)
+
+        @vmware_tool(risk_level="high")
+        def delete_segment(name: str) -> str:
+            return "deleted"
+
+        with pytest.raises(PolicyDenied, match="Deletion not allowed"):
+            delete_segment(name="seg1")
+
+        rows = engine.query(limit=1)
+        assert rows[0]["status"] == "denied"

vmware_policy-1.4.0/tests/test_policy.py

@@ -0,0 +1,119 @@
+"""Tests for vmware_policy.policy — the policy engine."""
+
+import pytest
+
+from vmware_policy.policy import PolicyEngine
+
+
+@pytest.mark.unit
+class TestPolicyEngine:
+    def test_no_rules_allows_all(self, tmp_path):
+        rules_path = tmp_path / "nonexistent.yaml"
+        engine = PolicyEngine(rules_path)
+        result = engine.check_allowed("delete_vm")
+        assert result.allowed is True
+        assert result.rule == "no_rules"
+
+    def test_deny_rule_blocks(self, tmp_path):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text(
+            "deny:\n"
+            "  - name: no-delete\n"
+            '    operations: ["delete_*"]\n'
+            "    reason: No deletions allowed\n"
+        )
+        engine = PolicyEngine(rules)
+        result = engine.check_allowed("delete_segment")
+        assert result.allowed is False
+        assert result.rule == "no-delete"
+        assert "No deletions" in result.reason
+
+    def test_deny_rule_env_filter(self, tmp_path):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text(
+            "deny:\n"
+            "  - name: no-delete-prod\n"
+            '    operations: ["delete_*"]\n'
+            '    environments: ["production"]\n'
+            "    reason: No deletions in prod\n"
+        )
+        engine = PolicyEngine(rules)
+
+        prod = engine.check_allowed("delete_vm", env="production")
+        assert prod.allowed is False
+
+        dev = engine.check_allowed("delete_vm", env="development")
+        assert dev.allowed is True
+
+    def test_deny_rule_risk_filter(self, tmp_path):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text(
+            "deny:\n"
+            "  - name: no-critical\n"
+            "    min_risk_level: critical\n"
+            "    reason: Critical ops blocked\n"
+        )
+        engine = PolicyEngine(rules)
+
+        crit = engine.check_allowed("any_op", risk_level="critical")
+        assert crit.allowed is False
+
+        low = engine.check_allowed("any_op", risk_level="low")
+        assert low.allowed is True
+
+    def test_wildcard_pattern(self, tmp_path):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text(
+            "deny:\n"
+            "  - name: block-all\n"
+            '    operations: ["*"]\n'
+            "    reason: Everything blocked\n"
+        )
+        engine = PolicyEngine(rules)
+        assert engine.check_allowed("anything").allowed is False
+
+    def test_exact_match(self, tmp_path):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text(
+            "deny:\n"
+            "  - name: specific\n"
+            '    operations: ["vm_power_off"]\n'
+            "    reason: Blocked\n"
+        )
+        engine = PolicyEngine(rules)
+        assert engine.check_allowed("vm_power_off").allowed is False
+        assert engine.check_allowed("vm_power_on").allowed is True
+
+    def test_hot_reload(self, tmp_path):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text("")
+        engine = PolicyEngine(rules)
+        assert engine.check_allowed("delete_vm").allowed is True
+
+        # Update rules file
+        rules.write_text(
+            "deny:\n"
+            "  - name: new-rule\n"
+            '    operations: ["delete_*"]\n'
+            "    reason: Now blocked\n"
+        )
+        # Force mtime change detection
+        import os
+        os.utime(rules, (rules.stat().st_mtime + 1, rules.stat().st_mtime + 1))
+
+        assert engine.check_allowed("delete_vm").allowed is False
+
+    def test_bypass_mode(self, tmp_path, monkeypatch):
+        rules = tmp_path / "rules.yaml"
+        rules.write_text(
+            "deny:\n"
+            "  - name: block-all\n"
+            '    operations: ["*"]\n'
+            "    reason: Blocked\n"
+        )
+        engine = PolicyEngine(rules)
+
+        monkeypatch.setenv("VMWARE_POLICY_DISABLED", "1")
+        result = engine.check_allowed("delete_vm")
+        assert result.allowed is True
+        assert result.rule == "policy_disabled"

vmware_policy-1.4.0/tests/test_sanitize.py

@@ -0,0 +1,33 @@
+"""Tests for vmware_policy.sanitize."""
+
+import pytest
+
+from vmware_policy.sanitize import sanitize
+
+
+@pytest.mark.unit
+class TestSanitize:
+    def test_strips_control_chars(self):
+        assert sanitize("hello\x00world") == "helloworld"
+        assert sanitize("a\x0b\x0cb") == "ab"
+        assert sanitize("\x7f\x80\x9f") == ""
+
+    def test_preserves_newline_and_tab(self):
+        assert sanitize("line1\nline2") == "line1\nline2"
+        assert sanitize("col1\tcol2") == "col1\tcol2"
+
+    def test_truncates_to_max_len(self):
+        long_text = "a" * 1000
+        assert len(sanitize(long_text)) == 500
+        assert len(sanitize(long_text, max_len=100)) == 100
+
+    def test_handles_non_string_input(self):
+        assert sanitize(12345) == "12345"
+        assert sanitize(None) == "None"
+
+    def test_empty_string(self):
+        assert sanitize("") == ""
+
+    def test_unicode_preserved(self):
+        assert sanitize("中文测试") == "中文测试"
+        assert sanitize("émojis 🎉") == "émojis 🎉"

vmware_policy-1.4.0/vmware_policy/__init__.py

@@ -0,0 +1,8 @@
+"""VMware Policy — unified audit, policy enforcement, and sanitization for VMware MCP skills."""
+
+__version__ = "1.4.0"
+
+from vmware_policy.decorators import vmware_tool
+from vmware_policy.sanitize import sanitize
+
+__all__ = ["vmware_tool", "sanitize"]