CopperSunDev/brasscoders

# BrassCoders — 捕捉你的AI编码助手遗漏的虫子 BrassCoders扫描代码库并生成一组结构化智能文件（`.brass/*.yaml`），这些文件旨在由Claude Code、Cursor或其他AI编码助手读取。目标是揭示重要内容——真实的安全风险、PII泄露、性能陷阱——并隐藏不重要内容，以便AI的审查不会在低置信度噪声中淹没有用的信号。 BrassCoders是一个单次CLI：它扫描、写入YAML并退出。没有后台守护进程，默认情况下没有遥测，除非你选择加入，否则没有出站网络调用。 ## 它生成的内容 在执行`brasscoders scan`之后，你将在`.brass/`目录中找到以下文件： | 文件 | 目的 | |---|---| | `ai_instructions.yaml` | AI应首先阅读的顶层摘要 | | `detailed_analysis.yaml` | 每个发现，按类型分组 | | `file_intelligence.yaml` | 按文件汇总的发现，按优先级排序 | | `security_report.yaml` | 仅安全视图（机密信息、注入、认证问题） | | `statistics.yaml` | 聚合计数和严重程度分布 | | `privacy_analysis.yaml` | 仅隐私视图（仅当存在PII发现时） | 输出目录权限为`0700`；单个文件权限为`0600`。BrassCoders扫描私有源代码，因此这被强制执行而不是选择加入。 ## 它检测的内容 | 类别 | 来源 | |---|---| | 机密信息（AWS、Azure、GitHub、GitLab、Slack、Stripe、NPM、PEM、JWT、……） | [`detect-secrets`](https://github.com/Yelp/detect-secrets) | | 代码质量问题（复杂性、死代码、常见错误） | Bandit + Pylint + Radon + AST模式 | | PII（信用卡、SSN、IBAN、NHS、NINO、Aadhaar、PAN、NRIC、Medicare、TFN） | 模式 + Luhn-验证的正则表达式 | | AI编码反模式（循环中的字符串连接、插入零、嵌套循环、输入上的eval） | BrassCoders特定的AST分析 | | 认证反模式（硬编码的机密信息、弱JWT、无速率限制） | BrassCoders特定的正则表达式 | 在发现写入磁盘之前，会进行去重和噪声过滤。 ## 支持的语言 BrassCoders以**Python**为首选。驱动最深分析的扫描器——Pysa（过程间污点）、Bandit、Pylint和BrassCoders特定的AI编码反模式检测器——仅适用于Python。 | 语言 | 覆盖率 | 备注 | |---|---|---| | Python | 全部 | 过程间污点、安全、质量、反模式 | | JavaScript / TypeScript | 模式级别 | 内过程间Semgrep OSS规则；无过程间污点 | | 其他 | 尽力而为 | 在适用的情况下检测机密信息和通用模式 | 对于需要深度污点分析的JS密集型应用程序，应将BrassCoders与JS特定的SAST（CodeQL等）配合使用。BrassCoders团队正在跟踪JS污点质量，这是一个已知的预发布限制。 ## 安装 ``` # Recommended — CLI tool, isolated env. pipx install brasscoders # Or with pip. pip install brasscoders # Verify: brasscoders --help ``` BrassCoders需要Python 3.10+，并拉取`PyYAML`、`requests`、`bandit`、`pylint`、`radon`、`vulture`、`detect-secrets`和`pyre-check`作为运行时依赖项。`requests`库仅在您明确选择加入网络检查时使用（请参阅下面的`--check-package-hallucination`）。`pyre-check`被固定在一个狭窄的版本窗口（`>=0.9.25,<0.10`），因为Pysa模型文件格式在次要版本之间不稳定；升级需要通过捆绑模型行进行验证通过。 Python 3.10是最低要求，因为推荐的Semgrep版本（1.143.0+，用于多核并行处理——请参阅以下内容）在PyPI上对Python 3.9不可用。 **可选**：安装Semgrep以进行额外的基于模式的污点检测。 BrassCoders建议版本1.143.0或更高版本，这启用了多核并行处理，使大型存储库的扫描速度提高约3倍： ``` pip install 'semgrep>=1.143.0' ``` ## 支持的平台 | OS | 状态 | 备注 | |---|---|---| | macOS（Apple Silicon + Intel） | ✅ 支持 | 本地化；主要开发目标 | | Linux x86_64 | ✅ 支持 | 主要CI目标 | | Linux arm64 | ⚠️ 部分支持 | 除了Pysa以外的每个扫描器都本地化工作。`pyre-check`仅提供为linux/amd64构建的`pyre.bin`——Pysa在arm64 Linux上跳过并显示清晰的“typeshed未找到”状态。 | | Windows原生 | ❌ 不支持 | 使用WSL2 | | 通过WSL2的Windows | ✅ 支持 | 作为Linux处理 | **为什么Windows原生不受支持：** - 过程间污点扫描器（Pysa）建立在Meta的Pyre之上，它没有Windows支持。 - `fcntl.flock`缓存并发保护是Unix-only——BrassCoders在Windows上警告并继续解锁。 - `ProcessPoolExecutor`批处理Bandit/Pylint扫描已在`fork`（Linux/macOS）上验证；Windows `spawn`语义未测试。 将Windows原生提升到支持状态需要几周到几个月的工作（替换或沙盒Pyre/Pysa；添加Windows `flock`替代方案；安全的ProcessPool重写）。不在v1路线图上。 对于Apple Silicon上的Docker用户：使用`--platform linux/amd64`固定，以便Pyre的捆绑二进制文件在Rosetta仿真下运行。请参阅[`docs/CI.md`](docs/CI.md)中的配方。 ## 使用方法 ``` # One-shot scan of the current directory. brasscoders --offline scan # Watch mode: re-run incrementally on file changes. brasscoders --offline watch # Show last analysis summary. brasscoders status # Print version and which components are available. brasscoders version ``` ### 第一次扫描注意：Pysa的typeshed引导 过程间污点扫描器（Pysa）需要Python的[typeshed](https://github.com/python/typeshed)存根来解决stdlib调用。BrassCoders没有捆绑typeshed（约33 MB）并且默认离线，因此在新安装时，Pysa会跳过并显示清晰的“typeshed未找到”状态，直到您引导它。最简单的方法是单次自动获取标志： ``` # First scan only — let brass git-clone python/typeshed on demand. BRASS_AUTOFETCH_TYPESHED=1 brasscoders --offline scan ``` 这会在第一次运行时进行一次出站`git clone`调用到GitHub（没有其他网络使用；其余的`--offline`语义仍然有效）。后续扫描将重用缓存的typeshed在`~/.cache/brass/typeshed/`中，无需网络访问。 如果您的环境在扫描期间无法访问GitHub，请将typeshed一次克隆到缓存位置： ``` git clone --depth 1 https://github.com/python/typeshed ~/.cache/brass/typeshed ``` 请参阅[`docs/CACHE.md`](docs/CACHE.md)以了解完整的typeshed-cache生命周期。 ### 网络策略 BrassCoders默认**离线**。唯一的出站网络表面是包幻觉检查，该检查验证导入的包名称与PyPI / npm / pkg.go.dev相匹配。此检查默认禁用，除非您传递`--check-package-hallucination`。传递`--offline`以确保没有任何内容离开您的机器——它覆盖了选择加入标志。 ``` # Hard offline mode — nothing leaves your machine. brasscoders --offline scan # Opt in to the hallucination check (sends imported package names to public # registries; do not use on closed-source code with private imports). brasscoders scan --check-package-hallucination ``` ### 扫描模式 ``` brasscoders scan --fast # Quick: code analysis only, no privacy/content brasscoders scan --dev # Source-only: skip tests/build artifacts brasscoders scan --code # Just bugs / security / quality brasscoders scan --privacy # Just PII detection brasscoders scan --content # Just content moderation ``` ## 性能和缓存 BrassCoders在`~/.cache/brass/pysa-state/`中缓存Pysa的调用图状态，因此重复扫描比冷启动快3-4倍。该缓存是按项目划分的，在配置漂移时自动失效，并且可以在任何时候安全删除。请参阅[`docs/CACHE.md`](docs/CACHE.md)以了解完整的生命周期（位置、大小配置文件、失效触发器、`BRASS_PYSA_CACHE_ROOT`环境变量、typeshed缓存）。 在CI中运行BrassCoders？请参阅[`docs/CI.md`](docs/CI.md)以获取GitHub Actions、GitLab CI和CircleCI的缓存挂载配方——如果没有缓存挂载，每次CI运行都要支付完整的冷启动成本。 ## 隐私与数据处理 - BrassCoders永远不会将您的源代码发送到任何地方。唯一的出站调用是上面描述的可选包幻觉注册表检查。 - 隐私扫描器检测PII并将发现写入磁盘*但已将匹配的值删除*。原始匹配文本在序列化之前被替换为掩码形式；原始上下文行被完全删除。 - 机密扫描器记录机密*类型*和用于去重的简短哈希。原始机密值永远不会持久化。 - 请参阅[`docs/PRIVACY_POLICY.md`](docs/PRIVACY_POLICY.md)以了解完整的披露。 ## 架构 ``` CLI ──► Scanners ──► IntelligenceRanker ──► YAMLOutputGeneratorV2 ──► .brass/*.yaml ``` 每个扫描器都是单功能的，并返回`List[Finding]`。排名器权衡并排序。输出生成器写入原子、所有者专有的YAML。 没有后台进程，没有调度程序，也没有扫描器之间的通信。 `src/brass/models/finding.py`中的`Finding`数据类是系统的单一合同；所有构建器、扫描器和排名器都依赖于它，但不依赖于彼此。 ## 许可证 Apache 2.0。请参阅[LICENSE](LICENSE)和[NOTICE](NOTICE).

标签：AI编码助手, AI辅助开发, Apache 2.0许可证, JWT检测, Luhn算法, PII检测, YAML文件, 代码复杂度分析, 代码模式识别, 代码质量工具, 安全漏洞检测, 安全风险识别, 常见错误检测, 性能分析, 文档结构分析, 模式匹配, 正则表达式检测, 死代码检测, 源代码扫描, 源代码权限管理, 源代码隐私保护, 网络安全, 自动化资产收集, 认证问题检测, 逆向工具, 速率限制检测, 隐私保护