docs: refresh security guidance (#64)

This commit is contained in:
Sammy Farida
2025-11-15 10:08:14 -05:00
committed by GitHub
parent 51c1fd7397
commit ab83aeabee
35 changed files with 1202 additions and 684 deletions
+103 -67
View File
@@ -1,69 +1,105 @@
---
name: Bug Report
about: Create a report to help us improve
title: '[BUG] '
labels: ['bug', 'needs-triage']
assignees: ''
---
description: Create a report to help us improve
title: "[BUG] "
labels:
- bug
- needs-triage
body:
- type: markdown
attributes:
value: |
## Thanks for filing a bug
Please include the exact MCP tool invocations (`ssh_plan`, `ssh_run`, etc.) so we can reproduce the issue.
- type: textarea
id: bug-description
attributes:
label: What happened?
description: Provide a concise summary of the problem.
placeholder: The orchestrator returned X when I expected Y...
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Steps to reproduce
description: List each MCP tool call and include command arguments + outputs.
placeholder: |
1. `ssh_plan alias="web-1" command="uptime"`
2. `ssh_run alias="web-1" command="uptime"`
3. Error output / denial message
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: Describe what you thought would happen.
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
description: Describe what actually happened (include error text if possible).
validations:
required: true
- type: checkboxes
id: prechecks
attributes:
label: Pre-checks
description: Run through these before filing so we can debug faster.
options:
- label: I confirmed `ssh_plan` reports the command should be allowed.
- label: I reran `ssh_reload_config` after editing any YAML.
- label: I verified the host alias/tag exists in `servers.yml`.
- label: I confirmed my `known_hosts` entry matches the target host.
- type: textarea
id: environment
attributes:
label: Environment
description: Include OS, Docker version, MCP client, and orchestrator version.
placeholder: |
OS: macOS 15.0
Docker: Docker Desktop 4.29.0
MCP SSH Orchestrator: 1.0.0
MCP client: Cursor
Python version (if local): 3.11.8
validations:
required: true
- type: textarea
id: configuration
attributes:
label: Sanitized configuration
description: Redact anything sensitive. Include only the sections that matter.
placeholder: |
```yaml
# servers.yml
hosts:
- alias: "example"
host: "10.0.0.1"
port: 22
credentials: "example_creds"
tags: ["test"]
## Bug Description
A clear and concise description of what the bug is.
## To Reproduce
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## Expected Behavior
A clear and concise description of what you expected to happen.
## Actual Behavior
A clear and concise description of what actually happened.
## Environment
Please complete the following information:
- **OS**: [e.g. macOS, Linux, Windows]
- **Docker Version**: [e.g. Docker Desktop 4.25.0]
- **Python Version**: [e.g. 3.11.5] (if running locally)
- **MCP SSH Orchestrator Version**: [e.g. 0.1.0]
- **MCP Client**: [e.g. Claude Desktop, Cline, etc.]
## Configuration
Please provide sanitized configuration snippets (remove sensitive information):
```yaml
# servers.yml (sanitized)
hosts:
- alias: "example"
host: "10.0.0.1"
port: 22
credentials: "example_creds"
tags: ["test"]
# policy.yml (sanitized)
limits:
max_seconds: 60
max_output_bytes: 1048576
```
## Logs
Please provide relevant error messages, stack traces, or logs:
```
Paste logs here
```
## Additional Context
Add any other context about the problem here.
## Security Note
⚠️ **Important**: Do not include any sensitive information such as:
- Real IP addresses or hostnames
- SSH private keys or passwords
- Actual credentials or secrets
- Internal network details
Please sanitize all configuration examples before posting.
# policy.yml
limits:
max_seconds: 60
max_output_bytes: 1048576
```
render: markdown
- type: textarea
id: logs
attributes:
label: Logs / stderr excerpts
description: Paste relevant error messages or audit log snippets (sanitized).
render: shell
- type: textarea
id: additional
attributes:
label: Additional context
description: Anything else we should know?
- type: markdown
attributes:
value: |
**Security Note**
Do **not** include sensitive information (IPs, credentials, secrets). Sanitize all snippets before posting.
+73 -61
View File
@@ -1,62 +1,74 @@
---
name: Documentation Issue
about: Report a documentation problem or suggest improvements
title: '[DOCS] '
labels: ['documentation', 'needs-triage']
assignees: ''
---
## Documentation Issue
## Type of Issue
- [ ] **Incorrect information**: The documentation contains wrong information
- [ ] **Missing information**: Important information is not documented
- [ ] **Unclear explanation**: The documentation is confusing or hard to understand
- [ ] **Outdated content**: The documentation is outdated and doesn't match current behavior
- [ ] **Formatting issue**: The documentation has formatting problems
- [ ] **Broken links**: Links in the documentation are broken
- [ ] **Missing examples**: More examples would be helpful
- [ ] **Other**: _______________
## Affected Documentation
Please specify which documentation is affected:
- [ ] README.md
- [ ] CONTRIBUTING.md
- [ ] docs/CONTRIBUTING.md
- [ ] docs/DOCKER_DESKTOP.md
- [ ] docs/LOCAL_DEVELOPMENT.md
- [ ] docs/SECURITY.md
- [ ] Example configuration files
- [ ] Code comments/docstrings
- [ ] Other: _______________
## Current Documentation
If reporting incorrect or unclear information, please quote the relevant section:
```markdown
[Paste the problematic documentation here]
```
## Problem Description
Describe what's wrong with the documentation or what's missing.
## Suggested Improvement
Describe how the documentation should be improved:
```markdown
[Paste your suggested improvement here]
```
## Additional Context
- **User level**: [Beginner/Intermediate/Advanced] - What level of user would be affected?
- **Use case**: Describe the specific use case or scenario where this documentation issue causes problems
- **Priority**: [Low/Medium/High] - How important is this documentation fix?
## Related Issues
Link any related issues:
- Related to #123
- Duplicate of #456
---
**Note**: For code-related issues, please use the bug report template instead.
description: Report a documentation problem or suggest improvements
title: "[DOCS] "
labels:
- documentation
- needs-triage
body:
- type: dropdown
id: issue-type
attributes:
label: Type of issue
multiple: true
options:
- Incorrect information
- Missing information
- Unclear explanation
- Outdated content
- Formatting issue
- Broken links
- Missing examples
- Other
- type: checkboxes
id: affected-docs
attributes:
label: Affected documentation
options:
- label: README.md
- label: SECURITY.md
- label: docs/wiki (specify file below)
- label: compose/README.md or setup.sh
- label: examples/*.yml
- label: `.github` templates
- label: Code comments/docstrings
- label: Other (describe below)
- type: textarea
id: location
attributes:
label: File / section
description: Provide the exact path or wiki link (e.g., `docs/wiki/14-FAQ.md#support`).
validations:
required: true
- type: textarea
id: current-text
attributes:
label: Current documentation
description: Quote the problematic text (sanitized).
render: markdown
- type: textarea
id: problem
attributes:
label: Problem description
description: Explain why the documentation is wrong or insufficient. Call out whether it references unsupported/future functionality or contradicts the code.
validations:
required: true
- type: textarea
id: suggestion
attributes:
label: Suggested improvement
description: Provide the wording or structure you recommend.
render: markdown
- type: textarea
id: context
attributes:
label: Additional context
description: Mention the affected user level, use case, and priority (Low/Medium/High).
- type: textarea
id: related
attributes:
label: Related issues or discussions
description: Link any relevant issues, PRs, or external references.
- type: markdown
attributes:
value: |
**Note:** For code-related bugs, please use the bug report template instead.
+68 -58
View File
@@ -1,59 +1,69 @@
---
name: Feature Request
about: Suggest an idea for this project
title: '[FEATURE] '
labels: ['enhancement', 'needs-triage']
assignees: ''
---
## Feature Summary
A clear and concise description of the feature you'd like to see implemented.
## Problem Statement
What problem does this feature solve? What use case does it address?
## Proposed Solution
Describe the solution you'd like to see implemented. Be as specific as possible.
## Alternative Solutions
Describe any alternative solutions or workarounds you've considered.
## Use Cases
Provide specific examples of how this feature would be used:
### Example 1: [Use case name]
```json
{
"name": "ssh_example_tool",
"arguments": {
"param1": "value1",
"param2": "value2"
}
}
```
### Example 2: [Use case name]
```bash
# Command line example
docker run -i --rm mcp-ssh-orchestrator:latest
```
## Impact Assessment
- **Who would benefit from this feature?** (e.g., DevOps teams, system administrators, developers)
- **How many users might use this?** (e.g., small subset, most users, all users)
- **Priority level**: [Low/Medium/High]
## Implementation Considerations
- **Complexity**: [Low/Medium/High]
- **Breaking changes**: Does this require changes to existing APIs or configurations?
- **Dependencies**: Are there any new dependencies required?
- **Security implications**: Any security considerations?
## Additional Context
Add any other context, mockups, or examples about the feature request here.
## Related Issues
Link any related issues or discussions:
- Related to #123
- Blocked by #456
- Duplicate of #789
description: Suggest an idea for this project
title: "[FEATURE] "
labels:
- enhancement
- needs-triage
body:
- type: markdown
attributes:
value: |
## Help us scope your idea
Please describe the problem first, then the change you'd like to see. Tie everything back to existing MCP tools or YAML.
- type: textarea
id: summary
attributes:
label: Feature summary
description: One paragraph describing the capability you need.
validations:
required: true
- type: textarea
id: problem
attributes:
label: Problem statement
description: What workflow is blocked today? Who is impacted?
placeholder: We're unable to ...
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed solution
description: Reference the MCP tool, prompt, or YAML file you expect will change.
placeholder: Update `ssh_plan` to return ...
- type: textarea
id: security
attributes:
label: Security alignment
description: Explain how this keeps the deny-by-default posture intact. List any new allow rules, network changes, or audit events required.
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Existing workarounds, even if imperfect.
- type: textarea
id: use-cases
attributes:
label: Representative use cases
description: Provide concrete command/tool examples that would benefit.
placeholder: |
1. Operator asks Cursor to ...
2. MCP client calls `ssh_run_on_tag ...`
- type: dropdown
id: priority
attributes:
label: Priority
options:
- Low
- Medium
- High
- type: textarea
id: implementation
attributes:
label: Implementation considerations
description: Complexity, dependencies, or breaking changes we should know about (transport must remain stdio-only).
- type: textarea
id: additional
attributes:
label: Additional context / references
description: Link related issues, designs, or screenshots.
+92 -73
View File
@@ -1,74 +1,93 @@
---
name: Question or Support Request
about: Ask a question or request support
title: '[QUESTION] '
labels: ['question', 'needs-triage']
assignees: ''
---
## Question or Support Request
## Type of Request
- [ ] **How-to question**: I need help with setup or configuration
- [ ] **Troubleshooting**: Something isn't working as expected
- [ ] **Best practices**: What's the recommended approach?
- [ ] **Integration help**: How to integrate with other tools?
- [ ] **Performance question**: How to optimize or improve performance?
- [ ] **Other**: _______________
## Question Summary
A clear and concise description of your question or the help you need.
## Current Setup
Please describe your current setup:
- **OS**: [e.g. macOS, Linux, Windows]
- **Docker Version**: [e.g. Docker Desktop 4.25.0]
- **Python Version**: [e.g. 3.11.5] (if running locally)
- **MCP SSH Orchestrator Version**: [e.g. 0.1.0]
- **MCP Client**: [e.g. Claude Desktop, Cline, etc.]
## What You've Tried
Describe what you've already tried to solve your problem:
1. Step 1
2. Step 2
3. Step 3
## Expected Outcome
What are you trying to achieve? What should happen?
## Current Behavior
What's currently happening? Include any error messages or unexpected behavior.
## Configuration
If relevant, please provide sanitized configuration snippets:
```yaml
# servers.yml (sanitized)
hosts:
- alias: "example"
host: "10.0.0.1"
port: 22
credentials: "example_creds"
tags: ["test"]
```
## Logs
If applicable, please provide relevant logs (sanitized):
```
[Paste logs here]
```
## Additional Context
Add any other context, screenshots, or examples that might help answer your question.
## Security Note
⚠️ **Important**: Do not include any sensitive information such as:
- Real IP addresses or hostnames
- SSH private keys or passwords
- Actual credentials or secrets
- Internal network details
Please sanitize all configuration examples before posting.
description: Ask a question or request support
title: "[QUESTION] "
labels:
- question
- needs-triage
body:
- type: dropdown
id: request-type
attributes:
label: Type of request
multiple: true
options:
- How-to question (setup / configuration)
- Troubleshooting
- Best practices
- Integration help
- Performance question
- Other
- type: textarea
id: summary
attributes:
label: Question summary
description: A concise description of what you need help with.
validations:
required: true
- type: textarea
id: setup
attributes:
label: Current setup
description: Include OS, Docker version, MCP client, orchestrator version, and whether you're running via Docker or local venv (stdio-only is required).
placeholder: |
OS: macOS 15.0
Docker: Docker Desktop 4.29.0
MCP client: Cursor
Orchestrator: 1.0.0 (Docker)
Transport: stdio
validations:
required: true
- type: textarea
id: tried
attributes:
label: What you've tried
description: Mention `ssh_plan`, `ssh_reload_config`, or other troubleshooting steps you've already taken.
placeholder: |
1. Ran `ssh_plan alias="web-1" command="uptime"`
2. Ran `ssh_reload_config`
3. ...
- type: textarea
id: expected
attributes:
label: Expected outcome
description: What are you trying to achieve?
- type: textarea
id: actual
attributes:
label: Current behavior
description: What actually happens? Include any error messages or unexpected results.
- type: textarea
id: config
attributes:
label: Sanitized configuration (optional)
description: Include only the relevant snippets (redact secrets).
placeholder: |
```yaml
hosts:
- alias: "example"
host: "10.0.0.1"
credentials: "example"
tags: ["lab"]
```
render: markdown
- type: textarea
id: logs
attributes:
label: Logs or command output (optional)
description: Paste sanitized stderr/audit lines or MCP responses.
render: shell
- type: textarea
id: docs-link
attributes:
label: Documentation reference (optional)
description: If this question relates to a doc section, paste the URL or file path.
- type: textarea
id: extras
attributes:
label: Additional context
description: Screenshots, links, or anything else that helps.
- type: markdown
attributes:
value: |
**Security Note**
Do **not** include sensitive information (IPs, credentials, secrets). Sanitize all snippets before posting.
@@ -1,61 +1,91 @@
---
name: Security Vulnerability
about: Report a security vulnerability
title: '[SECURITY] '
labels: ['security', 'needs-triage']
assignees: ''
---
## Security Vulnerability Report
⚠️ **IMPORTANT**: This template is for reporting security vulnerabilities. For general security questions or best practices, please use the regular bug report template.
## Vulnerability Description
A clear and concise description of the security vulnerability.
## Severity Assessment
Please indicate the severity level:
- [ ] **Critical**: Remote code execution, privilege escalation, data breach
- [ ] **High**: Authentication bypass, unauthorized access, data exposure
- [ ] **Medium**: Information disclosure, denial of service
- [ ] **Low**: Minor security improvements, hardening opportunities
## Affected Components
- [ ] SSH client implementation
- [ ] Policy engine
- [ ] Configuration handling
- [ ] Docker container
- [ ] MCP protocol handling
- [ ] Other: _______________
## Steps to Reproduce
1. Describe the vulnerable configuration or setup
2. Provide steps to trigger the vulnerability
3. Explain what sensitive information or access is exposed
## Impact
Describe the potential impact of this vulnerability:
- What data could be compromised?
- What systems could be affected?
- What are the potential attack vectors?
## Suggested Fix
If you have suggestions for how to fix this vulnerability, please describe them here.
## Responsible Disclosure
- [ ] I understand this is a security vulnerability and will not publicly disclose details until a fix is available
- [ ] I agree to work with the maintainers to coordinate disclosure
- [ ] I have not shared this information publicly
## Contact Information
Please provide a secure way to contact you for follow-up:
- Email: [your-email@example.com]
- PGP Key: [if you have one]
- Other: [secure communication method]
## Additional Context
Add any other context about the vulnerability here.
---
**Note**: For non-security bugs, please use the regular bug report template instead.
description: Report a security vulnerability (please use the bug template for non-security issues)
title: "[SECURITY] "
labels:
- security
- needs-triage
body:
- type: markdown
attributes:
value: |
**Important**
Please do **not** disclose sensitive details publicly until we coordinate a fix. For urgent issues, also email `samer.farida@yahoo.com` as documented in `SECURITY.md`.
- type: dropdown
id: severity
attributes:
label: Severity assessment
options:
- Critical (RCE, privilege escalation, data breach)
- High (auth bypass, unauthorized access, data exposure)
- Medium (information disclosure, DoS)
- Low (hardening opportunity)
- type: textarea
id: description
attributes:
label: Vulnerability description
description: Provide a concise description of the issue.
validations:
required: true
- type: textarea
id: affected-version
attributes:
label: Affected version / environment
description: Include commit SHA or tag, Docker vs local venv, MCP client, etc.
placeholder: |
Version: v1.0.0
Environment: Docker
MCP client: Cursor
validations:
required: true
- type: checkboxes
id: components
attributes:
label: Affected components
options:
- label: SSH client implementation
- label: Policy engine
- label: Configuration handling
- label: Docker container
- label: MCP protocol handling
- label: Other (describe below)
- type: textarea
id: reproduction
attributes:
label: Steps to reproduce
description: Include vulnerable configuration, commands, and observed behavior.
placeholder: |
1. Configure ...
2. Call `ssh_run ...`
3. Observe ...
validations:
required: true
- type: textarea
id: impact
attributes:
label: Impact
description: What data/systems could be affected? What attack vectors exist?
- type: textarea
id: suggested-fix
attributes:
label: Suggested fix (optional)
description: Share mitigation ideas if you have them.
- type: checkboxes
id: disclosure
attributes:
label: Responsible disclosure
options:
- label: I will not publicly disclose details until a fix is available.
required: true
- label: I agree to coordinate disclosure with the maintainers.
- label: I have not shared this information publicly.
- label: I reviewed `SECURITY.md` and emailed `samer.farida@yahoo.com` if urgent.
- type: textarea
id: contact
attributes:
label: Contact information
description: Provide a secure way to reach you (email, PGP link, etc.).
- type: textarea
id: additional
attributes:
label: Additional context
description: Anything else we should know? (Keep it factual—describe current behavior only.)
+30 -8
View File
@@ -1,10 +1,13 @@
## Summary
Brief description of what this PR does.
## Motivation
Why is this change needed? What problem does it solve?
## Changes
- [ ] Added new feature: [description]
- [ ] Fixed bug: [description]
- [ ] Updated documentation: [description]
@@ -13,23 +16,27 @@ Why is this change needed? What problem does it solve?
- [ ] Other: [description]
## Type of Change
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] 📚 Documentation update
- [ ] 🔧 Refactoring (no functional changes)
- [ ] ⚡ Performance improvement
- [ ] 🧪 Test improvements
- [ ] 🔒 Security improvement
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement
- [ ] Test improvements
- [ ] Security improvement
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Docker build succeeds
- [ ] Manual testing completed
- [ ] Tested with MCP client (Claude Desktop/Cline/etc.)
- [ ] `ssh_plan`/`ssh_run` (or async variants) exercised for new flows
### Test Details
Describe how you tested this change:
```bash
@@ -39,6 +46,7 @@ docker build -t mcp-ssh-orchestrator:test .
```
## MCP Compliance
- [ ] Follows MCP tool requirements (primitive types only, single-line docstrings)
- [ ] No `@mcp.prompt()` decorators used
- [ ] No `prompt` parameter to `FastMCP()`
@@ -47,39 +55,49 @@ docker build -t mcp-ssh-orchestrator:test .
- [ ] Logs to stderr appropriately
## Security Considerations
- [ ] No sensitive information exposed
- [ ] Proper input validation
- [ ] No security vulnerabilities introduced
- [ ] Follows security best practices
- [ ] Documentation and prompts avoid promising unsupported/future behavior
## Documentation
- [ ] README.md updated (if user-facing changes)
- [ ] Code comments/docstrings added
- [ ] Example configurations updated (if applicable)
- [ ] CHANGELOG.md updated (if significant change)
- [ ] docs/wiki updated when behavior changes or wording needed correction
## Configuration Changes
If this PR changes configuration options or behavior:
### Before
```yaml
# Old configuration example
old_config: "value"
```
### After
```yaml
# New configuration example
new_config: "value"
```
## Breaking Changes
If this PR introduces breaking changes, please describe:
- What breaks
- Migration path for users
- Timeline for deprecation
## Performance Impact
- [ ] No performance impact
- [ ] Performance improvement
- [ ] Performance regression (explain below)
@@ -87,6 +105,7 @@ If this PR introduces breaking changes, please describe:
If there's a performance impact, please describe:
## Screenshots/Output
If applicable, add screenshots or example output:
```json
@@ -96,6 +115,7 @@ If applicable, add screenshots or example output:
```
## Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
@@ -106,11 +126,13 @@ If applicable, add screenshots or example output:
- [ ] Any dependent changes have been merged and published
## Related Issues
- Fixes #123
- Related to #456
- Closes #789
## Additional Notes
Add any additional notes, concerns, or context for reviewers.
---
+3 -3
View File
@@ -157,8 +157,8 @@ jobs:
run: |
echo "Testing Docker image..."
docker images | grep mcp-ssh-orchestrator
docker run --rm mcp-ssh-orchestrator:test python -c "import mcp_ssh; print('✅ MCP SSH module imported successfully')"
echo "✅ Docker image test passed!"
docker run --rm mcp-ssh-orchestrator:test python -c "import mcp_ssh; print('MCP SSH module imported successfully')"
echo "Docker image test passed!"
skip-docs-only:
name: Skip (docs only)
@@ -169,5 +169,5 @@ jobs:
contents: read
steps:
- name: Skip workflow
run: echo "✅ Documentation-only PR - build and test checks skipped"
run: echo "Documentation-only PR - build and test checks skipped"
+1 -1
View File
@@ -120,5 +120,5 @@ jobs:
contents: read
steps:
- name: Skip workflow
run: echo "✅ Documentation-only PR - lint checks skipped"
run: echo "Documentation-only PR - lint checks skipped"
+8 -8
View File
@@ -33,25 +33,25 @@ jobs:
- name: Sync Wiki Content
run: |
echo "🔄 Starting wiki sync process..."
echo "Starting wiki sync process..."
# Create wiki directory
mkdir -p wiki-sync
cd wiki-sync
# Clone the existing wiki repository with authentication
echo "📥 Cloning wiki repository..."
echo "Cloning wiki repository..."
git clone https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.wiki.git .
# Copy new content from main repository
echo "📋 Copying wiki content..."
echo "Copying wiki content..."
rsync -av --delete --exclude='.git' ../docs/wiki/ ./
# Check for changes
git add .
if ! git diff --staged --quiet; then
echo "📝 Changes detected, committing..."
echo "Changes detected, committing..."
# Get list of changed files
CHANGED_FILES=$(git diff --staged --name-only | head -10)
@@ -66,12 +66,12 @@ jobs:
[skip ci]"
# Push to wiki repository with authentication
echo "🚀 Pushing to wiki repository..."
echo "Pushing to wiki repository..."
git push https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.wiki.git master
echo "✅ Wiki synced successfully"
echo "Wiki synced successfully"
else
echo "ℹ️ No changes to sync"
echo "No changes to sync"
fi
echo "🎉 Wiki sync process completed"
echo "Wiki sync process completed"
+1 -1
View File
@@ -1,5 +1,5 @@
Contact: mailto:samer.farida@yahoo.com
Encryption: TBD
Encryption: openpgp4fpr:6775BF3F439A2A8A198DE10D4FC5342A979BD358
Expires: 2026-10-27T23:59:59.000Z
Preferred-Languages: en
Canonical: https://github.com/samerfarida/mcp-ssh-orchestrator/.well-known/security.txt
+33 -4
View File
@@ -127,7 +127,7 @@ If you prefer to lay things out manually, follow the steps below.
```bash
# Pull the latest release
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Create directories for config, keys, and secrets
mkdir -p ~/mcp-ssh/{config,keys,secrets}
@@ -155,7 +155,7 @@ docker run -d --name mcp-ssh-orchestrator \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
Restart later with `docker start mcp-ssh-orchestrator`. Prefer disposable containers? Use `docker run -i --rm ...` instead.
@@ -187,7 +187,7 @@ Restart later with `docker start mcp-ssh-orchestrator`. Prefer disposable contai
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -207,7 +207,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_list_hosts","
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
Cursor/Claude should now show the orchestrator as connected. Jump to the [Usage Cookbook](https://github.com/samerfarida/mcp-ssh-orchestrator/wiki/08-Usage-Cookbook) for guided scenarios.
@@ -322,6 +322,28 @@ MCP SSH Orchestrator directly addresses documented vulnerabilities in the MCP ec
| **[Observability & Audit](https://github.com/samerfarida/mcp-ssh-orchestrator/wiki/11-Observability-Audit)** | Logging, monitoring, compliance |
| **[Deployment](https://github.com/samerfarida/mcp-ssh-orchestrator/wiki/09-Deployment)** | Production setup guide |
## Supply Chain Integrity
- **Signed release artifacts**: Every tarball/zip in GitHub Releases ships with a detached GPG signature produced by the maintainer key (`openpgp4fpr:6775BF3F439A2A8A198DE10D4FC5342A979BD358`). Import the key and verify before unpacking:
```bash
gpg --receive-keys 4FC5342A979BD358
gpg --verify mcp-ssh-orchestrator-v1.0.0.tar.gz.asc mcp-ssh-orchestrator-v1.0.0.tar.gz
```
- **Cosign-signed container images**: The images under `ghcr.io/samerfarida/mcp-ssh-orchestrator` are signed via Sigstore keyless signing in the release workflow. Verify the signature (and optional attestations) before deploying:
```bash
COSIGN_EXPERIMENTAL=1 cosign verify \
--certificate-identity-regexp "https://github.com/samerfarida/mcp-ssh-orchestrator/.github/workflows/release.yml@.*" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
Image digests and signatures are published with every tag in GitHub Packages so you can pin exact references when promoting builds between environments ([package feed](https://github.com/samerfarida/mcp-ssh-orchestrator/pkgs/container/mcp-ssh-orchestrator/versions)).
- **OpenSSF Scorecard**: The repository maintains an automated Scorecard run to track security posture across dependencies, build settings, branch protections, and more ([scorecard summary](https://api.scorecard.dev/projects/github.com/samerfarida/mcp-ssh-orchestrator)).
## What Can AI Do With This? (MCP Tools)
Your AI assistant gets 13 powerful tools with built-in security:
@@ -395,6 +417,13 @@ Repeat the same workflow inside Docker Desktop or a remote host by setting `IMAG
> *"The structured audit logs make incident response so much easier."* - Security Engineer
## Scope & Non-Goals
- **Transport**: Ships strictly as an MCP stdio server. There is no HTTP API, webhook emitter, or background push agent.
- **Support**: Community-driven open source only; no bundled professional services, training programs, or paid SLAs.
- **UI surfaces**: No first-party dashboard. Operate it through MCP-aware clients (Cursor, Claude Desktop, etc.).
- **Roadmap language**: Docs describe what exists in `src/mcp_ssh` today—deny-by-default policy, network allowlists, async tooling, and strict host key validation. Anything else is out of scope until implemented.
## Contributing
We welcome contributions! See our [Contributing Guide](https://github.com/samerfarida/mcp-ssh-orchestrator/wiki/13-Contributing) for:
+4 -4
View File
@@ -6,9 +6,9 @@ Security fixes are applied to actively maintained releases of mcp-ssh-orchestrat
| Version | Status |
|---------|--------|
| `main` branch | ✅ actively supported |
| Latest tagged release | ✅ supported |
| Older releases | ⚠️ best effort (consider upgrading) |
| `main` branch | Actively supported |
| `v1.0.x` | Supported (critical + high fixes) |
| Older releases | Best effort (consider upgrading) |
If you are running an older release and cannot upgrade, please highlight that in your report so we can discuss options.
@@ -25,7 +25,7 @@ Please follow the steps below to report a potential vulnerability:
- Affected versions (commit SHA or release tag)
- Impact assessment and suggested mitigations, if known
- Preferred contact information and availability
4. (Optional) If you require encryption, let us know and we will provide a PGP key for follow-up.
4. If you require encryption, use our OpenPGP key (`openpgp4fpr:6775BF3F439A2A8A198DE10D4FC5342A979BD358`) or mention it and we can send the key via email.
## What Happens Next
+101 -62
View File
@@ -1,8 +1,8 @@
# MCP-SSH-ORCHESTRATOR — Compose Environment
This directory provides Docker Compose configurations for the
[`mcp-ssh-orchestrator`](https://github.com/samerfarida/mcp-ssh-orchestrator)
MCP (Model Context Protocol) server.
This directory provides Docker Compose configurations for the
[`mcp-ssh-orchestrator`](https://github.com/samerfarida/mcp-ssh-orchestrator)
MCP (Model Context Protocol) server.
## Choose Your Setup
@@ -20,41 +20,52 @@ We provide two Docker Compose files depending on your use case:
If you just want to use the tool and don't plan to modify the code:
1. **Create configuration directories:**
```bash
mkdir -p ~/mcp-ssh/{config,keys,secrets}
```
2. **Copy example configurations:**
```bash
```bash
mkdir -p ~/mcp-ssh/{config,keys,secrets}
```
1. **Copy example configurations:**
```bash
# If you've cloned the repo
cd mcp-ssh-orchestrator
cp examples/example-servers.yml ~/mcp-ssh/config/servers.yml
cp examples/example-credentials.yml ~/mcp-ssh/config/credentials.yml
cp examples/example-policy.yml ~/mcp-ssh/config/policy.yml
# Edit these files with your actual hosts and credentials
```
3. **Add your SSH keys:**
```bash
# Edit these files with your actual hosts and credentials
```
1. **Add your SSH keys:**
```bash
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
chmod 0400 ~/mcp-ssh/keys/id_ed25519
cp ~/.ssh/known_hosts ~/mcp-ssh/keys/known_hosts # optional but recommended
```
4. **Bootstrap with the setup script (recommended):**
```bash
```
1. **Bootstrap with the setup script (recommended):**
```bash
cd mcp-ssh-orchestrator/compose
./setup.sh enduser # or simply ./setup.sh (auto-detects)
```
```
This creates `config/`, `keys/`, `secrets/`, and `.env`, copying the latest example configs.
5. **Run with compose (default production setup):**
```bash
docker compose up
```
1. **Run with compose (default production setup):**
The production compose file pulls `ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8` by default.
```bash
docker compose up
```
The production compose file pulls `ghcr.io/samerfarida/mcp-ssh-orchestrator:latest` by default.
---
@@ -63,19 +74,26 @@ The production compose file pulls `ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.
If you're developing or contributing to the project:
1. **Use the setup script (auto-detects dev mode in repo):**
```bash
```bash
cd compose
./setup.sh dev
```
Or just:
```bash
./setup.sh
```
2. **Run with development compose (builds from source):**
```bash
```
Or just:
```bash
./setup.sh
```
1. **Run with development compose (builds from source):**
```bash
docker compose -f docker-compose.dev.yml up --build
```
```
This will build the container from the local Dockerfile in the repository root.
@@ -87,8 +105,7 @@ This will build the container from the local Dockerfile in the repository root.
|------|----------|
| `docker-compose.yml` | **Prod**: Pulls published image from ghcr.io (default) |
| `docker-compose.dev.yml` | **Dev**: Builds container from local source |
| `.env.example` | Template for environment variables (copy to `.env`) |
| `setup.sh` | Automated setup script for directories and configs |
| `setup.sh` | Automated setup script for directories, configs, and `.env` stub |
| `README.md` | You're reading it! Usage guide and examples |
---
@@ -96,30 +113,39 @@ This will build the container from the local Dockerfile in the repository root.
## Prerequisites
Before running the container:
1. Ensure **Docker** and **Docker Compose v2+** are installed.
2. **For production use**: Clone the repo or copy example configs to your chosen location.
3. **For development**: Use the automated setup script:
```bash
1. **For production use**: Clone the repo or copy example configs to your chosen location.
1. **For development**: Use the automated setup script:
```bash
cd compose
./setup.sh dev
```
```
This will:
- Create required directories (`../config`, `../keys`, `../secrets`)
- Copy example configuration files from `../examples/`
- Create `.env` from `.env.example`
- Create required directories (`../config`, `../keys`, `../secrets`)
- Copy example configuration files from `../examples/`
- Generate a `.env` stub you can customize
**Note**: The script auto-detects if you're in the repo, so just `./setup.sh` works too.
**For end users**: You can also fetch the script directly:
```bash
```bash
mkdir -p ~/mcp-ssh && cd ~/mcp-ssh
curl -fsSLO https://raw.githubusercontent.com/samerfarida/mcp-ssh-orchestrator/main/compose/setup.sh
chmod +x setup.sh
./setup.sh enduser
```
4. Add your SSH private keys and password files under:
- `../keys` — SSH key files (e.g., id_ed25519)
- `../secrets` — password or passphrase files
```
1. Add your SSH private keys and password files under:
- `../keys` — SSH key files (e.g., id_ed25519)
- `../secrets` — password or passphrase files
---
@@ -127,20 +153,19 @@ Before running the container:
### Environment Variables
Create a `.env` file to customize settings (optional):
```bash
# Copy example if not exists
cp .env.example .env
# Edit to tune settings
nano .env
```
The `.env` file is optional. It lets you remap where configs/secrets live *inside* the container or inject Docker secrets as environment variables.
Example `.env`:
```env
MCP_SSH_MAX_CONCURRENCY=10
MCP_SSH_TIMEOUT_SEC=60
# Override only if you mount to different locations
# MCP_SSH_CONFIG_DIR=/app/config
# MCP_SSH_KEYS_DIR=/app/keys
# MCP_SSH_SECRETS_DIR=/app/secrets
# Example secret injection
# MCP_SSH_SECRET_DB_PASSWORD=supersecretvalue
```
---
@@ -154,9 +179,11 @@ Pull and run the published image (default):
```bash
# From the compose directory
docker compose up
```
This:
- Pulls the `ghcr.io/samerfarida/mcp-ssh-orchestrator:latest` image
- Mounts `../config`, `../keys`, and `../secrets` as read-only volumes
- Launches the MCP server in STDIO mode
@@ -168,9 +195,11 @@ Build from local source:
```bash
# From the compose directory
docker compose -f docker-compose.dev.yml up --build
```
This:
- Builds the container from the local Dockerfile
- Mounts `../config`, `../keys`, and `../secrets` as read-only volumes
- Launches the MCP server in STDIO mode
@@ -180,8 +209,10 @@ This:
### Verify It's Running
You should see startup logs like:
```json
{"evt": "server_start", "tool": "mcp-ssh-orchestrator", "mode": "stdio"}
```
---
@@ -191,6 +222,7 @@ You should see startup logs like:
**For Production (using published image - default):**
Add this to your Claude Desktop config.json:
```json
{
"mcpServers": {
@@ -207,6 +239,7 @@ Add this to your Claude Desktop config.json:
}
}
}
```
**For Development (using local build):**
@@ -227,11 +260,13 @@ Add this to your Claude Desktop config.json:
}
}
}
```
> **Important**: Replace `/ABS/PATH/mcp-ssh-orchestrator/` with your actual directory path.
**Alternative**: You can also use the direct Docker run command (simpler, no compose needed):
```json
{
"mcpServers": {
@@ -249,6 +284,7 @@ Add this to your Claude Desktop config.json:
}
}
}
```
---
@@ -256,6 +292,7 @@ Add this to your Claude Desktop config.json:
## Useful Commands
### Production Mode (Default)
| Action | Command |
|--------|---------|
| Check logs | `docker compose logs -f` |
@@ -263,6 +300,7 @@ Add this to your Claude Desktop config.json:
| Stop everything | `docker compose down -v` |
### Development Mode
| Action | Command |
|--------|---------|
| Check logs | `docker compose -f docker-compose.dev.yml logs -f` |
@@ -273,8 +311,9 @@ Add this to your Claude Desktop config.json:
---
## Developer Notes
• The server uses STDIO transport only.
• Default config path: /app/config
• Default entrypoint: python -m mcp_ssh.mcp_server stdio
• Parallel SSH execution supports configurable concurrency limits.
• Policy enforcement supports glob and regex patterns.
- The server uses STDIO transport only.
- Default config path: /app/config
- Default entrypoint: `python -m mcp_ssh.mcp_server stdio`
- Tag fan-out and async jobs still flow through the same deny-by-default policy engine.
- Policy enforcement uses glob patterns (`fnmatch`), paired with hard-coded deny substrings.
+3 -5
View File
@@ -1,7 +1,7 @@
# ─────────────────────────────────────────────────────────────
# 🧩 mcp-ssh-orchestrator (STDIO MCP Server)
# ============================================================
# mcp-ssh-orchestrator (STDIO MCP Server)
# Purpose: Local test or integration with Claude / Docker MCP
# ─────────────────────────────────────────────────────────────
# ============================================================
services:
mcp-ssh:
@@ -15,8 +15,6 @@ services:
user: "1000:1000" # Run as non-root user
environment:
MCP_SSH_CONFIG_DIR: /app/config
MCP_SSH_MAX_CONCURRENCY: ${MCP_SSH_MAX_CONCURRENCY:-5}
MCP_SSH_TIMEOUT_SEC: ${MCP_SSH_TIMEOUT_SEC:-45}
PYTHONUNBUFFERED: "1"
volumes:
- ../config:/app/config:ro # Main YAML configs
+4 -6
View File
@@ -1,21 +1,19 @@
# ─────────────────────────────────────────────────────────────
# 🚀 mcp-ssh-orchestrator (Production Ready)
# ============================================================
# mcp-ssh-orchestrator (Production Ready)
# Purpose: For end users pulling the published image from ghcr.io
# Usage: docker compose up
# Note: For development, use docker-compose.dev.yml instead
# ─────────────────────────────────────────────────────────────
# ============================================================
services:
mcp-ssh:
container_name: mcp-ssh-orchestrator
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
restart: "no"
stdin_open: true
tty: true
environment:
MCP_SSH_CONFIG_DIR: /app/config
MCP_SSH_MAX_CONCURRENCY: ${MCP_SSH_MAX_CONCURRENCY:-5}
MCP_SSH_TIMEOUT_SEC: ${MCP_SSH_TIMEOUT_SEC:-45}
PYTHONUNBUFFERED: "1"
volumes:
# Mount your local config directory (create it first!)
+23 -24
View File
@@ -17,47 +17,47 @@ if [ "$MODE" = "auto" ]; then
fi
if [ "$MODE" = "dev" ]; then
echo "🧪 Setting up mcp-ssh-orchestrator (Development Mode)..."
echo "Setting up mcp-ssh-orchestrator (Development Mode)..."
BASE_DIR=".."
elif [ "$MODE" = "enduser" ]; then
echo "🚀 Setting up mcp-ssh-orchestrator (End User Mode)..."
echo "Setting up mcp-ssh-orchestrator (End User Mode)..."
# For end users, assume they're running from their config location
BASE_DIR="."
else
echo "❌ Invalid mode: $MODE. Use 'dev' or 'enduser'"
echo "Invalid mode: $MODE. Use 'dev' or 'enduser'"
exit 1
fi
# Create required directories
echo "📁 Creating directories..."
echo "Creating directories..."
mkdir -p "${BASE_DIR}/config" "${BASE_DIR}/keys" "${BASE_DIR}/secrets"
if [ "$MODE" = "dev" ]; then
# Copy example configuration files
echo "📋 Copying example configuration files..."
echo "Copying example configuration files..."
if [ -f "../examples/example-servers.yml" ]; then
cp ../examples/example-servers.yml "${BASE_DIR}/config/servers.yml"
echo " ✓ servers.yml"
echo " - servers.yml copied"
else
echo " ⚠️ example-servers.yml not found"
echo " - example-servers.yml not found"
fi
if [ -f "../examples/example-credentials.yml" ]; then
cp ../examples/example-credentials.yml "${BASE_DIR}/config/credentials.yml"
echo " ✓ credentials.yml"
echo " - credentials.yml copied"
else
echo " ⚠️ example-credentials.yml not found"
echo " - example-credentials.yml not found"
fi
if [ -f "../examples/example-policy.yml" ]; then
cp ../examples/example-policy.yml "${BASE_DIR}/config/policy.yml"
echo " ✓ policy.yml"
echo " - policy.yml copied"
else
echo " ⚠️ example-policy.yml not found"
echo " - example-policy.yml not found"
fi
else
# For end users, just create empty config files with instructions
echo "📋 Creating configuration file templates..."
echo "Creating configuration file templates..."
cat > "${BASE_DIR}/config/servers.yml" << 'EOF'
# servers.yml - Add your SSH hosts here
# See examples at: https://github.com/samerfarida/mcp-ssh-orchestrator/blob/main/examples/example-servers.yml
@@ -87,26 +87,25 @@ network:
rules: []
EOF
echo " ✓ Configuration templates created"
echo " Configuration templates created"
fi
# Copy environment file
echo "🔧 Setting up environment..."
if [ -f ".env.example" ]; then
cp .env.example .env
echo " ✓ .env created from .env.example"
else
cat > .env <<'EOF'
echo "Setting up environment..."
cat > .env <<'EOF'
# Generated by setup.sh
MCP_SSH_MAX_CONCURRENCY=5
MCP_SSH_TIMEOUT_SEC=45
# Override these only if you mount the configs to a different path inside the container.
# MCP_SSH_CONFIG_DIR=/app/config
# MCP_SSH_KEYS_DIR=/app/keys
# MCP_SSH_SECRETS_DIR=/app/secrets
# Example: export secrets via env instead of files
# MCP_SSH_SECRET_DB_PASSWORD=supersecretvalue
EOF
echo " ✓ .env created with default values"
fi
echo " .env created with default values"
echo ""
echo "✅ Setup complete!"
echo "Setup complete!"
echo ""
echo "Next steps:"
echo "1. Edit ${BASE_DIR}/config/servers.yml with your server details"
+37 -10
View File
@@ -37,12 +37,12 @@ Secret names and paths are validated to prevent directory traversal attacks:
1. **Secret Name Validation**: Only alphanumeric characters, dashes, and underscores are allowed
```yaml
# ✅ Valid secret names
# Valid secret names
password_secret: "prod_password"
password_secret: "key-passphrase-2024"
password_secret: "admin_password_1"
# ❌ Invalid (will be rejected)
# Invalid (will be rejected)
password_secret: "../etc/passwd" # Path traversal
password_secret: "/absolute/path" # Absolute path
password_secret: "secret.name" # Special characters
@@ -70,12 +70,12 @@ SSH key paths include similar protections:
1. **Traversal Pattern Detection**: Paths containing `..` patterns are rejected
```yaml
# ✅ Valid key paths
# Valid key paths
key_path: "id_ed25519"
key_path: "prod_key"
key_path: "/app/keys/id_ed25519" # Absolute within keys_dir
# ❌ Invalid (will be rejected)
# Invalid (will be rejected)
key_path: "../outside_key" # Path traversal
key_path: "/etc/passwd" # Outside keys_dir
key_path: "key/../../etc/passwd" # Encoded traversal
@@ -95,13 +95,13 @@ All resolved paths are validated to ensure they are regular files:
1. **Directory Rejection**: Paths pointing to directories are rejected
```yaml
# ❌ Invalid (will be rejected)
# Invalid (will be rejected)
password_secret: "subdirectory" # Points to a directory, not a file
```
2. **Symlink Rejection**: Symbolic links are rejected for security
```yaml
# ❌ Invalid (will be rejected)
# Invalid (will be rejected)
password_secret: "symlink_secret" # Points to a symlink, not a regular file
```
**Why reject symlinks?** Symlinks can be manipulated to point outside the allowed directory or to sensitive files, creating security risks.
@@ -385,7 +385,7 @@ secrets:
```bash
docker run -i --rm \
-e MCP_SSH_SECRET_ADMIN_PASSWORD="dev-password" \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**File-Based Secrets (Simple Deployments):**
@@ -400,6 +400,33 @@ echo "passphrase" > ~/mcp-ssh/secrets/key_passphrase
chmod 0400 ~/mcp-ssh/secrets/key_passphrase
```
### Package & Image Verification
1. **GitHub Release Assets**
- Every tarball/zip produced by the release workflow is signed with the maintainer GPG key (`openpgp4fpr:6775BF3F439A2A8A198DE10D4FC5342A979BD358`).
- Import the public key once, then verify each artifact:
```bash
gpg --receive-keys 4FC5342A979BD358
gpg --verify mcp-ssh-orchestrator-v1.0.0.tar.gz.asc mcp-ssh-orchestrator-v1.0.0.tar.gz
```
2. **Container Images (GHCR)**
- The `ghcr.io/samerfarida/mcp-ssh-orchestrator` images are keylessly signed with Sigstore cosign in `.github/workflows/release.yml`.
- Verify signatures (and optional attestations) before promoting an image between environments:
```bash
COSIGN_EXPERIMENTAL=1 cosign verify \
--certificate-identity-regexp "https://github.com/samerfarida/mcp-ssh-orchestrator/.github/workflows/release.yml@.*" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
- Published digests and signature bundles are available for every tag in the GitHub Packages feed so you can pin exact builds.
3. **OpenSSF Scorecard**
- The repository maintains a public Scorecard run covering branch protections, dependency update hygiene, build hardening, and other supply-chain controls. Monitor the score at `https://api.scorecard.dev/projects/github.com/samerfarida/mcp-ssh-orchestrator`.
## Network Security
### Host Key Verification
@@ -634,7 +661,7 @@ USER appuser
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Effect**: Prevents accidental or malicious modification of config/keys.
@@ -828,12 +855,12 @@ docker logs -f mcp-ssh-orchestrator 2>&1 | \
### OWASP LLM Top 10 Coverage
**LLM07: Insecure Plugin Design** ✅
**LLM07: Insecure Plugin Design**
- Policy-based command validation prevents unauthorized execution
- Input sanitization and dangerous command blocking
- Access control for AI plugin operations
**LLM08: Excessive Agency** ✅
**LLM08: Excessive Agency**
- Role-based restrictions via host tags
- Deny-by-default security model
- Command pattern matching limits autonomous actions
+3 -3
View File
@@ -124,7 +124,7 @@ rules:
# Docker Compose integration
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
volumes:
- ./config:/app/config:ro
- ./keys:/app/keys:ro
@@ -327,13 +327,13 @@ services:
### Forward Compatibility
**Principle:** Design for future MCP protocol evolution.
**Principle:** Keep the server adaptable to MCP protocol evolution without promising unbuilt features.
**Implementation:**
- MCP specification compliance
- Extensible policy engine
- Plugin-ready architecture (future)
- Plugin-ready architecture (not yet implemented; tracked separately)
- API versioning support
## Success Metrics
+24 -2
View File
@@ -442,12 +442,12 @@ overrides:
### OWASP LLM Top 10
**LLM07: Insecure Plugin Design** ✅
**LLM07: Insecure Plugin Design**
- Policy-based command validation prevents unauthorized execution
- Input sanitization and dangerous command blocking
- Access control for AI plugin operations
**LLM08: Excessive Agency** ✅
**LLM08: Excessive Agency**
- Role-based restrictions via host tags
- Deny-by-default security model
- Command pattern matching limits autonomous actions
@@ -486,6 +486,28 @@ overrides:
*Note: Compliance remains the responsibility of the deploying organization. This project offers logs and controls that can assist with reporting but does not provide certifications.*
## Supply Chain & Integrity Controls
- **GPG release signatures**: All archives attached to GitHub Releases include detached `.asc` files signed by `openpgp4fpr:6775BF3F439A2A8A198DE10D4FC5342A979BD358`. Import the key and verify every artifact before unpacking:
```bash
gpg --receive-keys 4FC5342A979BD358
gpg --verify mcp-ssh-orchestrator-v1.0.0.tar.gz.asc mcp-ssh-orchestrator-v1.0.0.tar.gz
```
- **Cosign-signed container images**: The GitHub Actions release workflow signs `ghcr.io/samerfarida/mcp-ssh-orchestrator` with Sigstore keyless certificates (`release.yml`). Validate the signature and provenance in CI/CD before promotion:
```bash
COSIGN_EXPERIMENTAL=1 cosign verify \
--certificate-identity-regexp "https://github.com/samerfarida/mcp-ssh-orchestrator/.github/workflows/release.yml@.*" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
Digests, signatures, and attestations are published alongside each tag in the GitHub Packages feed, enabling immutable deployment pins.
- **OpenSSF Scorecard**: Automated Scorecard runs track branch protections, dependency update hygiene, CI hardening, and token hygiene. Monitor the live score at `https://api.scorecard.dev/projects/github.com/samerfarida/mcp-ssh-orchestrator` and treat regressions as release blockers.
## Security Monitoring
### Real-Time Monitoring
+12
View File
@@ -128,6 +128,16 @@ limits:
require_known_host: true # Enforces host key verification
```
## Policy Quick Reference
Designing `policy.yml` is easier when you follow a few core rules (see [6.3](06.3-policy.yml) for full details):
1. **Deny substrings run first.** If a command contains a blocked substring, it is rejected before rules are evaluated. Override the list per-alias/tag if a host truly needs the command.
2. **Rules are evaluated top-to-bottom, last match wins.** Place broad denies after their paired allows when you want them to override, and keep conflicting rules close together.
3. **Default is deny.** Any command that doesn’t match a rule is automatically blocked.
4. **Overrides stack.** Alias overrides beat tag overrides, which beat global limits. Use them to adjust `max_seconds`, `task_result_ttl`, or `deny_substrings` for sensitive hosts.
5. **Test before running.** Run `ssh_plan` to confirm the policy decision, then `ssh_run`/`ssh_run_async`, and finish with `ssh_reload_config` after YAML edits.
## Configuration Validation
### Syntax Validation
@@ -356,6 +366,8 @@ python -m mcp_ssh.config check-refs config/
- **Use CI linting**: run `python -m mcp_ssh.config validate` or `ssh_plan` checks in pipelines to catch syntax or policy regressions before deployment.
- **Reference snippets in docs/PRs**: when proposing access changes, cite the exact YAML so auditors can trace policy intent to implementation.
- **Leverage `ssh_reload_config`**: hot-reload after merging approved YAML to keep runtime behavior in sync with the code-reviewed source of truth.
- **Document the reasoning**: if you relax a deny substring or extend `max_seconds`, explain why in Git history and reference the host/tag it applies to.
- **Prefer non-interactive recipes**: when allowing privileged commands (e.g., package upgrades), require explicit patterns such as `DEBIAN_FRONTEND=noninteractive sudo apt-get upgrade -y` and pair them with per-host overrides.
## Next Steps
+13 -13
View File
@@ -117,11 +117,11 @@ All string parameters in credentials configuration have length limits:
- **Rejected**: Special characters, path separators, traversal patterns
- **Examples**:
```yaml
# ✅ Valid
# Valid
password_secret: "prod_password"
password_secret: "key-passphrase"
# ❌ Invalid (rejected)
# Invalid (rejected)
password_secret: "../etc/passwd" # Path traversal
password_secret: "/absolute/path" # Absolute path
password_secret: "secret.name" # Special characters
@@ -136,9 +136,9 @@ All string parameters in credentials configuration have length limits:
5. **Security logging**: Path traversal and file validation failures are logged as security events
**File Type Requirements:**
- ✅ Regular files within secrets directory
- ❌ Directories (must be files, not directories)
- ❌ Symbolic links (rejected for security)
- Regular files within secrets directory
- Directories (must be files, not directories)
- Symbolic links (rejected for security)
**Effect**: Prevents accessing files outside the secrets directory via path traversal attacks and blocks access to directories or symlinks that could pose security risks.
@@ -154,7 +154,7 @@ export MCP_SSH_SECRET_ADMIN_PASSWORD="admin-password"
docker run -i --rm \
-e MCP_SSH_SECRET_PROD_KEY_PASSPHRASE="my-passphrase" \
-e MCP_SSH_SECRET_ADMIN_PASSWORD="admin-password" \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Claude Desktop configuration:**
@@ -168,7 +168,7 @@ docker run -i --rm \
"-e", "MCP_SSH_SECRET_PROD_PASSWORD=your-password",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -185,7 +185,7 @@ echo "my-passphrase" | docker secret create ssh_key_passphrase -
# Use in Docker Compose
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
secrets:
- ssh_key_passphrase
volumes:
@@ -406,11 +406,11 @@ entries:
**Examples**:
```yaml
# ✅ Valid key paths
# Valid key paths
key_path: "id_ed25519" # Relative, within keys_dir
key_path: "/app/keys/id_ed25519" # Absolute, within keys_dir
# ❌ Invalid (rejected)
# Invalid (rejected)
key_path: "../outside_key" # Path traversal
key_path: "/etc/passwd" # Outside keys_dir
key_path: "../../root/.ssh/id_rsa" # Traversal attempt
@@ -419,9 +419,9 @@ key_path: "symlink_key" # Points to symlink, not regular file
```
**File Type Requirements:**
- ✅ Regular files within keys_dir (or non-existent files - validated when used)
- ❌ Directories
- ❌ Symbolic links (rejected for security)
- Regular files within keys_dir (or non-existent files - validated when used)
- Directories
- Symbolic links (rejected for security)
**Effect**: Prevents accessing SSH keys from unauthorized locations and blocks access to directories or symlinks that could pose security risks.
+76
View File
@@ -226,6 +226,26 @@ The policy engine uses Python's `fnmatch` module for pattern matching, supportin
2. **Rule Matching**: Rules are evaluated in order until a match is found
3. **Default Deny**: If no rule matches, command is denied
### Rule Resolution Details
- Rules are processed **top-to-bottom** and the **last matching rule wins**. Each match updates the pending decision, so place broad deny rules after their paired allows if you intend them to override.
- Because matches overwrite previous decisions, keep conflicting rules close together and comment them for future reviewers.
- `deny_substrings` are evaluated **before** any rule logic. If a command is blocked there (for example, it contains `sudo `), later allow rules will never run. To permit that operation, remove or override the substring entry for the specific hosts.
- Always test with `ssh_plan` to verify the final decision after ordering changes.
```yaml
rules:
- action: "allow"
aliases: ["prod-*"]
commands: ["systemctl status *"]
- action: "deny"
aliases: ["prod-*"]
commands: ["systemctl *"] # Overrides the allow above
```
In the example, `systemctl status nginx` is denied because the later rule matches the same alias and command pattern.
## Override Hierarchy
When multiple overrides apply, precedence is (highest to lowest):
@@ -235,6 +255,27 @@ When multiple overrides apply, precedence is (highest to lowest):
3. **Global Limits** - Settings in the `limits` section
4. **Default Values** - Hardcoded defaults in the policy engine
### Deny Substring Overrides in Practice
Alias/tag overrides can redefine `deny_substrings`, which is useful when you want a strict global block list but still need an escape hatch for a small set of hosts:
```yaml
limits:
deny_substrings:
- "sudo "
- "rm -rf /"
- "kubectl "
overrides:
aliases:
docker-prod-manager1:
deny_substrings: # Clone the list without sudo
- "rm -rf /"
- "kubectl "
```
In this pattern, sudo stays blocked for every host **except** `docker-prod-manager1`. Pair the override with explicit allow rules and higher `max_seconds` values so privileged operations are both auditable and predictable.
## Default Values
| Setting | Default Value | Description |
@@ -445,6 +486,41 @@ overrides:
# Note: host_key_auto_add and require_known_host=false are deprecated (CWE-295)
```
### Privileged Maintenance (Non-Interactive Upgrades)
Long-running maintenance commands (like apt upgrades) often require sudo, additional flags, and longer timeouts. Combine explicit allow rules with per-alias overrides:
```yaml
rules:
- action: "allow"
aliases:
- "docker-prod-manager1"
- "docker-prod-manager2"
- "docker-prod-manager3"
commands:
- "sudo apt-get update*"
- "DEBIAN_FRONTEND=noninteractive sudo apt-get upgrade -y*"
overrides:
aliases:
docker-prod-manager1:
max_seconds: 300
task_result_ttl: 1800
docker-prod-manager2:
max_seconds: 300
task_result_ttl: 1800
docker-prod-manager3:
max_seconds: 300
task_result_ttl: 1800
```
Workflow:
1. Remove `sudo ` from the global `deny_substrings` list or override it for these hosts.
2. Allow only the exact command patterns required (non-interactive apt commands in this case).
3. Increase per-host `max_seconds` so `dpkg` has enough time, and extend `task_result_ttl` so you can retrieve async results later.
4. Test with `ssh_plan`, run via `ssh_run_async`, then monitor with `ssh_get_task_status/result` and revert overrides if they were temporary.
## YAML Style Guide
For consistency and readability, follow these YAML array formatting guidelines:
+2 -2
View File
@@ -266,7 +266,7 @@ ssh_describe_host --alias "web1"
}
```
> ℹ️ When `allowed` is `false`, the response also includes `why` and `hint` fields so MCP clients know to call `ssh_plan` again or consult the SSH Orchestrator prompts before retrying. No sensitive policy details are exposed.
> When `allowed` is `false`, the response also includes `why` and `hint` fields so MCP clients know to call `ssh_plan` again or consult the SSH Orchestrator prompts before retrying. No sensitive policy details are exposed.
**Use Cases:**
@@ -320,7 +320,7 @@ ssh_plan --alias "prod-web-1" --command "systemctl restart nginx"
}
```
> ❗ Policy or network denials return structured JSON with a `hint` field that reminds the caller to use `ssh_plan` or review the orchestrator prompts for next steps.
> Policy or network denials return structured JSON with a `hint` field that reminds the caller to use `ssh_plan` or review the orchestrator prompts for next steps.
**Response Fields:**
| Field | Type | Description |
+42
View File
@@ -407,6 +407,48 @@ ssh_run --alias "web1" --command "systemctl restart nginx"
ssh_run --alias "web1" --command "systemctl status nginx"
```
### Policy Tuning: Privileged Maintenance Window
**Goal:** Allow `DEBIAN_FRONTEND=noninteractive sudo apt-get upgrade -y` on a small set of hosts without loosening global policy.
1. **Edit policy.yml**
```yaml
rules:
- action: "allow"
aliases:
- "docker-prod-manager1"
- "docker-prod-manager2"
- "docker-prod-manager3"
commands:
- "sudo apt-get update*"
- "DEBIAN_FRONTEND=noninteractive sudo apt-get upgrade -y*"
overrides:
aliases:
docker-prod-manager1:
max_seconds: 300
task_result_ttl: 1800
```
- Remove `sudo ` from the global `deny_substrings` list or override it for these aliases.
- Copy the override block for each host that needs the longer timeout/output window.
2. **Reload & dry-run**
```bash
ssh_reload_config
ssh_plan --alias docker-prod-manager1 \
--command "DEBIAN_FRONTEND=noninteractive sudo apt-get upgrade -y"
```
3. **Execute asynchronously**
```bash
ssh_run_async --alias docker-prod-manager1 \
--command "DEBIAN_FRONTEND=noninteractive sudo apt-get upgrade -y"
ssh_get_task_status --task-id "<id>"
ssh_get_task_result --task-id "<id>"
```
4. **Roll back overrides if temporary** once the window closes.
### Bulk Operations with Error Handling
**Safe bulk operations:**
+73 -43
View File
@@ -11,19 +11,21 @@ mcp-ssh-orchestrator is designed for **containerized deployment** with security-
### Docker (Recommended)
**Single Container Deployment:**
```bash
# Pull the image
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Run with configuration
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Production Configuration:**
```bash
# Create secure directories
mkdir -p ~/mcp-ssh/{config,keys,secrets}
@@ -38,18 +40,33 @@ docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Image & Provenance Verification
Before promoting a new build, validate the Sigstore signature attached to the GHCR image:
```bash
COSIGN_EXPERIMENTAL=1 cosign verify \
--certificate-identity-regexp "https://github.com/samerfarida/mcp-ssh-orchestrator/.github/workflows/release.yml@.*" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
- Record the digest printed by `cosign verify` (or from the [package feed](https://github.com/samerfarida/mcp-ssh-orchestrator/pkgs/container/mcp-ssh-orchestrator/versions)) and pin it in your manifests.
- For air-gapped promotion, download the signature bundle produced by cosign and store it alongside the image tarball.
### Docker Compose
**Production Compose:**
```yaml
version: '3.8'
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
user: "10001:10001"
deploy:
resources:
@@ -73,6 +90,7 @@ services:
```
**Development Compose:**
```yaml
version: '3.8'
@@ -97,6 +115,7 @@ services:
### 1. Configuration Setup
**Create configuration directory:**
```bash
mkdir -p /opt/mcp-ssh/{config,keys,secrets}
chown -R 10001:10001 /opt/mcp-ssh
@@ -105,6 +124,7 @@ chmod 0400 /opt/mcp-ssh/keys/*
```
**Copy example configurations:**
```bash
cp examples/example-servers.yml /opt/mcp-ssh/config/servers.yml
cp examples/example-credentials.yml /opt/mcp-ssh/config/credentials.yml
@@ -114,6 +134,7 @@ cp examples/example-policy.yml /opt/mcp-ssh/config/policy.yml
### 2. SSH Key Management
**Generate production keys:**
```bash
# Generate Ed25519 key pair
ssh-keygen -t ed25519 -f /opt/mcp-ssh/keys/mcp_prod -C "mcp-ssh-orchestrator-prod"
@@ -127,6 +148,7 @@ ssh-copy-id -i /opt/mcp-ssh/keys/mcp_prod.pub ubuntu@10.0.0.11
```
**Update credentials.yml:**
```yaml
entries:
- name: "prod_admin"
@@ -139,6 +161,7 @@ entries:
### 3. Policy Configuration
**Production policy.yml:**
```yaml
known_hosts_path: "/app/keys/known_hosts"
@@ -182,6 +205,7 @@ overrides:
### 4. Secrets Management
**Docker Secrets (Recommended):**
```bash
# Create secrets
echo "production-passphrase" | docker secret create mcp_prod_passphrase -
@@ -190,7 +214,7 @@ echo "admin-password" | docker secret create mcp_admin_password -
# Use in Docker Compose
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
secrets:
- mcp_prod_passphrase
- mcp_admin_password
@@ -206,6 +230,7 @@ secrets:
```
**Environment Variables:**
```bash
# Set environment variables
export MCP_SSH_SECRET_PROD_KEY_PASSPHRASE="production-passphrase"
@@ -217,7 +242,7 @@ docker run -i --rm \
-e MCP_SSH_SECRET_ADMIN_PASSWORD \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
## Resource Management
@@ -227,11 +252,12 @@ docker run -i --rm \
MCP SSH Orchestrator is designed to run efficiently as a single container instance per MCP client connection.
**Resource Limits:**
```yaml
# docker-compose.yml
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
deploy:
resources:
limits:
@@ -246,54 +272,46 @@ services:
- Each MCP client connects to its own orchestrator instance
- No load balancer required for single-client scenarios
**Future Scaling Considerations:**
**Scaling Considerations:**
- Horizontal scaling would require additional infrastructure (load balancer, shared state)
- Currently not implemented - one orchestrator per MCP client is the recommended approach
- Horizontal fan-out requires external orchestration (load balancers, shared audit storage) and is not bundled with this project.
- Recommended pattern: keep one orchestrator container per MCP client session for deterministic policy enforcement.
### Health Monitoring
**Health Check Script:**
```bash
#!/bin/bash
# health-check.sh
set -e
# Check container health
docker ps --filter "name=mcp-ssh" --filter "health=healthy"
CONTAINER=${1:-mcp-ssh}
# Check MCP server responsiveness
echo '{"jsonrpc":"2.0","method":"ping","id":1}' | \
docker exec -i mcp-ssh-1 python -m mcp_ssh.mcp_server stdio
echo "== Container health =="
docker ps --filter "name=${CONTAINER}" --filter "health=healthy"
# Check policy configuration
docker exec mcp-ssh-1 python -c "
echo "== Recent logs =="
docker logs --tail=20 "${CONTAINER}"
echo "== Config summary =="
docker exec -i "${CONTAINER}" python - <<'PY'
from mcp_ssh.config import Config
config = Config('/app/config')
print('Configuration valid:', config.validate())
"
cfg = Config()
print("Hosts configured:", len(cfg.list_hosts()))
policy = cfg.get_policy() or {}
print("Policy rules:", len(policy.get("rules", [])))
print("Deny substrings:", len((policy.get("limits") or {}).get("deny_substrings", [])))
PY
```
**Monitoring with Prometheus:**
```yaml
version: '3.8'
**Structured Logging:**
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
volumes:
- ./config:/app/config:ro
- ./keys:/app/keys:ro
environment:
- PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus
- All policy/audit events are emitted as JSON on stderr. Collect them with `docker logs` or ship them to your logging stack (Loki, Elastic, CloudWatch, etc.).
- For scraping-friendly output, pipe stderr into `jq` or a log forwarder:
prometheus:
image: prom/prometheus
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
depends_on:
- mcp-ssh
```bash
docker logs -f mcp-ssh | jq '.'
```
## Security Hardening
@@ -301,6 +319,7 @@ services:
### Container Security
**Non-root execution:**
```dockerfile
# Container runs as UID 10001
RUN useradd -u 10001 -m appuser
@@ -308,6 +327,7 @@ USER appuser
```
**Resource limits:**
```yaml
deploy:
resources:
@@ -320,22 +340,24 @@ deploy:
```
**Read-only filesystem:**
```bash
docker run -i --rm \
--read-only \
--tmpfs /tmp \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Network Security
**Network isolation:**
```yaml
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
networks:
- mcp-network
volumes:
@@ -351,6 +373,7 @@ networks:
```
**Firewall rules:**
```bash
# Allow only necessary ports
ufw allow 22/tcp
@@ -365,6 +388,7 @@ ufw deny 2377/tcp # Docker swarm
### Configuration Updates
**Hot reload:**
```bash
# Update configuration files
vim /opt/mcp-ssh/config/policy.yml
@@ -377,17 +401,19 @@ reload_config()
```
**Rolling updates:**
```bash
# Update to new version
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.2.0
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Rolling update
docker service update --image ghcr.io/samerfarida/mcp-ssh-orchestrator:0.2.0 mcp-ssh
docker service update --image ghcr.io/samerfarida/mcp-ssh-orchestrator:latest mcp-ssh
```
### Backup and Recovery
**Configuration backup:**
```bash
#!/bin/bash
# backup-config.sh
@@ -404,6 +430,7 @@ find "$BACKUP_DIR" -name "config_*.tar.gz" -mtime +7 -delete
```
**Disaster recovery:**
```bash
#!/bin/bash
# restore-config.sh
@@ -426,6 +453,7 @@ docker-compose up -d
### Common Issues
**Container won't start:**
```bash
# Check logs
docker logs mcp-ssh-1
@@ -439,6 +467,7 @@ print('Config valid:', config.validate())
```
**SSH connection failures:**
```bash
# Test SSH connectivity
ssh -i /opt/mcp-ssh/keys/mcp_prod ubuntu@10.0.0.11
@@ -448,6 +477,7 @@ docker exec mcp-ssh-1 ssh-keyscan 10.0.0.11
```
**Policy issues:**
```bash
# Test policy rules
docker exec mcp-ssh-1 python -c "
+21 -21
View File
@@ -13,7 +13,7 @@ Complete these steps once on the machine where your MCP client (Cursor, Claude D
**1. Pull the image:**
```bash
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**2. Create configuration directories:**
@@ -60,7 +60,7 @@ Once the shared setup is in place, connect your MCP client using the appropriate
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
Restart it later with `docker start mcp-ssh-orchestrator` if needed.
@@ -109,7 +109,7 @@ Configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_c
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -136,7 +136,7 @@ On Windows the path is `%APPDATA%\Claude\claude_desktop_config.json`.
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -160,7 +160,7 @@ On Windows the path is `%APPDATA%\Claude\claude_desktop_config.json`.
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -189,7 +189,7 @@ Install Docker Desktop with the MCP Toolkit extension enabled.
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -204,7 +204,7 @@ docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
## OpenAI Codex Integration
@@ -227,7 +227,7 @@ docker run -i --rm \
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -243,7 +243,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_ping","argume
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
## Custom Application Integration
@@ -266,7 +266,7 @@ async def main():
"-v", "/path/to/config:/app/config:ro",
"-v", "/path/to/keys:/app/keys:ro",
"-v", "/path/to/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
)
@@ -309,7 +309,7 @@ async function main() {
'-v', '/path/to/config:/app/config:ro',
'-v', '/path/to/keys:/app/keys:ro',
'-v', '/path/to/secrets:/app/secrets:ro',
'ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3'
'ghcr.io/samerfarida/mcp-ssh-orchestrator:latest'
]
});
@@ -365,7 +365,7 @@ main().catch(console.error);
"-v", "/Users/YOUR_USERNAME/mcp-ssh-dev/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh-dev/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh-dev/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -388,7 +388,7 @@ main().catch(console.error);
"-v", "/Users/YOUR_USERNAME/mcp-ssh-staging/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh-staging/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh-staging/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -414,7 +414,7 @@ main().catch(console.error);
"-v", "/Users/YOUR_USERNAME/mcp-ssh-prod/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh-prod/keys:/app/keys:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh-prod/secrets:/app/secrets:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -434,7 +434,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_ping","argume
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Test host listing:**
@@ -446,7 +446,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_list_hosts","
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Command Testing
@@ -460,7 +460,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_plan","argume
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Execute test command:**
@@ -472,7 +472,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_run","argumen
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
## Troubleshooting
@@ -483,10 +483,10 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_run","argumen
```bash
# Check container logs
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3")
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:latest")
# Test container health
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3 python -c "import mcp_ssh; print('OK')"
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:latest python -c "import mcp_ssh; print('OK')"
```
**Configuration errors:**
@@ -496,7 +496,7 @@ docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3 python -c "import
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.config import Config
config = Config('/app/config')
+22 -22
View File
@@ -37,7 +37,7 @@ ls -la config/
# Validate configuration
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.config import Config
config = Config('/app/config')
@@ -102,7 +102,7 @@ print('Policy valid:', 'rules' in policy)
# Test policy rules
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.policy import Policy
policy = Policy('/app/config/policy.yml')
@@ -197,10 +197,10 @@ ssh-keyscan -H <hostname> >> /app/keys/known_hosts
**Solutions:**
```bash
# Check container logs
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0")
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:latest")
# Test container health
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 python -c "import mcp_ssh; print('OK')"
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:latest python -c "import mcp_ssh; print('OK')"
# Check resource usage
docker stats
@@ -211,7 +211,7 @@ docker run -i --rm \
--cpus=2 \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
#### Permission Issues
@@ -239,10 +239,10 @@ docker run -i --rm \
--user=10001:10001 \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Check container user
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 whoami
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:latest whoami
```
### MCP Client Issues
@@ -269,7 +269,7 @@ echo '{"jsonrpc":"2.0","method":"ping","id":1}' | \
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Check Claude Desktop configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
@@ -301,14 +301,14 @@ echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Test tool execution
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_ping","arguments":{}},"id":1}' | \
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
## Debugging Techniques
@@ -323,7 +323,7 @@ docker run -i --rm \
-e LOG_LEVEL=DEBUG \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Production Debugging:**
@@ -334,7 +334,7 @@ docker run -i --rm \
-e LOG_FORMAT=json \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Network Debugging
@@ -349,14 +349,14 @@ docker run -i --rm \
-e SSH_DEBUG=1 \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Network Connectivity Tests:**
```bash
# Test network connectivity
docker run --rm --network=host \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
import socket
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
@@ -373,7 +373,7 @@ s.close()
# Test specific policy rules
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.policy import Policy
policy = Policy('/app/config/policy.yml')
@@ -393,7 +393,7 @@ print('Deny rule result:', result)
# Validate policy configuration
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.policy import Policy
policy = Policy('/app/config/policy.yml')
@@ -460,7 +460,7 @@ docker run -i --rm \
--memory=1g \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Limit output size
# In policy.yml:
@@ -523,7 +523,7 @@ cat ~/mcp-ssh/config/policy.yml
# Test policy evaluation
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.policy import Policy
policy = Policy('/app/config/policy.yml')
@@ -553,16 +553,16 @@ ls -la ~/mcp-ssh/config/
**Container Restart:**
```bash
# Stop all containers
docker stop $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0")
docker stop $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:latest")
# Remove containers
docker rm $(docker ps -aq --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0")
docker rm $(docker ps -aq --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:latest")
# Start fresh
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Service Recovery
@@ -601,7 +601,7 @@ cp -r ~/mcp-ssh/config "$DEBUG_DIR/"
cp -r ~/mcp-ssh/keys "$DEBUG_DIR/"
# Container logs
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0") > "$DEBUG_DIR/container-logs.txt"
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:latest") > "$DEBUG_DIR/container-logs.txt"
# Network information
netstat -an > "$DEBUG_DIR/network-info.txt"
+1 -1
View File
@@ -81,7 +81,7 @@ docker run -it --rm \
-v $(pwd):/app \
-v $(pwd)/config:/app/config:ro \
-v $(pwd)/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
bash
```
+65 -38
View File
@@ -47,18 +47,20 @@ AI agents interacting with external systems introduce significant security risks
### How do I install mcp-ssh-orchestrator?
**Docker (Recommended):**
```bash
# Pull the image
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Run with configuration
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**From Source:**
```bash
git clone https://github.com/samerfarida/mcp-ssh-orchestrator.git
cd mcp-ssh-orchestrator
@@ -84,6 +86,7 @@ pip install -e .
### How do I configure Claude Desktop?
**macOS Configuration** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
@@ -93,7 +96,7 @@ pip install -e .
"run", "-i", "--rm",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
"-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -101,6 +104,7 @@ pip install -e .
```
**Windows Configuration** (`%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
"mcpServers": {
@@ -110,7 +114,7 @@ pip install -e .
"run", "-i", "--rm",
"-v", "C:\\Users\\YOUR_USERNAME\\mcp-ssh\\config:/app/config:ro",
"-v", "C:\\Users\\YOUR_USERNAME\\mcp-ssh\\keys:/app/keys:ro",
"ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0"
"ghcr.io/samerfarida/mcp-ssh-orchestrator:latest"
]
}
}
@@ -122,22 +126,26 @@ pip install -e .
### How do I configure SSH keys?
**1. Generate SSH key pair:**
```bash
ssh-keygen -t ed25519 -f ~/mcp-ssh/keys/id_ed25519 -C "mcp-ssh-orchestrator"
```
**2. Set permissions:**
```bash
chmod 0400 ~/mcp-ssh/keys/id_ed25519
chmod 0444 ~/mcp-ssh/keys/id_ed25519.pub
```
**3. Deploy public key:**
```bash
ssh-copy-id -i ~/mcp-ssh/keys/id_ed25519.pub ubuntu@10.0.0.11
```
**4. Update credentials.yml:**
```yaml
entries:
- name: "admin"
@@ -150,6 +158,7 @@ entries:
### How do I configure policy rules?
**Basic Policy Configuration:**
```yaml
# policy.yml
known_hosts_path: "/app/keys/known_hosts"
@@ -168,7 +177,7 @@ rules:
- "uptime*"
- "df -h*"
- "systemctl status *"
- action: "deny"
aliases: ["*"]
tags: ["*"]
@@ -181,13 +190,14 @@ rules:
### How do I add new hosts?
**1. Update servers.yml:**
```yaml
entries:
- alias: "web1"
hostname: "10.0.0.11"
port: 22
tags: ["production", "web"]
- alias: "web2"
hostname: "10.0.0.12"
port: 22
@@ -195,12 +205,14 @@ entries:
```
**2. Add host keys:**
```bash
ssh-keyscan 10.0.0.11 >> ~/mcp-ssh/keys/known_hosts
ssh-keyscan 10.0.0.12 >> ~/mcp-ssh/keys/known_hosts
```
**3. Test connectivity:**
```bash
ssh -i ~/mcp-ssh/keys/id_ed25519 ubuntu@10.0.0.11
```
@@ -235,6 +247,7 @@ Yes, mcp-ssh-orchestrator implements multiple security layers:
### How do I handle secrets?
**Docker Secrets (Recommended):**
```bash
# Create secrets
echo "your-passphrase" | docker secret create mcp_key_passphrase -
@@ -243,13 +256,14 @@ echo "your-password" | docker secret create mcp_password -
# Use in Docker Compose
services:
mcp-ssh:
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
image: ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
secrets:
- mcp_key_passphrase
- mcp_password
```
**Environment Variables:**
```bash
# Set environment variables
export MCP_SSH_SECRET_KEY_PASSPHRASE="your-passphrase"
@@ -261,18 +275,20 @@ docker run -i --rm \
-e MCP_SSH_SECRET_PASSWORD \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### How do I enable host key verification?
**1. Collect host keys:**
```bash
ssh-keyscan 10.0.0.11 >> ~/mcp-ssh/keys/known_hosts
ssh-keyscan 10.0.0.12 >> ~/mcp-ssh/keys/known_hosts
```
**2. Update policy:**
```yaml
# policy.yml
known_hosts_path: "/app/keys/known_hosts"
@@ -281,6 +297,7 @@ host_key_auto_add: false
```
**3. Test verification:**
```bash
ssh -i ~/mcp-ssh/keys/id_ed25519 ubuntu@10.0.0.11
```
@@ -290,11 +307,13 @@ ssh -i ~/mcp-ssh/keys/id_ed25519 ubuntu@10.0.0.11
### How do I execute commands?
**Via Claude Desktop:**
```
```text
Execute the command "uptime" on the production web server
```
**Via MCP Client:**
```python
result = await session.call_tool(
"ssh_run",
@@ -303,51 +322,57 @@ result = await session.call_tool(
```
**Via Docker:**
```bash
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_run","arguments":{"alias":"web1","command":"uptime"}},"id":1}' | \
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### How do I list available hosts?
**Via Claude Desktop:**
```
```text
List all available SSH hosts
```
**Via MCP Client:**
```python
result = await session.call_tool("ssh_list_hosts", {})
```
**Via Docker:**
```bash
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_list_hosts","arguments":{}},"id":1}' | \
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### How do I test policy rules?
**Dry Run:**
```bash
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_plan","arguments":{"alias":"web1","command":"uptime"}},"id":1}' | \
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Policy Validation:**
```bash
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.policy import Policy
policy = Policy('/app/config/policy.yml')
@@ -367,11 +392,12 @@ print('Policy valid:', policy.validate())
- Network filtering
**Debug Steps:**
```bash
# Check policy evaluation
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.policy import Policy
policy = Policy('/app/config/policy.yml')
@@ -384,7 +410,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_plan","argume
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Why is SSH connection failing?
@@ -397,6 +423,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_plan","argume
- Host key verification failed
**Debug Steps:**
```bash
# Test SSH connectivity
ssh -i ~/mcp-ssh/keys/id_ed25519 ubuntu@10.0.0.11
@@ -419,17 +446,18 @@ telnet 10.0.0.11 22
- Missing dependencies
**Debug Steps:**
```bash
# Check container logs
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0")
docker logs $(docker ps -q --filter "ancestor=ghcr.io/samerfarida/mcp-ssh-orchestrator:latest")
# Test container health
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 python -c "import mcp_ssh; print('OK')"
docker run --rm ghcr.io/samerfarida/mcp-ssh-orchestrator:latest python -c "import mcp_ssh; print('OK')"
# Validate configuration
docker run --rm \
-v ~/mcp-ssh/config:/app/config:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0 \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest \
python -c "
from mcp_ssh.config import Config
config = Config('/app/config')
@@ -458,34 +486,38 @@ print('Config valid:', config.validate())
### How do I optimize performance?
**Configuration Optimization:**
```yaml
# policy.yml
limits:
max_seconds: 15 # Reduce timeout
max_output_bytes: 65536 # Limit output size
max_concurrent_connections: 50 # Limit connections
max_seconds: 15 # Shorter timeout for sensitive hosts
max_output_bytes: 65536 # Tighter output cap
task_result_ttl: 120 # Reduce async retention window
```
**Docker Optimization:**
```bash
# Increase resources
# Increase container resources
docker run -i --rm \
--memory=1g \
--cpus=2 \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
-v ~/mcp-ssh/secrets:/app/secrets:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
**Network Optimization:**
```yaml
# servers.yml
entries:
hosts:
- alias: "web1"
hostname: "10.0.0.11"
host: "10.0.0.11"
port: 22
connection_timeout: 10
keepalive: true
credentials: "prod-admin"
tags: ["production", "web"]
```
## Support
@@ -496,26 +528,21 @@ entries:
- This wiki for comprehensive guides
- GitHub README for quick start
- Code examples and tutorials
- Video demonstrations
- `examples/` directory for ready-to-edit YAML
**Community:**
- GitHub Discussions for questions
- GitHub Issues for bugs
- Discord server for real-time chat
- Community forums for discussions
- GitHub Issues for bugs or feature requests
**Professional Support:**
- Enterprise support available
- Professional services
- Training and certification
- Consulting services
- Not offered. This is a community-supported Apache-2.0 project.
### How do I report bugs?
**Bug Report Template:**
```markdown
## Bug Description
Brief description of the bug
@@ -534,7 +561,7 @@ What actually happens
## Environment
- OS: macOS/Windows/Linux
- Docker version: 24.0+
- mcp-ssh-orchestrator version: 0.1.0
- mcp-ssh-orchestrator version: 1.0.0
## Additional Context
Any other relevant information
+125 -66
View File
@@ -8,291 +8,350 @@ This glossary provides definitions for technical terms, concepts, and acronyms u
## A
**Access Control**
### Access Control
- **Definition**: Security mechanism that controls who can access what resources and under what conditions
- **Context**: MCP SSH Orchestrator implements policy-based access control for SSH command execution
**Agent**
### Agent
- **Definition**: An AI system that can perceive its environment and take actions to achieve goals
- **Context**: AI agents interact with mcp-ssh-orchestrator through the MCP protocol to execute SSH commands
**Alias**
### Alias
- **Definition**: A human-readable name for a host in the servers.yml configuration
- **Context**: Used to reference hosts instead of IP addresses (e.g., "web1" instead of "10.0.0.11")
**Audit Log**
### Audit Log
- **Definition**: A chronological record of events and activities for security oversight
- **Context**: MCP SSH Orchestrator provides structured JSON audit logs for every command execution
**Authentication**
### Authentication
- **Definition**: The process of verifying the identity of a user or system
- **Context**: SSH authentication using public/private key pairs or passwords
## B
**Blocklist**
### Blocklist
- **Definition**: A list of items (IPs, commands, hosts) that are explicitly denied access
- **Context**: Network blocklists prevent connections to unauthorized IP addresses
## C
**CIDR**
### CIDR
- **Definition**: Classless Inter-Domain Routing, a method for allocating IP addresses and routing
- **Context**: Used for network filtering (e.g., "10.0.0.0/8" allows all 10.x.x.x addresses)
**Command Injection**
### Command Injection
- **Definition**: A security vulnerability where malicious commands are injected into legitimate commands
- **Context**: MCP SSH Orchestrator prevents command injection through policy enforcement and input validation
**Compliance**
### Compliance
- **Definition**: Adherence to regulatory or organizational policies and standards
- **Context**: MCP SSH Orchestrator provides security features that can assist with internal governance. Certification against external standards is the responsibility of the deploying organization.
**Container**
### Container
- **Definition**: A lightweight, portable unit of software that packages code and dependencies
- **Context**: MCP SSH Orchestrator is distributed as a Docker container for easy deployment
## D
**Defense in Depth**
### Defense in Depth
- **Definition**: A security strategy that implements multiple layers of security controls
- **Context**: MCP SSH Orchestrator implements policy enforcement, network filtering, audit logging, and container security
**Docker**
### Docker
- **Definition**: A platform for developing, shipping, and running applications in containers
- **Context**: MCP SSH Orchestrator uses Docker for packaging and deployment
**Dry Run**
### Dry Run
- **Definition**: A test execution that simulates a command without actually executing it
- **Context**: The ssh_plan tool performs dry runs to test policy rules before execution
## E
**Ed25519**
### Ed25519
- **Definition**: A public-key signature algorithm that is fast, secure, and compact
- **Context**: Recommended SSH key type for mcp-ssh-orchestrator deployments
**Environment Variable**
### Environment Variable
- **Definition**: A dynamic value that can affect how processes behave
- **Context**: Used for configuration and secret management in mcp-ssh-orchestrator
## F
**Fleet**
### Fleet
- **Definition**: A collection of servers or hosts managed as a group
- **Context**: MCP SSH Orchestrator manages SSH access to a fleet of servers
**Firewall**
### Firewall
- **Definition**: A network security device that monitors and controls network traffic
- **Context**: MCP SSH Orchestrator implements network filtering similar to firewall rules
## G
**GitHub Actions**
### GitHub Actions
- **Definition**: A CI/CD platform that automates software workflows
- **Context**: Used for automated testing, building, and deployment of mcp-ssh-orchestrator
**GitHub Wiki**
### GitHub Wiki
- **Definition**: A documentation platform for GitHub repositories
- **Context**: MCP SSH Orchestrator documentation is maintained in the GitHub wiki
## H
**Host Key**
### Host Key
- **Definition**: A cryptographic key used to verify the identity of an SSH server
- **Context**: MCP SSH Orchestrator verifies host keys to prevent man-in-the-middle attacks
**Hostname**
### Hostname
- **Definition**: A human-readable name for a network device
- **Context**: Used in servers.yml to specify the target host for SSH connections
## I
**IP Address**
### IP Address
- **Definition**: A numerical label assigned to each device connected to a network
- **Context**: Used to identify target hosts in servers.yml configuration
**Incident Response**
### Incident Response
- **Definition**: The process of responding to security incidents and breaches
- **Context**: MCP SSH Orchestrator provides audit logs and monitoring for incident response
## J
**JSON-RPC**
### JSON-RPC
- **Definition**: A remote procedure call protocol encoded in JSON
- **Context**: MCP uses JSON-RPC for communication between clients and servers
## K
**Key Pair**
### Key Pair
- **Definition**: A set of two cryptographic keys (public and private) used for encryption
- **Context**: SSH key pairs are used for authentication in mcp-ssh-orchestrator
**Known Hosts**
### Known Hosts
- **Definition**: A file containing the public keys of SSH servers
- **Context**: MCP SSH Orchestrator uses known_hosts for host key verification
## L
**LLM**
### LLM
- **Definition**: Large Language Model, an AI system trained on vast amounts of text data
- **Context**: LLMs interact with mcp-ssh-orchestrator through MCP clients
**Load Balancer**
### Load Balancer
- **Definition**: A device that distributes network traffic across multiple servers
- **Context**: Not currently implemented in MCP SSH Orchestrator. The tool is designed for one container per MCP client, with scaling handled at the client level.
## M
**MCP**
### MCP
- **Definition**: Model Context Protocol, a standardized interface for AI agents to interact with external tools
- **Context**: MCP SSH Orchestrator implements the MCP protocol for AI agent integration
**Mermaid**
### Mermaid
- **Definition**: A markdown-like syntax for generating diagrams
- **Context**: Used in mcp-ssh-orchestrator documentation for architecture diagrams
**Microservices**
### Microservices
- **Definition**: An architectural approach where applications are built as a collection of loosely coupled services
- **Context**: Future mcp-ssh-orchestrator versions may adopt microservices architecture
- **Context**: Not applicable—the orchestrator is a single MCP stdio server process.
## N
**Network Segmentation**
### Network Segmentation
- **Definition**: The practice of dividing a network into smaller, isolated segments
- **Context**: MCP SSH Orchestrator supports network filtering for segmentation
**Non-root**
### Non-root
- **Definition**: Running processes with limited privileges instead of administrator/root privileges
- **Context**: MCP SSH Orchestrator containers run as non-root user for security
## O
**OWASP**
### OWASP
- **Definition**: Open Web Application Security Project, a nonprofit foundation focused on software security
- **Context**: MCP SSH Orchestrator addresses OWASP Top 10 for LLMs security risks
**Orchestrator**
### Orchestrator
- **Definition**: A system that manages and coordinates multiple components or services
- **Context**: MCP SSH Orchestrator orchestrates SSH access across a fleet of servers
## P
**Policy**
### Policy
- **Definition**: A set of rules that govern behavior or access control
- **Context**: MCP SSH Orchestrator uses policies to control SSH command execution
**Policy Engine**
### Policy Engine
- **Definition**: A system that evaluates policies and makes access control decisions
- **Context**: The core component of mcp-ssh-orchestrator that enforces security policies
**Prompt Injection**
### Prompt Injection
- **Definition**: A security vulnerability where malicious input manipulates AI system behavior
- **Context**: MCP SSH Orchestrator prevents prompt injection through policy enforcement
**Privilege Escalation**
### Privilege Escalation
- **Definition**: The act of exploiting a bug or design flaw to gain elevated access
- **Context**: MCP SSH Orchestrator prevents privilege escalation through command restrictions
## Q
**QoS**
### QoS
- **Definition**: Quality of Service, the ability to provide different priority levels for different applications
- **Context**: MCP SSH Orchestrator implements QoS through resource limits and rate limiting
## R
**Rate Limiting**
### Rate Limiting
- **Definition**: A technique to control the rate of requests or operations
- **Context**: MCP SSH Orchestrator implements rate limiting to prevent abuse
**RBAC**
### RBAC
- **Definition**: Role-Based Access Control, a method of restricting access based on user roles
- **Context**: Future mcp-ssh-orchestrator versions will support RBAC
- **Context**: Not implemented. Use policy rules (aliases, tags, commands) to approximate RBAC behavior today.
### Read-only
**Read-only**
- **Definition**: A filesystem or volume that can only be read from, not written to
- **Context**: MCP SSH Orchestrator containers use read-only filesystems for security
## S
**SSH**
### SSH
- **Definition**: Secure Shell, a cryptographic network protocol for secure remote access
- **Context**: MCP SSH Orchestrator manages SSH access to remote servers
**SSH Key**
### SSH Key
- **Definition**: A cryptographic key used for SSH authentication
- **Context**: MCP SSH Orchestrator uses SSH keys for secure authentication
**Secret**
### Secret
- **Definition**: Sensitive information such as passwords, keys, or tokens
- **Context**: MCP SSH Orchestrator manages secrets through Docker secrets or environment variables
**stdio**
### stdio
- **Definition**: Standard input/output, a communication method using standard streams
- **Context**: MCP uses stdio transport for communication between clients and servers
## T
**Tag**
### Tag
- **Definition**: A label or identifier used to categorize or group items
- **Context**: Hosts in mcp-ssh-orchestrator are tagged for policy grouping (e.g., "production", "web")
**TLS**
### TLS
- **Definition**: Transport Layer Security, a cryptographic protocol for secure communication
- **Context**: MCP SSH Orchestrator may use TLS for secure communication in future versions
- **Context**: Not used directly; the server communicates via stdio and relies on SSH for encrypted transport.
### Timeout
**Timeout**
- **Definition**: A maximum time limit for an operation before it is terminated
- **Context**: MCP SSH Orchestrator implements timeouts to prevent hanging commands
## U
**Uptime**
### Uptime
- **Definition**: The amount of time a system has been running without interruption
- **Context**: MCP SSH Orchestrator monitors uptime and system health
**User**
### User
- **Definition**: An individual or system that interacts with mcp-ssh-orchestrator
- **Context**: Users can be human operators or AI agents
## V
**Vulnerability**
### Vulnerability
- **Definition**: A weakness in a system that can be exploited to cause harm
- **Context**: MCP SSH Orchestrator addresses common SSH and MCP vulnerabilities
## W
**Webhook**
### Webhook
- **Definition**: A way for an application to provide real-time information to other applications
- **Context**: Future mcp-ssh-orchestrator versions may support webhooks for notifications
- **Context**: Not supported. MCP SSH Orchestrator communicates strictly via MCP stdio streams.
### Wiki
**Wiki**
- **Definition**: A collaborative website that allows users to create and edit content
- **Context**: MCP SSH Orchestrator documentation is maintained in the GitHub wiki
## X
**XSS**
### XSS
- **Definition**: Cross-Site Scripting, a security vulnerability where malicious scripts are injected into web pages
- **Context**: Not directly applicable to mcp-ssh-orchestrator, but related to web security
- **Context**: Out of scope; the orchestrator exposes no web UI and relies on MCP clients for presentation.
## Y
**YAML**
### YAML
- **Definition**: YAML Ain't Markup Language, a human-readable data serialization format
- **Context**: MCP SSH Orchestrator configuration files use YAML format
## Z
**Zero Trust**
### Zero Trust
- **Definition**: A security model that assumes no implicit trust and verifies every request
- **Context**: Future mcp-ssh-orchestrator versions will implement zero trust architecture
- **Context**: Implemented today via deny-by-default policy, known-host enforcement, and network allowlists.
### Zone
**Zone**
- **Definition**: A logical grouping of network resources
- **Context**: MCP SSH Orchestrator supports network zones for security segmentation
- **Context**: Use host tags and policy rules to approximate zones; there is no separate “zone” object in the codebase.
## Acronyms
+2 -2
View File
@@ -78,13 +78,13 @@ graph TB
```bash
# Pull the image
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Run interactively
docker run -i --rm \
-v ~/mcp-ssh/config:/app/config:ro \
-v ~/mcp-ssh/keys:/app/keys:ro \
ghcr.io/samerfarida/mcp-ssh-orchestrator:0.1.0
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
```
### Basic Configuration
+7 -5
View File
@@ -2,7 +2,7 @@
"name": "mcp-ssh-orchestrator",
"displayName": "MCP SSH Orchestrator",
"description": "A Model Context Protocol (MCP) server for orchestrating SSH operations across multiple servers with security policies and parallel execution capabilities.",
"version": "0.3.8",
"version": "1.0.0",
"author": "samerfarida",
"license": "Apache-2.0",
"repository": {
@@ -35,8 +35,10 @@
"ssh_cancel_async_task"
],
"resources": [
"server_status",
"connection_health"
"ssh://hosts",
"ssh://host/{alias}",
"ssh://host/{alias}/tags",
"ssh://host/{alias}/capabilities"
]
},
"configuration": {
@@ -80,8 +82,8 @@
],
"environment": {
"MCP_SSH_CONFIG_DIR": "/app/config",
"MCP_SSH_MAX_CONCURRENCY": "5",
"MCP_SSH_TIMEOUT_SEC": "45"
"MCP_SSH_KEYS_DIR": "/app/keys",
"MCP_SSH_SECRETS_DIR": "/app/secrets"
}
},
"mcp": {
+29
View File
@@ -0,0 +1,29 @@
# v1.0.0 Code Audit Snapshot
Source of truth: `src/mcp_ssh/*`
## Capabilities Confirmed
- **Transport & entrypoint**: `FastMCP` server exporting stdio transport only (`mcp_server.py`).
- **Tools available**: `ssh_ping`, `ssh_list_hosts`, `ssh_describe_host`, `ssh_plan`, `ssh_run`, `ssh_run_on_tag`, `ssh_run_async`, `ssh_get_task_status`, `ssh_get_task_result`, `ssh_get_task_output`, `ssh_cancel`, `ssh_cancel_async_task`, `ssh_reload_config`.
- **Config sources**: YAML files under `/app/config` (overridable via `MCP_SSH_*_DIR`). Validated for size, traversal, and symlink abuse (`config.py`).
- **Secrets & keys**: Resolved from `/app/secrets` + env for secrets; `/app/keys` for SSH keys with strict path enforcement.
- **Policy engine**: Glob-based allow rules + deny substrings + per-alias/tag overrides + network allow/block lists + execution limits (`policy.py`).
- **Network guardrails**: DNS resolution rate limiting/caching, require-known-host enforcement, allow/block CIDRs verified both pre- and post-connect.
- **Audit/logging**: Structured policy decisions, execution audits, async task progress, and security events emitted via stderr JSON.
- **Async orchestration**: SEP-1686 compliant async task manager with notifications, cancellable tasks, TTL-scoped results, streaming output buffers.
- **Command hygiene**: Input validators for alias/tag/command/task_id, command normalization before deny-list comparison, sanitized errors before returning to clients.
## Unsupported/Out-of-Scope
- No webhook emitters, push notifications, or third-party integrations beyond MCP itself.
- No professional support, paid services, training, or certifications included in codebase.
- No browser/UI surface; product is MCP server + Docker packaging only.
- No roadmap-only features (e.g., futuristic “zone” constructs) implemented in current code.
## Documentation Requirements
- Emphasize zero-trust posture is already enforced (not future tense).
- Align README/wiki descriptions with actual deny list, network allowlist, async tooling, and MCP prompts.
- Remove claims about professional services, webhook plans, or unrelated security topics (e.g., XSS) unless tied directly to orchestrator behavior.
- Document the existing GPG release signatures, cosign image attestations, and reference the OpenSSF Scorecard feed so users can verify provenance before deploying.
+9 -9
View File
@@ -49,10 +49,10 @@ if docker buildx build \
--load \
-t ${TEST_MIN}:latest \
. > /tmp/test-min.log 2>&1; then
echo -e "${GREEN}✅ Test 1 PASSED: Minimal description format works${NC}"
echo -e "${GREEN}Test 1 PASSED: Minimal description format works${NC}"
echo ""
else
echo -e "${RED}❌ Test 1 FAILED: Minimal description format failed${NC}"
echo -e "${RED}Test 1 FAILED: Minimal description format failed${NC}"
echo "Error log:"
cat /tmp/test-min.log
exit 1
@@ -71,10 +71,10 @@ if docker buildx build \
--load \
-t ${TEST_FULL}:latest \
. > /tmp/test-full.log 2>&1; then
echo -e "${GREEN}✅ Test 2 PASSED: Full simplified description format works${NC}"
echo -e "${GREEN}Test 2 PASSED: Full simplified description format works${NC}"
echo ""
else
echo -e "${RED}❌ Test 2 FAILED: Full simplified description format failed${NC}"
echo -e "${RED}Test 2 FAILED: Full simplified description format failed${NC}"
echo "Error log:"
cat /tmp/test-full.log
exit 1
@@ -87,13 +87,13 @@ echo "Inspecting built image to verify annotations are present..."
echo ""
if docker image inspect ${TEST_FULL}:latest | grep -q "org.opencontainers.image.description"; then
echo -e "${GREEN}✅ Test 3 PASSED: Annotations found in image${NC}"
echo -e "${GREEN}Test 3 PASSED: Annotations found in image${NC}"
echo ""
echo "Image labels:"
docker image inspect ${TEST_FULL}:latest | grep -A 10 "Labels" || true
echo ""
else
echo -e "${YELLOW}⚠️ Test 3 WARNING: Annotations not found in image labels (may be in manifest index for multi-arch)${NC}"
echo -e "${YELLOW}Test 3 WARNING: Annotations not found in image labels (may be in manifest index for multi-arch)${NC}"
echo ""
fi
@@ -108,11 +108,11 @@ if docker buildx build \
--platform linux/amd64,linux/arm64 \
--output type=oci,dest=${TMP_DIR}/test-multi.tar,annotation-index.org.opencontainers.image.description="A secure SSH fleet orchestrator for MCP STDIO transport. Enforces declarative policy and audited access for Claude Desktop Cursor and MCP-aware clients",annotation-index.org.opencontainers.image.source="https://github.com/samerfarida/mcp-ssh-orchestrator",annotation-index.org.opencontainers.image.licenses=Apache-2.0 \
. > /tmp/test-multi.log 2>&1; then
echo -e "${GREEN}✅ Test 4 PASSED: Multi-platform syntax is valid${NC}"
echo -e "${GREEN}Test 4 PASSED: Multi-platform syntax is valid${NC}"
echo ""
rm -rf ${TMP_DIR}
else
echo -e "${RED}❌ Test 4 FAILED: Multi-platform syntax validation failed${NC}"
echo -e "${RED}Test 4 FAILED: Multi-platform syntax validation failed${NC}"
echo "Error log:"
cat /tmp/test-multi.log
rm -rf ${TMP_DIR}
@@ -123,7 +123,7 @@ fi
echo "========================================="
echo "Test Summary"
echo "========================================="
echo -e "${GREEN}✅ All tests passed!${NC}"
echo -e "${GREEN}All tests passed!${NC}"
echo ""
echo "The outputs parameter format is valid and ready for implementation."
echo "Format that will be used in release workflow:"
@@ -1,6 +1,6 @@
{
"name": "mcp-ssh-orchestrator",
"version": "0.3.8",
"version": "1.0.0",
"description": "A secure SSH fleet orchestrator exposing list/plan/run tools with policy enforcement over STDIO.",
"license": "Apache-2.0",
"homepage": "https://github.com/samerfarida/mcp-ssh-orchestrator",
@@ -8,7 +8,7 @@
"publisher": "io.github.samerfarida",
"containers": [
{
"image": "ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.8",
"image": "ghcr.io/samerfarida/mcp-ssh-orchestrator:latest",
"transport": "stdio",
"entrypoint": ["python", "-m", "mcp_ssh.mcp_server", "stdio"],
"env": [