Open Cybersecurity Schema Framework Server
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.
ocsf-schema
) repository
Clone the OCFS schema (git clone https://github.com/ocsf/ocsf-schema.git
ocsf-server
) repository
Clone the OCFS schema server (git clone https://github.com/ocsf/ocsf-server.git
Build a server docker image
cd ocsf-server
docker build -t ocsf-server .
Run the server docker image
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-server
To access the schema server, open localhost:8080
or localhost:8443
in your Web browser.
Run the server docker image with a local schema extension:
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-server
Development with docker-compose
The 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.
Run the ocsf-server and build the development container
docker-compose up
Then browse to the schema server at http://localhost:8080
Testing the schema with docker-compose
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
Set aliases to avoid docker-compose inflicted RSI
source docker-source.sh
Using aliases to run docker-compose commands
# 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
Using environment variables to change docker-compose defaults
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
Local Usage
This section describes how to build and run the OCSF Schema server.
Required build tools
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.
Building the schema server
Elixir uses the mix
build tool, which is included in the Elixir installation package.
Install the build tools
mix local.hex --force && mix local.rebar --force
Get the dependencies
Change to the schema directory, fetch and compile the dependencies:
cd ocsf-server
mix do deps.get, deps.compile
Compile the source code
mix compile
Testing local schema changes
You 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 test
If everything is correct, then you should not see any errors or warnings.
Running the schema server
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.server
Now you can access the Schema server at localhost:8080
or localhost:8443
.
Reloading the schema
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 with the default dev
extension (note the folder is relative to the SCHEMA_DIR
folder):
Schema.reload(["extensions/dev"])
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:
Schema.reload(["/home/schema/cloud", "../linux"])
Runtime configuration
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