Skip to main content

BugX — effortless audits of AI-written code

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.

PyPI Version Python Versions License: BSL-1.1 Platform

🌐 Website · 官网:https://bugx.dev · GitHub:https://github.com/Bencibr/bugx

English • 简体中文


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:

  1. 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.
  2. Checking is expensive; claiming is cheap. Reading hundreds of files takes real work. Replying "no issues found" takes a few words.
  3. 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-verify mutates your code to check whether the tests actually catch the bugs.
  • Patch bundles — bugx patch-forge builds 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 knowledge accumulate project and global experience; bugx autonomous and bugx goal run 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:

BugX Studio workbench

Every connected host keeps its own audit sessions (ChatGPT, ZCode, Claude, Codex, DSH, OpenCode, Pi, and more):

ChatGPT workspace ZCode workspace

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):

Skill marketplace

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 status reports whether credentials exist — it never prints them.
  • Cloud uploads, feedback, diagnostic log reporting, and sync are all explicit operations: each states its --scope before it runs.
  • reset / uninstall / purge / --no-backup delete 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 写代码的速度远超人工审查,而且模型带着训练层面的偏差——听起来做完了,比真的做完了更容易:

  1. 评分机制奖励自信。 人类评分员给「我仔细查过了,没发现问题」的分数高于「文件我还没看完」。模型学会的是报喜。
  2. 检查贵,声称便宜。 读几百个文件是体力活,回一句「没发现问题」只要几个字。
  3. 它不知道自己没查完。 模型看不见自己的覆盖盲区,也不会说「做了一半」。

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

Business Source License 1.1

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)

Source distribution for bugx-cli 0.1.1
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)

Table of built distributions (wheels) for bugx-cli 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page