This repository contains the Open Cybersecurity Schema Framework (OCSF) Schema Server source code. The schema server is an HTTP server that provides a convenient way to browse and use the OCSF schema.
You can access the OCSF schema server, which is running the latest released schema, at schema.ocsf.io.
The schema server can be also used locally. To do that clone the ocsf-server and ocsf-schema repositories and follow the instruction below to build and run the schema server.
git clone https://github.com/ocsf/ocsf-schema.gitgit clone https://github.com/ocsf/ocsf-server.gitcd ocsf-server
docker build -t ocsf-server .Change the /path/to to your local OCSF schema directory (use an absolute path). Note, the -p 8443:8443 parameter enables HTTPS with a self-signed SSL certificate.
docker run -it --rm --volume /path/to/ocsf-schema:/app/schema -p 8080:8080 -p 8443:8443 ocsf-serverFor example, if the ocsf-schema and ocsf-server repos were cloned to the local directory ~/github-projects, this would be the proper replacement for /path/to:
docker run -it --rm --volume ~/github-projects/ocsf/ocsf-schema:/app/schema -p 8080:8080 -p 8443:8443 ocsf-server(Note that paths used for volume mounts with docker run cannot be relative.)
To access the schema server, open localhost:8080 or localhost:8443 in your Web browser.
docker run -it --rm --volume /path/to/ocsf-schema:/app/schema --volume /path/to/ocsf-schema:/app/extension -e SCHEMA_EXTENSION="/app/extension" -p 8080:8080 -p 8443:8443 ocsf-serverThe docker-compose environment enables development without needing to install any dependencies (apart from Docker/Podman and docker-compose) on the development machine.
When run, the standard _build and deps folders are created, along with a .mix folder. If the environment needs to be recreated for whatever reason, the _build folder can be removed and docker-compose brought down and up again and the environment will automatically rebuild.
docker-compose upThen browse to the schema server at http://localhost:8080
NOTE: it is not necessary to run the server with docker-compose up first in order to test the schema (or run any other commands in the development container).
# docker-compose run ocsf-elixir mix test
Creating ocsf-server_ocsf-elixir_run ... done
Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg.
Finished in 0.00 seconds (0.00s async, 0.00s sync)
0 failures
Randomized with seed 933777
source docker-source.sh# testschema
Creating ocsf-server_ocsf-elixir_run ... done
Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg.
Finished in 0.00 seconds (0.00s async, 0.00s sync)
0 failures
Randomized with seed 636407
Optional environment variables can be placed in a .env file in the root of the repo to change the default behavior.
An .env.sample is provided, and the following options are available:
SCHEMA_PATH=../ocsf-schema # Set the local schema path, eg. ../ocsf-schema, defaults to ../ocsf-schema
OCSF_SERVER_PORT=8080 # Set the port for Docker to listen on for forwarding traffic to the Schema server, defaults to 8080
ELIXIR_VERSION=otp-25-alpine # Set the Elixir container version for development, defaults to otp-25-alpine
This section describes how to build and run the OCSF Schema server.
The Schema server is written in Elixir using the Phoenix Web framework.
The Elixir site maintains a great installation page, see https://elixir-lang.org/install.html for help.
Elixir uses the mix build tool, which is included in the Elixir installation package.
mix local.hex --force && mix local.rebar --forceChange to the schema directory, fetch and compile the dependencies:
cd ocsf-server
mix do deps.get, deps.compilemix compileYou can use mix test command to test the changes made to the schema. For example to ensure the JSON files are correct or the attributes are defined.
Assuming the schema repo has been cloned in ../ocsf-schema directory, then you can test the schema with this command:
SCHEMA_DIR=../ocsf-schema SCHEMA_EXTENSION=extensions mix testIf everything is correct, then you should not see any errors or warnings.
You can use the Elixir's interactive shell, IEx, to start the schema server use:
SCHEMA_DIR=../ocsf-schema SCHEMA_EXTENSION=extensions iex -S mix phx.serverNow you can access the Schema server at localhost:8080 or localhost:8443.
You can use the following command in the iex shell to force reloading the schema with extensions:
Schema.reload(["<extension folder>", "<extension folder>", ...])Reload the core schema without extensions:
Schema.reload()Reload the schema only with the linux extension (note the folder is relative to the SCHEMA_DIR folder):
Schema.reload(["extensions/linux"])Reload the schema with all extensions defined in the extensions folder (note the folder is relative to the SCHEMA_DIR folder):
Schema.reload(["extensions"])Reload the schema with extensions defined outside the SCHEMA_DIR folder (use an absolute or relative path):
Schema.reload(["/home/schema/cloud", "../dev-ext"])The schema server uses a number of environment variables.
| Variable Name | Description |
|---|---|
| HTTP_PORT | The server HTTP port number, default: 8080 |
| HTTPS_PORT | The server HTTPS port number, default: 8443 |
| SCHEMA_DIR | The directory containing the schema, default: ../ocsf-schema |
| SCHEMA_EXTENSION | The directory containing the schema extensions, relative to SCHEMA_DIR or absolute path |
| RELEASE_NODE | The Erlang node name. Set it if you want to run more than one server on the same computer |
SCHEMA_DIR=../ocsf-schema SCHEMA_EXTENSION=extensions iex -S mix phx.server