Skip to main content

Introduction

Open Security Compliance is a standalone rules engine framework that allows customers to automate and orchestrate security rules. Rules can be deployed in a standalone mode in docker and can be executed through a CLI called cowctl. This user-friendly CLI can be used to perform useful utility functions such as initializing and scaffolding, allowing developers to develop, unit test rules for automating, and running them standalone in your docker environment.

Glossary​

NameDescription
Application PackageApplication package contains the application scope validations and other common methods related to the application
TaskA task is an automatic unit of work in OpenSecurityCompliance. This can be written in Go or Python, and can be unit tested.
RuleA Rule, which is a collection of tasks, can be mapped to a control in any assessment. When an assessment is run, the mapped rules are executed to assess the controls they are mapped to.

Things to note​

  • OpenSecurityCompliance has a folder named catalog, which in turn contains the sub-folders globalcatalog and localcatalog where we store the rules, tasks, etc.
    • The globalcatalog serves as a folder for publicly accessible rules, tasks and other related components.
    • By default, rules, tasks, and other artifacts (except the application classes and the credential classes) are initialized in the localcatalog. To maintain code privacy, you can include this folder in the gitignore file.
    • To precisely choose an item from the globalcatalog or initialize an item within the globalcatalog, utilize the --catalog=globalcatalog flag.
    • A rule present in globalcatalog won't be able to access a task from localcatalog while the other way is possible.
  • cowctl CLI has Minio as a dependency. Minio is required to manage all the file outputs from tasks.
  • Changes to environment values, located within the etc folder in the form of environment files, will take effect only upon restarting cowctl.

Setting up cowctl CLI​

info

If you've already set up the CLI, you can skip this section and proceed by executing sh run.sh (in Mac or Ubuntu) or ./windows_setup/run.ps1 (in Windows). Then enter cowctl to access the command line interface.

warning

While the CLI functionality on Windows has been partially tested, it may not yet offer full stability or support.

Prerequisites​

The cowctl CLI is tested/certified in:

  • Mac (Min version: Monterey)
  • Ubuntu (Min version: 22.04.3)
  • PowerShell in Windows (Min Version: 11)

Please make sure to have the following installed in your machine.

  • Docker (v24.0.6 or higher)
    • In case of Windows, you might need WSL2 too, with Hyper-V enabled.
  • Docker Compose (v2.22.0 or higher)
  • Python (v3.10 or higher)
  • Golang (v1.21.3 or higher)
  • yq (to process YAML, JSON, XML, CSV and properties documents from the CLI). Refer to the yq GitHub page for the install instructions.

Instructions​

  1. Clone the OpenSecurityCompliance Repo.

  2. Since OpenSecurityCompliance utilizes a containerized Minio instance, you need to configure Minio with credentials, by setting up username and password of your choice, within the etc/policycow.env file.

My Image

  1. If you are running this on a Linux machine, please make sure to update the docker-compose file (docker-compose.yaml) and comment the specified line (as shown below).

My Image

  1. Rename the .credentials.env.template in the etc/ folder to .credential.env. This env file which contains predefined credential values, can be used to configure additional credentials for your custom applications. These credentials will be available as environment variables that can be used in your tasks.

  2. To start the cowctl docker container, run the build_and_run script in the OpenSecurityCompliance main folder (as explained in the OS specific collapsibles below). This step typically requires anywhere from 5 to 10 minutes to finish. In case you run into any errors related to loading metadata for certain libraries, rename the key credsStore to credStore in the docker config file in your system (For instance in Mac: ~/.docker/config.json). This is a known issue in Docker. Note: You may have to restart docker.

Mac or Ubuntu
 sh build_and_run.sh
Windows (PowerShell)
 ./windows_setup/build_and_run.ps1
  1. Once it is built, type cowctl and you will get in to the prompt (as shown below).
    1. Explore the Command & Flag suggestions by typing --help or -h.
    2. You can filter names from a list of names using the "/" key when using commands such as cowctl exec.
    3. Type exit to get out of the cowctl prompt any time.

My Image