Skip to content

docker.md

Latest commit

 

History

History
156 lines (120 loc) · 4.77 KB

docker.md

File metadata and controls

156 lines (120 loc) · 4.77 KB

Container images

The openwec container image enables you to test and deploy openwec easily. It contains two precompiled binaries: openwec (cli) and openwecd (server).

Getting openwec image

From ghcr.io

The openwec container image is automatically built using Github Actions:

  • On each commit to the main branch, the image is built and pushed with the main tag.
  • When a version tag is pushed, the image is built and pushed with a tag corresponding to that version. The latest version tag can be retrieved using the latest tag.

The openwec container image comes in two flavors: the default, Debian-based image, and a more minimal Alpine-based option tagged with the -alpine suffix.

Example:

$ docker pull ghcr.io/cea-sec/openwec:latest
$ docker pull ghcr.io/cea-sec/openwec:latest-alpine

Building the image by yourself

Dockerfiles are present in the docker directory of the repository. You can build it using:

$ docker build -t openwec -f docker/openwec.Dockerfile .

To build the Alpine image:

$ docker build -t openwec -f docker/openwec-alpine.Dockerfile .

Using openwec image

The openwec image does not come with any predefined configuration.

Configuration file

openwec reads its configuration from /etc/openwec.conf.toml. See Getting Started for a basic configuration example.

  • If you use SQLite backend, you should configure its path to /var/lib/openwec/db/openwec.sqlite (so that the openwec user used inside the container can write to it) and mount a Docker volume at this directory.
  • If you use Kerberos authentication, make sure to mount the keytab file in the container (read-only).
  • If you use TLS authentication, make sure to mount TLS certificates and keys in the container (read-only).

Subscriptions

The openwec image entry point looks for subscription configuration files (see Subscription) in /etc/openwec.d/ and loads them on startup. You should mount your configuration files in this directory (read-only).

If one of your outputs uses the Files driver, you should configure its path in /var/lib/openwec/data/ (so that the openwec user used inside the container can write files).

Example with SQLite, Kerberos authentication and Files driver

  1. In a new directory, create a file named openwec.conf.toml with the following content:
# openwec.conf.toml
[[collectors]]
hostname = "openwec.realm.local" # FIXME
listen_address = "0.0.0.0"
listen_port = 5985

[collectors.authentication]
type = "Kerberos"
service_principal_name = "http/openwec.realm.local@REALM.LOCAL" # FIXME

[database]
type = "SQLite"
path = "/var/lib/openwec/db/db.sqlite"

[server]
keytab = "/etc/openwec.keytab"

[logging]
verbosity = "info"
access_logs = "stdout"

  1. Get a keytab containing the keys for http/openwec.realm.local@REALM.LOCAL and name it openwec.keytab.

  2. Create a directory conf, and put inside your subscription configuration files (see Subscription). For example, we configure two subscriptions:

  • simple:
# conf/01-simple.toml

# Unique identifier of the subscription
uuid = "e493fa95-4810-4c61-8ac7-7fa8d028a144"
# Unique name of the subscription
name = "simple"

# Subscription query
query = """
<QueryList>
    <Query Id="0" Path="Application">
        <Select Path="Application">*</Select>
        <Select Path="Security">*</Select>
        <Select Path="Setup">*</Select>
        <Select Path="System">*</Select>
    </Query>
</QueryList>
"""

# Subscription outputs
[[outputs]]
driver = "Files"
format = "Raw"
config = { path = "/var/lib/openwec/data/simple/{ip}/{client}/messages" }
  • test:
# conf/02-test.toml

# Unique identifier of the subscription
uuid = "b50df578-b814-4fad-9d6a-1215fddc0f96"
# Unique name of the subscription
name = "test"

# Subscription query
query = """
<QueryList>
    <Query Id="0" Path="Application">
        <Select Path="Microsoft-Windows-WinRM/Operational">*</Select>
    </Query>
</QueryList>
"""

[options]
content_format = "RenderedText"

[[outputs]]
driver = "Files"
format = "RawJson"
config = { path = "/var/lib/openwec/data/test/{ip}/{client}/messages" }

You should end up with the following tree structure:

.
├── conf
│   ├── 01-simple.toml
│   └── 02-test.toml
├── openwec.conf.toml
└── openwec.keytab
  1. Start the openwec container with named volumes for files (openwec-data) and the SQLite database (openwec-db):
$ docker run --rm -it \
    -v ./openwec.conf.toml:/etc/openwec.conf.toml:ro \
    -v openwec-db:/var/lib/openwec/db \
    -v openwec-data:/var/lib/openwec/data \
    -v ./openwec.keytab:/etc/openwec.keytab:ro \
    -v ./conf/:/etc/openwec.d/:ro \
    -p 5985:5985 \
    ghcr.io/cea-sec/openwec:latest