dannystocker/mcp-multiagent-bridge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Add governance files for OSS release

Browse source 
- Add MIT LICENSE
- Add SECURITY.md with responsible disclosure policy
  * Vulnerability reporting guidelines
  * YOLO mode security considerations
  * Agentic AI threat model
  * Anthropic & OpenAI policy compliance
  * Security roadmap
- Add CONTRIBUTING.md with guidelines
  * Bug reporting template
  * Feature request process
  * PR workflow and commit format
  * Development setup instructions
- Update README.md with policy compliance
  * Beta software warning
  * YOLO mode safety notice
  * Anthropic Acceptable Use Policy
  * Anthropic Responsible Scaling Policy
  * Updated security features list
- Pin dependencies to specific versions
  * mcp>=1.0.0,<2.0.0

Ready for public GitHub release.
This commit is contained in:
ggq-admin 2025-10-27 00:50:33 +01:00
parent 4c75bf5713
commit e5003e9653
5 changed files with 365 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

116
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,116 @@
# Contributing to Claude Code Bridge
## Welcome!
Thanks for your interest in contributing! This project aims to make multi-agent
coordination with Claude Code secure and practical.
## How to Contribute
### Reporting Bugs
Open a GitHub issue with:
- Description of the bug
- Steps to reproduce
- Expected vs actual behavior
- Environment (OS, Python version, MCP version)
### Suggesting Features
Open a GitHub issue with:
- Use case description
- Proposed solution
- Alternative approaches considered
- Potential security implications
### Pull Requests
1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes**
4. **Add tests** for new functionality
5. **Run the test suite**: `python test_bridge.py && python test_security.py`
6. **Lint your code**: `ruff check . --fix` (if available)
7. **Commit with descriptive message**: `git commit -m 'feat: Add amazing feature'`
8. **Push to your fork**: `git push origin feature/amazing-feature`
9. **Open a Pull Request**
### Commit Message Format
```
<type>: <subject>
<body>
<footer>
```
**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `test`: Test additions/changes
- `refactor`: Code refactoring
- `chore`: Maintenance tasks
- `security`: Security improvements
**Example:**
```
feat: Add rate limiting per session
Implement token bucket rate limiter to prevent abuse.
Configurable limits: 10 req/min, 100 req/hour.
Closes #15
```
## Development Setup
```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/claude-code-bridge.git
cd claude-code-bridge
# Install dependencies
pip install -r requirements.txt
# Run tests
python test_bridge.py
python test_security.py
# Run with MCP debug mode
claude-code --mcp-debug
```
## Code Style
- Follow PEP 8
- Use type hints
- Add docstrings to public methods
- Keep functions under 50 lines when possible
- Write self-documenting code
## Testing
- Add tests for all new features
- Maintain test coverage above 80%
- Include both positive and negative test cases
- Test security-critical paths thoroughly
## Security Considerations
When contributing:
- Never commit secrets or tokens
- Be extra cautious with YOLO mode changes
- Consider security implications of all changes
- Add security tests for authentication/authorization changes
- Update SECURITY.md if threat model changes
## Questions?
Open a GitHub discussion or issue. We're here to help!
## License
By contributing, you agree that your contributions will be licensed under
the same MIT License that covers this project.

21
LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 Danny Stocker
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

21
README.md
View file

@ -2,6 +2,25 @@
Production-lean MCP server enabling two Claude Code CLI sessions to communicate securely. Production-lean MCP server enabling two Claude Code CLI sessions to communicate securely.
> ⚠️ **Beta Software**: Suitable for development/testing. See [Security Policy](SECURITY.md) before production use.
## ⚠️ YOLO Mode Warning
This project includes an optional YOLO mode for command execution. This is inherently dangerous and should only be used:
- In isolated development environments
- With explicit user confirmation
- By users who understand the risks
See [YOLO_MODE.md](YOLO_MODE.md) and [SECURITY.md](SECURITY.md) for details.
## Policy Compliance
This project complies with:
- [Anthropic Acceptable Use Policy](https://www.anthropic.com/legal/aup)
- [Anthropic Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
Users are responsible for ensuring appropriate use and maintaining human oversight of all operations.
## Security Features ✅ ## Security Features ✅
- **HMAC Authentication**: Session tokens prevent spoofing - **HMAC Authentication**: Session tokens prevent spoofing
@ -11,6 +30,8 @@ Production-lean MCP server enabling two Claude Code CLI sessions to communicate
- **Token Expiration**: Conversations expire after 3 hours - **Token Expiration**: Conversations expire after 3 hours
- **Schema Validation**: Strict JSON schemas for all tools - **Schema Validation**: Strict JSON schemas for all tools
- **No Auto-Execution**: Bridge returns proposals only - no command execution - **No Auto-Execution**: Bridge returns proposals only - no command execution
- **YOLO Guard**: Multi-stage confirmation for command execution (when enabled)
- **Rate Limiting**: 10 req/min, 100 req/hour, 500 req/day per session
## Installation ## Installation

200
SECURITY.md Normal file
View file

@ -0,0 +1,200 @@
# Security Policy
## Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 1.0.x | :white_check_mark: |
## Reporting a Vulnerability
**DO NOT** open a public GitHub issue for security vulnerabilities.
Instead, please report security issues responsibly:
- Create a private security advisory on GitHub
- Or email: [your-email]@[domain].com (replace with actual email)
- Subject: "SECURITY: Claude Code Bridge - [brief description]"
Please include:
1. Description of the vulnerability
2. Steps to reproduce
3. Potential impact
4. Suggested fix (if any)
You will receive a response within 48 hours.
---
## Security Considerations
### ⚠️ YOLO Mode
YOLO mode enables command execution. This is inherently dangerous and should only be used:
- In isolated development environments
- With explicit user confirmation
- With audit logging enabled
- By users who understand the risks
**Never enable YOLO mode:**
- On production systems
- With untrusted agents
- On shared machines
- Without proper backups
**Safety Features:**
1. Environment variable gate (`YOLO_MODE=1` required)
2. Double confirmation (typed phrase + one-time code)
3. Dry-run default (no actual execution without approval token)
4. Command validation (blocks dangerous patterns)
5. Audit logging (all actions logged with timestamps)
6. Timeout limits (commands killed after 30s by default)
7. Workspace restriction (commands run in specified directory)
### Token Security
Session tokens are cryptographically secure (64-char hex) but:
- Stored in plain text in SQLite
- Visible in MCP debug logs
- Not encrypted at rest
- Expire after 3 hours
For production use, consider:
- Encrypting database at rest
- Using environment-specific key management
- Shorter token lifetimes for sensitive operations
### Known Limitations
1. **No encryption in transit**: Messages stored as plain text in SQLite
2. **No user authentication**: Anyone with file access can read database
3. **Rate limiting**: Implemented but test in your environment
4. **Command execution risks**: YOLO mode can modify system
5. **Audit logs not tamper-proof**: SQLite database can be modified
---
## Threat Model
### In Scope:
- Local multi-agent coordination
- Development/testing environments
- Isolated workspaces
- Human-supervised operations
### Out of Scope:
- Production deployments without additional safeguards
- Multi-tenant systems
- Public-facing APIs
- Unattended automation
---
## Agentic AI Considerations
### Command Execution Risks
YOLO mode enables agentic behavior (AI taking actions in the real world).
This carries significant risks:
**Threat Model:**
- Malicious commands injected by adversarial prompts
- Unintended destructive operations from AI errors
- Privilege escalation attempts
- Data exfiltration
- Credential theft
**Mitigations:**
- Command validation (whitelist + blacklist)
- Execution timeout (30s default)
- Workspace restriction
- Audit logging
- Multi-step approval process
- Environment-specific gating
**Recommended Controls:**
- Run in Docker container with no network access
- Use read-only filesystem where possible
- Drop all unnecessary capabilities
- Monitor audit logs continuously
- Set up alerts for suspicious patterns
- Maintain offline backups
### Compliance with AI Provider Policies
**Anthropic Claude:**
- Comply with [Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
- Maintain human oversight
- Document intended use
- Implement operational safeguards
**OpenAI:**
- Comply with [Usage Policies](https://openai.com/policies/usage-policies)
- No unauthorized system access
- No malware development
- Human-in-the-loop for high-risk actions
**Your Responsibility:**
- Ensure compliance with provider terms
- Supervise all agent operations
- Report security issues responsibly
- Maintain appropriate logging
### Acceptable Use
**Allowed:**
- Development and testing workflows
- Automated code quality checks
- Safe file operations (within workspace)
- Git operations (with confirmation)
- Package management (npm/pip install)
**Not Allowed:**
- Production deployments without safeguards
- Unattended operation on critical systems
- Privilege escalation attempts
- Network attacks or exploitation
- Data theft or unauthorized access
- Malware development or deployment
---
## Security Roadmap
Future security enhancements:
- [ ] Message encryption at rest
- [ ] Rate limiting per session (implemented, needs hardening)
- [ ] Command execution sandboxing (Docker)
- [ ] Tamper-evident audit logs
- [ ] TLS for network transport
- [ ] OAuth/OIDC authentication
- [ ] Role-based access control
---
## Security Best Practices
When using this bridge:
1. **Isolate**: Run in dedicated VM or container
2. **Monitor**: Review audit logs regularly
3. **Limit**: Use restrictive YOLO modes
4. **Backup**: Maintain offline backups
5. **Update**: Keep dependencies current
6. **Test**: Validate before production use
7. **Document**: Record configuration decisions
---
## Contact
For security concerns:
- GitHub Security Advisories (preferred)
- Email: [Add your email here]
For general questions:
- GitHub Issues
- GitHub Discussions
---
**Last Updated:** 2025-10-27

17
requirements.txt
View file

@ -1,9 +1,10 @@
# Claude Code Multi-Agent Bridge Requirements # Claude Code Bridge Requirements
# Production dependencies
# Core MCP SDK for Model Context Protocol # MCP Server (pinned to specific version for stability)
mcp>=1.0.0 mcp>=1.0.0,<2.0.0
# Standard library dependencies (included with Python) # Python standard library (no installation needed):
# - asyncio # - asyncio
# - json # - json
# - hmac # - hmac
@ -14,9 +15,5 @@ mcp>=1.0.0
# - subprocess # - subprocess
# - datetime # - datetime
# - pathlib # - pathlib
# - typing
# Optional: For enhanced features # - collections
# redis>=4.0.0 # If using Redis instead of SQLite
# Installation:
# pip install -r requirements.txt