| 1 | # Security Policy |
| 2 | |
| 3 | codewhale is a coding agent with direct access to file operations, shell execution, and the network. Security disclosures are taken seriously. |
| 4 | |
| 5 | ## Supported Versions |
| 6 | |
| 7 | Only the latest stable release receives security patches. No backports to older versions. |
| 8 | |
| 9 | | Version | Supported | |
| 10 | |---|---| |
| 11 | | latest stable | :white_check_mark: | |
| 12 | | < latest | :x: | |
| 13 | |
| 14 | Check the [releases page](https://github.com/Hmbown/CodeWhale/releases) for the current version. |
| 15 | |
| 16 | ## Reporting a Vulnerability |
| 17 | |
| 18 | **Do not open a public GitHub issue for security vulnerabilities.** |
| 19 | |
| 20 | Report privately via one of: |
| 21 | |
| 22 | - **GitHub private advisory**: [github.com/Hmbown/CodeWhale/security/advisories/new](https://github.com/Hmbown/CodeWhale/security/advisories/new) |
| 23 | - **Email**: [hmbown@gmail.com](mailto:hmbown@gmail.com) — include `[SECURITY]` in the subject line |
| 24 | |
| 25 | Include in your report: |
| 26 | |
| 27 | - A description of the vulnerability and the impact if exploited |
| 28 | - Steps to reproduce or a proof of concept |
| 29 | - Affected versions and configuration details |
| 30 | - Any suggested mitigation (optional) |
| 31 | |
| 32 | ## Response Timeline |
| 33 | |
| 34 | | Phase | Target | |
| 35 | |---|---| |
| 36 | | Acknowledgment | Within 48 hours of receipt | |
| 37 | | Assessment | Within 5 days — triage severity, scope, and fix approach | |
| 38 | | Patch (critical) | Within 14 days from assessment | |
| 39 | | Patch (moderate/low) | Next feature release or per-maintainer timeline | |
| 40 | | Disclosure | After patch is shipped and users have had time to update | |
| 41 | |
| 42 | You will receive status updates at each phase. If the timeline slips, we will communicate the reason and the revised estimate. |
| 43 | |
| 44 | ## Scope |
| 45 | |
| 46 | ### In scope (what counts) |
| 47 | |
| 48 | - Remote code execution through crafted prompts or model responses |
| 49 | - Sandbox escape — breaking out of an active Seatbelt/bubblewrap wrapper or a declared workspace boundary |
| 50 | - Credential leak — exfiltration of API keys, tokens, or environment secrets |
| 51 | - Arbitrary file read/write outside the intended workspace (`PathEscape` bypass) |
| 52 | - SSRF via `fetch_url` or `web_search` against internal network endpoints |
| 53 | - Unauthorised MCP server access or tool invocation |
| 54 | |
| 55 | ### Out of scope |
| 56 | |
| 57 | - Social engineering of the maintainer or contributors |
| 58 | - Denial of service / rate-limit exhaustion against the DeepSeek API |
| 59 | - Vulnerabilities in third-party dependencies (report to the upstream project) |
| 60 | - Attacks requiring physical access to the victim's machine |
| 61 | - Theoretical ML-model injection attacks not demonstrated in the codewhale context |
| 62 | |
| 63 | If you are unsure whether a bug is in scope, report it anyway. We will triage and respond. |
| 64 | |
| 65 | |
| 66 | ## WeCom Bridge Security |
| 67 | |
| 68 | The WeCom Bridge (`integrations/wecom-bridge/`) extends Codewhale to WeCom |
| 69 | (企业微信) Smart Bot WebSocket sessions. It inherits all standard Codewhale |
| 70 | security boundaries and adds bridge-specific controls. |
| 71 | |
| 72 | ### Bridge-specific protections |
| 73 | |
| 74 | - **No public port**: The bridge communicates with `codewhale serve --http` on `127.0.0.1` only |
| 75 | - **Token gate**: All runtime API calls carry `CODEWHALE_RUNTIME_TOKEN` |
| 76 | - **Chat allowlist**: Only chats/users listed in `WECOM_CHAT_ALLOWLIST` can interact. First-pairing mode (`WECOM_ALLOW_UNLISTED=true`) is meant for onboarding only |
| 77 | - **Approval required**: Tool calls from WeCom sessions must be approved — either via explicit `/allow <id>` commands or natural-language keywords (`允许`, `yes`, `ok`, etc.) |
| 78 | - **No workspace exposure**: Only prompts, status summaries, and approval requests are sent to WeCom. Workspace contents, shell output, and runtime internals stay on the local machine |
| 79 | |
| 80 | ### Reporting WeCom Bridge vulnerabilities |
| 81 | |
| 82 | Report bridge-specific security issues through the same channels listed above. |
| 83 | Include the bridge version (check `package.json`) and your WeCom deployment configuration |
| 84 | (sensitive values redacted). Bridge logs may be requested for reproduction. |
| 85 | |
| 86 | ### Bridge environment safety |
| 87 | |
| 88 | - `WECOM_BOT_SECRET` and `CODEWHALE_RUNTIME_TOKEN` must never be committed to git |
| 89 | - The `.env` file is gitignored; use `.env.example` as the template |
| 90 | - Rotate secrets periodically, especially after sharing screen captures |
| 91 | - Use `CODEWHALE_APPROVAL_TIMEOUT_MS` (default 5 min) to limit the approval window |
| 92 | |
| 93 | ## Hall of Fame |
| 94 | |
| 95 | We maintain a hall of fame for reporters who submit verified security vulnerabilities. To be credited, include your preferred name / handle in the report. |
| 96 | |
| 97 | *No entries yet — be the first.* |
| 98 |