Codex 使用场景
设置安全上下文
明确要保护哪些对象、要检查哪些规则,以及要报告哪些内容。
了解如何准备和配置 Codex 执行安全审查和扫描所需的上下文。
最适合
- 为代码仓库的安全审查和扫描做准备的开发者。
- 需要记录系统风险、安全要求和报告标准的应用安全团队。
- 需要向安全智能体提供架构、工程和运维知识的团队。
目录
设置安全上下文
明确要保护哪些对象、要检查哪些规则,以及要报告哪些内容。
了解如何准备和配置 Codex 执行安全审查和扫描所需的上下文。
了解如何准备和配置 Codex 执行安全审查和扫描所需的上下文。
最适合
- 为代码仓库的安全审查和扫描做准备的开发者。
- 需要记录系统风险、安全要求和报告标准的应用安全团队。
- 需要向安全智能体提供架构、工程和运维知识的团队。
技能与插件
- 为您的应用创建威胁模型,涵盖资产、入口点、安全边界和假设条件。
- 生成初始安全策略,并将其添加到您的代码仓库中。
| 技能 | 使用理由 |
|---|---|
| Codex Security:threat Model | 为您的应用创建威胁模型,涵盖资产、入口点、安全边界和假设条件。 |
| Codex Security:define Security Policy | 生成初始安全策略,并将其添加到您的代码仓库中。 |
威胁模型、AGENTS.md、SECURITY.md 和知识库的区别
AGENTS.md 记录团队共用的工程指令,明确大家应遵循的标准。SECURITY.md 告诉 Codex,您的组织希望如何评估系统的安全状况并报告发现的问题。威胁模型则描述系统实际面临的安全威胁。这些文档的内容有所重叠,但威胁模型通常只是整体安全策略的一部分。
例如,威胁模型会详细说明需要保护的资产、系统入口点、攻击者可控的输入、信任边界、身份验证方面的假设、特权操作以及存在风险的组件。
# Threat Model
The public API accepts untrusted JSON and file uploads.
Requests cross from the internet-facing API into internal billing and
identity services. Attackers are unauthenticated users or compromised
tenant accounts. Protect tenant data, billing mutations, and service credentials.
security.md 告诉 Codex,您的组织希望如何评估上述安全状况并报告发现的问题。
# Security Policy
## Security Invariants
- Every billing mutation must be authorized for the active tenant.
- Uploaded content must be parsed within explicit size and resource limits.
- Service credentials must never be returned to clients.
## Reportable Findings
Report realistic violations of tenant isolation, authentication bypass,
unsafe parsing, secret exposure, or unauthorized billing mutations.
## Severity Context
Cross-tenant access is Critical.
Single-tenant unauthorized mutation is High.
## Out of Scope
Development-only tools that cannot be included in production builds.
知识库可以为特定扫描提供参考文档,包括架构文档、安全策略、其他威胁模型,或 CLI 扫描器需要考虑的运行背景。下面是一份为 CLI 扫描器准备的 Markdown 架构文档示例。
# Payment Service Security Context
## Purpose
The payment service creates charges, issues refunds, and stores references
to payment-provider customers. It does not store full card numbers or CVVs.
## Deployment and Exposure
- `POST /api/payments` is internet-facing through the API gateway.
- `POST /internal/refunds` is reachable only from the support service.
- Background workers consume messages from the `payment-events` queue.
- The service runs with access to the payment-provider API and billing database.
## Authentication and Authorization
- Public endpoints use JWTs issued by the identity service.
- The API gateway validates signatures, issuer, and expiration.
- This service remains responsible for tenant authorization.
- Internal requests use workload identity; network location alone is not trusted.
- Refunds above £1,000 require a previously recorded approval.
## Trust Boundaries
1. Internet client → API gateway
2. API gateway → payment service
3. Payment service → payment provider
4. Payment service → billing database
5. Message producers → `payment-events` consumer
Inputs crossing any of these boundaries must be treated as untrusted unless
the receiving component performs the documented validation.
## Sensitive Assets and Operations
- Payment-provider API credentials
- Customer-to-provider identifier mappings
- Charge creation
- Refund issuance
- Webhook signature secrets
- Tenant billing history
## Important Data Flows
### Creating a charge
1. The API receives an authenticated request containing an order identifier.
2. The service retrieves the order using both tenant ID and order ID.
3. The service calculates the amount from server-side order data.
4. The service creates the provider charge with an idempotency key.
5. The resulting provider identifier is stored in the billing database.
Client-supplied amounts must never be passed directly to the provider.
### Processing a webhook
1. The raw request body is retained.
2. The provider signature is verified over the raw bytes.
3. The event timestamp must be within five minutes.
4. Duplicate event IDs are ignored.
5. State changes occur only after all validation succeeds.
## Relevant Code
- `src/http/payments.ts`: public payment endpoints
- `src/http/refunds.ts`: refund endpoints
- `src/webhooks/provider.ts`: webhook validation
- `src/workers/payment-events.ts`: asynchronous event processing
- `src/auth/tenant.ts`: tenant authorization
- `src/provider/client.ts`: provider API wrapper
## Security Assumptions
- The identity service is trusted to authenticate users, but not to authorize
access to payment records.
- Queue publishers may be compromised; consumers must validate message content.
- API-gateway authentication does not replace service-level tenant checks.
- Provider webhook payloads are attacker-controlled until signature validation
completes.
## Known Limitations
- Legacy refunds created before 2025 do not have idempotency keys.
- Webhook replay protection is local to one region.
- The development payment-provider emulator does not validate signatures.
您可以使用以下命令,让扫描器在扫描时读取知识库:
codex-security scan . \
--knowledge-base /path/to/security-policies
您可以按以下目录结构组织这些文件:
SECURITY.md
docs/security/
├── threat-model.md
├── architecture.md
├── authentication.md
└── deployment-boundaries.md
创建初始威胁模型
将威胁模型提交到代码仓库,是指导 Codex 开展安全审查的关键步骤。您可以在 Codex 中调用威胁建模技能来生成初始模型,然后提交该模型。

在 Codex 中输入 $threat-model 即可调用威胁建模技能。创建威胁模型后,请将其提交到代码仓库的 /docs/security 目录,然后在 Codex 云端所选代码仓库的设置中添加指向该模型的链接。如果未指定威胁模型,Codex 会在每次安全审查时重新生成威胁模型。

创建初始 SECURITY.md 文件
您可以使用 $define-security-policy 技能在代码仓库中生成初始安全策略。

一份完善的安全策略应详细说明应用的运行方式。以下提示词示例提供了这些细节,供 Codex 据此逐项列出并明确安全要求:
### 身份验证与授权
- 每个非公开端点都必须验证调用方的身份。
- 验证会话和 Token 时,必须核查签发方、目标受众、签名、到期时间和撤销状态,并确认其适用于预期的身份验证场景。
- 身份验证失败时,必须拒绝访问。
- 对于敏感操作,必须视情况要求调用方近期已完成身份验证,或要求其通过更强的身份验证。
- 密码重置、账户恢复、MFA 和身份关联流程均不得允许他人接管账户。
- 身份验证用的机密信息和 Token 绝不能出现在日志、URL、分析数据或错误响应中。
- 每次读取、修改、交易、导出或执行管理操作前,都必须先检查授权。
- 仅凭持有有效账户或资源标识符,不能认定调用方已获授权。
- 列表、详情、搜索、批量操作、导出和间接引用端点都必须确保客户之间、账户之间以及租户之间相互隔离。
- 服务端授权不得依赖客户端提供的角色、归属字段、价格、余额或审批状态。
- 分配管理权限和服务间调用权限时,必须遵循最小权限原则。
- 即使只有一个端点受影响,也应报告允许跨客户访问的缺陷。
### 交易与账本完整性
- 每笔交易都必须核实已通过身份验证的客户是否有权使用相应的资金来源账户进行该笔交易,并确认该账户符合交易条件。
- 必须在服务端验证金额、币种、资金去向、费用、限额和审批状态。
- 必须防止交易请求遭到重放或重复处理,并防范竞态条件和幂等键混用。
- 余额检查和账本更新必须作为一个原子操作执行。
- 已入账的分录不得直接修改。如需更正,必须通过可审计的补偿分录处理。
- 对于高风险交易,必须根据适用要求执行限额控制、加强身份验证、履行审批程序或采取反欺诈措施。
- 任何失败路径一旦导致交易状态不明,都必须通过对账确认最终状态。
### 数据保护
- 敏感数据在传输和存储时都必须使用获准的措施加密。
- 机密信息必须来自获准的机密管理系统,不得从源代码或普通配置文件中获取。
- 日志、跟踪记录、指标、支持工具和安全相关产物均不得包含凭据,其中的个人数据和财务数据必须减至最低限度。
- 导出数据和备份必须采用与主数据同等的授权要求和保护措施。
- 错误响应不得泄露系统内部细节、敏感记录、凭据或授权细节。
- 数据保留和删除方式必须符合系统已批准的数据治理要求。
### 输入与输出处理
- 将请求头、路径、查询参数、请求体、上传文件、webhook 载荷、第三方响应和已存储的客户内容一律视为不可信输入。
- 在安全敏感操作中使用输入前,必须验证其模式、类型、范围、长度和格式。
- 访问数据库时必须使用参数化查询。
- 对于出站请求,必须限制目标地址、协议、重定向、DNS 解析行为和响应大小。
- 必须限制解析、上传、解压缩和序列化所能消耗的资源,防止资源耗尽。
- 输出客户可控的内容时,必须根据具体输出上下文对内容进行安全编码。
\ 相关使用场景
使用 GitHub Actions 创建自定义审查工作流
将安全审查纳入开发流程,以便重复执行。配置 GitHub Actions 工作流,让 Codex Security 检查拟议的代码变更,并保存结果供您的团队查看。
在 CI 中自动运行安全扫描
将 Codex Security CLI 添加到您的 CI 流水线中。选择何时扫描、审查哪些代码,保留扫描发现的问题及扫描覆盖范围的记录,并决定扫描结果如何影响交付流程。
在 CI/CD 中管理供应链风险
使用 Codex Security CLI 评估第三方依赖项对应用安全性的影响。对 Dependabot 警报进行分级和验证,并在引入或更新软件包时运行安全扫描。