Open Security Compliance

ReadMe (Version 3.1)

Introduction
1. Glossary
2. Things to note
Setting up cowctl CLI
1. Prerequisites
2. Instructions
Getting Started
1. Developing a Rule
2. Executing a rule
Other Essential Features

🚀 Deployment Options

The setup script (setup-mcp.sh) offers two deployment modes:

📘 MCP + No-Code UI Deployment Guide — Requires an Anthropic API key

No-Code Web UI + AI-powered rule creation via MCP
7 services including MCP integration, Goose AI Assistant support
External MCP Client Support (Goose Desktop/CLI, Claude Desktop/Code)

📗 No-Code UI Deployment Guide — No API key needed

No-Code Web UI for manual rule creation and management
4 services: Web UI, API Service, Reverse Proxy, MinIO Storage
Lightweight setup, can be upgraded to MCP mode later

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

| Name | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ApplicationType | A package for a specific application type that provides reusable methods and validations, which can be imported and used within tasks to perform application-related operations. | | Task | A task is an automatic unit of work in OpenSecurityCompliance. This can be written in Go or Python, and can be unit tested. | | Rule | A 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 ApplicationType classes and the CredentialType 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

Note: 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.

Note: 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)

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

Docker (v24.0.6 or higher)
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

Clone the OpenSecurityCompliance Repo.
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.

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 lines (as shown below).

Rename the .credentials.env.template in the etc/ folder to .credential.env. This env file which contains predefined CredentialType values, can be used to configure additional CredentialTypes for your custom ApplicationTypes. These CredentialTypes will be available as environment variables that can be used in your tasks.
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.

<details> <summary>Mac or Ubuntu</summary> sh build_and_run.sh </details> <details> <summary>Windows (PowerShell)</summary> ./windows_setup/build_and_run.ps1 </details>

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.

Getting started

GitHub Use Case Note: To enhance your understanding of this readme, we will provide examples throughout using a GitHub use case. The use case is a very simple control that enforces protection for all branches in your GitHub repository. This control can be automated by accessing your GitHub repository, listing all branches, and verifying whether protection is enabled for each of them.

1. Developing a rule

The development step consists of 4 sub-steps as demonstrated in the GIF below.

1.1 Creating a credential-type

As illustrated in the GIF above, CredentialTypes play a crucial role in enabling the task code to access ApplicationTypes. Therefore, let's begin by defining the specific type of CredentiaTypes required for this purpose.

1.1.1 cowctl init credential-type Initialize a new CredentialType (config YAML file) with the init credential-type command. You'll be prompted for a name and version.

You can then locate the CredentialType YAML file at catalog/gobalcatalog/yamlfiles/credentialtypes. Customize the attributes in it to match your CredentialType, like connecting to GitHub with a Personal Access Token (1 attribute) or username/password (2 attributes).

<details> <summary>Here is an example from the GitHub use case.</summary> A few attributes are omitted here for simplicity.

apiVersion: v1alpha1
kind: credentialType
meta:
  name: GithubTokenCred
  displayName: Github Token Credential
  version: 1.1.1 # optional.
spec:
  extends: [] # optional.
  attributes:
    - name: personalAccessToken
      displayName: Personal Access Token
      secret: true # optional. boolean: true | false. If true, this attribute value should go to the vault
      required: true
      multiSelect: false
      dataType: STRING
      allowedValues: [] # optional
      defaultValue: # optional

</details>

1.1.2 cowctl create credential-type After defining the attributes in the CredentialType YAML file, run create credential-type to validate it and copy it to catalog/globalcatalog/declaratives/credentialtypes, where the subsequent cowctl commands will reference it.

You will need to choose the YAML file for the CredentialTypes that you've just created.

1.2 Creating an application-type

An ApplicationType is essentially a class in Go or Python, where you can implement these:

a validation method to veri

Opensecuritycompliance

Install / Use

README