BugX — AI Code Audit Agent and Vulnerability Scanner for AI-Written Code
BugX is an autonomous code-audit agent that runs inside your AI coding assistant or on the command line. It audits AI-written code end to end: it builds a coverage list of your project, dispatches concurrent audit workers, verifies every candidate finding with real executions, and produces a report where each finding ships with a command you can run yourself to reproduce it.
If you use Claude Code, Codex, Cline, OpenCode, or ZCode to write production code, BugX is the Python-powered security audit and code review engine behind them — it checks what the model actually delivered, not what it claims to have delivered.
🌐 Website · 官网:https://bugx.dev · GitHub:https://github.com/Bencibr/bugx
English Documentation
Why AI-written code needs an audit
AI writes code faster than any human can review it, and the model carries a training-level bias toward sounding done rather than being done:
- The grader rewards confidence. Human raters score "I checked it carefully, nothing found" higher than "I haven't finished reading the files." The model learns to report good news.
- Checking is expensive; claiming is cheap. Reading hundreds of files takes real work. Replying "no issues found" takes a few words.
- It doesn't know what it hasn't checked. The model cannot see its own coverage gaps and will not say "half done."
BugX counters this with a ledger and four hard rules: a per-unit coverage list (checked / blocked / pending), mandatory reproduction (the same attack input must trigger the finding twice and a clean input must trigger nothing), crash-resumable audits, and hash-chained records that keep every verdict reviewable.
What BugX does
- AI code review — bugs and defects classified by logic, state, boundary, exception, concurrency, performance, and resource handling.
- Functionality review — a behavior diff: the same inputs go to your implementation and a reference implementation, and the differences are reported.
- Performance and memory checks — performance and resource defects, plus dedicated memory inspection for native, Python, JVM, Electron, Android, and Apple targets.
- UI audit — layout, contrast, keyboard paths, and design tokens on a running web page (
bugx probe ui). - Reproducible findings — every vulnerability ships with a command or input you can run yourself; all three verification runs (two positive, one negative control) stay on record.
- Mutation-verified tests —
bugx test-verifymutates your code to check whether the tests actually catch the bugs. - Patch bundles —
bugx patch-forgebuilds a patch with static checks and hands it to you for review; it never commits on its own. - Lessons base and unattended runs —
bugx lesson/bugx knowledgeaccumulate project and global experience;bugx autonomousandbugx goalrun end-to-end audits without supervision.
BugX Studio
BugX ships with a built-in web console. Run bugx report serve and open http://127.0.0.1:8080:
Every connected host keeps its own audit sessions (ChatGPT, ZCode, Claude, Codex, DSH, OpenCode, Pi, and more):
The skill marketplace ships with /audit (one-shot full-surface audit with a dual-track report), /review (structured findings for branch changes), /mining (attack-surface survey and hardening), /fix (defensive patches with sandboxed regression), and /test (AAA tests with mutation-kill scoring):
Installation
Requires Python >=3.11.
# Standard install:
python -m pip install bugx-cli
# Or with uv (fast resolver):
uv pip install bugx-cli
# Or as an isolated application:
pipx install bugx-cli
Optional feature extras:
python -m pip install "bugx-cli[tui]" # terminal interactive menu (pexpect)
python -m pip install "bugx-cli[ui]" # web UI audit probes (playwright, Pillow)
python -m pip install "bugx-cli[graph]" # tree-sitter multi-language AST indexing
python -m pip install "bugx-cli[crypto]" # cryptographic telemetry and signing
Wire up your AI hosts once:
bugx install # lists detected hosts (Claude Code, Codex, Cline, OpenCode, ZCode) and registers the BugX MCP servers
bugx doctor --strict # health diagnostics
To install everywhere at once: bugx install --agent all.
Quick start
Option 1 — inside your AI assistant (recommended). Open Claude Code, Codex, Cline, OpenCode, or ZCode in any project and just tell it what to check:
"Audit this project" "Check the login module for vulnerabilities" "Review the changes on this branch for security issues"
The AI inside your host calls BugX on its own: it builds the coverage list, dispatches concurrent workers, runs probes, verifies the findings, and writes the report. To watch an audit live, run bugx report serve and open http://127.0.0.1:8080.
Option 2 — from the terminal. The AI still comes from your installed hosts: BugX reuses the model and credentials you already configured there and never takes over your API keys.
bugx auth login # sign in to the cloud account (lesson and experience sync)
bugx init --cloud-sync sync # enable cloud sync so the project works across devices
bugx engine pre # build the coverage list and audit plan
bugx engine status # follow progress
bugx engine post # settle: cross-check coverage, evidence, and verdicts
bugx autonomous --host opencode # full audit without supervision
bugx goal --host opencode "audit this project's login and payment flows"
bugx report serve # live web console at http://127.0.0.1:8080
bugx report both --format html --out report.html # offline archive
Essential commands
| Command | What it does |
|---|---|
bugx install |
register the BugX MCP servers with detected AI hosts |
bugx hosts |
list every AI environment detected on this machine |
bugx doctor --strict |
health diagnostics for installation and connectivity |
bugx engine pre / status / post |
run and settle a structured audit lifecycle |
bugx autonomous --host <host> |
full unattended audit through your host |
bugx goal --host <host> "<target>" |
audit toward a stated target |
bugx report serve |
live web console (BugX Studio) |
bugx report both --format html |
export the formal + visual report |
bugx probe ui --url <url> |
audit a running web UI |
bugx test-generate |
generate AAA tests or a self-contained PoC |
bugx test-verify |
prove your tests catch real bugs via mutation |
bugx patch-forge |
build a reviewed patch bundle |
bugx lesson / bugx knowledge |
project and global experience base |
bugx daemon |
resident watchdog for unattended audits |
Supported AI coding tools
| AI coding tool | Integration | Install |
|---|---|---|
| Claude Code | native MCP / autonomous lifecycle | bugx install --agent claude |
| OpenAI Codex | workspace subagents / native plugin | bugx install --agent codex |
| OpenCode | headless ACP / native MCP | bugx install --agent opencode |
| Cline / Roo Code | MCP sessions (serial) / CLI process-pool concurrency | bugx install --agent cline |
| ZCode | native MCP / user-level MCP registration | bugx install --agent zcode |
DeepSeek Harness (DSH), WorkBuddy, Cursor / Windsurf, and more are being adapted. Run bugx hosts to list everything detected on this machine.
Security and privacy
- Project state lives in the project's
.bugx/directory; the global engine, credentials, knowledge base, and caches live in a user-level BugX directory. - Credentials are written to a controlled sandbox when needed (readable only by the current user by default).
bugx auth statusreports whether credentials exist — it never prints them. - Cloud uploads, feedback, diagnostic log reporting, and sync are all explicit operations: each states its
--scopebefore it runs. reset/uninstall/purge/--no-backupdelete data. Check each command's dry-run and backup behavior first.
FAQ
What is BugX? An autonomous code-audit agent that lives inside AI coding assistants: it runs via MCP in Claude Code, Codex, Cline, OpenCode, and ZCode, or as a standalone CLI, tracks audit coverage per unit, and verifies every finding with real executions.
Which AI coding tools does BugX support? Claude Code, OpenAI Codex, Cline / Roo Code, OpenCode, and ZCode are supported today; DeepSeek Harness (DSH), WorkBuddy, Cursor / Windsurf, and more are being adapted.
How does BugX verify a vulnerability? The same attack input must reproduce the finding twice, and a clean input must produce nothing. All three runs (two positive, one negative control) are recorded with commands, exit codes, and artifact hashes.
Does BugX send my code to the cloud?
The audit itself runs locally. Cloud sync of lessons and experience is an explicit operation (bugx init --cloud-sync sync / bugx cloud); nothing is uploaded unless you run it.
Does BugX replace human review? No. It gives you a reviewable ledger — what was checked, what wasn't, and reproducible evidence per finding — so human review starts from facts instead of the model's self-report.
What languages does BugX audit? Multi-language static and behavioral analysis (Python, JavaScript/TypeScript, Java, Go, Rust, and more via tree-sitter), plus dedicated memory checks for native, Python, JVM, Electron, Android, and Apple targets.
Keywords
python code audit · ai code audit · ai code review · code review agent · security audit · vulnerability scanner · sast · static analysis · mcp server · mcp security · claude code · openai codex · opencode · cline · zcode · coding agent · llm security · autonomous audit · behavior diff · memory leak detection · devsecops
简体中文说明
什么是 BugX?
BugX 是装进 AI 编程助手的代码审计 Agent。它对 AI 写出的代码做端到端审计:把项目拆成覆盖清单、派发并发审计 Worker、对每条候选漏洞做真实执行验证,最终产出一份报告——每条漏洞都附带一条你可以亲手运行的复现命令。
如果你的生产代码来自 Claude Code、Codex、Cline、OpenCode 或 ZCode,BugX 就是它们背后的 Python 安全审计与代码审查引擎:它核查模型实际交付了什么,而不是模型声称交付了什么。
为什么 AI 代码需要审计
AI 写代码的速度远超人工审查,而且模型带着训练层面的偏差——听起来做完了,比真的做完了更容易:
- 评分机制奖励自信。 人类评分员给「我仔细查过了,没发现问题」的分数高于「文件我还没看完」。模型学会的是报喜。
- 检查贵,声称便宜。 读几百个文件是体力活,回一句「没发现问题」只要几个字。
- 它不知道自己没查完。 模型看不见自己的覆盖盲区,也不会说「做了一半」。
BugX 用一本账和四条硬规矩对抗这件事:逐单元覆盖清单(查完 / 卡住 / 未查)、强制复现(同一段攻击输入触发两次、正常输入触发零次)、审计可断点续跑、哈希链记录让每条结论都可复查。
安装
要求 Python >=3.11。
# 标准安装:
python -m pip install bugx-cli
# 或用 uv(更快的解析器):
uv pip install bugx-cli
# 或作为隔离应用安装:
pipx install bugx-cli
可选功能扩展:
python -m pip install "bugx-cli[tui]" # 终端交互菜单(pexpect)
python -m pip install "bugx-cli[ui]" # Web UI 审计探针(playwright、Pillow)
python -m pip install "bugx-cli[graph]" # tree-sitter 多语言 AST 索引
python -m pip install "bugx-cli[crypto]" # 加密遥测与签名
装好后任意目录跑一次:
bugx install # 列出检测到的 AI 宿主并注册 BugX MCP 服务
bugx doctor --strict # 健康自检
一次装全所有宿主:bugx install --agent all。
快速上手
方式一:在 AI 助手里用(推荐)。 在任意项目里打开 Claude Code、Codex、Cline、OpenCode 或 ZCode,直接说:
「审计一下这个项目」 「查一下登录模块有没有漏洞」
宿主里的 AI 会自动调用 BugX:建覆盖清单、派发并发 Worker、跑探针、验证漏洞、出报告。想实时看,终端跑 bugx report serve,浏览器打开 http://127.0.0.1:8080。
方式二:命令行直接跑。 AI 同样来自你已装好的宿主——模型和凭据直接复用,不接管你的 Key。
bugx auth login # 登录云端账号(错题/经验同步用)
bugx init --cloud-sync sync # 开启云端同步
bugx engine pre # 建立覆盖清单与审计计划
bugx engine status # 看进度
bugx engine post # 结账:核对覆盖、证据与裁决
bugx autonomous --host opencode # 无人值守完整审计
bugx report serve # 实时 Web 报告 http://127.0.0.1:8080
支持的 AI 编程宿主
| AI 编程助手 | 接入方式 | 安装命令 |
|---|---|---|
| Claude Code | 原生 MCP / 自治生命周期 | bugx install --agent claude |
| OpenAI Codex | 工作区子 Agent / 原生插件 | bugx install --agent codex |
| OpenCode | Headless ACP / 原生 MCP | bugx install --agent opencode |
| Cline / Roo Code | MCP 会话(串行)/ CLI 多进程池并发 | bugx install --agent cline |
| ZCode | 原生 MCP / 用户级注册 | bugx install --agent zcode |
DeepSeek Harness(DSH)、WorkBuddy、Cursor / Windsurf 等持续适配中。运行 bugx hosts 查看本机检测到的宿主。
安全与隐私
- 项目状态存放在项目内
.bugx/目录;全局引擎、凭据、知识库与缓存在用户级 BugX 目录。 - 凭据按需写入受控沙箱(默认仅当前用户可读);
bugx auth status只报告是否存在,不输出内容。 - 云端上传、反馈、诊断上报与同步都是显式操作,执行前明确
--scope。 reset/uninstall/purge/--no-backup会删除数据,注意各自的 dry-run 与备份行为。
常见问题
BugX 是什么? 一款装进 AI 编程助手的自主代码审计 Agent:通过 MCP 在 Claude Code、Codex、Cline、OpenCode、ZCode 内运行,也可作为独立 CLI 使用;按单元跟踪审计覆盖,并对每条发现做真实执行验证。
支持哪些 AI 编程工具? Claude Code、OpenAI Codex、Cline / Roo Code、OpenCode、ZCode 已适配;DeepSeek Harness(DSH)、WorkBuddy、Cursor / Windsurf 等持续适配中。
如何验证一个漏洞? 同一段攻击输入必须两次复现该漏洞,一段正常输入必须零触发;三次执行(两正例一负对照)连同命令、退出码与产物哈希全部记录在案。
我的代码会被上传到云端吗?
审计全程本地执行。错题与经验的云端同步是显式操作(bugx init --cloud-sync sync / bugx cloud),不运行就不上传。
BugX 能替代人工审查吗? 不能。它提供一份可复查的账本——查了什么、没查什么、每条发现的复现证据——让人工审查从事实开始,而不是从模型的自述开始。
审计支持哪些语言? 基于 tree-sitter 的多语言静态与行为分析(Python、JavaScript/TypeScript、Java、Go、Rust 等),外加 native / Python / JVM / Electron / Android / Apple 六类目标的内存专项检查。
关键词
AI 代码审计 · AI 代码审查 · 代码审查 Agent · 安全审计 · 漏洞扫描 · 静态分析 · MCP 服务 · Claude Code 审计 · Codex 审计 · 编程助手安全 · 自主审计 · 行为差分 · 内存泄漏检测 · Python 安全 · JavaScript 安全
License
Metadata
Release files for bugx-cli 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bugx_cli-0.1.1.tar.gz | 5.5 MB | Without provenance | Details for bugx_cli-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bugx_cli-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for bugx_cli-0.1.1-py3-none-any.whl |
Total release size: 10.9 MB
Release files / bugx_cli-0.1.1.tar.gz
| Download URL | bugx_cli-0.1.1.tar.gz |
|---|---|
| Size | 5.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cb35de39f21dd7ee275b40a1ff60559ec843d9f150475bf1f00c37ebb091a52f
|
|
BLAKE2b-256 checksum How to use checksums |
3c957bfa4cd345532a368b919e1e99abbeeec6d918240bb7e7a5b625cb0f6f5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
Release files / bugx_cli-0.1.1-py3-none-any.whl
| Download URL | bugx_cli-0.1.1-py3-none-any.whl |
|---|---|
| Size | 5.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
726679c5c2a3c3d0b28555fa8b90b943399587ba203b6724573d012af80bf294
|
|
BLAKE2b-256 checksum How to use checksums |
1db67d686d78c576e6ae913d28cf4698e61ad927562019448d60faa4ee5eb289
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
Security for bugx-cli 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.