内容
# CodeWard
[](https://github.com/IvoryCanvas/codeward/actions/workflows/ci.yml)
**AI 编程代理和他们所改变的代码的防护栏.**
CodeWard 检查代码仓库中使 AI 辅助开发变得危险的因素：缺少的代理指令、危险的 MCP 配置、提交的本地环境文件、危险的自动化脚本、过度的流程权限和薄弱的验证信号。
Codex、Claude Code、Cursor、GitHub Copilot 编程代理或基于 MCP 的工具的团队可以使用 CodeWard，在代理编辑代码仓库或审查 PR 之前进行轻量级的安全检查。
<details>
<summary>English translation</summary>
**Guardrails for AI coding agents and the code they change.**
CodeWard scans a repository for the things that make AI-assisted development risky: missing agent instructions, unsafe MCP configuration, leaked local env files, dangerous automation scripts, broad workflow permissions, and weak validation signals.
It is designed for teams that use Codex, Claude Code, Cursor, GitHub Copilot coding agent, or MCP-powered tools and want a lightweight safety check before an agent edits the repo or a PR gets reviewed.
</details>
## 为什么创建 CodeWard
AI 编程代理速度快，但也容易被过度信任。最尴尬的失败模式不是明显损坏的代码，而是几乎正确但在缺乏上下文和防护栏的情况下合并的代码。
CodeWard 为维护者提供了一个简单的第一道防线：
- 查找危险的代理/MCP 设置
- 检测缺失或冲突的项目指令
- 标记过度的 CI 权限和危险的脚本
- 生成干净的 `AGENTS.md` 启动点
- 为拉取请求生成 Markdown 报告
## 安装
```sh
pnpm add -D @ivorycanvas/codeward
```
无需安装即可运行：
```sh
pnpm dlx @ivorycanvas/codeward scan .
```
<details>
<summary>npm / Yarn</summary>
```sh
npm install -D @ivorycanvas/codeward
npx @ivorycanvas/codeward scan .
```
```sh
yarn add -D @ivorycanvas/codeward
yarn dlx @ivorycanvas/codeward scan .
```
</details>
## 用法
扫描当前代码仓库：
```sh
codeward scan .
```
当存在中级或以上的发现时，失败 CI：
```sh
codeward scan . --fail-on medium
```
生成 Markdown 报告：
```sh
codeward report . --output CODEWARD_REPORT.md
```
生成代理指令：
```sh
codeward context . --write AGENTS.md
```
以 JSON 格式输出用于自定义自动化：
```sh
codeward scan . --json
```
以 SARIF 格式输出：
```sh
codeward scan . --format sarif --output codeward.sarif
```
创建配置文件：
```sh
codeward init .
```
## 当前检查的内容
CodeWard 的第一个版本专注于许多代码仓库中有用的高信号检查：
| 规则 | 捕获的内容 |
| --- | --- |
| `CW001` | 缺失的代理指令文件 |
| `CW002` | 冲突的代理指导 |
| `CW003` | 可疑的指令文本，可能误导代理 |
| `CW004` | 危险的 MCP 命令配置 |
| `CW005` | MCP 配置中嵌入的类似秘密的值 |
| `CW006` | 缺失或占位符测试脚本 |
| `CW007` | 缺失的 GitHub Actions 工作流程 |
| `CW008` | 提交的本地环境文件 |
| `CW009` | 可以发布、推送、合并或运行不安全 shell 管道的包脚本 |
| `CW010` | 过度的流程权限 |
| `CW011` | 缺失的社区健康文件 |
## 配置
使用 `codeward.config.json` 或 `.codeward.json` 调整代码仓库策略：
```json
{
"$schema": "https://raw.githubusercontent.com/IvoryCanvas/codeward/main/schema/codeward.schema.json",
"failOn": "high",
"ignoreRules": ["CW011"],
"maxFiles": 2000,
"severity": {
"CW007": "info"
}
}
```
详见 [docs/configuration.md](docs/configuration.md)。
## GitHub Actions
```yaml
name: CodeWard
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: pnpm/action-setup@v6
with:
version: 10.32.1
- uses: actions/setup-node@v6
with:
node-version: 24
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm dlx @ivorycanvas/codeward scan . --fail-on high
```
## 哲学
CodeWard 不是代码审查、测试、威胁建模或分支保护的替代品。它是一个小型、尖锐的检查，帮助团队尽早发现代码仓库级别的 AI 风险。
## 项目状态
CodeWard 还处于早期阶段。在 `1.0` 版本之前，公共 API 可能会发生变化，但该项目的目标是从第一个版本开始就保持小巧、易读并在实际代码仓库中实用。
## 贡献
欢迎提出问题和拉取请求。维护者权限仅限于 IvoryCanvas 成员，`main` 分支受到保护，外部贡献者无法直接推送或合并。
参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[GOVERNANCE.md](GOVERNANCE.md) 和 [SECURITY.md](SECURITY.md)。
<details>
<summary>Full English README</summary>
## Why CodeWard Exists
AI coding agents are fast, but they are also easy to over-trust. The awkward failure mode is not obviously broken code; it is code that is almost right, merged through a workflow that had too little context and too few guardrails.
CodeWard gives maintainers a simple first line of defense:
- find risky agent and MCP setup
- detect missing project instructions
- flag broad CI permissions and unsafe scripts
- generate a clean `AGENTS.md` starter
- produce a Markdown report for pull requests
## Install
```sh
pnpm add -D @ivorycanvas/codeward
```
Run it without installing:
```sh
pnpm dlx @ivorycanvas/codeward scan .
```
## Usage
Scan the current repository:
```sh
codeward scan .
```
Fail CI when medium-or-higher findings are present:
```sh
codeward scan . --fail-on medium
```
Generate a Markdown report:
```sh
codeward report . --output CODEWARD_REPORT.md
```
Generate agent instructions:
```sh
codeward context . --write AGENTS.md
```
Print JSON for custom automation:
```sh
codeward scan . --json
```
Print SARIF for code scanning integrations:
```sh
codeward scan . --format sarif --output codeward.sarif
```
Create a config file:
```sh
codeward init .
```
## What It Checks Today
CodeWard's first release focuses on high-signal checks that are useful across many repositories:
| Rule | What it catches |
| --- | --- |
| `CW001` | Missing agent instruction files |
| `CW002` | Conflicting agent guidance |
| `CW003` | Suspicious instruction text that can misdirect agents |
| `CW004` | Risky MCP command configuration |
| `CW005` | Secret-like values embedded in MCP config |
| `CW006` | Missing or placeholder test scripts |
| `CW007` | Missing GitHub Actions workflows |
| `CW008` | Committed local environment files |
| `CW009` | Package scripts that can publish, push, merge, or run unsafe shell pipelines |
| `CW010` | Broad workflow permissions |
| `CW011` | Missing community health files |
## Configuration
Use `codeward.config.json` or `.codeward.json` to tune repository policy.
```json
{
"$schema": "https://raw.githubusercontent.com/IvoryCanvas/codeward/main/schema/codeward.schema.json",
"failOn": "high",
"ignoreRules": ["CW011"],
"maxFiles": 2000,
"severity": {
"CW007": "info"
}
}
```
See [docs/configuration.md](docs/configuration.md) for details.
## GitHub Actions
```yaml
name: CodeWard
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: pnpm/action-setup@v6
with:
version: 10.32.1
- uses: actions/setup-node@v6
with:
node-version: 24
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm dlx @ivorycanvas/codeward scan . --fail-on high
```
## Philosophy
CodeWard is not a replacement for code review, tests, threat modeling, or branch protection. It is a small, sharp check that helps teams notice repo-level AI risks early enough to do something about them.
## Project Status
CodeWard is early. The public API may change before `1.0`, but the project is intended to stay small, readable, and useful in real repositories from the first release.
## Contributing
Issues and pull requests are welcome. Maintainer permissions stay with IvoryCanvas members, and `main` is protected so external contributors cannot push or merge directly.
See [CONTRIBUTING.md](CONTRIBUTING.md), [GOVERNANCE.md](GOVERNANCE.md), and [SECURITY.md](SECURITY.md).
</details>
连接信息
猜你喜欢
暂无推荐服务器