[repo] Detect shared directory creation capability

.github/codeql/queries/python/FilesystemWriteUsage.ql

@@ -0,0 +1,24 @@
+/**
+ * @name Plugin shared directory creation capability use
+ * @description Dispatcharr's watched directory creation helper requires the filesystem_write capability.
+ * @kind problem
+ * @problem.severity warning
+ * @precision medium
+ * @id plugin/capability-contract/filesystem-write
+ * @tags security external/cwe/cwe-269
+ */
+
+import python
+
+from Call call, Subscript helper, Subscript dispatcharr, StringLiteral helperKey,
+  StringLiteral dispatcharrKey, Name context
+where
+  call.getFunc() = helper and
+  helper.getObject() = dispatcharr and
+  helper.getIndex() = helperKey and
+  helperKey.getText() = "ensure_directory" and
+  dispatcharr.getObject() = context and
+  context.getId() = "context" and
+  dispatcharr.getIndex() = dispatcharrKey and
+  dispatcharrKey.getText() = "dispatcharr"
+select call, "Creating a watched directory requires the `filesystem_write` capability."

.github/codeql/queries/python/tests/FilesystemWriteUsage/FilesystemWriteUsage.expected

@@ -0,0 +1 @@
+| bad.py:1:1:1:51 | Subscript() | Creating a watched directory requires the `filesystem_write` capability. |

.github/codeql/queries/python/tests/FilesystemWriteUsage/FilesystemWriteUsage.qlref

@@ -0,0 +1 @@
+FilesystemWriteUsage.ql

.github/codeql/queries/python/tests/FilesystemWriteUsage/bad.py

@@ -0,0 +1 @@
+context["dispatcharr"]["ensure_directory"]("logos")

.github/codeql/queries/python/tests/FilesystemWriteUsage/good.py

@@ -0,0 +1,3 @@
+context["dispatcharr"]["remove_directory"](context["data_dir"] + "/snapshot")
+context["other"]["ensure_directory"]("logos")
+other["dispatcharr"]["ensure_directory"]("logos")

.github/pluginctl/src/pluginctl/capabilities.py

@@ -77,7 +77,7 @@
         "min_manifest_version": 1,
         "max_manifest_version": None,
         "runtime_enforced": True,
-        "codeql_rules": [],
+        "codeql_rules": ["plugin/capability-contract/filesystem-write"],
     },
     "celery_dispatch": {
         "group": "system",

.github/pluginctl/tests/test_capabilities.py

@@ -70,6 +70,7 @@ def test_each_runtime_enforced_static_rule_maps_to_its_capability():
         "network_listener": "plugin/capability-contract/network-listener",
         "subprocess": "plugin/capability-contract/subprocess",
         "outbound_network": "plugin/capability-contract/outbound-network",
+        "filesystem_write": "plugin/capability-contract/filesystem-write",
         "celery_dispatch": "plugin/capability-contract/celery-dispatch",
     }
     for capability_id, rule_id in expected.items():

.github/pluginctl/tests/test_sarif.py

@@ -221,6 +221,25 @@ def test_sandbox_bypass_rules_respect_schema_ranges(tmp_path, monkeypatch):
     assert not sarif.sandbox_result_requires_review(result(retired_rule))
 
 
+def test_filesystem_write_contract_respects_manifest_and_capability(tmp_path, monkeypatch):
+    plugin_dir = tmp_path / "plugins" / "demo"
+    plugin_dir.mkdir(parents=True)
+    monkeypatch.chdir(tmp_path)
+    result = {
+        "ruleId": "plugin/capability-contract/filesystem-write",
+        "locations": [{"physicalLocation": {"artifactLocation": {"uri": "plugins/demo/plugin.py"},
+                                               "region": {"startLine": 1}}}],
+    }
+    for version, declared, requires_review in (
+        (0, [], False), (1, [], False), (2, [], True),
+        (2, ["filesystem_write"], False),
+    ):
+        (plugin_dir / "plugin.json").write_text(json.dumps({
+            "manifest_version": version, "capabilities": declared,
+        }), encoding="utf-8")
+        assert sarif.contract_result_requires_review(result) == requires_review
+
+
 def test_capability_contract_accepts_declared_or_legacy_manifests(tmp_path, monkeypatch):
     plugin_dir = tmp_path / "plugins" / "demo"
     plugin_dir.mkdir(parents=True)