Files
mcp-ssh-orchestrator/scripts
Sammy Farida 90eb9bd128 Security: Fix command substitution bypass and implement version 2 policy schema (#76)
* Security: Fix command substitution bypass and implement version 2 policy schema

- Hard-ban all command substitution ($(), backticks, $((())) to prevent policy bypasses
- Implement version 2 policy schema with simple_binaries and structured rules
- Remove legacy commands fnmatch patterns (breaking change)
- Add shlex-based argument parsing for argument-aware rule matching
- Block path-based binaries by default for security
- Update config/policy.yml and examples/example-policy.yml to version 2 schema
- Add comprehensive tests for command substitution blocking and version 2 schema
- Update documentation to reflect version 2 schema only
- Update CHANGELOG with security fix and breaking changes

Fixes: Command substitution bypass vulnerabilities (15+ bypasses blocked)
Breaking: Legacy commands patterns removed, version 2 schema only

* Add comprehensive test coverage and improve policy validation

- Add new test files for comprehensive coverage:
  - test_ssh_coverage.py: SSH client edge cases and error handling
  - test_ssh_integration.py: SSH integration scenarios
  - test_utilities_coverage.py: Async task management and progress callbacks
  - test_mcp_server_coverage.py: MCP server coverage (notification handlers, context logging, resources)

- Expand test_ssh.py with extensive test cases (1000+ lines added)

- Improve policy.py structured rule matching:
  - Fix validation to require binary field for structured rules
  - Add validation to ensure structured rules have at least one restriction
  - Improve allow_extra_args logic with path_args support
  - Fix edge cases in argument matching
  - Add type annotations for mypy compliance

- Update documentation:
  - Update CHANGELOG.md with test coverage details
  - Update README.md, SECURITY.md, and wiki documentation
  - Update example-policy.yml with version 2 schema
  - Update CONTRIBUTING.md with script documentation
  - Fix markdownlint issues in SECURITY.md

- Script maintenance:
  - Add scripts/README.md documenting all scripts
  - Add scripts/test-mcp-automated.py for automated testing
  - Remove obsolete scripts (fix-markdownlint.py, fix-markdownlint.sh, test-annotations.sh)
  - Enhance scripts/validate-mcp-schema.py with improved type checking

- Update pyproject.toml configuration

- Clean up .cursor/commands/issues.md (no longer needed)

- Fix code quality issues:
  - Fix ruff UP038: Use X | Y instead of (X, Y) in isinstance
  - Add missing type annotations for mypy compliance
  - Fix unreachable code warnings

* Add .cursor/ to .gitignore and remove from tracking

* fix: Add pytest-asyncio dependency to fix async test failures

- Add pytest-asyncio>=0.21.0,<1.0.0 to test dependencies
- Configure asyncio_mode = 'auto' in pytest settings
- Fixes 10 failing async tests in test_mcp_server_coverage.py

* fix: Fix all broken code blocks and formatting issues in markdown files

- Fix unclosed code blocks in docs/CONTRIBUTING.md
- Fix broken code blocks in docs/wiki/12-Troubleshooting.md
- Fix broken code blocks in docs/wiki/13-Contributing.md
- Fix broken code blocks in docs/wiki/06-Configuration.md
- Fix broken code blocks in docs/wiki/11-Observability-Audit.md
- Wrap JSON examples in proper code blocks with json language specifier
- Fix code block language specifiers
- Ensure all code blocks are properly closed

Addresses PR review feedback from CodeBotD
2025-11-20 23:24:07 -05:00
..

Scripts Directory

This directory contains utility scripts for development, testing, and validation.

Essential Scripts (Keep)

validate-mcp-schema.py

Purpose: Validates MCP tool definitions against MCP schema 2025-06-18.

Usage:

python scripts/validate-mcp-schema.py

Status: ✅ Active - Used in pre-commit hooks and CI/CD


validate-config.py

Purpose: Validates YAML configuration files (servers.yml, credentials.yml, policy.yml).

Usage:

python scripts/validate-config.py [config_dir]

Status: ✅ Active - Used in pre-commit hooks (optional)


setup-pre-commit.sh

Purpose: Sets up pre-commit hooks for developers.

Usage:

./scripts/setup-pre-commit.sh

Status: ✅ Active - Referenced in CONTRIBUTING.md


docker-build.sh

Purpose: Helper script for building Docker images locally.

Usage:

./scripts/docker-build.sh
# Or with custom image name:
IMAGE_NAME=my-image:tag ./scripts/docker-build.sh

Status: ✅ Active - Referenced in documentation


docker-smoketest.sh

Purpose: Smoke test Docker image with MCP Inspector.

Usage:

./scripts/docker-smoketest.sh

Status: ✅ Active - Referenced in documentation and CHANGELOG


test-mcp-inspector-errors.sh

Purpose: Tests error handling scenarios with MCP Inspector.

Usage:

./scripts/test-mcp-inspector-errors.sh

Status: ✅ Active - Useful for manual testing of error paths


test-mcp-automated.py

Purpose: Automated programmatic testing of all MCP tools without requiring interactive MCP Inspector.

Usage:

# Test with default Docker image
python3 scripts/test-mcp-automated.py

# Test with custom Docker image
python3 scripts/test-mcp-automated.py --docker-image mcp-ssh-orchestrator:dev

# Test with custom config directory
python3 scripts/test-mcp-automated.py --config-dir /path/to/config

Status: ✅ Active - Automated CI/CD testing, validates all 13 tools programmatically


Notes

  • Markdownlint fixes: Handled automatically by pre-commit hooks (no manual scripts needed)
  • Docker annotations: Validated and implemented in .github/workflows/release.yml