Metadata-Version: 2.4
Name: bugx-cli
Version: 0.1.1
Summary: Host-neutral adversarial white-box and black-box auditing agent
License-Expression: BUSL-1.1
Project-URL: Homepage, https://bugx.dev
Project-URL: Source, https://github.com/Bencibr/bugx
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tui
Requires-Dist: pexpect==4.9.0; extra == "tui"
Provides-Extra: ui
Requires-Dist: playwright<2,>=1.51; extra == "ui"
Requires-Dist: Pillow>=12.3; extra == "ui"
Provides-Extra: graph
Requires-Dist: tree-sitter-language-pack==1.14.3; extra == "graph"
Provides-Extra: crypto
Requires-Dist: cryptography>=41; extra == "crypto"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Bencibr/bugx/main/core/assets/bugx-hero-en.svg" alt="BugX — effortless audits of AI-written code" width="1000">
</p>

# 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.

<p align="center">
  <a href="https://pypi.org/project/bugx-cli/"><img src="https://img.shields.io/pypi/v/bugx-cli.svg?style=flat&color=0284c7&label=PyPI" alt="PyPI Version"></a>
  <a href="https://pypi.org/project/bugx-cli/"><img src="https://img.shields.io/pypi/pyversions/bugx-cli.svg?style=flat&color=334155&label=Python" alt="Python Versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-BSL--1.1-334155.svg?style=flat" alt="License: BSL-1.1"></a>
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-334155.svg?style=flat" alt="Platform">
</p>

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

<p align="center">
  <a href="#-english-documentation">English</a> •
  <a href="#简体中文说明">简体中文</a>
</p>

---

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

<p align="center">
  <img src="https://raw.githubusercontent.com/Bencibr/bugx/main/core/assets/webui-studio.jpg" alt="BugX Studio workbench" width="860">
</p>

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

<p align="center">
  <img src="https://raw.githubusercontent.com/Bencibr/bugx/main/core/assets/webui-chatgpt.jpg" alt="ChatGPT workspace" width="420">
  <img src="https://raw.githubusercontent.com/Bencibr/bugx/main/core/assets/webui-zcode.jpg" alt="ZCode workspace" width="420">
</p>

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

<p align="center">
  <img src="https://raw.githubusercontent.com/Bencibr/bugx/main/core/assets/webui-skills.jpg" alt="Skill marketplace" width="860">
</p>

### Installation

Requires Python `>=3.11`.

```bash
# 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:

```bash
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:

```bash
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.

```bash
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`。

```bash
# 标准安装：
python -m pip install bugx-cli

# 或用 uv（更快的解析器）：
uv pip install bugx-cli

# 或作为隔离应用安装：
pipx install bugx-cli
```

可选功能扩展：

```bash
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]"   # 加密遥测与签名
```

装好后任意目录跑一次：

```bash
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。

```bash
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](LICENSE)
