Skip to content
Community

Contributing

Thank you for your interest in improving this workshop! Here's how to get involved.

Workshop site · OWASP MCP Azure Security Guide · Open an issue

Repository Structure

sherpa/
├── camps/                       # Workshop modules
│   ├── base-camp/               # Local-only MCP fundamentals
│   ├── camp1-identity/          # OAuth, Managed Identity, Key Vault
│   ├── camp2-gateway/           # APIM, Content Safety, API Center
│   ├── camp3-io-security/       # Input validation, PII, prompt injection
│   └── camp4-monitoring/        # Logging, dashboards, alerts
├── docs/                        # MkDocs documentation site
│   └── camps/                   # Workshop guides (mirrors camps/ structure)
├── infra/                       # Shared infrastructure docs
└── mkdocs.yml                   # MkDocs configuration

Each Azure camp (1–4) follows this layout:

Path Purpose
azure.yaml azd project definition with lifecycle hooks
infra/ Bicep modules for Azure resources
scripts/ Waypoint scripts (.sh + .ps1)
scripts/hooks/ azd preprovision / postprovision hooks
servers/ MCP server source code (Python, FastMCP)
tests/ Test and example scripts

Workshop Pattern

Every camp follows the same exploit → fix → validate methodology:

  1. Start with a vulnerable or incomplete configuration
  2. Run an exploit to demonstrate the real-world risk
  3. Apply the security fix
  4. Validate the fix blocks the attack

Scripts: Bash & PowerShell Parity

All scripts must have both a .sh (Bash) and .ps1 (PowerShell) version. Camp 2 is the reference implementation with full parity.

Bash conventions:

  • Use set -euo pipefail at the top
  • Clear progress output with section headers
  • Script naming: {section}.{waypoint}-{action}.sh (e.g., 1.1-deploy.sh)

PowerShell conventions:

  • Use $ErrorActionPreference = 'Stop' at the top
  • Use curl.exe (not the PowerShell alias curl)
  • Use ConvertFrom-Json / ConvertTo-Json instead of jq

azure.yaml hooks support both platforms:

hooks:
  preprovision:
    posix:
      shell: sh
      run: ./scripts/hooks/preprovision.sh
    windows:
      shell: pwsh
      run: ./scripts/hooks/preprovision.ps1

Documentation

The docs site is built with MkDocs Material (mkdocs.yml at repo root).

Run locally:

pip install -r requirements-docs.txt
mkdocs serve

Key conventions:

  • OS-specific commands use content tabs: === "Bash" / === "PowerShell"
  • Cross-platform commands (e.g., azd provision) do not need tabs
  • Tabs inside admonitions (!!!, ???) need an extra 4-space indent

Code Guidelines

Language Standard
Python 3.11+, type hints, uv for package management
Bash set -euo pipefail, clear section headers
PowerShell $ErrorActionPreference = 'Stop', no aliases
Bicep Consistent naming with abbreviations.json, security comments

Submitting Changes

  1. Fork the repo and create a feature branch
  2. Test your changes — run through the workshop guide yourself, verify exploits demonstrate the vulnerability, and confirm fixes resolve the issue
  3. Check docs render correctly with mkdocs serve
  4. Submit a PR with a clear description of what changed and why

Before submitting

If you're adding or modifying scripts, make sure both .sh and .ps1 versions exist and are tested.