CoGuard
CoGuard is a comprehensive static analysis tool for IT infrastructure configurations (cloud and on-premise).
Finding and fixing misconfigurations and security vulnerabilities for IaC, devices, containers, cloud settings, and applications. Reduce the noise of CVE notifications and focus on small improvements for big wins.
Table of Contents
- Why CoGuard
- Introduction to the CLI
- Installation
- Usage
- Screenshots
- Supported Technologies & Roadmap
- Learn More
Why CoGuard
Infrastructure as Code (IaC) is here to stay. The versioning and continuous scanning of every layer of your IT (on premise and cloud) infrastructure is crucial.
CoGuard's team observed that there are a lot of policy checks on the layers communicating to the cloud, but the configurations inside specific compute devices such as physical servers, virtual machines or containers are mostly neglected, or have silo-ed solutions at best.
In order to have static analysis practices for IaC that go as deep as the available tools for code, every layer needs to be equally addressed.
In our practice, we observed that, at times, even an awareness of locations of configuration files is lacking. This is why we created a command line tool helping with discovering those configurations, and scanning them.
CoGuard's CLI combines multiple ways to extract and scan your configuration files.
- Docker images: Modern container scanners check for versions of software and libraries installed on those containers, and establish if there are common known vulnerabilities and exposures (CVEs). The CoGuard CLI is trying to find known configuration files for e.g. web servers or databases, and scans these for security and best practice. Additionally, the last Docker file used to create an image is analyzed as well.
- Project Repositories: Modern projects store their infrastructure information inside code repositories for better visibility and traceability. CoGuard can extract Infrastructure as Code (IaC) files and other supported configurations. It also searches for external container references and scans these as well.
- Cloud configurations not represented as IaC: Many organizations have either not yet started using IaC tools, or have a hybrid model of part IaC, part manual management. For these cases, we can extract cloud configurations for AWS, Azure or GCP, and scan them as well. The same applies to platforms with their own management layer, such as a Cloudera cluster managed by Cloudera Manager.
Introduction to the CoGuard CLI
This project is the command line interface to CoGuard, with additional functionality for the auto-discovery of configuration files.
The current release scans for:
- Docker images and its contents,
- project folders (such as GitHub Repositories) and
- will automatically extracted cloud configurations from the AWS, Azure and GCP
It searches for known configuration files of different software packages (like webservers, databases, etc.), and scans these configurations for configuration errors and security best practices.
Installation Instructions
Pre-Requisites
You need to have python3, pip3 and docker installed on your system.
Instructions for different operating systems and commands to be used for Python and Pip are provided below.
Ubuntu/Debian
sudo apt install -y python3 python3-pip
Alpine
apk add python3 py3-pip
CentOS/Fedora
sudo yum install -y python3 python3-pip
Arch Linux
sudo pacman -S python python-pip
Mac OS
Assuming you are using [Homebrew](https://brew.sh), you have to runbrew install python3
Windows
Download Python3 for Windows using this link, and install it.
Installation
CoGuard CLI can either be pulled from this repository and used
directly, or installed via pip:
pip3 install coguard-cli
This is a reminder that it is a requirement to have Docker installed locally.
Installation remarks
Remark 1: It may happen that the folder where pip is installing packages is not
in included in PATH. We have observed it on some Ubuntu installations, and on
Homebrew Mac installs. For the Linux case, such as Ubuntu,
you can find the binary usually under $HOME/.local/bin/coguard, i.e. you run
$HOME/.local/bin/coguard docker-image [<YOUR-IMAGE-NAME-OR-ID>]
For the Mac case, it is often installed under ~/Library/Python/<YOUR_PYTHON_VERSION>/bin/coguard, i.e. you would run
~/Library/Python/<YOUR_PYTHON_VERSION>/bin/coguard docker-image [<YOUR-IMAGE-NAME-OR-ID>]
If you omit the image ID parameter, CoGuard will scan all the images currently stored on your device.
Remark 2: Windows users need to be allowed to create and read symbolic links. This can be achieved using three options:
Option 1
1. Run the CoGuard execution as admin temporarily. This can be achieved by opening the PowerShell or command prompt as administrative user (right click on the icon), or by issuing the command ```shell Start-Process powershell -Verb runAs ``` inside an already open command/Powershell window.Option 2
2. Run Windows in Developer Mode (instructions on how to run Windows as a developer can be found [here](https://docs.microsoft.com/en-us/gaming/game-bar/guide/developer-mode)).Option 3
3. Run CoGuard on a Linux virtual machine, e.g. using the Windows subsystem for Linux. This is commonly installed with Docker Desktop for Windows. If you do not have it installed, then installation instructions can be found [here](https://docs.microsoft.com/en-us/windows/wsl/install). The installation steps for CoGuard using WSL are equivalent to the pre-requisites and installation steps described for Linux (dependent on the distribution you choose).How to use it
Any of the following options requires you to create a CoGuard account. After completion, this image check will return the findings of CoGuard on this particular image. You can view the latest historical scan results when logging in to https://portal.coguard.io.
Scanning Docker images and containers
Using the CoGuard CLI, you can run a scan on your local Docker images using
coguard docker-image [scan] [<YOUR-IMAGE-NAME-OR-ID>]
For containers, similarly, you would execute
coguard docker-container [scan] [<YOUR-CONTAINER-NAME-OR-ID>]
Scanning project repository folders
Using the CoGuard CLI, you can run a scan on your local file repositories using
coguard folder [scan] [<PATH-TO-FOLDER>]
Extracting and scanning cloud configurations
Using the CoGuard CLI, you can run a scan a current snapshot of your
cloud configurations. For AWS, Azure and GCP, this requires you to
have the respective cloud CLI tools (aws-cli for AWS, gcloud for
GCP or az for Azure) installed and authenticated on your device.
coguard cloud [scan] {aws, azure, gcp}
The extraction may take a couple of minutes, depending on your internet speed.
Cloudera
Cloudera deployments are inspected through the Cloudera Manager API instead of a cloud CLI. CoGuard walks the services and roles of the managed cluster and retrieves the generated configuration files of each role, i.e. the configuration as it is actually deployed on the hosts.
coguard cloud [scan] cloudera --cloudera-manager-url https://cm.example.com --cloudera-manager-user admin
The password is read from the CLOUDERA_MANAGER_PASSWORD environment
variable, and prompted for interactively if it is not set.
For scheduled use, the command coguard-cloudera-check is installed
alongside the CLI. It reads the event feed of Cloudera Manager to find out
whether the configuration of the cluster has changed, and runs the scan
when it has, which makes it suitable for a systemd timer or a cron job.
A second command, coguard-cloudera-banner, takes the result of a scan and
shows a summary of it in the header of Cloudera Manager, so that the state of
the configuration is visible where the cluster is administered. It writes one
line of plain text after whatever the banner already says, and replaces only
that line on the next run, so a banner which is already in use is kept. With
--header-color RED, it also tints the header bar of Cloudera Manager while
there are findings and puts the colour back once there are none, which is the
difference between a line somebody may read and a page nobody can open without
noticing.
For a signal which is harder to walk past than a line of text, csd/
holds a custom service descriptor which adds a Configuration Assurance service
to the cluster. Its health is the state of the configuration: good while the
scans come back clean, bad while there are findings, in the same channel
Cloudera Manager already alerts an operator through. Installing it means a jar
in /opt/cloudera/csd and a restart of the Cloudera Manager server, which
csd/README.md describes along with the limits of the
mechanism.
Details and all available options can be found in the Cloudera integration documentation.
General scan
To get a general scan, which includes all locally installed Docker images, anything in the current-working directory (recursive) and any installed cloud provider authentication, simply run
coguard scan
Inclusion into CI/CD pipeline
CoGuard can be included as a step in your CI/CD pipeline. CoGuard generates the necessary templates and scripts.
GitHub Actions is available in the current release. To generate e.g. a GitHub Actions YAML which automatically scans your repository on pull request/push, simply type
coguard pipeline github add <PATH_TO_YOUR_REPOSITORY>
A pipeline can also gate a deployment instead of a repository. Adding --cloud cloudera generates a workflow which scans a running Cloudera cluster and fails
the job on findings, which is how a change to such a cluster is gated —
Cloudera Manager itself offers no hook to block one. See
doc/integrations/cloudera.md.
Future support is planned for GitLab CI/CD, Jenkins, Bamboo, CircleCI, etc.
Screenshot and further information
Here is a screenshot of a sample scan:
As you can see, CoGuard also analyzes the last Dockerfile used.
The checks are gathered from different security controls, but also directly from the user manuals of these software projects. At times, known issues for certain versions and security remediations specific to a certain version are being taken into account as well.
Supported Technologies and Roadmap
CoGuard currently supports the the auto-discovery of configuration files inside Docker containers, folders and cloud configuration exports. The full list of configurations files can be found in this folder.
- Supported Applications & Infrastructure as Code
- Apache Kafka
- Apache Tomcat
- Apache WebServer
- CloudFormation
- Dockerfile
- ElasticSearch
- Helm
- Kerberos
- Kubernetes
- MongoDB
- MySQL
- Netlify
- NGINX
- OpenTelemetry Collector
- PostgreSQL
- Redis
- RethinkDB
- TerraForm
- Ansible
- Jenkins
- OpenAPI
- Apache Cassandra
- BitBucket Pipelines
- Apache Druid
- Apache Spark
- Flink
- SystemD
- Supported Cloud Hosts
- AWS
- Azure
- GCP
- Cloudera (via Cloudera Manager)
- OVH Cloud
- Hetzner Cloud
- Vultr
- Roadmap (Future Support Planned)
- Bamboo
- CircleCI
- Puppet
- Contact us for full list or to add a specific request or custom rules
This list will expand in the future. In addition, we are scanning the Dockerfile used to create the images, and will add some Linux configuration files in the near future.
Learn more
1 maintainer
Metadata
1 maintainer
Release files for coguard-cli 0.3.16
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| coguard_cli-0.3.16.tar.gz | 209.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| coguard_cli-0.3.16-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 522.3 kB
Release files / coguard_cli-0.3.16.tar.gz
| Download URL | coguard_cli-0.3.16.tar.gz |
|---|---|
| Size | 209.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64644ab392f491ffc18cd09b0357c4da4593de2e60d65b3782fc543d5bf3c1b8
|
|
BLAKE2b-256 checksum How to use checksums |
a259ac41ee840c92425f01f67ab6a79c6eebc8a2eb31c63e3fffc66d24a12e1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / coguard_cli-0.3.16-py3-none-any.whl
| Download URL | coguard_cli-0.3.16-py3-none-any.whl |
|---|---|
| Size | 313.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f4d2c53b45c73a4905cb9635acc3089054915a23e065273e90b3a3ece5b657f
|
|
BLAKE2b-256 checksum How to use checksums |
d8696a46ebdf41ff340a5efdd192ae813b7b9c5b0d3120a4ee8d17861e21147a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
