Skip to content

Commit e68a4d3

Browse files
dbarkoldbarkol
committed
Updated contributing guidelines
1 parent 0f64f43 commit e68a4d3

File tree

2 files changed

+92
-232
lines changed

2 files changed

+92
-232
lines changed

‎CONTRIBUTING.md‎

Lines changed: 46 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -1,180 +1,73 @@
1-
# Contributing to MCP Security Summit Workshop
1+
# Contributing
22

3-
Thank you for your interest in improving this workshop! This guide explains the repository structure and how to contribute effectively.
3+
Thank you for your interest in improving this workshop!
44

5-
## Repository Structure
6-
7-
```
8-
/
9-
├── camps/ # Workshop modules (Base Camp → Summit)
10-
│ ├── base-camp/ # Fundamentals + basic authentication
11-
│ ├── camp1-identity/ # OAuth, Managed Identity, Key Vault
12-
│ ├── camp2-gateway/ # API/MCP Gateway, Network Security
13-
│ ├── camp3-io-security/ # Content Safety, Input Validation
14-
│ └── camp4-monitoring/ # Logging, Monitoring, Alerts
15-
├── infra/ # Shared Bicep templates
16-
│ ├── shared/ # Common Azure resources
17-
│ └── README.md
18-
├── scripts/ # Deployment automation helpers
19-
│ └── README.md
20-
├── docs/ # GitHub Pages documentation
21-
│ └── index.md
22-
└── README.md # Workshop overview
23-
```
24-
25-
## How to Add a New Camp
5+
## Quick Links
266

27-
Each camp follows the **vulnerable → secure** pattern established in Base Camp. Use this template:
7+
- **📚 Workshop:** [azure-samples.github.io/sherpa](https://azure-samples.github.io/sherpa/)
8+
- **🔒 Security Guide:** [microsoft.github.io/mcp-azure-security-guide](https://microsoft.github.io/mcp-azure-security-guide/)
289

29-
### Camp Directory Structure
10+
## Repository Structure
3011

3112
```
32-
camps/your-camp/
33-
├── README.md # Participant guide (5-phase format)
34-
├── pyproject.toml # Dependencies (managed by uv)
35-
├── vulnerable-server/ # Insecure implementation
36-
│ ├── src/
37-
│ │ ├── server.py # MCP server with vulnerabilities
38-
│ │ └── ...
39-
│ ├── pyproject.toml # Package metadata
40-
│ ├── Dockerfile
41-
│ └── .env.example
42-
├── secure-server/ # Fixed implementation
43-
│ ├── src/
44-
│ │ ├── server.py # MCP server with security controls
45-
│ │ └── ...
46-
│ ├── pyproject.toml # Package metadata
47-
│ ├── Dockerfile
48-
│ └── .env.example
49-
├── exploits/ # Demonstration scripts
50-
│ └── test_exploit.py
51-
├── infra/ # Camp-specific Bicep
52-
│ └── main.bicep
53-
└── vscode-config/ # Example MCP client configs
54-
└── mcp-settings.json
13+
sherpa/
14+
├── camps/ # Workshop modules
15+
│ ├── base-camp/ # Local-only, MCP fundamentals
16+
│ ├── camp1-identity/ # Azure: OAuth, Managed Identity
17+
│ ├── camp2-gateway/ # Azure: APIM, Content Safety
18+
│ ├── camp3-io-security/ # Azure: Input validation, PII
19+
│ └── camp4-monitoring/ # Azure: Logging, alerts
20+
├── docs/ # MkDocs documentation
21+
│ └── camps/ # Workshop guides
22+
└── mkdocs.yml
5523
```
5624

57-
**Note:** Camps use `uv` for fast, reliable dependency management. Run `uv sync` in the camp root to set up the environment.
58-
59-
### Camp README.md Format
60-
61-
```markdown
62-
# Camp [N]: [Theme Name]
63-
64-
*"[Mountain metaphor subtitle]"*
65-
66-
**Duration:** [X] minutes
67-
**OWASP Risks:** [MCP0X, MCP0Y]
68-
**Azure Services:** [Service A, Service B]
69-
**Guide Reference:** [Link to microsoft.github.io/mcp-azure-security-guide]
25+
## Workshop Pattern
7026

71-
## Learning Objectives
72-
- Objective 1
73-
- Objective 2
27+
All camps follow **exploit → fix → validate**:
7428

75-
## Route Map
76-
| Phase | Activity | Duration | Type |
77-
|:-----:|----------|:--------:|:----:|
78-
| **1** | Deploy Vulnerable System | [X] min | Setup |
79-
| **2** | Exploit Vulnerabilities | [X] min | Hands-on |
80-
| **3** | Implement Security Fixes | [X] min | Hands-on |
81-
| **4** | Validate Fixes | [X] min | Verification |
82-
| **5** | Summary & Teaching Points | [X] min | Discussion |
29+
1. Start with a vulnerable or incomplete configuration
30+
2. Demonstrate the security risk
31+
3. Apply the fix
32+
4. Validate the fix works
8333

84-
[... detailed phase instructions ...]
85-
```
86-
87-
## Code Style Guidelines
34+
## Camp Types
8835

89-
### Python MCP Servers
36+
| Type | Example | Deployment | Key Files |
37+
|------|---------|------------|-----------|
38+
| **Local** | Base Camp | `uv run python -m src.server` | `vulnerable-server/`, `secure-server/` |
39+
| **Azure** | Camps 1-4 | `azd up` | `azure.yaml`, `infra/`, `scripts/` |
9040

91-
- Use the official `mcp` Python package (not FastMCP)
92-
- Python 3.10+ with type hints
93-
- Clear comments explaining vulnerabilities and fixes
94-
- Follow PEP 8 style guidelines
41+
## Running Docs Locally
9542

96-
**Example vulnerability comment:**
97-
```python
98-
# VULNERABILITY: No authentication check!
99-
# This allows ANY client to access ANY user's data.
100-
# Maps to OWASP MCP07: Insufficient Authentication
101-
@server.list_resources()
102-
async def list_resources() -> list[Resource]:
103-
# Should check authentication here but doesn't
104-
return [Resource(...)]
43+
```bash
44+
pip install -r requirements-docs.txt
45+
mkdocs serve
10546
```
10647

107-
**Example security fix comment:**
108-
```python
109-
# SECURITY FIX: Validate authentication on every request
110-
# This addresses OWASP MCP07 by ensuring only authorized
111-
# clients can access resources.
112-
def require_auth(func):
113-
async def wrapper(*args, **kwargs):
114-
token = get_token_from_context()
115-
if not validate_token(token):
116-
raise PermissionError("Unauthorized")
117-
return await func(*args, **kwargs)
118-
return wrapper
119-
```
120-
121-
### Bicep Templates
122-
123-
- Use consistent naming conventions: `{resource-type}-{camp-name}`
124-
- Include comments explaining security controls
125-
- Output important values (endpoints, resource IDs)
126-
- Follow Azure naming best practices
127-
128-
### Documentation
129-
130-
- Use clear, action-oriented headings
131-
- Include code snippets with explanations
132-
- Provide expected outputs for validation steps
133-
- Link to relevant OWASP MCP Top 10 sections
134-
- Use callout boxes for important notes
135-
136-
## Testing Your Contribution
137-
138-
Before submitting a pull request:
139-
140-
1. **Set up the environment:**
141-
```bash
142-
cd camps/your-camp
143-
uv sync # Install dependencies
144-
```
48+
## Code Guidelines
14549

146-
2. **Test the vulnerable version:**
147-
- Deploy and run the vulnerable server
148-
- Verify the exploit works as documented
149-
- Ensure the vulnerability is clear to participants
50+
- **Python:** 3.11+, type hints, `uv` for dependencies
51+
- **Bicep:** Consistent naming, security comments
52+
- **Scripts:** Bash, `set -e`, clear progress output
15053

151-
3. **Test the secure version:**
152-
- Deploy and run the secure server
153-
- Verify the exploit now fails appropriately
154-
- Ensure security controls work as documented
54+
## Testing Changes
15555

156-
4. **Validate documentation:**
157-
- Follow your own instructions step-by-step
158-
- Verify all commands work
159-
- Check all links are valid
56+
1. Run through the workshop guide yourself
57+
2. Verify exploit scripts demonstrate the vulnerability
58+
3. Verify fix scripts resolve the issue
59+
4. Check documentation renders correctly
16060

161-
## Submission Guidelines
61+
## Submitting Changes
16262

163-
1. Fork the repository
164-
2. Create a feature branch: `git checkout -b camp-feature-name`
165-
3. Make your changes following the guidelines above
166-
4. Test thoroughly (see Testing section)
167-
5. Commit with clear messages: `git commit -m "Add Camp X: [Feature]"`
168-
6. Push to your fork: `git push origin camp-feature-name`
169-
7. Open a Pull Request with:
170-
- Clear description of what was added/changed
171-
- Which OWASP MCP risks are addressed
172-
- Testing steps you performed
63+
1. Fork and create a branch
64+
2. Make changes and test thoroughly
65+
3. Submit a Pull Request with a clear description
17366

17467
## Questions?
17568

176-
Open an issue or discussion in the repository. We're here to help!
69+
Open an [issue](https://github.com/Azure-Samples/sherpa/issues).
17770

17871
---
17972

180-
*Thank you for helping others scale the summit safely! 🏔️*
73+
*Thank you for helping others reach the summit safely! 🏔️*

‎docs/resources/contributing.md‎

Lines changed: 46 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,73 @@
1-
# Contributing to MCP Security Summit Workshop
1+
# Contributing
22

3-
Thank you for your interest in improving this workshop! This guide explains the repository structure and how to contribute effectively.
3+
Thank you for your interest in improving this workshop!
4+
5+
## Quick Links
6+
7+
- **📚 Workshop:** [azure-samples.github.io/sherpa](https://azure-samples.github.io/sherpa/)
8+
- **🔒 Security Guide:** [microsoft.github.io/mcp-azure-security-guide](https://microsoft.github.io/mcp-azure-security-guide/)
49

510
## Repository Structure
611

712
```
8-
/
9-
├── camps/ # Workshop modules (Base Camp → Summit)
10-
│ ├── base-camp/ # Fundamentals + basic authentication
11-
│ ├── camp1-identity/ # OAuth, Managed Identity, Key Vault
12-
│ ├── camp2-gateway/ # API/MCP Gateway, Network Security
13-
│ ├── camp3-io-security/ # Content Safety, Input Validation
14-
│ └── camp4-monitoring/ # Logging, Monitoring, Alerts
15-
├── infra/ # Shared Bicep templates
16-
│ ├── shared/ # Common Azure resources
17-
│ └── README.md
18-
├── scripts/ # Deployment automation helpers
19-
│ └── README.md
20-
├── docs/ # GitHub Pages documentation
21-
│ └── index.md
22-
└── README.md # Workshop overview
13+
sherpa/
14+
├── camps/ # Workshop modules
15+
│ ├── base-camp/ # Local-only, MCP fundamentals
16+
│ ├── camp1-identity/ # Azure: OAuth, Managed Identity
17+
│ ├── camp2-gateway/ # Azure: APIM, Content Safety
18+
│ ├── camp3-io-security/ # Azure: Input validation, PII
19+
│ └── camp4-monitoring/ # Azure: Logging, alerts
20+
├── docs/ # MkDocs documentation
21+
│ └── camps/ # Workshop guides
22+
└── mkdocs.yml
2323
```
2424

25-
## How to Add a New Camp
25+
## Workshop Pattern
2626

27-
Each camp follows the **vulnerable → secure** pattern established in Base Camp. Use this template:
27+
All camps follow **exploit → fix → validate**:
2828

29-
### Camp Directory Structure
29+
1. Start with a vulnerable or incomplete configuration
30+
2. Demonstrate the security risk
31+
3. Apply the fix
32+
4. Validate the fix works
3033

31-
```
32-
camps/your-camp/
33-
├── README.md # Participant guide (5-phase format)
34-
├── pyproject.toml # Dependencies (managed by uv)
35-
├── vulnerable-server/ # Insecure implementation
36-
│ ├── src/
37-
│ │ ├── server.py # MCP server with vulnerabilities
38-
│ │ └── ...
39-
│ ├── pyproject.toml # Package metadata
40-
│ ├── Dockerfile
41-
│ └── .env.example
42-
├── secure-server/ # Fixed implementation
43-
│ ├── src/
44-
│ │ ├── server.py # MCP server with security controls
45-
│ │ └── ...
46-
│ ├── pyproject.toml # Package metadata
47-
│ ├── Dockerfile
48-
│ └── .env.example
49-
├── exploits/ # Demonstration scripts
50-
│ └── test_exploit.py
51-
├── infra/ # Camp-specific Bicep
52-
│ └── main.bicep
53-
└── vscode-config/ # Example MCP client configs
54-
└── mcp-settings.json
55-
```
34+
## Camp Types
5635

57-
**Note:** Camps use `uv` for fast, reliable dependency management. Run `uv sync` in the camp root to set up the environment.
36+
| Type | Example | Deployment | Key Files |
37+
|------|---------|------------|-----------|
38+
| **Local** | Base Camp | `uv run python -m src.server` | `vulnerable-server/`, `secure-server/` |
39+
| **Azure** | Camps 1-4 | `azd up` | `azure.yaml`, `infra/`, `scripts/` |
5840

59-
## Code Style Guidelines
41+
## Running Docs Locally
6042

61-
### Python MCP Servers
62-
63-
- Use the official `mcp` Python package (not FastMCP)
64-
- Python 3.10+ with type hints
65-
- Clear comments explaining vulnerabilities and fixes
66-
- Follow PEP 8 style guidelines
67-
68-
**Example vulnerability comment:**
69-
```python
70-
# VULNERABILITY: No authentication check!
71-
# This allows ANY client to access ANY user's data.
72-
# Maps to OWASP MCP07: Insufficient Authentication
43+
```bash
44+
pip install -r requirements-docs.txt
45+
mkdocs serve
7346
```
7447

75-
## Documentation
76-
77-
### GitHub Pages
48+
## Code Guidelines
7849

79-
Documentation lives in the `docs/` directory:
80-
- Keep docs separate from code README files
81-
- Use clear headings and navigation
82-
- Include code examples and screenshots
83-
- Link to relevant Azure documentation
50+
- **Python:** 3.11+, type hints, `uv` for dependencies
51+
- **Bicep:** Consistent naming, security comments
52+
- **Scripts:** Bash, `set -e`, clear progress output
8453

85-
### README Files
54+
## Testing Changes
8655

87-
README files in each camp serve as:
88-
- Quick reference for workshop participants
89-
- Navigation within GitHub repository
90-
- Detailed step-by-step instructions
56+
1. Run through the workshop guide yourself
57+
2. Verify exploit scripts demonstrate the vulnerability
58+
3. Verify fix scripts resolve the issue
59+
4. Check documentation renders correctly
9160

9261
## Submitting Changes
9362

94-
1. **Fork the repository**
95-
2. **Create a feature branch**: `git checkout -b feature/your-feature`
96-
3. **Make your changes** with clear commit messages
97-
4. **Test thoroughly** - ensure all exploits and fixes work
98-
5. **Submit a pull request** with description of changes
63+
1. Fork and create a branch
64+
2. Make changes and test thoroughly
65+
3. Submit a Pull Request with a clear description
9966

10067
## Questions?
10168

102-
Open an issue on GitHub if you have questions or suggestions!
69+
Open an [issue](https://github.com/Azure-Samples/sherpa/issues).
10370

10471
---
10572

106-
**Thank you for helping make this workshop better! 🏔️**
73+
*Thank you for helping others reach the summit safely! 🏔️*

0 commit comments

Comments
 (0)