OpenCRE

Vá para https://www.opencre.org para ver o OpenCRE em funcionamento e mais explicações. OpenCRE é a sigla para Open Common Requirement enumeration. É uma plataforma interativa de vinculação de conteúdo para unir padrões e diretrizes de segurança. Ela oferece acesso fácil e robusto às informações relevantes ao projetar, desenvolver, testar e adquirir software seguro.

O OpenCRE consiste em:

• O aplicativo: um aplicativo web e CLI em Python para acessar os dados, executado publicamente em opencre.org
• Os dados do catálogo: um catálogo de Common Requirements (CREs)
• Os dados de mapeamento: links de cada CRE para seções relevantes em uma variedade de padrões
• Ferramentas e diretrizes para contribuir com os dados e executar o aplicativo localmente

Contribua com código ou mapeamentos

Para ver como você pode contribuir com o aplicativo ou com os dados (catálogo ou mapeamentos de padrões), consulte Contribuindo. Sua contribuição é muito bem-vinda!

Documentação

• Documentação no aplicativo — primeiros passos, FAQ e referência interativa da API
• FAQ — perguntas frequentes (também exibida em /docs#faq)
• Especificação OpenAPI — API REST pública (/rest/v1/openapi.yaml quando em execução)

Roteiro

Para um roteiro, consulte as issues.

Executando seu próprio OpenCRE

Você é livre para usar o aplicativo público do opencre em opencre.org. Além disso, você pode executar o seu próprio caso queira incluir, por exemplo, seus próprios padrões e diretrizes de segurança. Chamamos isso de myOpenCRE.

Localmente

Docker

A maneira mais fácil de executar o OpenCRE localmente é usando o container docker publicado. Você pode fazer isso executando:

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

Após o container terminar de baixar as informações remotas, você pode acessá-lo em http://127.0.0.1:5000.

Se quiser desenvolver no OpenCRE ou se o docker não estiver disponível no seu ambiente, você também pode executá-lo via CLI.

Linha de Comando

Para executar fora do Docker, você precisa instalar o OpenCRE. Para instalar este aplicativo, você precisa de python3, yarn e virtualenv.

Clone o repositório:

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

(Recomendado) Crie e ative um ambiente virtual Python:

python3 -m venv venv
source venv/bin/activate

Instale as dependências:

make install

Baixe o grafo de CRE mais recente do upstream executando:

make upstream-sync

Você pode pré-calcular o cache local de gap-analysis após as importações com:

make backfill-gap-analysis

Para executar o CRE localmente, você pode usar:

make dev-flask

Para executar o aplicativo CLI, use:

python cre.py --help

Para exportar a taxonomia de CRE + padrões para CSV (amigável para CI), execute:

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

Exemplo:

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

Notas:

• --export é um modo de exportação dedicado e encerra após gravar o CSV.
• --csv é obrigatório ao usar --export.
• Este modo exporta dados de relatório da API do OpenCRE e não altera o banco de dados local.

Para baixar localmente uma planilha CRE remota, execute:

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

Para adicionar uma planilha remota ao seu banco de dados local, execute:

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

Para executar o aplicativo web em modo de desenvolvimento, use:

make start-containers
make start-worker

# in a separate shell
make dev-flask

Alternativamente, você pode usar o dockerfile com:

make docker && make docker-run

Alguns recursos, como Gap Analysis, exigem um banco de dados neo4j em execução; você pode iniciá-lo com:

make docker-neo4j

Para executar apenas o preenchimento retroativo (backfill) dos pares de gap-analysis ausentes (sem iniciar o Flask), use:

RUN_COUNT=8 bash scripts/backfill_gap_analysis.sh

Operações de Banco de Dados em Produção (opencreorg)

Prefira os scripts dedicados em scripts/db/ para operações em produção. Esses scripts aplicam proteções de segurança e sempre capturam um backup novo antes de alterações no banco de dados.

• Somente backup:
  • APP_NAME=opencreorg scripts/db/backup-opencreorg.sh
• Sincronizar Postgres local com o Heroku:
  • APP_NAME=opencreorg SOURCE_DB_URL="postgresql://cre:[email protected]:5432/cre" scripts/db/sync-local-to-opencreorg.sh
• Cirurgia SQL direcionada:
  • APP_NAME=opencreorg scripts/db/surgery-opencreorg.sh --sql-file ./tmp/change.sql

Para cirurgia destrutiva (DELETE, DROP, TRUNCATE, ALTER irreversível), use:

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

Runbooks:

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

Variáveis de ambiente para o aplicativo se conectar ao neo4jDB (padrão):

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

Para executar o aplicativo web em produção, você precisa do gunicorn e pode executar a partir do diretório cre_sync:

make prod-run

Notas sobre macOS (Apple Silicon e Intel)

O OpenCRE é totalmente suportado no macOS. As notas a seguir são opcionais e destinadas a ajudar contribuidores que executam o OpenCRE localmente em sistemas macOS.

Pré-requisitos

Instale as ferramentas necessárias usando o Homebrew:

brew install [email protected] yarn make

Nota: Recomenda-se Python 3.11. Versões mais novas do Python podem causar incompatibilidades de dependências.

Verifique a versão do Python:

python3 --version

Configuração do Ambiente Virtual

Crie e ative um ambiente virtual explicitamente usando Python 3:

python3 -m venv venv
source venv/bin/activate

Atualize o pip:

pip install --upgrade pip

Instalação de Dependências

Instale as dependências usando o fluxo de trabalho padrão:

make install

Se você encontrar problemas de build, certifique-se de que as Xcode Command Line Tools estejam instaladas:

xcode-select --install

Executando Localmente

Sincronize os dados de CRE do upstream (requer acesso à internet):

make upstream-sync

Em seguida, inicie o servidor local:

make dev-flask

O aplicativo estará disponível em:

http://127.0.0.1:5000

Dica: Para a maioria dos usuários de macOS, executar via Docker é a abordagem mais simples e confiável.

Usando a API do OpenCRE

Consulte o guia do usuário do myOpenCRE sobre como usar a API do OpenCRE para, por exemplo, adicionar suas próprias diretrizes e padrões de segurança.

Criando e executando com Docker

Você pode criar as imagens docker de produção ou de desenvolvimento com:

make docker-prod
make docker-dev

As variáveis de ambiente usadas pelo OpenCRE são:

Configuração de Ambiente

Copie o arquivo de configuração de exemplo:

cp .env.example .env

Em seguida, edite .env e forneça valores adequados ao seu ambiente.

Variáveis

• Banco de dados: DEV_DATABASE_URL
• Neo4j: NEO4J_URL
• Redis: REDIS_HOST, REDIS_PORT, REDIS_URL, REDIS_NO_SSL
• Flask: FLASK_CONFIG, INSECURE_REQUESTS
• Embeddings: NO_GEN_EMBEDDINGS, CRE_EMBED_MODEL, CRE_EMBED_EXPECTED_DIM, CRE_VALIDATE_EMBED_DIM_ON_INIT
• Modelos/retentativas de LLM: CRE_LLM_CHAT_MODEL, CRE_EMBED_ALIGN_MODEL, ,

Consulte .env.example para a lista completa e os valores padrão.

Backend LiteLLM (opcional)

O OpenCRE usa LiteLLM para chamadas de LLM. Configure modelos e credenciais do provedor por meio de variáveis de ambiente.

Exemplo mínimo recomendado:

# 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

Notas:

• Trate alterações em CRE_EMBED_MODEL ou CRE_EMBED_EXPECTED_DIM como um evento de migração de dados (geralmente exige re-embedding).
• CRE_EMBED_EXPECTED_DIM é uma proteção de segurança: as gravações falham rapidamente em caso de incompatibilidade de dimensão.
• Mantenha os modelos de chat/alinhamento e o modelo de embedding configuráveis de forma independente; apenas os embeddings devem permanecer compatíveis em dimensão com os vetores armazenados.

Você pode executar os containers com:

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

Desenvolvimento

Você pode executar os testes de backend com:

make test

Você pode obter um relatório de cobertura com:

make cover

Tente manter a cobertura acima de 70%.