mirror of
https://github.com/samerfarida/mcp-ssh-orchestrator.git
synced 2026-11-18 18:03:42 +00:00
42 KiB
42 KiB
Changelog
All notable changes to mcp-ssh-orchestrator will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
[1.3.2] - 2026-07-02
Security
- cryptography: 46.0.7 → 49.0.0 — major bump via transitive
paramiko/pyjwt[crypto]chain;requirements.incap updated to<50.0.0(#145). - PyJWT: 2.12.1 → 2.13.0 — patch bump; security floor in
requirements.inupdated (#140). - python-multipart: 0.0.26 → 0.0.32 — security floor and lockfile updated (#143).
Changed
- Dependencies: Updated MCP SDK from 1.27.0 to 1.27.2 (#141).
- Dependencies: Expanded
paramikoupper bound to<6.0.0; bumped transitiveidnain lockfile (#139). - Docker: Updated Python 3.13-slim base image from 3.13.13 to 3.13.14 (#144).
- Development Dependencies: Expanded mypy constraint from
<2.0.0to<3.0.0inpyproject.toml(#134). - CI/CD: Refreshed stale
# v3version comments on pinned action SHAs inrelease.yml(docker/login-action→# v3.7.0,actions/attest-build-provenance→# v4.1.0). Comment-only; no SHA or behavior changes (#125). - CI/CD: Bumped
actions/upload-artifactfrom 7.0.0 to 7.0.1 in Scorecards workflow (#128). - CI/CD: Bumped
docker/setup-qemu-actionfrom 3.7.0 to 4.0.0 in release workflow (#130). - CI/CD: Bumped
docker/login-actionfrom 3.7.0 to 4.1.0 in release workflow (#126). - CI/CD: Bumped
dorny/paths-filterfrom 3.0.2 to 4.0.1 in build and lint workflows (#127). - CI/CD: Bumped
codecov/codecov-actionfrom 5.5.2 to 6.0.0 in build workflow (#129).
Notes
- Reviewed cryptography 49.0.0 breaking changes — none apply to mcp-ssh-orchestrator code paths (no direct imports; CI uses linux/amd64).
- All dependency PRs (#125–#145) merged; this CHANGELOG entry consolidates release notes that were intentionally kept out of individual Dependabot PRs to avoid merge conflicts.
[1.3.1] - 2026-04-27
Security
Patches the seven open Dependabot advisories that were unaddressed at v1.3.0. All bumps are minimum-impact (patch/minor only); no API changes are expected.
- cryptography: 46.0.3 → 46.0.7 — fixes:
- GHSA buffer overflow when non-contiguous buffers are passed to APIs (alert #8, medium)
- Subgroup attack on SECT curves due to missing subgroup validation (alert #5, high)
- Incomplete DNS name-constraint enforcement on peer names (alert #7, low)
- Capped to
<47.0.0inrequirements.inso the next major bump lands in its own PR.
- PyJWT: 2.10.1 → 2.12.1 — fixes acceptance of unknown
critheader extensions (alert #6, high). - PyNaCl: 1.6.0 → 1.6.2 — fixes incomplete list of disallowed inputs in libsodium binding (alert #3, medium).
- python-multipart: 0.0.22 → 0.0.26 — fixes denial-of-service via large multipart preamble/epilogue (alert #9, medium).
- python-dotenv: 1.2.1 → 1.2.2 — fixes symlink following in
set_keyallowing arbitrary file overwrite via cross-device rename fallback (alert #10, medium).
Changed
- Lockfile hygiene: Added explicit security floors to
requirements.in(with inline GHSA references) so futurepip-compileruns cannot resolve back into the vulnerable range. Re-evaluate these floors at every release. - Lockfile: Regenerated
requirements.txtviapip-compile --generate-hashes(Python 3.13.13, pip-tools 7.5.3) — same toolchain as the Docker base image.
Notes
- No source-code changes; this is a dependency-only security patch.
- CI workflow updates from the open Dependabot PRs (#126–#130) are intentionally not bundled here so this release stays scope-locked to vulnerability remediation. They will be triaged separately.
[1.3.0] - 2026-04-26
Changed
- Dependencies: Updated MCP SDK from 1.26.0 to 1.27.0 (#122, #111)
- Dependencies: Updated transitive
python-multipartpin in the hashed lockfile (#122, #102) - Docker: Updated Python 3.13-slim base image digest for the container image
- Updated from
51e1a0ato2ba73a4(#122, #112) and refreshed again tod2462a6(#112) - Additional digest refreshes landed on
mainafter v1.2.0:baf6668→1f3781f→51e1a0a(#97, #98)
- Updated from
- CI/CD: Grouped GitHub Actions updates for release + security scanning (#121)
docker/login-action3.7.0 (#121, #103)aquasecurity/trivy-action0.34.1 (#121, #107)actions/attest-build-provenance4.1.0 (#121, #108)actions/attest-sbom4.0.0 (#121, #109)actions/upload-artifact7.0.0 (Scorecards workflow) (#121, #110)actions/setup-node6.2.0 (#100)
- Development Dependencies: Raised dev/test tool floors (#123, #99, and related Dependabot PRs)
- Black 26.x, pytest 9.x, pytest-asyncio 1.3.x, pytest-cov 7.1.x, pytest-mock 3.15.x
- mypy 1.20.x, pip-tools 7.5.x, setuptools 82.x (build-system requires)
- Dependencies: Updated MCP SDK from 1.25.0 to 1.26.0 (#101)
- Developer Experience: Added
scripts/ci-local.shto run CI-parity checks locally before pushing (#121)
[1.2.0] - 2025-12-27
Changed
- Dependencies: Updated MCP SDK from 1.23.1 to 1.25.0 (#93)
- Updated to latest MCP SDK version with bug fixes and improvements
- All tests passing across Python 3.11, 3.12, and 3.13
- No breaking changes detected
- Docker: Updated Python base image SHA256 digest (#89)
- Updated from
326df67tobaf6668for latest security patches
- Updated from
- CI/CD: Updated GitHub Actions dependencies
- Updated codecov/codecov-action from 5.5.1 to 5.5.2 (#90)
- Updated actions/setup-node from 6.0.0 to 6.1.0 (#91)
- Updated actions/upload-artifact from 5.0.0 to 6.0.0 (#88)
- Updated actions/attest-build-provenance from 3.0.0 to 3.1.0 (#94)
- Updated docker/setup-buildx-action from 3.11.1 to 3.12.0 (#95)
- Updated softprops/action-gh-release from 2.4.2 to 2.5.0 (#85)
- Updated docker/metadata-action from 5.9.0 to 5.10.0 (#86)
- Updated actions/checkout from 4.2.2 to 4.3.1 (#82)
- Development Dependencies: Updated pytest-asyncio requirement (#81)
Fixed
- Documentation: Fixed markdown code blocks formatting (#78)
[1.1.0] - 2025-11-21
Security
- Command Substitution Bypass Fixed: Hard-banned all command substitution (
$(...), backticks,$((...))) to prevent policy bypasses. All command substitution is now blocked before rule evaluation. - Path-Based Binaries Blocked: Path-based binaries (e.g.,
/usr/bin/cat,./script.sh) are now always blocked for security. Only binaries in$PATHare allowed.
Added
- Version 2 Policy Schema: New argument-aware policy schema with
simple_binariesand structured rules for precise command control. - shlex-Based Argument Parsing: Commands are now parsed using
shlexfor safe, argument-aware rule matching. - Comprehensive Test Coverage: Added 7 new test files with 100+ tests covering:
- SSH client edge cases and error handling (
test_ssh_coverage.py,test_ssh_integration.py) - MCP server coverage including notification handlers, context logging, and resource endpoints (
test_mcp_server_coverage.py,test_mcp_server_edge_cases.py,test_mcp_server_on_tag_coverage.py) - Utilities coverage for async task management and progress callbacks (
test_utilities_coverage.py) - All tests pass linting (Ruff, Black) and maintain code quality standards
- SSH client edge cases and error handling (
Changed
- Breaking: Legacy
commandsPatterns Removed: Legacy full-linefnmatchpatterns incommandsfield are no longer supported. All policies must use version 2 schema (simple_binaries+ structured rules). - Breaking: Path-Based Execution: Path-based binaries are blocked by default. Use structured rules with explicit
binaryname if needed. - Code Quality: All new test files formatted with Black and pass Ruff linting checks. Fixed unused variable warnings and improved code consistency.
Fixed
- Command Substitution Bypass: Fixed 15+ critical bypasses where denied commands could be executed via command substitution (e.g.,
echo $(cat /etc/passwd)). - Insecure Full-Line Matching: Removed insecure full-line
fnmatchpatterns that enabled bypasses. - Linting Issues: Fixed all code linting issues in new test files (blank lines with whitespace, unused imports, unused variables, generator expressions).
[1.0.0] - 2025-11-19
Added
- README Documentation Improvements (#74):
- Added interactive mermaid diagram for Defense-in-Depth Architecture visualization
- Enhanced Real-World Use Cases with persona-aligned scenarios (Homelab Enthusiasts, DevOps Teams, Platform Engineers)
- Improved code block formatting throughout the document for better readability
Changed
- README Structure (#74):
- Fixed all broken code blocks and formatting issues (bash, json, yaml blocks)
- Removed redundant "Docker Build & Inspector Workflow" section (content already in Contributing guide and Usage Cookbook)
- Improved flow and organization for better readability
- Enhanced use case scenarios to be more practical and aligned with target personas
Fixed
- Documentation Formatting (#74):
- Fixed stray markdown characters and formatting inconsistencies
- Corrected ordered list prefixes to follow markdown linting standards (MD029)
- Removed empty lines in code blocks
- Fixed all markdown linting issues for publication readiness
[0.9.0] - 2025-11-18
Added
- .env File Support for Consolidated Secrets Management (#72):
- Added support for consolidated
.envfile in secrets directory for easier secret management - Maintains backward compatibility with individual secret files
- Implements caching with proper cache invalidation on missing files
- Supports comments, quoted values, and values with
=characters - Resolution order: environment variables →
.envfile → individual files - Added 20 comprehensive tests covering all edge cases
- Updated all documentation with
.envfile usage and examples
- Added support for consolidated
Changed
- Documentation Comprehensive Review and Alignment (#73):
- Fixed markdown linting issues across all documentation files
- Added language tags to fenced code blocks for better syntax highlighting
- Fixed ordered list numbering in SECURITY.md and other wiki documents
- Improved consistency and formatting across docs/wiki files
- Enhanced readability and maintainability of documentation structure
Security
- OSSF Scorecard Pinned-Dependencies: Fixed all 58 Pinned-Dependencies security alerts by pinning all GitHub Actions to commit SHAs and all package managers to specific versions
- Pinned 42 GitHub Actions to commit SHAs (replacing version tags like
@v4,@v5) - Pinned 1 GitHub Action (
codeql-action/upload-sarif) to tag@v4due to monorepo sub-action verification requirements - Pinned pip to version 24.0 in all workflows and Dockerfile (5 instances)
- Pinned npm package
markdownlint-cli2to version 0.19.0 - Improved supply chain security by using immutable commit references instead of mutable version tags
- Expected Scorecard Pinned-Dependencies score improvement: 1/10 → 10/10
- All changes validated with YAML syntax checks, GitHub Actions parsing (act), and consistency verification
- Fixed workflow verification error for
codeql-action/upload-sarif(imposter commit error)
- Pinned 42 GitHub Actions to commit SHAs (replacing version tags like
Fixed
- Issue #1: Fixed SSH client exception handling to be more specific - now only catches
KeyErrorandAttributeErrorfrom host key access, preventingRuntimeErrorfrom known_hosts check from being incorrectly caught - Issue #2: Fixed DNS cache race condition (TOCTOU) by adding 1-second grace period to expiry check
- Issue #3: Fixed cleanup thread to support graceful shutdown via
shutdown()method and improved exception logging instead of silently ignoring errors - Workflow Verification: Fixed "imposter commit" error in Scorecard workflow by using tag
@v4forcodeql-action/upload-sarif(monorepo sub-action requirement)
Changed
- Issue #7: Improved type hints for
_ctx_log()function - changedpayload: dict | Nonetopayload: dict[str, Any] | Nonefor better type safety - Issue #11: Increased command hash length from 12 to 16 characters (48 to 64 bits) for better collision resistance in audit trails
- BREAKING: External tools that parse command hashes may need to update to handle 16-character hashes instead of 12
- Dependencies: Updated
sigstore/cosign-installerfrom 3.6.0 to 4.0.0 - Dependencies: Updated CodeQL SARIF upload action version
Added
- Comprehensive unit tests for exception handling fixes (3 new tests)
- Unit tests for DNS cache grace period mechanism
- Unit tests for cleanup thread shutdown mechanism
- Unit tests for hash command function (5 new tests in
test_utilities.py) shutdown()method toAsyncTaskManagerfor graceful cleanup thread termination
[0.8.0] - 2025-11-18
Security
- CRITICAL FIX: Fixed command chaining bypass vulnerability where commands like
uptime && apt list --upgradablecould bypass policy restrictions by chaining an allowed command with a denied one - Command chaining operators (
&&,||,;,|) are now parsed and each command is validated individually - All commands in a chain must be allowed for the chain to execute; if any command is denied, the entire chain is blocked
- Enhanced error messages in
ssh_planto identify which specific command in a chain is denied - Added comprehensive security logging for command chain parsing and denials
- Added 25+ unit tests and 8 integration tests for command chaining validation
- Backward compatibility maintained: simple commands (no chaining) work exactly as before
Added
- Command chain parsing function
_parse_command_chain()supporting all chaining operators and command substitution get_denied_command_in_chain()helper method to identify which command in a chain is denied- Security logging for command chain parsing (
command_chain_parsed) and denials (command_chain_denied) - Comprehensive documentation for command chaining behavior in policy.yml and troubleshooting guides
- Pre-commit hooks configuration for code quality (Ruff, Black, Mypy, markdownlint, yamllint)
- Validation scripts for MCP schema and YAML configuration files
- Markdown linting fix script for automated documentation formatting
[0.7.0] - 2025-11-17
Added
- Enhanced SSH error messages with specific failure reasons (authentication, timeout, connection refused, DNS resolution, etc.)
- Per-host exception handling in
ssh_run_on_tag- individual host failures no longer stop entire operation - Comprehensive test coverage for SSH error scenarios (12 new unit tests, 5 new integration tests)
- MCP Inspector automated testing script for error handling validation
- MCP specification compliance tests for error handling patterns
Changed
- SSH error messages now provide specific, actionable information instead of generic "SSH connection failed"
ssh_run_on_tagnow handles per-host failures gracefully, continuing execution on remaining hosts- Error messages are sanitized for security (no IPs, hostnames, or file paths in user-facing errors)
- Async task error handling now sanitizes error messages before storing/notifying
Fixed
- Fixed issue where one host failure in
ssh_run_on_tagwould stop execution on all hosts - Improved error categorization for better troubleshooting (authentication vs network vs configuration errors)
[0.6.0] - 2025-11-17
Added
Changed
Fixed
[0.6.0] - 2025-11-17
Added
- Docker MCP Gateway secret support: secrets can now be injected as direct environment variables (matching
env:field inserver.yml) in addition to existing prefixed env vars and file-based secrets - Support for all 10 Docker MCP Registry secrets (5 passphrase + 5 password) with flexible expansion capability
- Comprehensive test coverage for Docker MCP Gateway secret resolution including unit tests, integration tests, and priority order verification
- Safe MCP resources:
ssh://hosts(inventory),ssh://host/{alias},ssh://host/{alias}/tags,ssh://host/{alias}/capabilities- Reuse
_validate_alias()+Confighelpers and redact credentials automatically
- Optional context logging for synchronous tooling (
ssh_run,ssh_run_on_tag,ssh_reload_config, cancel + async polling) so MCP clients show task start/finish/cancel updates without leaking commands - Targeted unit tests covering resources +
_ctx_log, plus Docker helper scripts (scripts/docker-build.sh,scripts/docker-smoketest.sh) for repeatable inspector validation - Helper unit tests for policy/network denial responses, plus README/wiki coverage explaining the new hint behavior
Changed
- Secret resolution priority updated to support Docker MCP Gateway pattern:
- Direct env var (Docker MCP Gateway):
<SECRET_NAME>(matchesenv:field inserver.yml) - Prefixed env var (standalone/backward compatibility):
MCP_SSH_SECRET_<SECRET_NAME> - File-based (standalone):
/app/secrets/<secret_name>
- Direct env var (Docker MCP Gateway):
- README, tools reference, observability, and usage cookbook now document the new resources, context logging, and the Docker/Inspector/manual test workflow
- Policy/network denial responses now include MCP-friendly
hinttext (andssh_plansurfaceswhy/hintwhen blocked) so clients know to re-runssh_plan, consult the orchestrator prompts, or explicitly ask about policy/network updates before retrying
Fixed
[0.5.0] - 2025-11-15
Added
- Safe MCP resources:
ssh://hosts(inventory),ssh://host/{alias},ssh://host/{alias}/tags,ssh://host/{alias}/capabilities- Reuse
_validate_alias()+Confighelpers and redact credentials automatically
- Optional context logging for synchronous tooling (
ssh_run,ssh_run_on_tag,ssh_reload_config, cancel + async polling) so MCP clients show task start/finish/cancel updates without leaking commands - Targeted unit tests covering resources +
_ctx_log, plus Docker helper scripts (scripts/docker-build.sh,scripts/docker-smoketest.sh) for repeatable inspector validation - Helper unit tests for policy/network denial responses, plus README/wiki coverage explaining the new hint behavior
Changed
- README, tools reference, observability, and usage cookbook now document the new resources, context logging, and the Docker/Inspector/manual test workflow
- Policy/network denial responses now include MCP-friendly
hinttext (andssh_plansurfaceswhy/hintwhen blocked) so clients know to re-runssh_plan, consult the orchestrator prompts, or explicitly ask about policy/network updates before retrying - Development extras (
pip install ".[dev,test]") documented/verified so contributors can run Black/Ruff/Pytest locally just like CI
Fixed
- Resolved CI lint/test failures by formatting
src/mcp_ssh/mcp_server.pyand the new test suites with Black and ensuring the dev/test extras install pipeline keeps Ruff/Pytest available locally and in automation
[0.4.0] - 2025-11-13
Added
- MCP Prompts Support: Added 6 prompts to guide LLM behavior
ssh_orchestrator_usage- General usage guidance for SSH orchestrator toolsssh_policy_denied_guidance- How to handle policy denialsssh_network_denied_guidance- How to handle network policy denialsssh_missing_host_guidance- How to handle missing host aliasesssh_missing_credentials_guidance- How to handle missing/incomplete credentialsssh_config_change_workflow- Global rules for config change suggestions- Prompts are exposed via MCP protocol (
prompts/listandprompts/get) - Prompts help LLMs understand how to safely interact with the orchestrator
- See: MCP Prompts specification
Changed
- Structured JSON Denial Responses: All denial responses now return structured JSON format
- Policy denials return JSON with
status: "denied",reason: "policy",alias,hash,command - Network denials return JSON with
status: "denied",reason: "network",alias,hostname,detail - This improves LLM understanding and enables better prompt-based guidance
- Per MCP recommendation for better structured outputs
- Updated
ssh_run(),ssh_run_async(), and post-connect network denials
- Policy denials return JSON with
Fixed
[0.3.8] - 2025-11-13
Fixed
- Dockerfile & Dependabot: Prevented accidental Python 3.14 updates
- Reverted Dockerfile from Python 3.14-slim to Python 3.13-slim (MCP SDK doesn't officially support 3.14 yet)
- Added Dependabot ignore rules to block Python 3.14+ updates in Docker ecosystem
- Fixed Dependabot configuration errors (removed unsupported
reviewersproperty, corrected timezone toAmerica/Detroit) - Pinned Python 3.13-slim with SHA256 digest for reproducibility
- Added documentation explaining the Python version constraint
- See: https://github.com/modelcontextprotocol/python-sdk
[0.3.7] - 2025-11-12
Changed
- Dependencies: Bumped MCP SDK from 1.19.0 to 1.21.0
- Updated to latest MCP SDK version with bug fixes and improvements
- Includes SEP-985: OAuth Protected Resource Metadata discovery fallback
- Added
get_server_capabilities()to ClientSession - All tests passing, no breaking changes detected
- See: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.21.0
[0.3.6] - 2025-11-12
Changed
- Release Workflow: Simplified release process by removing problematic Python SBOM generation
- Workflow now relies on GitHub's native dependency graph for Python package SBOM
- Container SBOM generation (Trivy) continues to work reliably
[0.3.5] - 2025-11-12
Changed
- SBOM Generation: Removed Python package SBOM generation from release workflow
- GitHub's native dependency graph already provides Python package SBOM via UI/API
- Container SBOM (Trivy) remains in releases for OSSF Scorecard compliance
- Simplifies workflow and eliminates cyclonedx-py dependency issues
[0.3.4] - 2025-11-12
Added
- OSSF Scorecard Compliance: Enhanced release workflow to meet OSSF Scorecard security requirements
- Added Python package SBOM generation (CycloneDX format) for supply chain transparency
- Implemented least-privilege token permissions (read-only at top level, write only at job level)
- Added concurrency control to prevent multiple simultaneous releases
- Added job timeouts to prevent runaway workflows (15min for tests, 45min for release)
- Improved SBOM generation to include only production dependencies
Changed
- Release Workflow Security: Restructured GitHub Actions permissions following principle of least privilege
- Top-level permissions set to read-only for Token-Permissions check compliance
- Write permissions scoped to release job only where needed
- Added comprehensive documentation comments referencing OSSF Scorecard requirements
Fixed
- Container Tagging: Fixed
latesttag generation in release workflow (removed incorrect branch condition) - SBOM Error Handling: Improved SBOM generation error handling with graceful fallback when Trivy fails
[0.3.3] - 2025-11-08
Changed
- Compose Workflow Polish: Pinned
docker-compose.ymltoghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3, refreshed compose documentation, and updatedcompose/setup.shto generate a baseline.envautomatically when no template is present. - Quick Start Bootstrap: README now highlights the compose setup script as the fastest path to create config/keys/secrets before running Docker, aligning the hero pitch around declarative policy and zero-trust SSH orchestration.
- Documentation Cleanup: Removed references to external compliance frameworks, replaced security tag examples with neutral labels (
critical,restricted,audit,sandbox), and clarified governance messaging across SECURITY.md and the wiki.
Removed
- Legacy Requirements Files: Dropped
requirements-dev.*andrequirements-test.*in favor of installing extras viapip install -e ".[dev,test]", updating the contributor guide accordingly.
Fixed
- Unreleased Notification Note: Carried forward the async notification handler clarification so MCP
ctx.infocalls continue emitting without keyword errors while progress updates still flow viactx.report_progress.
[0.3.2] - 2025-11-07
Added
- MCP Notification Handler Builder: Added
_build_notification_handler()so async tasks broadcast lifecycle events through the MCP context APIs while retaining structured logging fallback when no session loop is available.
Fixed
- Async Task Notifications: Reworked async task notifications to use the MCP 2025-06-18 notification pathway—
ssh_run_asyncnow captures the toolContext, schedules updates on the active event loop, and reports progress/info viactx.report_progress/ctx.info, eliminatingnotification_failedwarnings and restoring real-time updates (MCP Spec, Python SDK). - Security: SSH Host Key Validation (CWE-295): Documented the hardening work from commit
46a8919d95that enforces Paramiko'sRejectPolicy(), ignores unsafe host-key options, and requires known_hosts entries to mitigate MITM risks.
[0.3.0] - 2025-11-02
Added
- Security Audit Logging (PR10): Added comprehensive security audit logging for security-relevant events
- Created
_log_security_event()function with structured JSON format - Unified all security event logging to use audit format
- Includes both Unix timestamp (ts) and ISO 8601 timestamp (timestamp)
- Logs attempted_path and resolved_path for path-related events
- Logs additional context (field names, sizes, limits, patterns)
- Event types: path_traversal_attempt, file_validation_failed, file_size_limit_exceeded, input_length_limit_exceeded, invalid_secret_name, dns_rate_limit_exceeded, command_bypass_attempt
- Comprehensive tests for audit logging (format validation, path traversal, invalid file access, oversized files, timestamp validation)
- Updated documentation with security audit logging format and event types
- Enables security monitoring and incident response via structured audit trail
- Created
- Input Length Limits for Configuration Parameters (PR9): Added length validation for secret names and SSH key paths
- Secret name length limit: 100 characters (prevents oversized secret names in credentials.yml)
- SSH key path length limit: 500 characters (prevents oversized key paths)
- Length validation occurs before other validations (character checks, path traversal checks)
- Security event logging for length limit violations
- Comprehensive tests for length limits (at limit, exceeds limit, under limit)
- Updated documentation with all input length limits (MCP tools + config parameters)
- Complements PR6 input validation for MCP tool parameters (alias, command, tag, task_id)
- DNS Rate Limiting (PR8): Added rate limiting and caching for DNS resolution to prevent DoS attacks
- Rate limiting: Maximum 10 resolutions per second per hostname (time-window based)
- Result caching: 60-second TTL cache for DNS results (reduces DNS server load)
- Timeout protection: 5-second timeout for DNS resolution (prevents hanging)
- Thread-safe implementation for concurrent access
- Rate limit violations logged as security events
- Comprehensive tests for rate limiting, caching, and timeout handling
- Updated documentation with DNS rate limiting details
- Command Denial Bypass Prevention (PR7): Enhanced command denial logic to prevent bypass attempts
- Added
_normalize_command()function that removes quotes, handles escaped characters, and normalizes whitespace - Enhanced
is_allowed()method with dual checking (original + normalized command) - Added token-based matching for common bypass patterns
- Added security event logging for detected bypass attempts
- Prevents bypasses via: quote obfuscation (
'rm -rf /'), escaped characters (rm\ -rf\ /), whitespace variations - Comprehensive tests for all bypass prevention techniques
- Updated documentation with bypass prevention details and limitations
- Added
- Input Validation for User-Controlled Parameters (PR6): Added comprehensive input validation to prevent injection attacks and resource exhaustion
- Added validation helper functions:
_validate_alias(),_validate_command(),_validate_tag(),_validate_task_id() - Alias validation: 100 char limit, alphanumeric/dash/underscore/dot only
- Command validation: 10,000 char limit, rejects null bytes and control characters
- Tag validation: 50 char limit, alphanumeric/dash/underscore/dot only
- Task ID validation: 200 char limit, format validation
- Applied validation to all MCP tools:
ssh_describe_host,ssh_plan,ssh_run,ssh_run_on_tag,ssh_run_async,ssh_cancel,ssh_get_task_status,ssh_get_task_result,ssh_get_task_output,ssh_cancel_async_task - Security event logging for injection attempts (null bytes, control characters)
- Comprehensive tests for all validation functions
- Updated documentation with input validation requirements
- Added validation helper functions:
- Error Message Sanitization (PR5): Added error message sanitization to prevent information disclosure
- All user-facing error messages sanitized to remove sensitive information
- File paths, IP addresses, hostnames, credentials, and port numbers removed from user responses
- Original detailed errors logged to stderr (structured JSON logs) for debugging
- Added
sanitize_error()function inmcp_ssh/tools/utilities.pywith comprehensive pattern matching - Updated all exception handlers in
mcp_server.pyto sanitize errors - Updated
ssh_client.pyto provide generic error messages (detailed errors in exception chain) - Comprehensive tests for all sanitization patterns
- Updated documentation with error sanitization details
- YAML File Size Limits (PR4): Added file size validation for YAML configuration files
- Maximum file size limit of 10MB per YAML file (
servers.yml,credentials.yml,policy.yml) - File size validation before parsing to prevent resource exhaustion attacks
- Security event logging for size limit violations
- Added
MAX_YAML_FILE_SIZEconstant (10MB) with clear documentation - Updated
_load_yaml()function with size checking logic - Comprehensive tests for normal, oversized, and edge case file sizes
- Updated documentation with file size limit details
- Maximum file size limit of 10MB per YAML file (
- Path Traversal Protection (PR1 & PR2): Security enhancements to prevent path traversal attacks
- Secret Path Protection (
_resolve_secret):- Secret name validation: only alphanumeric characters, dashes, and underscores allowed
- Path normalization and validation to ensure paths stay within
/app/secrets - Absolute path rejection for secrets (relative paths only)
- Path traversal pattern detection and blocking (
../,..\\) - Security event logging for all traversal attempts
- SSH Key Path Protection (
_resolve_key_path):- Traversal pattern detection and rejection
- Absolute path validation (must be within
keys_dir) - Relative path validation with directory confinement
- Cross-platform support (handles both forward slash and backslash traversal)
- Security event logging for all traversal attempts
- Comprehensive test coverage with 9 new security-focused tests per function
- Secret Path Protection (
- File Path Validation (PR3): Added file type validation for secret and key paths
- Added
_validate_file_path()helper function that validates paths are regular files - Rejects directories (paths must point to files, not directories)
- Rejects symbolic links (symlinks rejected for security)
- Integrated validation into
_resolve_secret()and_resolve_key_path() - Added comprehensive tests for directory/symlink rejection and regular file validation
- Updated documentation with file type validation requirements
- Added
- Path traversal protection documentation
- Comprehensive path traversal protection section in
docs/SECURITY.md - Secret name validation documentation with allowed characters and examples
- SSH key path validation documentation with relative/absolute path rules
- Security event logging examples for path traversal attempts
- Updated credentials and configuration documentation with security features
- Comprehensive path traversal protection section in
Fixed
- Security Fix: SSH Host Key Validation (CWE-295): Fixed CodeQL security alert by removing unsafe Paramiko host key policies
- Removed
AcceptPolicyclass andAutoAddPolicy()usage which accept unknown host keys - Always use
RejectPolicy()for strict host key verification to prevent MITM attacks host_key_auto_addandrequire_known_host=Falseare now deprecated and ignored- Deprecation warnings logged when unsafe configurations are detected
- All SSH connections now require known_hosts entry for security
- Updated documentation to reflect security requirements and migration path
- References CodeQL alert: py/paramiko-missing-host-key-validation
- Removed
- CI/CD Workflow Fix: Fixed lint and build workflows to run on documentation-only PRs
- Removed restrictive
paths:filter frompull_requesttriggers inlint.ymlandbuild.yml - Added
check-changesjob usingdorny/paths-filterto detect code vs documentation changes - Made all lint/build/test jobs conditional - they skip gracefully when only documentation changed
- Added
skip-docs-onlyjob that always succeeds when no code changes detected - Workflows now always run (satisfies required branch protection checks) while skipping unnecessary jobs
- Prevents "Expected - Waiting for status to be reported" blocking merges on documentation PRs
- Removed restrictive
- Repository Maintenance: Added
plan.plan.mdto.gitignoreto prevent planning documents from being committed
[0.2.1] - 2025-10-31
Changed
- Updated Dockerfile to use Python 3.13-slim with pinned SHA256 digest for reproducibility
- Switched from Python 3.14 (pre-release) to stable Python 3.13
- Changed from editable install (
pip install -e .) to production install (pip install .)
Removed
- Removed
openssh-clientfrom Docker image (debug tool not needed in production) - Removed
libffi8system dependency (not required by Python wheels) - Removed redundant example configuration file copies in Docker image
- Removed unused PATH modification for user local bin directory
Fixed
- Fixed trailing whitespace in Dockerfile apt-get command
[0.2.0] - 2025-10-25
Added
- Async Task Support (SEP-1686): Complete implementation of asynchronous task execution with real-time progress monitoring
ssh_run_async: Start SSH commands asynchronously with immediate task ID returnssh_get_task_status: Poll task status with progress percentage and elapsed timessh_get_task_result: Retrieve final results with complete output and metadatassh_get_task_output: Stream recent output lines from running tasksssh_cancel_async_task: Cancel running async tasks mid-execution
- AsyncTaskManager: Thread-safe task management with background execution
- Task lifecycle states: pending → running → completed/failed/cancelled/timeout
- Output buffering with line-by-line streaming
- Result storage with configurable TTL (default 5 minutes)
- MCP notification support for task events
- Policy Configuration Enhancements:
task_result_ttl: Configurable task result retention (default 300 seconds)task_progress_interval: Progress update frequency (default 5 seconds)- Per-host and per-tag overrides for async task settings
- MCP Notifications: Server-initiated notifications for task state changes
tasks/created: Task startedtasks/progress: Periodic progress updatestasks/completed: Task finished successfullytasks/failed: Task finished with errortasks/cancelled: Task was cancelled
- Production-ready Docker Compose configuration (
docker-compose.yml) that pulls published image from ghcr.io - Development Docker Compose configuration (
docker-compose.dev.yml) for local builds - Smart setup script with auto-detection for dev vs end-user modes
- Enhanced compose documentation with clear production vs development workflows
- YAML Style Guide in
docs/POLICY_REFERENCE.mdwith consistent formatting guidelines - Standardized array formatting rules for improved readability
Changed
- Renamed docker-compose files to follow convention:
docker-compose.ymlfor production (default),docker-compose.dev.ymlfor development - Updated
compose/setup.shto support both dev and end-user workflows with auto-detection - Refactored compose README to clearly distinguish production and development setup paths
- Updated main README with separate instructions for end users vs developers
- Enforced consistent YAML array formatting across all configuration files:
- Empty arrays: inline format
[] - Single items: inline format
["item"] - Multiple items: multi-line format with dash syntax
- Empty arrays: inline format
- Updated all documentation examples to follow consistent style guide
- Standardized
aliasesandtagsarrays in policy rules (multi-line for 2+ items) - Updated all
servers.ymltag arrays to multi-line format for consistency - Refactored all YAML configuration files to follow unified style guidelines
Removed
- Old
docker-compose.prod.ymlfile (consolidated into defaultdocker-compose.yml)
Files Modified
compose/docker-compose.yml(now default production)compose/docker-compose.dev.yml(new development file)compose/setup.sh(enhanced with dev/enduser modes)compose/README.md(completely restructured)README.md(updated Docker Compose instructions)config/policy.ymlconfig/servers.ymlexamples/example-policy.ymlexamples/example-servers.ymldocs/POLICY_EXAMPLES.mddocs/POLICY_REFERENCE.md
[0.1.3] - 2025-01-27
Added
- Comprehensive policy configuration documentation
docs/POLICY_REFERENCE.md- Complete technical reference with all configuration options, types, defaults, and examplesdocs/POLICY_EXAMPLES.md- 10+ practical configuration examples for different environments and use casesdocs/POLICY_SECURITY.md- Security best practices, troubleshooting guide, and incident response procedures
- Policy documentation links in main README.md
- Cross-references between all policy documentation files
- Comprehensive tables for all policy configuration sections (limits, network, rules, overrides)
- Real-world examples for production, development, staging, Proxmox, and network-restricted environments
- Security checklists and troubleshooting guides
- Glob pattern matching syntax documentation
- Rule evaluation order and precedence explanations
Changed
- Updated README.md to include dedicated "Policy Configuration" section with links to comprehensive documentation
- Enhanced documentation structure with consistent cross-references between policy docs
[0.1.2] - 2025-10-24
Fixed
- Fixed SSH host key handling when
require_known_hostis set to false - Added
AcceptPolicyclass to handle unknown host keys without saving them - Resolved "Server not found in known_hosts" error when using permissive host key policies
- Improved SSH connection reliability for environments with dynamic host keys
Changed
- Enhanced SSH client logic to properly respect
require_known_host: falsesetting - Updated host key policy handling to support three modes: strict, permissive, and auto-add
[0.1.1] - 2025-10-22
Fixed
- Fixed Docker build issues in CI/CD pipeline
- Resolved linting and formatting errors for automated workflows
- Fixed Docker test step to properly load built images
- Corrected exception chaining in SSH client error handling
- Fixed loop variable binding issues in progress callbacks
Changed
- Updated Python base image to 3.14-slim for latest security patches
- Improved Docker build process with better .dockerignore configuration
- Enhanced CI/CD workflows with proper dependency management
- Updated development dependencies (black, ruff, mypy, pytest)
Added
- Automated dependency management with Dependabot
- Comprehensive CI/CD pipeline with linting, testing, and Docker builds
- Automated code formatting and type checking
- Docker Compose setup with automated configuration
- Example configuration files and setup scripts
[0.1.0] - 2025-10-21
Added
- Initial release of MCP SSH Orchestrator
- Core MCP server implementation with STDIO transport
- SSH command execution with Paramiko
- Policy-based access control engine
- Allow/deny rules with glob pattern matching
- Per-alias and per-tag limit overrides
- Deny substrings for dangerous commands
- Network security controls
- IP allowlist/blocklist with CIDR support
- Pre-connect DNS resolution verification
- Post-connect peer IP validation
- Credential management
- SSH key-based authentication
- Password-based authentication
- Docker secrets integration
- Environment variable support for secrets
- Configuration system
- YAML-based configuration (servers, credentials, policy)
- Hot-reload capability
- Example configuration files
- MCP Tools
ssh_ping- Health checkssh_list_hosts- List configured hostsssh_describe_host- Get host detailsssh_plan- Dry-run command with policy checkssh_run- Execute command on single hostssh_run_on_tag- Execute command on tagged hostsssh_cancel- Cancel running commandsssh_reload_config- Hot-reload configuration
- Execution features
- Real-time streaming output
- Cancellation support
- Timeout enforcement
- Output size limits
- Progress callbacks
- Docker support
- Multi-stage Dockerfile
- Non-root user (UID 10001)
- Health checks
- Docker Compose configuration
- Audit logging
- JSON-formatted logs to stderr
- Policy decisions
- Execution metrics
- Network events
- Documentation
- Comprehensive README
- Example configurations
- Docker Desktop integration guide
- Docker MCP Registry compliance
- Registry-compliant server.json metadata
- Proper versioning and tagging
Security
- Host key verification with known_hosts
- Network egress controls
- Deny-by-default policy model
- Audit trail for all commands
- Read-only container mounts
- Non-root container execution