Security Concern: Pervasive ../ in Skill Files Creates Agent Behavior Normalization Risk

[sipuxd]

`## Summary

BMAD skill files contain 42 lines containing ../ directory traversal patterns across 25 files in src/bmm-skills/ and src/core-skills/. This directly conflicts with Anthropic's Claude Code security best practices, which explicitly recommend blocking .. in file paths. More critically, it creates an agent behavior normalization risk where the AI agent becomes conditioned to treat directory traversal as routine, increasing the likelihood of unintended file access (including sensitive files like .env, API keys, and credentials) during normal development workflows.

BMAD's own SECURITY.md lists "Path traversal or file system access issues" as in-scope vulnerabilities they want reported. The pervasive use of ../ across 25 skill files falls squarely within this category.

The Conflict

Anthropic's Claude Code Hooks documentation (https://code.claude.com/docs/en/hooks), under "Security best practices," states:

Block path traversal: check for .. in file paths

BMAD's skill validator rule PATH-01 (tools/skill-validator.md) mandates ../ for parent traversal:

Use ./ prefix for siblings or children, ../ for parent traversal.

And PATH-02 bans the old installed_path variable, explicitly recommending ../ as the replacement:

If the reference is in a step file and points to a skill-root file, use ../path instead.

These two positions are in direct conflict. The platform vendor says block ..; the framework mandates it.

Affected Files — Complete List

src/bmm-skills/ — 19 files, 33 occurrences

File	Lines
4-implementation/bmad-quick-dev/step-05-present.md	L25, L36, L39, L44, L47
1-analysis/bmad-product-brief/prompts/draft-and-review.md	L11, L39, L41
1-analysis/bmad-product-brief/prompts/contextual-discovery.md	L15, L17
2-plan-workflows/bmad-create-prd/steps-c/step-05-domain.md	L7, L82
2-plan-workflows/bmad-create-ux-design/steps/step-01-init.md	L83
2-plan-workflows/bmad-create-prd/steps-c/step-11-polish.md	L45
2-plan-workflows/bmad-create-prd/steps-c/step-06-innovation.md	L52
2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md	L4
3-solutioning/bmad-generate-project-context/steps/step-01-discover.md	L126
2-plan-workflows/bmad-create-prd/steps-c/step-07-project-type.md	L43
2-plan-workflows/bmad-validate-prd/steps-v/step-v-08-domain-compliance-validation.md	L7, L64
1-analysis/bmad-document-project/workflows/deep-dive-instructions.md	L196
1-analysis/bmad-document-project/workflows/full-scan-instructions.md	L19, L39, L813
3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md	L72, L163
2-plan-workflows/bmad-validate-prd/steps-v/step-v-09-project-type-validation.md	L7, L64
2-plan-workflows/bmad-create-prd/steps-c/step-01-init.md	L104
2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md	L83, L95
3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md	L120
3-solutioning/bmad-create-architecture/steps/step-01-init.md	L98

src/core-skills/ — 6 files, 9 occurrences

File	Lines
bmad-distillator/agents/distillate-compressor.md	L7, L34, L61, L83
bmad-brainstorming/steps/step-01-session-setup.md	L70
bmad-brainstorming/steps/step-02a-user-selected.md	L43
bmad-brainstorming/steps/step-02b-ai-recommended.md	L50
bmad-brainstorming/steps/step-02c-random-selection.md	L50
bmad-brainstorming/steps/step-02d-progressive-flow.md	L69

The Normalization Risk

This is not about a malicious actor crafting a bad path. It's about what happens to agent behavior when ../ is the standard navigation pattern across every workflow.

During a typical BMAD session, the agent follows ../ dozens of times: reading templates, loading CSV data, referencing agent prompts. Every successful traversal reinforces that .. is safe, normal, and expected. The agent becomes desensitized to directory traversal.

When that same agent then works on the user's actual production code — in the same session or a subsequent one — it encounters relative paths in source code imports, config references, and documentation. Having been conditioned by BMAD's skill files that ../ means "go read that file for context," the agent is more likely to follow those paths without hesitation, including paths that lead to sensitive files.

Example Scenario: Unintended API Key Exposure

1. Developer installs BMAD and runs architecture + implementation workflows throughout the week
2. The agent follows ../ paths across 42+ lines in skill files — this becomes a normalized behavior pattern
3. Developer asks the agent to help refactor a payment integration module
4. The agent reads src/services/payments/webhook-handler.js, which contains: const config = require('../../config/stripe-keys');
5. The agent follows the ../../ path to build context — exactly as it's been doing all week with BMAD skill files — and reads the secrets file
6. The agent then generates test fixtures or documentation that includes the actual credential values it just read
7. Developer commits without noticing the embedded secrets

The agent didn't do anything malicious. It followed a ../ path to be helpful, exactly as every BMAD skill file trained it to do.

SECURITY.md Contradiction

BMAD's SECURITY.md explicitly lists "Path traversal or file system access issues" as in-scope vulnerabilities they want reported. It also recommends under "Security Best Practices for Users":

Limit File Access: Configure your AI IDE to limit file system access where possible

Yet the framework's own skill files use ../ — the most common path traversal mechanism — as the standard file reference convention across 25 files and 42 occurrences, and the skill validator rules (PATH-01, PATH-02) mandate and encourage it. While BMAD's SECURITY.md does not explicitly call out .. by name, ../ directory traversal is the textbook definition of the "path traversal" category that SECURITY.md declares in-scope.

Suggested Remediation

Consider one or more of the following:

1. Flatten skill directory structure so that step files don't need to traverse up to the skill root. If steps and templates are siblings rather than in subdirectories, ./ replaces all ../ usage.
2. Use a skill-scoped variable (like the original installed_path but with proper resolution) that references the skill root without using .. — e.g., {skill_root}/template.md instead of ../template.md.
3. Add a validator rule that warns when ../ is used, or at minimum, ensures no ../ path resolves outside the skill's own directory boundary.
4. Document the risk so users running BMAD alongside production development are aware of the agent normalization concern.
5. Add a Claude Code PreToolUse hook as an immediate defensive measure that users can adopt today. The following hook blocks any file operation containing .. in the path, aligning with Anthropic's security best practices. Save as .claude/hooks/block-traversal.js:

// .claude/hooks/block-traversal.js

async function main() {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }
  const toolArgs = JSON.parse(Buffer.concat(chunks).toString());
  const filePath =
    toolArgs.tool_input?.file_path || toolArgs.tool_input?.path || "";

  if (filePath.includes("..")) {
    console.error(`Blocked: path traversal detected in "${filePath}"`);
    process.exit(2);
  }
}

main();

Then register it in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [{ "type": "command", "command": "node .claude/hooks/block-traversal.js" }]
      },
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node .claude/hooks/block-traversal.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node .claude/hooks/block-traversal.js" }]
      }
    ]
  }
}

Environment

• BMAD Version: 6.2.2 (current as of report date)
• Reference: Anthropic Claude Code Hooks Security Best Practices
• Reference: BMAD SECURITY.md
• Reference: BMAD Skill Validator`

[coderabbitai]

🔗 Related PRs

#1850 - docs: update terminology from commands to skills [merged]
#1892 - docs: drop slash-command prefix from skill references [merged]
#1925 - refactor(skills): convert advanced-elicitation.xml to native skill [merged]
#2004 - chore: normalize skill invocation syntax [merged]
#2008 - fix(skills): validation pass 2 — path, variable, and sequence fixes [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!