diff --git a/docs/B.3.1-mcp-least-privilege.md b/docs/B.3.1-mcp-least-privilege.md index 38434204..a38a77fb 100644 --- a/docs/B.3.1-mcp-least-privilege.md +++ b/docs/B.3.1-mcp-least-privilege.md @@ -160,19 +160,24 @@ permissions. Request only the minimum access needed. | **Confidence** | 0.70 | | **Tags** | ASI02 | -**Triggers when:** The manifest has no `permissions` field (or it is an empty -list) **and** the analyzer detects code capabilities in executable files. +**Triggers when:** The manifest declares no tool scope -- no `permissions` +field (or an empty list) **and** no `allowed-tools` frontmatter -- and the +analyzer detects code capabilities in executable files. **Why it matters:** Without declared permissions, the skill's intent is completely opaque. Users and agents cannot evaluate whether the skill's access level is appropriate. This is less suspicious than LP1 (could be an oversight rather than deception) but still a significant transparency gap. -**Example:** A SKILL.md with no `permissions:` key, but the code calls -`os.environ["API_KEY"]` and `subprocess.run(...)`. +**Example:** A SKILL.md with neither a `permissions:` key nor an +`allowed-tools:` key, but the code calls `os.environ["API_KEY"]` and +`subprocess.run(...)`. -**Remediation:** Add a `permissions` field to SKILL.md listing the capabilities -the skill requires. +**Remediation:** Declare the skill's tool scope in the manifest type you are +authoring. For Claude Code / Agent Skills `SKILL.md`, list the tools the skill +may invoke in the `allowed-tools` frontmatter field (`permissions` is not part +of the SKILL.md schema and is ignored). For MCP server manifests, add a +`permissions` list naming the required capabilities. --- diff --git a/src/skillspector/nodes/analyzers/mcp_least_privilege.py b/src/skillspector/nodes/analyzers/mcp_least_privilege.py index 4a4106fe..dc2f387d 100644 --- a/src/skillspector/nodes/analyzers/mcp_least_privilege.py +++ b/src/skillspector/nodes/analyzers/mcp_least_privilege.py @@ -312,7 +312,8 @@ def node(state: SkillspectorState) -> AnalyzerNodeResponse: Finding( rule_id="LP3", message=( - f"Skill has no declared permissions but code capabilities were detected: {cap_names}." + f"Skill declares no tool scope ('permissions' or 'allowed-tools') " + f"but code capabilities were detected: {cap_names}." ), severity="MEDIUM", confidence=_clamp(0.70), @@ -323,7 +324,10 @@ def node(state: SkillspectorState) -> AnalyzerNodeResponse: "Without declared permissions the skill's intent is opaque and cannot be validated." ), remediation=( - "Add a 'permissions' field to SKILL.md listing the capabilities this skill requires." + "Declare the skill's tool scope: for Claude Code / Agent Skills " + "SKILL.md, list the tools the skill may invoke in the " + "'allowed-tools' frontmatter field; for MCP server manifests, " + "add a 'permissions' list naming the required capabilities." ), ) ) diff --git a/src/skillspector/nodes/analyzers/pattern_defaults.py b/src/skillspector/nodes/analyzers/pattern_defaults.py index bb0a7f2b..b860ba39 100644 --- a/src/skillspector/nodes/analyzers/pattern_defaults.py +++ b/src/skillspector/nodes/analyzers/pattern_defaults.py @@ -119,7 +119,7 @@ class PatternCategory(StrEnum): # MCP Least Privilege (B.3.1) "LP1": "Code uses capabilities (network, shell, file write, etc.) not covered by declared permissions. The skill does more than it claims, which may indicate deceptive intent.", "LP2": "Permission list contains a wildcard ('*' or 'all'), granting blanket access with no least-privilege boundary. This disables permission-based security controls entirely.", - "LP3": "Skill has no permissions field in its manifest but code uses detectable capabilities. Without declared permissions, the skill's intent is opaque and cannot be validated.", + "LP3": "Skill declares no tool scope ('permissions' or 'allowed-tools') in its manifest but code uses detectable capabilities. Without a declaration, the skill's intent is opaque and cannot be validated.", "LP4": "Permission is declared but no corresponding code capability was detected. This may indicate removed functionality or pre-staging for future abuse.", # MCP Tool Poisoning (B.3.2) "TP1": "Hidden instructions detected in skill metadata (description, triggers, or parameters). These concealed directives can steer LLM behavior without the user's knowledge.", @@ -372,7 +372,7 @@ class PatternCategory(StrEnum): # MCP Least Privilege (B.3.1) "LP1": "Add the missing permission to SKILL.md, or remove the code that requires it.", "LP2": "Replace wildcard permissions ('*', 'all', 'full', 'any') with an explicit list of required permissions.", - "LP3": "Add a 'permissions' field to SKILL.md listing the capabilities this skill requires.", + "LP3": "Declare the skill's tool scope: for Claude Code / Agent Skills SKILL.md, list the tools the skill may invoke in the 'allowed-tools' frontmatter field; for MCP server manifests, add a 'permissions' list naming the required capabilities.", "LP4": "Remove the declared permission if the corresponding capability is no longer used.", # MCP Tool Poisoning (B.3.2) "TP1": "Remove hidden content (HTML comments, markdown comments, zero-width characters, base64 blobs) from metadata fields. Metadata should contain plain, visible text only.",