mirror of
https://github.com/samerfarida/mcp-ssh-orchestrator.git
synced 2026-11-18 18:03:42 +00:00
docs: refresh security guidance (#64)
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.)
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
@@ -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 "
|
||||
|
||||
@@ -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')
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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": {
|
||||
|
||||
@@ -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.
|
||||
@@ -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": [
|
||||
|
||||
Reference in New Issue
Block a user