OpenCRE

前往 https://www.opencre.org 查看 OpenCRE 的实际运行效果和更多说明。 OpenCRE 全称是 Open Common Requirement enumeration（开放通用需求枚举）。它是一个交互式内容链接平台，用于整合安全标准与指南。在设计、开发、测试和采购安全软件时，它能够提供简便而可靠的相关信息访问途径。

OpenCRE 包含：

• 应用程序：一个用于访问数据的 Python Web 和 CLI 应用程序，公开运行于 opencre.org
• 目录数据：通用需求（CRE）目录
• 映射数据：从每个 CRE 到一系列标准中相关章节的链接
• 用于贡献数据以及在本地运行该应用程序的工具和指南

贡献代码或映射

要了解如何为应用程序或数据（目录或标准映射）做出贡献，请参阅贡献指南。 我们非常欢迎您的参与！

文档

• 应用内文档 — 入门指南、常见问题解答和交互式 API 参考
• 常见问题解答 — 常见问题（也显示在 /docs#faq）
• OpenAPI 规范 — 公共 REST API（运行时为 /rest/v1/openapi.yaml）

路线图

有关路线图，请参阅议题。

运行您自己的 OpenCRE

您可以自由使用 opencre.org 上的公开 opencre 应用程序。除此之外，如果您想纳入自己的安全标准和指南，也可以自行运行一个实例。我们称之为 myOpenCRE。

本地运行

Docker

在本地运行 OpenCRE 最简单的方式是运行已发布的 docker 容器。 您可以执行以下命令：

docker run -p 5000:5000 ghcr.io/owasp/opencre/opencre:latest

容器完成远程信息下载后，您可以通过 http://127.0.0.1:5000 访问它。

如果您想在 OpenCRE 上进行开发，或者您的环境中没有 docker，您也可以选择通过 CLI 运行它。

命令行

要在 Docker 之外运行，您需要安装 OpenCRE。 要安装此应用程序，您需要 python3、yarn 和 virtualenv。

克隆仓库：

git clone https://github.com/OWASP/OpenCRE

（推荐）创建并激活 Python 虚拟环境：

python3 -m venv venv
source venv/bin/activate

安装依赖：

make install

运行以下命令从上游下载最新的 CRE 图谱：

make upstream-sync

您可以在导入后通过以下命令预计算本地差距分析缓存：

make backfill-gap-analysis

然后您可以通过以下命令在本地运行 CRE：

make dev-flask

要运行 CLI 应用程序，您可以执行：

python cre.py --help

要将 CRE + 标准分类法导出为 CSV（适合 CI 环境），请运行：

python cre.py --export --csv <path/to/output.csv>

示例：

python cre.py --export --csv artifacts/cres_and_standards.csv

说明：

• --export 是专用的导出模式，写入 CSV 后即退出。
• 使用 --export 时必须指定 --csv。
• 该模式从 OpenCRE API 导出报告数据，不会修改本地数据库。

要将远程 CRE 电子表格下载到本地，您可以运行：

python cre.py --review --from_spreadsheet <google sheets url>

要将远程电子表格添加到本地数据库，您可以运行：

python cre.py --add --from_spreadsheet <google sheets url>

要以开发模式运行 Web 应用程序，您可以执行：

make start-containers
make start-worker

# in a separate shell
make dev-flask

或者，您也可以通过以下方式使用 dockerfile：

make docker && make docker-run

某些功能（如差距分析）需要 neo4j 数据库处于运行状态，您可以通过以下命令启动它：

make docker-neo4j

要仅运行缺失的差距分析配对回填（不启动 Flask），请使用：

RUN_COUNT=8 bash scripts/backfill_gap_analysis.sh

生产数据库操作 (opencreorg)

生产环境操作请优先使用 scripts/db/ 中的专用脚本。这些脚本强制执行安全防护措施，并始终在数据库更改前捕获最新备份。

• 仅备份：
  • APP_NAME=opencreorg scripts/db/backup-opencreorg.sh
• 将本地 Postgres 同步到 Heroku：
  • APP_NAME=opencreorg SOURCE_DB_URL="postgresql://cre:[email protected]:5432/cre" scripts/db/sync-local-to-opencreorg.sh
• 定向 SQL 变更：
  • APP_NAME=opencreorg scripts/db/surgery-opencreorg.sh --sql-file ./tmp/change.sql

对于破坏性变更（DELETE、DROP、TRUNCATE、不可逆的 ALTER），请使用：

APP_NAME=opencreorg \
CONFIRM_DESTRUCTIVE=I_UNDERSTAND_OPENCREORG_PROD_DB_DESTRUCTIVE_ACTION \
scripts/db/surgery-opencreorg.sh --sql-file ./tmp/destructive-change.sql --destructive

运行手册：

• docs/runbooks/opencreorg-db-sync-and-surgery.md
• docs/runbooks/opencreorg-db-destructive-ops-checklist.md

应用程序连接 neo4jDB 的环境变量（默认值）：

• NEO4J_URL (neo4j//neo4j:password@localhost:7687)

要以生产模式运行 Web 应用程序，您需要 gunicorn，并且可以在 cre_sync 目录内运行：

make prod-run

macOS 说明（Apple Silicon 与 Intel）

OpenCRE 在 macOS 上完全受支持。以下说明为可选内容，旨在帮助贡献者在 macOS 系统上本地运行 OpenCRE。

前置要求

使用 Homebrew 安装所需工具：

brew install [email protected] yarn make

注意：建议使用 Python 3.11。较新的 Python 版本可能会导致依赖不兼容。

验证 Python 版本：

python3 --version

虚拟环境设置

显式使用 Python 3 创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate

升级 pip：

pip install --upgrade pip

依赖安装

使用标准流程安装依赖：

make install

如果遇到构建问题，请确保已安装 Xcode 命令行工具：

xcode-select --install

本地运行

同步上游 CRE 数据（需要互联网连接）：

make upstream-sync

然后启动本地服务器：

make dev-flask

应用程序将可通过以下地址访问：

http://127.0.0.1:5000

提示：对于大多数 macOS 用户来说，通过 Docker 运行是最简单、最可靠的方式。

使用 OpenCRE API

有关使用 OpenCRE API 的说明（例如添加您自己的安全指南和标准），请参阅 myOpenCRE 用户指南。

Docker 构建与运行

您可以通过以下命令构建生产或开发 docker 镜像：

make docker-prod
make docker-dev

OpenCRE 使用的环境变量如下：

环境配置

复制示例配置文件：

cp .env.example .env

然后编辑 .env 并为您的环境提供合适的值。

变量

• 数据库：DEV_DATABASE_URL
• Neo4j：NEO4J_URL
• Redis：REDIS_HOST、REDIS_PORT、REDIS_URL、REDIS_NO_SSL
• Flask：FLASK_CONFIG、INSECURE_REQUESTS
• 嵌入：NO_GEN_EMBEDDINGS、CRE_EMBED_MODEL、CRE_EMBED_EXPECTED_DIM、CRE_VALIDATE_EMBED_DIM_ON_INIT
• LLM 模型/重试：CRE_LLM_CHAT_MODEL、CRE_EMBED_ALIGN_MODEL、、

完整列表和默认值请参阅 .env.example。

LiteLLM 后端（可选）

OpenCRE 使用 LiteLLM 进行 LLM 调用。请通过环境变量配置模型和提供商凭据。

推荐的最小配置示例：

# Chat / completion models (LiteLLM model strings)
CRE_LLM_CHAT_MODEL=gemini/gemini-2.5-flash
CRE_EMBED_ALIGN_MODEL=gemini/gemini-2.5-flash

# Embedding model used for persisted vectors
CRE_EMBED_MODEL=gemini/gemini-embedding-001
CRE_EMBED_EXPECTED_DIM=3072
CRE_VALIDATE_EMBED_DIM_ON_INIT=1

# Retry policy
CRE_LLM_MAX_RETRIES=2
CRE_LLM_RETRY_SLEEP_SECONDS=15

# Provider credential (example for Gemini)
GEMINI_API_KEY=your-key

说明：

• 请将 CRE_EMBED_MODEL 或 CRE_EMBED_EXPECTED_DIM 的更改视为数据迁移事件（通常需要重新嵌入）。
• CRE_EMBED_EXPECTED_DIM 是一个安全防护：当维度不匹配时，写入会快速失败。
• 保持聊天/对齐模型与嵌入模型可独立配置；只有嵌入必须与存储的向量保持维度兼容。

您可以通过以下命令运行容器：

make docker-prod-run
make docker-dev-run

开发

您可以通过以下命令运行后端测试：

make test

您可以通过以下命令获取覆盖率报告：

make cover

请尽量将覆盖率保持在 70% 以上。