This project contains the core libraries and executables for the CISA Cyber Hygiene program. It coordinates the multiple scanners and allows the creation of pretty reports.

The cyhy-core library requires a configuration be created. The default location for this file is /etc/cyhy/cyhy.conf. An example configuration is below.

[DEFAULT]
default-section = cyhy-ops-ssh-tunnel-docker-mac
report-key = master-report-password

[cyhy-ops-ssh-tunnel-docker-mac]
database-uri = mongodb:https://<MONGO_USERNAME>:<MONGO_PASSWORD>@host.docker.internal:27017/cyhy
database-name = cyhy

[cyhy-ops-ssh-tunnel-docker]
database-uri = mongodb:https://<MONGO_USERNAME>:<MONGO_PASSWORD>@localhost:27017/cyhy
database-name = cyhy

[cyhy-ops-staging-read]
database-uri = mongodb:https://<MONGO_USERNAME>:<MONGO_PASSWORD>@database1:27017/cyhy
database-name = cyhy

The CyHy commands implemented in the docker container can be aliased into the host environment by using the procedure below.

Alias the container commands to the local environment:

eval "$(docker run cisagov/cyhy-core)"

To run a CyHy command:

cyhy-tool status NASA

Whenever an aliased CyHy command is executed, it will use the current working directory as its home volume. This limits your ability to use absolute paths as parameters to commands, or relative paths that reference parent directories, e.g.; ../foo. That means all path parameters to a CyHy command must be in the current working directory, or a subdirectory.

By default, the container will look for your CyHy configurations in /etc/cyhy. This location can be changed by setting the CYHY_CONF_DIR environment variable to point to your CyHy configuration directory. The commands will also attempt to run using the cisagov/cyhy-core image. A different image can be used by setting the CYHY_CORE_IMAGE environment variable to the image name.

Example:

export CYHY_CONF_DIR=/private/etc/cyhy
export CYHY_CORE_IMAGE=cisagov/cyhy-core

If you want to include a MaxMind GeoIP2 database in the docker image you must provide a key and optionally the type of key to Docker. The default type is "lite", but if you have the subscription license you can instead use the "full" type.

The following commands show how to build the Docker container for cyhy-core.

docker build --tag cisagov/cyhy-core .

docker build --tag cisagov/cyhy-core \
             --build-arg maxmind_license_key=<license key> .

docker build --tag cisagov/cyhy-core \
             --build-arg maxmind_license_type="full" \
             --build-arg maxmind_license_key=<license key> .

WARNING: Be careful- you really don't want to push a Docker image to the public Docker Hub if it was built with your MaxMind license key!

The helper script generate_cyhy_docker_image.sh can be used to automate building and saving a Docker image.

Usage:
  generate_cyhy_docker_image.sh [options]

Options:
  -k, --maxmind-key KEY  The MaxMind GeoIP2 key to use (defaults to
                         retrieval from AWS SSM)
  -n, --image-name NAME  Image name to use [default: cisagov/cyhy-core].
  -t, --image-tag TAG    Image tag to use [default: latest].
  -h, --help             Display this message.

Notes:
- Requires Docker and optionally the AWS CLI to run.

./generate_cyhy_docker_image.sh

./generate_cyhy_docker_image.sh --maxmind-key <license key>

./generate_cyhy_docker_image.sh --image-name cisagov/cyhy-env

./generate_cyhy_docker_image.sh  --image-tag testing

./generate_cyhy_docker_image.sh --image-name cisagov/cyhy-env --image-tag testing

Required third party libraries can be installed using:

pip install --requirement requirements.txt

Required configurations: The commander will read /etc/cyhy/commander.conf If you do not have this file, please create one (even if empty)

IP Address Geolocation Database: The geolocation database is not included in the source tree due to size and licensing. Please cd into the var directory and run the get-geo-db.sh script to get the latest database.

If you are developing the source the following installation will allow in place editing with live updates to the libraries, and command line utilities.

sudo pip install numpy
sudo pip install geos
sudo pip install --requirement requirements.txt