Skip to content

docs: add macOS local development setup guide #658

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
northdpole merged 4 commits into from
Dec 26, 2025
Merged

docs: add macOS local development setup guide #658

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f1011aa
docs: add macOS local development setup guide
PRAteek-singHWY Dec 13, 2025
80a9853
Merge branch 'main' into docs/macos-local-setup
PRAteek-singHWY Dec 16, 2025
0dffcbc
Merge branch 'main' into docs/macos-local-setup
PRAteek-singHWY Dec 17, 2025
6b450b9
docs(readme): restore original content and add macOS setup notes
PRAteek-singHWY Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
301 changes: 222 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,126 +1,269 @@
# OpenCRE readme
# OpenCRE

Go to https://www.opencre.org to see OpenCRE working and more explanation.
OpenCRE stands for Open Common Requirement enumeration. It is an interactive content linking platform for uniting security standards and guidelines. It offers easy and robust access to relevant information when designing, developing, testing and procuring secure software.
Go to [https://www.opencre.org](https://www.opencre.org) to see OpenCRE working and more explanation.
OpenCRE stands for Open Common Requirement enumeration. It is an interactive content linking platform for uniting security standards and guidelines. It offers easy and robust access to relevant information when designing, developing, testing and procuring secure software.

OpenCRE consists of:
- The application: a python web and cli application to access the data, running publicly at opencre.org
- The catalog data: a catalog of Common Requirements (CREs)
- The mapping data: links from each CRE to relevant sections in a range of standards
- Tools and guidelines to contribute to the data and to run the application locally

* The application: a python web and cli application to access the data, running publicly at opencre.org
* The catalog data: a catalog of Common Requirements (CREs)
* The mapping data: links from each CRE to relevant sections in a range of standards
* Tools and guidelines to contribute to the data and to run the application locally

# Contribute code or mappings
To see how you can contribute to the application or to the data (catalog or standard mappings), see [Contributing](docs/CONTRIBUTING.md).

To see how you can contribute to the application or to the data (catalog or standard mappings), see [Contributing](docs/CONTRIBUTING.md).
We really welcome you!

# Roadmap

For a roadmap please see the [issues](https://github.com/OWASP/OpenCRE/issues).

# Running your own OpenCRE

You are free to use the public opencre application at opencre.org. Apart from that, you can run your own if you want to include your own security standards and guidelines for example. We call that myOpenCRE.

### Locally
## Locally

### Docker

#### Docker
The easiest way to run OpenCRE locally is by running the published docker container.
You can do so by running:
`docker run -p 5000:5000 ghcr.io/owasp/opencre/opencre:latest`
After the container has finished downloading the remote information you can access it in [localhost](http://127.0.0.1:5000)
If you want to develop on OpenCRE or docker is not available in your environment, you can alternatively run it via CLI

#### Command Line
```bash
docker run -p 5000:5000 ghcr.io/owasp/opencre/opencre:latest
```

After the container has finished downloading the remote information you can access it in [http://127.0.0.1:5000](http://127.0.0.1:5000).

If you want to develop on OpenCRE or docker is not available in your environment, you can alternatively run it via CLI.

### Command Line

To run outside of Docker you need to install OpenCRE.
To install this application you need python3, yarn and virtualenv.
* Clone the repository:
<pre>git clone https://github.com/OWASP/common-requirement-enumeration </pre>

* (Recommend) Create and activate a Python virtual environment:
<pre>python3 -m venv venv
source venv/bin/activate </pre>
Clone the repository:

```bash
git clone https://github.com/OWASP/common-requirement-enumeration
```

(Recommended) Create and activate a Python virtual environment:

```bash
python3 -m venv venv
source venv/bin/activate
```

Install dependencies:

```bash
make install
```

Download the latest CRE graph from upstream by running:

```bash
make upstream-sync
```

Keep in mind that until [Issue #534](https://github.com/OWASP/OpenCRE/issues/534) is fixed you won't have access to gap analysis results locally.

To run CRE locally then you can do:

```bash
make dev-flask
```

To run the CLI application, you can run:

```bash
python cre.py --help
```

To download a remote CRE spreadsheet locally you can run:

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

To add a remote spreadsheet to your local database you can run:

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

To run the web application for development you can run:

```bash
make start-containers
make start-worker

# in a separate shell
make dev-flask
```

Alternatively, you can use the dockerfile with:

```bash
make docker && make docker-run
```

Some features like Gap Analysis require a neo4j DB running, you can start this with:

```bash
make docker-neo4j
```

Environment variables for app to connect to neo4jDB (default):

* `NEO4J_URL` (neo4j//neo4j:password@localhost:7687)

To run the web application for production you need gunicorn and you can run from within the cre_sync dir:

* Install dependencies
<pre> make install </pre>
```bash
make prod-run
```

---

### macOS Notes (Apple Silicon & Intel)

OpenCRE is fully supported on macOS. The following notes are optional and intended to help contributors running OpenCRE locally on macOS systems.

#### Prerequisites

Install required tools using Homebrew:

* Download the latest CRE graph from upstream by running
<pre>make upstream-sync </pre>
Keep in mind that until [Issue #534](https://github.com/OWASP/OpenCRE/issues/534) is fixed you won't have access to gap analysis results locally
```bash
brew install [email protected] yarn make
```

* To run CRE locally then you can do:
<pre> make dev-flask </pre>
> Note: Python 3.11 is recommended. Newer Python versions may cause dependency incompatibilities.

To run the CLI application, you can run
<pre>python cre.py --help</pre>
Verify Python version:

To download a remote cre spreadsheet locally you can run
<pre>python cre.py --review --from_spreadsheet < google sheets url></pre>
```bash
python3 --version
```

To add a remote spreadsheet to your local database you can run
<pre>python cre.py --add --from_spreadsheet < google sheets url></pre>
#### Virtual Environment Setup

To run the web application for development you can run
<pre>
$ make start-containers
$ make start-worker
Create and activate a virtual environment explicitly using Python 3:

# in a seperate shell
$ make dev-flask
</pre>
```bash
python3 -m venv venv
source venv/bin/activate
```

Alternatively, you can use the dockerfile with
<pre>make docker && make docker-run</pre>
Upgrade pip:

Some features like Gap Analysis require a neo4j DB running, you can start this with
<pre>make docker-neo4j</pre>
enviroment varaibles for app to connect to neo4jDB (default):
- NEO4J_URL (neo4j//neo4j:password@localhost:7687)
```bash
pip install --upgrade pip
```

To run the web application for production you need gunicorn and you can run from within the cre_sync dir
<pre>make prod-run</pre>
#### Dependency Installation

Install dependencies using the standard workflow:

### Using the OpenCRE API
See [the myOpenCRE user guide](docs/my-opencre-user-guide.md) on using the OpenCRE API to for example add your own security guidelines and standards.
```bash
make install
```

If you encounter build issues, ensure Xcode Command Line Tools are installed:

```bash
xcode-select --install
```

#### Running Locally

Sync upstream CRE data (requires internet access):

```bash
make upstream-sync
```

Then start the local server:

```bash
make dev-flask
```

The application will be available at:

```
http://127.0.0.1:5000
```

> Tip: For most macOS users, running via Docker is the simplest and most reliable approach.

---

## Using the OpenCRE API

See [the myOpenCRE user guide](docs/my-opencre-user-guide.md) on using the OpenCRE API to, for example, add your own security guidelines and standards.

## Docker building and running

You can build the production or the development docker images with:

```bash
make docker-prod
make docker-dev
```

### Docker building and running
You can build the production or the development docker images with
`make docker-prod` and `make docker-dev` respectively
The environment variables used by OpenCRE are:

```
- NEO4J_URL
- NO_GEN_EMBEDDINGS
- FLASK_CONFIG
- DEV_DATABASE_URL
- INSECURE_REQUESTS
- REDIS_HOST
- REDIS_PORT
- REDIS_NO_SSL
- REDIS_URL
- GCP_NATIVE
- GOOGLE_SECRET_JSON
- GOOGLE_CLIENT_ID
- GOOGLE_CLIENT_SECRET
- LOGIN_ALLOWED_DOMAINS
- OpenCRE_gspread_Auth
```
- name: NEO4J_URL
- name: NO_GEN_EMBEDDINGS
- name: FLASK_CONFIG
- name: DEV_DATABASE_URL
- name: INSECURE_REQUESTS # development or TLS terminated environments only
- name: REDIS_HOST
- name: REDIS_PORT
- name: REDIS_NO_SSL
- name: REDIS_URL # in case REDIS_HOST and REDIS_PORT are unavailable
- name: GCP_NATIVE # if there are ambient GCP credentials, only useful for VERTEX chatbot
- name: GOOGLE_SECRET_JSON # if not running on GCP
- name: GOOGLE_CLIENT_ID # useful for login only
- name: GOOGLE_CLIENT_SECRET # useful for login only
- name: LOGIN_ALLOWED_DOMAINS # useful for login only
- name: OpenCRE_gspread_Auth # useful only when importing data, possible values 'oauth' or 'service_account'
```
You can run the containers with `make docker-prod-run` and `make-docker-dev-run`

### Developing

You can run backend tests with
<pre>make test</pre>
You can run get a coverage report with
<pre>make cover</pre>
Try to keep the coverage above 70%

You can run the containers with:

```bash
make docker-prod-run
make docker-dev-run
```

## Developing

You can run backend tests with:

```bash
make test
```

You can get a coverage report with:

```bash
make cover
```

Try to keep the coverage above 70%.

---

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![GitHub Super-Linter](https://github.com/OWASP/common-requirement-enumeration/workflows/Lint%20Code%20Base/badge.svg)](https://github.com/marketplace/actions/super-linter)
[![Main Branch Build](https://github.com/OWASP/common-requirement-enumeration/workflows/Test/badge.svg?branch=main)](https://github.com/OWASP/OWASP/common-requirement-enumeration/workflows/Test)
[![Main Branch Build](https://github.com/OWASP/common-requirement-enumeration/workflows/Test/badge.svg?branch=main)](https://github.com/OWASP/common-requirement-enumeration/workflows/Test)

[![Issues](https://img.shields.io/github/issues/owasp/common-requirement-enumeration)](https://github.com/OWASP/common-requirement-enumeration/issues)
[![Issues](https://img.shields.io/github/issues/owasp/common-requirement-enumeration)](https://github.com/OWASP/common-requirement-enumeration/issues)
[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
![GitHub contributors](https://img.shields.io/github/contributors/owasp/common-requirement-enumeration)
![GitHub last commit](https://img.shields.io/github/last-commit/owasp/common-requirement-enumeration)
Expand Down