bex-security - Open-source AI security scanner for Codex, Claude

项目说明

Bex Security

Open security workflows for every coding agent and model.

![Upstream: openai/codex-security]()
![npm: @bex-co/bex-security]()
![ACP alpha]()

Bex Security is an upstream-first fork of
OpenAI Codex Security. It keeps the
pro for finding, , and fixing while
working toward an open agent layer based on the
Agent Client Protocol (ACP).

Our north star is simple: run a consistent, e security workflow
with the agent and model that fit your repository, without falling behind
upstream security impro.

> ⭐ If you want security tooling that is portable across agents, editors, and
> models, star this repository and watch the roadmap.

Supported Agents

Run the same e security workflow with your preferred coding
agent. Codex is the default; Claude Code, Kimi Code, Muse Code, Qwen Code, and
MiMo Code support is currently alpha.

<p>
<a href=" src=" alt="Codex logo" width="16" ="middle" /> Codex</kbd></a> &nbsp;
<a href=" src=" alt="Claude Code logo" width="16" ="middle" /> Claude Code</kbd></a> &nbsp;
<a href=" src=" alt="Kimi Code logo" width="16" ="middle" /> Kimi Code</kbd></a> &nbsp;
<a href=" src=" alt="Muse Code logo" width="16" ="middle" /> Muse Code</kbd></a> &nbsp;
<a href=" src=" alt="Qwen Code logo" width="16" ="middle" /> Qwen Code</kbd></a> &nbsp;
<a href=" src=" alt="MiMo Code logo" width="16" ="middle" /> MiMo Code</kbd></a>
</p>

Quick start

Requires Node.js 22.13.0 or later in the 22.x release line, Node.js 24.x or
Node.js 26.x, and Python 3.10 or later.

Or run directly without a global installation:

The published npm package already contains the generated security plugin; the
additional build steps below apply only to a source checkout.

To work from source, clone the repository, install both dependency trees, and
build the bundled plugin and CLI:

Run ./bex-security from the checkout, or add the checkout to PATH for the
current shell if you prefer the bare command:

Why Bex Security

Upstream-first, not a rewrite. Bex uses a repeatable upstream main

merge workflow and treats Codex Security compatibility as a product
requirement.

Agent-open by design. ACP standardizes communication between code editors

and coding agents. Bex uses that boundary to support a growing ecosystem
without building a bespoke integration for every client.

Model choice today. The inherited CLI already supports OpenAI,

OpenRouter, Fireworks, and Amazon Bedrock provider paths.

Security outcomes over raw output. The workflow carries findings from

discovery through , remediation, comparison, and publication.

Project status

Bex Security is an early-stage fork published as @bex-co/bex-security. It
preserves the upstream CLI behavior and codex-security command alias while
making bex-security the primary command. Its first ACP slice runs
Codex sessions through codex-acp, and its pluggable agent integrations run
Claude Code through claude-agent-acp; Kimi Code, Qwen Code, and MiMo Code
through their native ACP servers; and Muse Code through Bex's community
muse-code-acp adapter.

| Capability | Status |
| ------------------------------------------------ | -------------------- |
| Codex Security-compatible CLI and TypeScript SDK | A |
| Multiple inference-provider paths | A |
| Repeatable upstream merge workflow | A |
| Codex sessions over ACP v1 and codex-acp | Alpha |
| Claude Code sessions over claude-agent-acp | Alpha |
| Kimi Code sessions o kimi acp | Alpha |
| Muse Code sessions over muse-code-acp | Alpha |
| Qwen Code sessions o qwen --acp | Alpha |
| MiMo Code sessions o mimo acp | Alpha |
| Kimi models through Claude Code | Alpha |
| Additional ACP agents | Contributors welcome |
| Bex-branded CLI (bex-security) | A |
| Bex-branded npm package | A |

Target architecture

ACP is an agent-runtime boundary, not a replacement for Bex's security
orchestration or a uni model API. Bex must continue to own scan scope,
workflow selection, permissions, artifact , persistence, and final
sealing regardless of which agent executes the work.

The adapter makes Bex the ACP client and selects a small agent driver for
codex-acp, claude-agent-acp, native kimi acp, muse-code-acp, native
qwen --acp, or native mimo acp. Bex
launches the selected agent per turn, negotiates ACP v1, creates or resumes its session, streams
protocol updates into the existing scan observers, forwards cancellation, and
preserves the current noninteracti boundary. The agent still owns
model authentication and access; Bex continues to own scan scope, the workflow,
workbench tools, and artifact . This keeps the integration small
enough to track upstream while proving that orchestration is independent of one
agent transport.

The adapter boundary is capability-based rather than Codex-shaped. A new agent
must prove that it can run the same scoped workflow and produce artifacts that
pass Bex's existing and sealing contract. ACP does not make agents
or model APIs interchangeable by itself.

To make the workflow portable, Bex must extract the security instructions and
schemas from Codex-specific plugin loading into a runtime-neutral workflow pack.
Agent-produced files remain drafts until the Bex workbench and seals
them. codex-acp is a useful
first compatibility target and reference implementation, not a required layer
for every agent.

Roadmap

1. Stay current: continuously merge upstream changes and keep the existing
CLI, SDK, security controls, and scan artifacts compatible.
2. Extract the stable host contract: separate portable prompts, schemas,
workbench tools, artifact rules, and progress events from Codex plugin
installation details.
3. Harden the ACP v1 slice: expand the Codex and Claude drivers
from protocol and compatibility tests to repeatable full-scan fixtures,
structured-output conformance, and interruption tests.
4. Open the agent port: add registry agents only when they pass the same
capability, artifact-contract, and scan-integrity suite.
5. Expand by e: publish a capability-based compatibility matrix for
agents and the models they expose. Keep draft ACP v2 support experimental
until the protocol stabilizes.
6. Release independently: publish Bex builds as
upstream.N, with package metadata recording the exact upstream
baseline.

Want to help? High-le contributions include ACP protocol mapping,
official-schema contract fixtures, agent/model compatibility reports, upstream
regression automation, and concise onboarding examples. Tell us which
ACP agent you want Bex to
support first.

Upstream compatibility

Bex publishes the TypeScript SDK and CLI as @bex-co/bex-security. The
bex-security command is primary, while codex-security remains a compatible
alias for existing scripts. Bex releases use upstream.N and record
their upstream package and commit in npm metadata. See the upstream
Codex Security documentation for
the complete CLI reference and
upstream releases for the
canonical changelog and upgrade notes.

The wrapper forwards every argument to the Bex CLI. The TypeScript package also
exposes bex-security as a bin alias while retaining codex-security for
upstream compatibility.

Some cybersecurity requests and protected findings require appro
Trusted Access for Cyber. To join the program, visit
chatgpt.com/cyber.

Choose an agent

To scan with Claude Code, authenticate Claude locally and select the Claude ACP
agent:

Bex keeps no model allowlist for --agent claude: it forwards --model and
--effort to Claude Code over ACP and them against the models and
reasoning levels your local installation ad. Claude Code exposes its
models as tier aliases rather than ids — a current install offers
default, opus[1m], fable, sonnet, and haiku. Select one by alias; for
example, fable resolves to your Claude Code's current Fable build (Fable 5.1):

To pin a specific behind an alias, export the matching Claude Code
(for example ANTHROPIC_DEFAULT_FABLE_MODEL) before scanning; the
native --agent claude path forwards it to Claude Code unchanged. If Bex
reports that a value is not offered, the local Claude Code does not ad it
yet — upgrade Claude Code rather than Bex.

To run Claude Code with GLM through Z.AI, provide a Z.AI API key and select the
Z.AI provider:

This defaults to glm-5.3[1m]. Select another GLM model explicitly when
needed:

Bex configures Z.AI only for the Claude ACP subprocess. It does not rewrite
your Claude Code settings or store the API key. See the
Z.AI Claude Code guide for account and
model a details.

Kimi is a either as a model provider behind Claude Code or as a native
ACP agent. The Claude provider path uses a Kimi API key and defaults to
kimi-for-coding:

For the native path, install Kimi Code, make sure kimi is on PATH, and log
in once before scanning:

The nati uses Kimi Code's sa and provider settings.
Bex starts kimi acp, forwards its security workbench over ACP, and reports the
model and thinking le by Kimi. See the
Kimi Code installation guide,
Kimi ACP reference,
and Kimi Claude Code guide.

Muse Code is a through the Bex-maintained
@bex-co/muse-code-acp adapter.
The adapter ships with Bex Security; install Muse Code and authenticate it once:

Then select Muse for a scan:

Bex forwards its stdio security workbench through ACP. Muse owns model
authentication and configuration. Muse does not expose additional ACP
workspace roots or interactive tool approvals, and usage or cost may be
una when a scan completes. Because Muse does not expose delegated
workers through ACP, Bex automatically runs bounded host-managed review
assignments and ad file co only for completed, non-truncated read
operations. Each candidate those assignments report then gets two independent
turns that try to refute it across the repository, and the more skeptical
result informs the final . The existing scan command needs no
Muse-specific orchestration flag.

Host-managed reviews sa requests and outcomes in the scan output
directory. If assignment review fails or is canceled, incomplete-report.md explains the
co gap and links to retained diagnostics and un candidates.
The scan still fails; this summary is not the report.md.
See retained host-review diagnostics
for artifact details and output retention.

Qwen Code runs through its native ACP server. Install it, launch qwen, and
use /auth once to configure a provider before scanning:

Bex starts qwen --acp and negotiates the models and reasoning levels
ad by Qwen Code. See the
Qwen Code quickstart.

MiMo Code also runs through its native ACP server. Install it and complete its
first-run provider setup before scanning:

Bex starts mimo acp and preserves MiMo's current primary agent mode. MiMo
exposes thinking levels as model , so --effort high selects the
ad .../high of the selected or current model. Bex reports an
error with the a when the requested level is una.
See the MiMo Code repository.

Codex remains the default agent. Sign in with ChatGPT or provide an API key:

Common scan commands:

For CI with Codex, set OPENAI_API_KEY or CODEX_API_KEY instead of signing
in. --agent claude delegates authentication and model discovery to the local
Claude Code installation unless a provider is selected. --agent kimi
delegates both to the local Kimi Code installation, --agent muse delegates
both to Muse Code through muse-code-acp, and --agent qwen and --agent
mimo delegate both to their respecti installations. The default
remains --agent codex; saved scan
recipes created before agent selection also replay with Codex.

Use -- to replace final with your own setup,
testing, and cleanup instructions. This works for standard and diff scans;
Deep scans do not support it. See custom .
For a runnable local example, see the custom demo.
En API keys are passed directly to the current scan and are never
stored in Codex's credential home or system keyring.

After showing the findings summary, interacti with findings ask whether
to open a finding browser where you can inspect full details, choose a se
threshold, select indi findings, and add patch instructions for each one.
Each selected finding runs in its own sa desktop task.
Use --patch --patch-se high to fix high and critical findings. Add
--create-pr, or enable the pull request option during review, to commit the
files and open a draft GitHub pull request. Ordinary scans do not
change repository files.

Deep-scan discovery stops after 96 hours by default. Set --max-time-hours to
any positi of hours, including fractional hours, up to 96. Completed
findings are preserved and returned when the limit is reached.

For a monorepo, run separate standard scans and combine their results by root
cause:

Use --auto to let Codex choose the components, or --auto --plan-only to
review the split first. See component scans
for reusable plans, combined reports, and co details.

To use another inference provider, set its API key and select a model:

Amazon Bedrock also supports standard AWS access keys, profiles, web identity,
container credentials, and the default AWS credential chain.

Local sign-in honors Codex's configured credential backend, including a system
keyring required by a managed device. Bex Security keeps login and scan
credentials in the same private, persistent state directory.

If both a ChatGPT sign-in and an API key are a, interacti ask
which credential to use. CI and other noninteracti keep the existing
API-key precedence. Select a credential explicitly when needed:

To make your ChatGPT sign-in the automatic default, unset any configured API
keys:

Scan history is stored in the Bex Security workbench state directory. If that
directory cannot be written, set CODEX_SECURITY_STATE_DIR to a writable
directory outside the repository.

Applications can attribute API-key scans to an end user with
scan --safety-identifier ID or the SDK's per-run safetyIdentifier option.
See Safety ID setup and runtime requirements.

findings list [repository] shows open findings across a repository's scans
and identifies findings not confirmed in its latest scan.

Use patch OCCURRENCE_ID to fix one sa, or
patch --scan SCAN_ID --se high to fix selected findings from a saved
scan. Add --json for structured results or --create-pr to open a draft
GitHub pull request after . If publication fails, use the printed
patch --resume-pr BRANCH command to retry without running Codex again.

Use patch --linear-issue SEC-123 to import and fix a Linear issue, or
patch --linear-project "Security backlog" --linear-filter '{"labels":{"name":{"eq":"security"}}}'
to fix matching open issues from a project. Set
CODEX_SECURITY_LINEAR_API_KEY to authorize read-only Linear access.

scans compare BEFORE_SCAN_ID AFTER_SCAN_ID automatically matches findings by
root cause, reuses sa, and identifies new, persisting, reopened,
resolved, or unknown findings. Missing findings remain unknown when co is
incomplete or their original location was not re.

Publish scan findings

Publish every finding from a completed scan to a Linear team:

Add --linear-project PROJECT_ID to place the issues in a Linear project, or
omit it to create issues directly in the team. The existing --project flag
remains an alias. Omit the scan directory to select a
completed scan interactively. You can also set CODEX_SECURITY_LINEAR_TEAM and
the optional CODEX_SECURITY_LINEAR_PROJECT instead of passing the destination
flags. Add --dry-run to preview the issues or --json to return
machine-readable results.

By default, publishing uses your existing Codex sign-in and connected Linear
app without a separate Linear token. To publish directly through the Linear API
instead, set CODEX_SECURITY_LINEAR_API_KEY to a Linear personal API key.
Direct publication lea unassigned by default; pass
--linear-assignee EMAIL_OR_USER_ID to select a Linear user:

Use --linear-assignee USER_ID to select a Linear user ID instead of an email
address, or omit the flag to leave the issues unassigned.

--linear-api-key KEY also selects direct publication and takes precedence
over the en . Prefer the en to keep API keys
out of shell history and process listings. Every finding creates a new issue
containing the scan ID, affected code locations, source snippets, and
remediation guidance. Choose a destination authorized to receive the
repository's source code and details.

diagnostics

Add -- to print scan diagnostics to stderr:

CODEX_SECURITY_LOG_LE also enables diagnostics;
LOG_LE is its fallback. JSON results remain on stdout.

diagnostics may contain sensitive data. Review local logs before
sharing them. Sa summaries, bulk-scan receipts, and the normal
activity feed preser text, including credential-shaped .

Use ./bex-security scans logs SCAN_ID to inspect sa
events from a scan and its workers. Press d during a scan to inspect
unredacted details; a, m, and 1–9 select all, main, or worker
sessions. These events can contain credentials.

Generate SECURITY.md

Draft repository-wide or component-scoped SECURITY.md guidance for future scans:

The command saves a draft outside the checkout; it does not install it or run a
scan. Review the proposed diff before copying the policy. Supporting architecture,
threat-model, and review documents stay outside the repository and may contain
sensiti. See the SDK policy guide
for headless generation, sa, and SDK usage.

TypeScript SDK

To suggest owners for existing findings from source and Git history, see
Suggest finding owners.

Codex Security is a Ja package:

Containerized bulk scans

Use the upstream image and included Docker Compose configuration for
noninteracti scans of repositories pinned to immutable Git
re. See the container quick start
for authentication, private result storage, and optional Ubuntu AppArmor
hardening.

Pass --knowledge-base PATH to share security documents with every repository;
repeat the option for multiple files or directories.

Use --scan-prompt-file PATH to add shared scan instructions, and add a prompt
CS for repository-specific instructions. Use
--post-scan-prompt-file PATH to run a follow-up after each scan, including
incomplete or failed scans.

For indi CLI stages with durable state and access to a separately deployed
findings service, use the same scanner image with the
workflow runner Compose example.

Findings service (preview)

Run bex-security serve to start the service without Docker. See
running without Docker
for prerequisites, credentials, and storage configuration.

The findings service runs
from the same ghcr.io/openai/codex-security image as the scanner (or a local
source build), with a separate container and state configured by
compose.findings.yaml. It stores findings and embeddings in SQLite and lists
findings with pagination. Its read-only dashboard at /dashboard refreshes every
fi and shows stored findings and duplicate groups from the service's
database. It also returns potential duplicates by embedding similarity within a
repository or an explicit all-repository scope. The
bex-security publish scan --to custom --findings-url
command uploads completed findings and their repository ID. The SDK and
bex-security dedupe command retrie, run independent reviews
locally, and persist accepted duplicate groups; --all-repositories
opts into the broader scope.

Use npx @bex-co/bex-security classify-se --scan SCAN_ID --rubric /path/to/policy.md
to assess selected findings under your own policy before publishing tickets.
Scan classification checkpoints each finding in SQLite and reuses matching
assessments on reruns; --reprocess forces reassessment. The SDK exposes the same
classification operation; original scan se stays unchanged. See se classification.

Other pro

To use another inference provider, set its API key and select a model:

Documentation

See project configuration for reusable YAML/JSON
settings, CLI o, and editor schema support.

For complete command help, runtime defaults, nati worker limits,
en , deep-scan configuration, and SDK options, see the
package README and the
upstream CLI reference.
Upstream behavior this fork keeps is documented in the
Codex Security documentation.

项目信息

开发语言：TypeScript

Star 数：50

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source AI security scanner for Codex, Claude Code, and ACP-compatible coding agents—kept current with OpenAI Codex Security.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。