fix(lp3): remediation and docs name allowed-tools for SKILL.md (#316)

LP3's detection logic accepts `allowed-tools` as a valid tool-scope
declaration, but the runtime remediation string, the pattern-defaults
fallback, and docs/B.3.1 still directed authors to add a `permissions`
field. For Claude Code / Agent Skills SKILL.md, `permissions` is not part
of the frontmatter schema and is ignored as unknown, so following the
advice could never resolve the finding.

Aligned the three user-facing strings with the code:

- LP3 remediation (analyzer + pattern_defaults): declare `allowed-tools`
  in SKILL.md frontmatter, or a `permissions` list in MCP server
  manifests, stating which applies to which manifest type.
- LP3 finding message + description: "declares no tool scope
  ('permissions' or 'allowed-tools')" instead of "no declared
  permissions", matching the actual trigger condition.
- docs/B.3.1 LP3 section: Triggers when / Example / Remediation updated
  the same way.

No behavior change; detection logic untouched. tests/test_mcp_least_privilege.py 15/15.

Closes #313

Signed-off-by: ppcvote <risky9763@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: ppcvote

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.
 
 ---
 

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."
                 ),
             )
         )

src/skillspector/nodes/analyzers/pattern_defaults.py

@@ -121,7 +121,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.",
@@ -380,7 +380,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.",