This is the multi-page printable view of this section.
Click here to print.
Return to the regular view of this page.
Documentation
About
m9sweeper is a free and easy kubernetes security platform. It integrates industry standard open source utilities
into a one-stop-shop kubernetes security tool.
Why m9sweeper
Today, technology is relied upon for the goods and services we need.
Everything from agriculture to transportation to good and services is orchestrated through
information systems. And increasingly, these information systems are deployed using kubernetes.
Kubernetes is a wonderful tool, but few administrators know much about kubernetes security
And even in organizations where its administrators have learned about kubernetes security, few administrators are given
adequate time to secure their clusters.
m9sweeper makes this easy by giving you a solid platform for securing your kubernetes cluster.
The learning curve is low. The tools it uses are rock-solid and endorsed by the Linux Foundation. All are even covered
by the CKS (Certified Kubernetes Security) examination, which tests ones knowledge of how to secure a kubernetes
cluster. m9sweeper makes kubernetes security finally accessible (and free!) for every kubernetes administrator.
Getting Started
The easiest way to get started is to visit our registration portal, which will
walk you through step-by-step setting up m9sweeper in your organization.
If you do not want to register, you can go to our easy install tutorial.
Support
Intelletive Consulting is the official maintainer of the project.
It is actively maintained and patched by them, free of charge.
They also offer enterprise support of the product, which could
include everything from customer feature development, bugfixing, security analysis', as well as
support and implementation of the m9sweeper product.
Bug Reporting
If you find bugs or issues, please report them to use on github.
m9sweeper makes it easy to orchestrate the implementation of a number of free security tools:
Trivy: CVE Scanner
Kubesec: Deployment Best Practices
Kube Bench: CIS Benchmarks
OPA Gatekeeper: Compliance and Security Policies
Kube Hunter: Cluster Penetration Testing
Project Falco: Intrusion Detection (Coming Soon)
1 - License
Apache License 2.0
m9sweeper is licensed under the Apache License 2.0.
It was originally produced by Intelletive Consulting,
owned by
Jacob Beasley and
Jason Woodman. Once feature complete, we chose to open source
instead of selling it as a licensed product because we saw a huge need for the product and were deeply passionate
about open source.
While the software is open source, but we do offer professional services for enterprises. This is ultimately how
we fund ongoing support and maintenance for the product.
Please contact us if you want information about a professional support contract.
A support contract can include professional installation, support, monitoring, managed upgrades, and even coordinating
security fixes and remediation in your environment. We also are available, at times, to do Kubernetes DevOps
work.
We have released several open source products, including:
2 - Overview
What is it?
m9sweeper is an app for securing your kubernetes cluster. It does so by orchestrating a number of
kubernetes security capabilities:
- CVE Scanning with Trivy
- Compliance with Gatekeeper
- CIS Benchmarking with Kube Bench
- Pen Testing with Kube Hunter
- Secure Deployments with KubeSec
- Intrusion Detection with Project Falco (Coming Soon)
If you are a beginner or experienced administrator, m9sweeper is a one-stop-shop to secure a
kubernetes environment in a matter of hours, not days or weeks, as well as to continue to
assess and report on your kubernetes security posture.
Why do I want it?
If you deploy apps on kubernetes, you should absolutely be making sure you are doing so securely.
m9sweeper makes it extremely easy to deploy and scan your cluster and its applications. It is
the cheapest and fastest way to understand your security posture, and it walks you through
securing a cluster step-by-step.
Where should I go next?
We recommend you proceed to the getting started guide.
3 - Getting Started
M9sweeper deploys as an app in your Kubernetes cluster. We like to say that is Kubernetes-native; that is to say,
you can deploy it entirely inside of kubernetes. You do not need to install complicated applications in your Kubernetes
nodes. This makes it very safe and easy to install.

It also can be installed in a hub-and-spoke way, with a single m9sweeper install monitoring multiple kubernetes
clusters. This requires that you ingress traffic to m9sweeper, and is preferred if you have a lot of kubernetes clusters.

There are 3 ways to get started:
3.1 - Registration Portal
Our registration portal walks you through installing m9sweeper.
To make installing m9sweeper as easy as possible, we have created a registration portal that lets you
sign up your company to manage m9sweeper.
It includes a wizard that walks you through installing m9sweeper end-to-end, letting you just fill in the blanks.


When you are done, it generates a helm install command for you, which could be used to install it using
our helm chart with a single command.

Register |
Login
3.2 - Easy Install
Install m9sweeper with a one-liner.
You can install m9sweeper using our helm chart. This
is a one-line cli command that installs m9sweeper. Change the default username/password to your
own username/password and the API Key to something random/unpredictable.
helm repo add m9sweeper https://helm.m9sweeper.io/chartrepo/m9sweeper && \
helm repo update && \
helm upgrade m9sweeper m9sweeper/m9sweeper --install --wait --create-namespace --namespace m9sweeper-system \
--set-string dash.init.superAdminEmail="super.admin@m9sweeper.io" \
--set-string dash.init.superAdminPassword="password" \
--set-string global.jwtSecret="changeme" \
--set-string global.apiKey="YOUR-API-KEY"
Many more options are available. For serious enterprise deployments, we recommend creating a helm
values.yaml file and versioning this in a code repository to make upgrades easier.
For more information, see the advanced install guide.
3.3 - Advanced Install
Full list of installation options using m9sweeper’s helm chart.
Install
License
To claim a free license go to m9sweeper licensing. Claiming a license
is optional, but if you setup a license our online portal will enable remote monitoring. We can notify you, for example,
if you a new version is available or if your environment is no longer being monitored for some reason.
Installation
We recommend putting your configuration in a values.yaml file and then deploying our app using helm. This
example uses “helm upgrade –install”, which is an idempotent way of installing and/or upgrading the app. This
is repeatable and the same command can be run regardless of whether you intend to upgrade or install the app.
helm repo add m9sweeper https://helm.m9sweeper.io/chartrepo/m9sweeper && \
helm repo update && \
helm upgrade m9sweeper m9sweeper/m9sweeper --install --wait --create-namespace --namespace m9sweeper-system \
--values values.yaml --version latest
When implementing for our customers we automate this in a CICD pipeline. Upgrades can be done simply by changing
which chart version you are deploying. By default, it installs the latest version, but you can add
–version to install a specific version of m9sweeper.
At a minimum, you MUST specify these 4 values:
--set-string dash.init.superAdminEmail="super.admin@m9sweeper.io"
--set-string dash.init.superAdminPassword="password"
--set-string global.jwtSecret="changeme" \
--set-string global.apiKey="YOUR-API-KEY"
Validating Webhook
If you wish to have m9sweeper prevent applications from booting up that are not compliant with your specified
policies, you will need the validating webhook. This installs automatically and should work without any configuration.
However, if you are running in Azure Kubernetes Service OR have the kubernetes api firewalled in such a way that it
cannot reach out to a remote url for the validating webhook, then you will need to
setup an nginx reverse proxy
using our reverse proxy self-installer. This script will generate a CA Certificate Bundle and Nginx configuration
to enable the reverse proxy to work in Azure Kubernetes Service.
Falco bulkhead Deployment
Depending on your environment, Falco can send an immense amount of alerts to M9sweeper. This could overload the application
and cause it to crash. To avoid this, there is an option to deploy multiple instances of M9sweeper that only take api requests sent to /api/falco.
falco:
bulkhead: true
replicas: 1
When set to true, this will create a seperate deployment appended with “-falco”, a service, and when applicable, a service monitor.
This also edits ingress, routing all API calls from Falco, into the bulkhead deployment.
Configuration Options
If postgresql is enabled, then it will deploy postgres db. Set to false to use an external postgres DB
If rabbitmq is enabled, then it will deploy rabbitmq. Set to false to use an external rabbitmq.
The following table lists the configurable parameters of the chart and the default values.
Parameter |
Description |
Default |
postgresql properties |
|
|
|
|
|
global.postgres.host |
postgresql hostname |
minesweeper-postgres |
global.postgres.username |
postgresql username |
postgres |
global.postgres.password |
postgresql password |
postgres |
global.postgres.database |
postgresql database |
postgres |
global.postgres.port |
postgresql port |
5432 |
|
|
|
rabbitmq properties |
|
|
|
|
|
global.rabbitmq.host |
rabbitmq hostname |
minesweeper-rabbitmq |
global.rabbitmq.port |
rabbitmq port |
5672 |
global.rabbitmq.username |
rabbitmq username |
guest |
global.rabbitmq.password |
rabbitmq password |
guest |
global.rabbitmq.queueName |
rabbitmq queue name |
trawler_queue |
global.jwtSecret |
Provide a secret string that will be used to sign JWT tokens |
asdfasdfasd |
global.baseUrl |
URL will be used in email templates to reference a http link to Dash |
localhost:3000 |
global.apiKey |
Provide a secret string that will be the default api key used for integrations |
1234567890 |
global.trawlerApiKey |
Provide a secret string that will be the default api key for trawler |
1234567890 |
global.kubeBenchApiKey |
Provide a secret string that will be the default kube bench api key |
1234567890 |
global.kubeHunterApiKey |
Provide a secret string that will be the default kube hunter api key |
1234567890 |
global.falcoApiKey |
Provide a secret string that will be the default falco API key |
1234567890 |
|
|
|
Dash Properties |
|
|
|
|
|
dash.image.registry |
Registry for Dash Helm chart |
dockerhub.io |
dash.image.repository |
Repository for Dash Helm chart |
m9sweeper/dash |
dash.image.tag |
Tag for Dash Helm chart |
latest |
|
|
|
values that will be used to initialize the Dash database during installation |
|
|
|
|
|
dash.init.clusterGroupName |
Dash Init clusterGroupName |
default-cluster-group |
dash.init.clusterName |
Dash Init clusterName |
default-cluster |
dash.init.superAdminEmail |
Dash Init superAdminEmail |
admin@test.com |
dash.init.superAdminPassword |
Dash Init superAdminPassword |
superadmin4me |
dash.init.licenseKey |
Dash Init licenseKey for permission to run project |
`` |
dash.init.instanceKey |
Dash Init instanceKey for permission to run project |
`` |
dash.init.docker.registries.name |
Dash Init Registry Name |
`` |
dash.init.docker.registries.hostname |
Dash Init Registry Hostname |
`` |
dash.init.docker.registries.login_required |
Dash Init login_required |
`` |
dash.init.docker.registries.username |
Dash Init Registry Username |
`` |
dash.init.docker.registries.password |
Dash Init password |
`` |
Trawler Configuration |
|
|
trawler.image.registry |
Registry for Trawler Helm chart |
dockerhub.io |
trawler.image.repository |
Repository for Trawler Helm chart |
m9sweeper/trawler |
trawler.image.tag |
Tag for Trawler Helm chart |
latest |
|
|
|
Dash Email Properties |
|
|
|
|
|
dash.email.method |
Email method options are SMTP or SENDGRID |
SMTP |
dash.email.smtp.host |
Choose smtp host |
localhost |
dash.email.smtp.port |
Choose smtp port |
465 |
dash.email.smtp.tlsRequired |
Choose smtp tls authentication required or not |
true |
dash.email.smtp.user |
Choose smtp username |
smtp |
dash.email.smtp.password |
Choose smtp password |
smtp |
dash.email.sendgridApiKey |
Choose email sendgridApiKey |
'' |
dash.email.senderEmail |
Choose email senderEmail |
`` |
dash.email.enableSystemErrorEmail |
Enable/disable system error email notifications |
false |
dash.email.systemErrorMailTo |
The email address to send system error emails to |
`` |
|
|
|
Dash Ingress Properties |
|
|
|
|
|
dash.ingress.hosts |
Add lists of hosts |
`` |
dash.ingress.path |
Add backend endpoint path |
/ |
dash.ingress.k8sIngress.enabled |
Set true to enable nginx ingress |
false |
dash.ingress.k8sIngress.annotations |
Add annotations for nginx ingress |
kubernetes.io/ingress.class: nginx |
dash.ingress.k8sIngress.tls.secretName |
K8s secret where certificate is stored |
tls-secret |
dash.ingress.k8sIngress.tls.hosts |
Write hostname for apply tls |
`` |
Istio Config - VirtualService, DestinationRule, Gateway (optional), PeerAuthentication (optional) |
|
|
dash.ingress.istio.enabled |
Set true to enable Istio or false to disable |
false |
dash.ingress.istio.gateways.create |
Set true to enable create istio gateways |
false |
dash.ingress.istio.gateways.gatewayRefs |
Provide name to create istio gateway |
istio-system/example |
dash.ingress.istio.loadBalancerType |
Write name of loadBalancerType |
ROUND_ROBIN |
dash.ingress.istio.mtlsMode |
Set mtls mode, options are: PERMISSIVE or STRICT |
PERMISSIVE |
4 - Concepts
How to use M9sweeper
4.1 - Image Scanning
Using Trivy to scan images for CVEs and other issues.
Trivy is one of the best tools for scanning Kubernetes images, and m9sweeper
can coordinate scanning images deployed to your cluster, rescanning of those images, as well as
blocking images from deploying if they do not meet your minimum criteria for compliance.
M9sweeper also allows you to create exceptions or have your employees' request exceptions be approved when they
do not have the time to fix an issue in the moment but still want to allow applications to deploy.
For a full list of trawler configuration options, see the trawler reference guide
4.1.1 - Automating Scanning
How to automatically scan your images.
By default, m9sweeper will scan all images that it sees deployed in your cluster that have not been scanned.
Also, you can configure the Image Rescan Period (Days) when setting up policies to automatically rescan images. This
will then rescan any images currently running in your cluster if they have not been scanned in a certain number of
days.

4.1.2 - Scanning in CICD Pipelines
Learn how to give developers feedback in your CICD pipelines.
You can automatically scan images using trawler in your automated CICD pipelines. The easiest way to do this is by
running trawler from the command line using the container image. It will look something like this.
docker run \
--env "M9SWEEPER_URL=XXX" \
--env "M9SWEEPER_API_KEY=XXX" \
--env "CLUSTER_NAME=XXX" \
--env "DOCKER_IMAGE_URL=XXX" \
-it m9sweeper/trawler trawler scan
Note that you will need to provide an API key as well as the name of the cluster you are scanning it for
so that it can authenticate with m9sweeper. You will have to run a scan for each cluster you plan to deploy it to because
each cluster might have different policies setup.
4.1.3 - Enforcing Compliance
Keeping your cluster safe.
4.1.3.1 - Setting Up Policies
Define how much risk you are willing to tolerate.
Policy Settings
In the organization settings, you can click on policies in the left navigation and configure one or more policies
for your cluster. These policies define what criteria an image must meet to be considered compliant in the cluster.
It looks something like this.

Only policies and scanners that are active and required will be used in determing whether an image is compliant. Also,
when evaluating an image for a cluster, only policies that are configured for that cluster will be applied.
Configuring Trivy Requirements
When configuring the trivy scanner, you can define the maximum number of vulnerabilities for each category. The
defaults that come pre-installed essentially will block any image with a fixable major or critical vulnerability.

4.1.3.2 - Installing Webhook
Installing the Webhook
In order to have m9sweeper enforce image scanning compliance in your cluster, you need to install a validating webhook
in your cluster. This should be done automatically by m9sweeper during the setup process, but if for some reason it
was not you can click “Update Kubeconfig” on your cluster’s settings page and run through the setup wizard again
to have it install the webhook for you.

4.1.3.3 - Enabling Enforcement
How to enable enforcement.
To enable enforcement, you need to make your way to the Cluster settings for your cluster and check the box that
enables webhook enforcement.

Once checked, anything that is not compliant with the policies you have setup will be prevented from deploying. Note
that this only works if you have installed the webhook during the setup process.
4.1.3.4 - Exceptions
How to manage policy exceptions.
Sometimes, for practical reasons, you may need to allow something with a known security issue to continue to be deployed
in an environment. You can do this using exceptions.
Creating Exceptions
Your team can create exceptions when the need arises.

Temporary Exceptions
When a new exception is discovered such as through a nightly image rescan, you may want automatically provide teams
with a certain amount of time (lets say a week) before it would block their deployments. This can be done through the
use of a temporary exception.
To enable this feature, you need to edit the policy that is setup for your cluster(s) and check the box (see below) and
set how many days the temporary exceptions should be active.

When new temporary exceptions are created, it will email all of your admins to review and decide what to do. They should
notify your software development teams if the issue should be resolved right away and/or change the end date on the
exception.
Exception Statuses
Active: Active exceptions are the only exceptions that will be used when validating image compliance, and only
if the current date is within the exception’s start and end date.
In Review: When an exception is submitted for review, it will be in this status. It will not be used when validating
an image’s compliance, but someone should review to decide whether it is a risk your organization is willing to take.
Inactive: The exception will be ignored when validating image compliance.
Requesting Exceptions
When viewing an image, if a team member who is NOT an admin believes an exception is required, they can request an
exception. This exception falls into the In Review status and will not be active, but it does provide a forum for
your team to request exceptions and for someone else (such as your security/ops team) to review and approve the
exception. They would approve the exception by changing its status to Active.

Exception Types
Exception types are available as options: Policy and Override.
- Policy: Allow listed policy(s) to be bypassed. When this type is chosen, user should also select scanner(s) and policy(s) for the desired exception.
- Override: When this type is chosen, user should select an alternate severity level for desired exception.
4.2 - kube-bench
How to use kube-bench with M9sweeper to perform penetration testing.
kube-bench will run a scan of your cluster to compare its configuration against the Center for Internet Security (CIS)
benchmarks. This is a good way to check for obvious configuration issues, such as allowing anonymous users. It deploys as an
application in your cluster and then accesses the Kubernetes APIs to see how your cluster is configured.
We recommend setting up kube-bench to run as a nightly cron job so that you can see the effect of any changes you
make to your cluster.
First, you need to install kube-bench and set it up to upload its results to m9sweeper. To do this, go to kube-bench
for your cluster and click on Run Audit in the top right.

Then, you can use the wizard to generate a CLI command that will install kube-bench using our helm chart as a cron job
or one-time job in your cluster. It will upload its results back to the API (and you should see an API key in the url).
Note that this will only work IF you have enabled traffic ingressing or otherwise allowed kube-bench to pipe its
results back to the m9sweeper dash app.

And then this will display a summary report, like this:

You can click on any line to expand it and see directions for remediation.

4.3 - kube-hunter
How to use kube-hunter with M9sweeper to perform penetration testing.
kube-hunter will run a non-invasive (or invasive, if you want) penetration test of your cluster. It deploys as an
application in your cluster and then attempts to explore and see what all it is able to do. It reports back on any
concerns that you should be aware of.
We recommend setting up kube-hunter to run as a nightly cron job so that you can see the effect of any changes you
make to your cluster.
First, you need to install kube-hunter and set it up to upload its results to m9sweeper. To do this, go to kube-hunter
for your cluster and click on Run Audit in the top right.

Then, you can use the wizard to generate a CLI command that will install kube-hunter using our helm chart as a cron job
or one-time job in your cluster. It will upload its results back to the API (and you should see an API key in the url).
Note that this will only work IF you have enabled traffic ingressing or otherwise allowed kube-hunter to pipe its
results back to the m9sweeper dash app.

And then this will display a summary report, like this:

4.4 - KubeSec
How to use kubesec with M9sweeper to coach you towards secure pod configuration.
KubeSec coaches you about how to make your deployments more secure. You can find it in the left navigation after
selecting a cluster.

To get started, select a pod you want to evaluation and click Run KubeSec.

It will then display a report of your pods' compliance and any improvements that could be made.

4.5 - Gatekeeper
How to use Gatekeeper with M9sweeper to define and enforce rules for things deployed to Kubernetes.
4.5.1 - Getting Started
M9sweeper makes managing gatekeeper constraints and constraint templates easy!
Gatekeeper is a great tool for creating rules for your Kubernetes cluster. You configure
rules using constraint templates and constraints.
Constraint templates, such as this, allow you to define rules using a language called Rego.
apiVersion: templates.gatekeeper.sh/v1beta1
kind: ConstraintTemplate
metadata:
name: k8srequiredlabels
spec:
crd:
spec:
names:
kind: K8sRequiredLabels
validation:
# Schema for the `parameters` field
openAPIV3Schema:
properties:
labels:
type: array
items:
type: string
targets:
- target: admission.k8s.gatekeeper.sh
rego: |
package k8srequiredlabels
violation[{"msg": msg, "details": {"missing_labels": missing}}] {
provided := {label | input.review.object.metadata.labels[label]}
required := {label | label := input.parameters.labels[_]}
missing := required - provided
count(missing) > 0
msg := sprintf("you must provide labels: %v", [missing])
}
Constraints are then created to apply these rules to a particular set of kubernetes entities.
These constraints can also contain configuration parameters, such as which labels are required (in this example).
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
name: ns-must-have-gk
spec:
match:
kinds:
- apiGroups: [""]
kinds: ["Namespace"]
parameters:
labels: ["gatekeeper"]
M9sweeper makes managing your constraint templates and constraints extremely convenient through an easy-to-use user interface.
To get started, you need to install Gatekeeper.
Read more about constraint templates
4.5.2 - Managing Constraints
Using the M9sweeper Interface to Configure Gatekeeper
Managing Constraint Templates
After installing Gatekeeper, your next step is to install constraint templates. You can do this using a CICD pipeline,
or if you are new to this you can use the m9sweeper graphical user interface to install Constraint Templates from our
library of templates.
First, open the Gatekeeper page for your cluster and click on “+Add More” in the top right.

Then, check the boxes on the constraint templates you want to install and click save changes.

After doing this, you will see the list of constraint templates has been installed.
Managing Constraints
Just installing constraint templates alone does not do anything - you also have to apply these constraint templates
to specific workloads / namespaces. This is done through the use of constraints.
If you click on one of your constraint templates, you will be taken to a page that lists all of the constraints
created for this constraint template. After doing so, click “+Add More” to create a constraint for this template.

In this user interface, it will let you set which namespaces and type of entity it applies to. Reasonable defaults
are typically filled in if you used one of our templates.

If properties can be configured, we will automatically generate a user interface for configuring those properties. You
can fill in the required properties.

Do not forget to select whether it is to be in enforcement mode or audit mode. Only enforcement mode is actually
enforced - audit mode is purely used for evaluation purposes.

Click save changes and now you should have your constraint created!

4.5.3 - Reviewing Exceptions
M9sweeper extends Gatekeeper through the use of exceptions!
While gatekeeper constraints can be scoped to specific namespaces or entity types, sometimes you want to create
temporary exceptions for a particular namespace that end at a specific date, or sometimes you want to just target
a specific workload.
In those cases, you can use our exceptions feature. Our exceptions feature will automatically code-generate rego code
nightly, re-evaluating the exceptions every day and taking into account the exception’s status, start date, and end
date. These exceptions work just like image compliance exceptions, except they target gatekeeper constraint templates
rather than image scanning rules.
To use them, be sure and pick Gatekeeper as the exception type:

4.5.4 - Reviewing Pod Compliance
M9sweeper makes seeing a pod’s Gatekeeper compliance extremely easy!
To view a pod’s compliance, navigate to your cluster’s list of workloads. Then, click on the namespace you want to
review.

Next, it will list all pods in the namespace. Note that it re-populates this list hourly.

If you click on a pod, it will list all images in the pod and those images' own compliance.

If you click on the Gatekeeper icon in the top right, it will tell if you if any violations exist and, if so, what
violations exist.

4.6 - Falco
How to install and use Project Falco with M9sweeper to perform runtime security.
What is Falco?
The Falco Project is an open source runtime security tool originally built by Sysdig, Inc.
What does Falco do?
Falco uses system calls to secure and monitor a system, by:
- Parsing the Linux system calls from the kernel at runtime
- Asserting the stream against a powerful rules engine
- Alerting when a rule is violated
For more information, see the Falco Documentation.
Setup and configuration
M9sweeper consumes HTTP requests from Falco in JSON format to present readable information in our UI.
To accomplish this, FalcoSideKick is deployed to give us more control over Falco’s output.
Configuration Notes:
- Set the config.webhook.address value to your instance of M9sweeper.
- Depending on how you are deploying M9sweeper, you might need to set config.webhook.checkcert=false.
- We recommend setting the minimum priority to “error”. For more information see Minimum Priority
Deploy Falco
Add the Helm Chart Repo then install Falco:
helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update
helm install falco falcosecurity/falco \
--create-namespace \
--namespace falco \
--set falco.driver.enabled=true \
--set-string falco.driver.kind=ebpf \
--set falco.tty=true \
--set falco.json_output=true \
--set falco.json_include_output_property=true \
--set falco.http_output.enabled=true \
--set-string falco.http_output.url=http://falcosidekick:2801/ \
--set falcosidekick.enabled=true \
--set-string falcosidekick.config.webhook.address= 'https://M9SWEEPER/api/falco/CLUSTERID/create/?key=FALCO_API_KEY' \
--set falcosidekick.config.webhook.checkcert=true \
--set-string falcosidekick.config.webhook.minimumpriority='error'
Notes:
-
Make sure to change the URL value to point to your M9sweeper instance as well as enter the CLUSTER_ID of whatever cluster it is supposed to save to.
-
We recommend using the EBPF driver, however, if you have issues please refer to to the installation page. Or you may try to use the kernel driver and set “falco.driver.kind=module” above.
Anomaly Detection:
- Anomaly instrusion detection plays vital role in protecting networks against malicious activities.
- It detects unusual behaviors or threats in cloud-native environments with about 100 out-of-the-box security rules.
- Administrators can set up alert to receive email notification based on specific priority (severity) level(s) and email frequency that fits individual application needs.
- Simply go to Falco > Settings
Here is an example of Non-authorized container namespace change violation:
rule: change_thread_namespace
desc: an attempt to change a program/thread\'s namespace (commonly done as a part of creating a container) by calling setns.
condition: syscall.type = setns and not proc.name in (docker, sysdig, dragent)
output: "Namespace change (setns) by unexpected program (user=%user.name command=%proc.cmdline container=%container.id)"
priority: WARNING
Minimum Priority
Falco Alerts can get very noisy. This option lets you choose which levels of alerts you want to include/exclude. Once set, all rules having a priority more severe than this level will be loaded/run. The default is an empty string and includes all alerts. The order is as follows:
- Emergency
- Alert
- Critical
- Error
- Warning
- Notice
- Info
- Debug
For more information on Priority please refer to Falco Docs - Priorities
5 - Reference
Low level reference docs for the various components.
The app consists of several components. Each is documented below.
5.1 - Dash Parameters
Instructions for configuring dash.
The most common way to configure dash is to simply configure environment variables.
Some parameters are only used during the initial installation.
For details about configuring environment variables for the dash app, see the advanced install guide.
Required Parameters
Variable |
Description |
Default |
SECURITY_JWT_SECRET |
JWT Secret for signing JWT Tokens (REQUIRED) |
null |
DEFAULT_SUPER_ADMIN_EMAIL |
Default super admin email to create during installation |
null |
DEFAULT_SUPER_ADMIN_PASSWORD |
Default super admin password to create during installation |
null |
Complete List of ENV Variables
Server Configuration
Variable |
Description |
Default |
DEFAULT_SUPER_ADMIN_EMAIL |
Default super admin email to create during installation |
null |
DEFAULT_SUPER_ADMIN_PASSWORD |
Default super admin password to create during installation |
null |
SECURITY_JWT_SECRET |
JWT Secret for signing JWT Tokens (REQUIRED) |
null |
SERVER_NAME |
Server name (can largely ignore) |
M9sweeper |
SERVER_HOST |
What network adapter to listen on (defaults to all - 0.0.0.0) |
0.0.0.0 |
SERVER_PORT |
What port to listen on |
3000 |
SERVER_BASE_URL |
Server Base URL for things like links in emails |
http://localhost:3000/ |
SERVER_FRONTEND_URL |
Server Frontend URL for things like links in emails |
${SERVER_BASE_URL} |
Database Configuration
Variable |
Description |
Default |
DATABASE_CLIENT |
Database client (do not change) |
postgresql |
DATABASE_CONNECTION_HOST |
Database connection host |
localhost |
DATABASE_CONNECTION_PORT |
Database connection port |
5432 |
DATABASE_CONNECTION_DATABASE |
Database name |
postgres |
DATABASE_CONNECTION_USERNAME |
Database connection username |
postgres |
DATABASE_CONNECTION_PASSWORD |
Datbase connection password |
postgres |
DATABASE_POOL_MIN |
Database connection pool minimum connections |
1 |
DATABASE_POOL_MAX |
Database connection pool maximum connections |
5 |
DATABASE_POOL_IDLETIMEOUT |
Time before connections are reaped when inactive (in milliseconds) |
60000 |
DATABASE_ACQUIRE_CONNECTION_TIMEOUT |
How long to wait for database connections to be acquired before timing out (in milliseconds) |
20000 |
DATABASE_MIGRATION_ENABLED |
Whether to run db migrations (0 to disable) |
true |
DATABASE_MIGRATION_TABLE_NAME |
What table name to use to store which db migrations have been run |
migrations |
DATABASE_MIGRATION_DIRECTORY |
Where to look for db migration scripts (don’t change) |
./migrations |
DATABASE_SEED_ENABLED |
Whether to seed data with the sample data (1 to enable) |
off |
DATABASE_SEED_DIRECTORY |
Where to find db seed data |
./seeds |
DATABASE_DEFAULT_SCHEMA |
Database search path |
public |
Email Configuration
Variable |
Description |
Default |
EMAIL_CONFIG_USE |
What email protocol to use (smtp is all that is supported) |
SMTP |
EMAIL_SMTP_HOST |
SMPT Host (leave blank to disable) |
|
EMAIL_SMTP_PORT |
SMTP Port Number |
465 |
EMAIL_DEBUG |
Whether or not to print out emails to console (set to 1 to enable) |
off |
EMAIL_SMTP_SECURE_CONNECTION |
Whether SMTP is secured (set to 1 to enable) |
off |
EMAIL_SMTP_AUTH_USER |
SMTP user |
|
EMAIL_SMTP_AUTH_PASSWORD |
SMTP password |
|
EMAIL_DEFAULT_SENDER_EMAIL |
Who emails should appear from |
|
EMAIL_SYSTEM_ERROR_REPORT_ENABLE |
Email errors to a system email address (1 to enable) |
off |
EMAIL_SYSTEM_ERROR_REPORT |
Where to email system errors |
|
EMAIL_TEMPLATE_DIR |
Email template directory (mount/provide your own to customize emails) |
dist/email-templates |
RabbitMQ Configuration
Variable |
Description |
Default |
RABBITMQ_ENABLED |
Whether to enable rabbitmq (1 is enabled) |
1 - enabled |
RABBITMQ_HOST_NAME |
RabbitMQ Hostname |
rabbitmq |
RABBITMQ_HOST_PORT |
RabbitMQ Port Number |
5672 |
RABBITMQ_PROTOCOL |
RabbitMQ Protocol (don’t change) |
amqp |
RABBITMQ_USER_NAME |
RabbitMQ Username |
guest |
RABBITMQ_USER_PASSWORD |
RabbitMQ Password |
guest |
MSG_QUEUE_NAME_IMAGE_SCANNER |
RabbitMQ Queue Name for queueing scans |
trawler_queue |
RABBITMQ_VHOST |
RabbitMQ VHost |
/ |
RABBITMQ_FRAMEMAX |
RabbitMQ Framerate |
0 |
File Storage Configuration
Variable |
Description |
Default |
FILE_MANAGEMENT_MAX_FILE_FILE |
|
|
FILE_MANAGEMENT_STORAGE |
File storage method. local or s3 (see multer docs) |
local |
FILE_MANAGEMENT_LOCAL_DEST |
Where to store files |
/mnt/storage |
FILE_MANAGEMENT_S3_REGION |
Amazon S3 Region |
|
FILE_MANAGEMENT_S3_ACCESS_KEY_ID |
AWS Access Key ID |
|
FILE_MANAGEMENT_S3_ACCESS_KEY_SECRET |
AWS Access Key Secret |
|
FILE_MANAGEMENT_S3_BUCKET_NAME |
AWS S3 Bucket Name |
|
Misc App Configuration
Variable |
Description |
Default |
ADMISSION_CONTROLLER_DEFAULT_ACTION |
The default behavior when we fail to validate whether or not an image is compliant for some reason. |
deny |
GATEKEEPER_TEMPLATE_DIR |
Where gatekeeper templates should be loaded from |
dist/gatekeeper-templates |
KUBEBENCH_CONFIG_DIR |
Where to load the kubebench configuration templates |
kube-bench-templates |
RELEASE_NAMESPACE |
Where it should install things when using install wizards |
default |
5.2 - Trawler Parameters
Instructions for Configuring Trawler
Trawler is our app for running scans of your containers. Right now, it is a wrapper around Trivy, one of the best
container scanners available, but it is architected such that other scanners could be supported in the future
(contributions are welcome!).
Functions
Trawler is normally run in listening mode in the cluster and in scanning mode when scanning a single image
from a CICD Pipeline.
You can see how to use one mode or the other by just viewing the built-in help docs.
trawler help
The output looks something like this:
Usage:
trawler [-Dh] [-A=<m9sweeperApiKey>] [-H=<rabbitmqHostname>]
[-p=<rabbitmqPassword>] [-P=<trawlerParallelScanners>]
[-q=<rabbitmqQueueName>] [-t=<rabbitmqPort>] [-u=<rabbitmqUsername>]
[-U=<m9sweeperUrl>] [COMMAND]
Description:
Run Trawler in its RabbitMQ mode where it will monitor a specified RabbitMQ
queue for scan jobs.
Options:
-P, --parallel-scans=<trawlerParallelScanners>
number of scanners that Trawler can run at once
-U, --url=<m9sweeperUrl> URL of the m9sweeper instance
-A, --api-key=<m9sweeperApiKey>
API Key of the m9sweeper instance
-D, --debug whether to enable debug logs
-u, --rabbitmq-user=<rabbitmqUsername>
username of the RabbitMQ server
-p, --rabbitmq-password=<rabbitmqPassword>
password of the RabbitMQ server
-H, --rabbitmq-host=<rabbitmqHostname>
hostname of the RabbitMQ server
-t, --rabbitmq-port=<rabbitmqPort>
port of the RabbitMQ server
-q, --rabbitmq-queue=<rabbitmqQueueName>
name of the RabbitMQ queue to listen on
-h, --help display this help and exit
Commands:
scan Scan a single docker image in the standalone scan mode.
Many settings can be set through the CLI.
Running an image scan is as simple as:
trawler scan alpine:3.15
Environment Variables
In addition to CLI parameters, you can also configure Trawler using environment variables. This is the norm when
deploying a trawler runner to run automatic scans of new, unrecognized images as well as nightly image scans.
General Configuration Options
Parameter |
Description |
Default |
M9SWEEPER_URL |
URL of m9sweeper API (required) |
|
M9SWEEPER_API_KEY |
M9sweeper API Key |
|
TRAWLER_RUN_MODE |
Whether to run as a passive scan worker (rabbitmq) or scan a single image and exit (scan) |
rabbitmq |
Configuration Options for Running a Scan Worker
Parameter |
Description |
Default |
TRAWLER_PARALLEL_SCANNERS |
When passively listening for scans, how many parallel workers to run |
1 |
RABBITMQ_USERNAME |
RabbitMQ Username |
guest |
RABBITMQ_PASSWORD |
RabbitMQ Password |
guest |
RABBITMQ_HOSTNAME |
RabbitMQ Hostname |
rabbitmq |
RABBITMQ_PORT |
RabbitMQ Port Number |
5672 |
RABBITMQ_QUEUE_NAME |
RabbitMQ Queue Name to listen for Scans |
trawler_queue |
Configuration Options for Scanning a Single Image
Parameter |
Description |
Default |
CLUSTER_NAME |
Name of cluster to scan images for |
|
DOCKER_IMAGE_URL |
Docker image url to scan |
|
5.3 - API Docs
API Documentation.
API documentation is provided through swagger, which is available at /doc/. For example, if
you are hosting it at m9s.yoursite.com, it would be available at https://m9s.yoursite.com/doc/
6 - Contributing to m9sweeper
Contribution Guide
Contributing to m9sweeper
DEVELOPING
In our GitHub repository, our CONTRIBUTING.md contains all the steps to get started with hacking m9sweeper.
We are very excited to have you a part of our community!
REPOSITORIES
There are multiple repositories that comprise the m9sweeper platform
@TODO - create repos in github and link them here
m9sweeper Repo: This repo is the main repo that integrates all the other repos together.
Dash Repo: This repo contains the dash application and all the jobs/scripting to install the platform
Trawler Repo: This repo is where the scanning functionality of the platform is developed.
Kube Hunter Repo: Our helm wrapper for the kube-hunter image that is integrated in the m9sweeper platform
Kube Bench Repo: Our helm wrapper for the kube-bench image that is integrated in the m9sweeper platform
BUGS
If you find any bugs or are having any trouble, please contact us by filing an issue in the m9sweeper repo issues.
If you have any updates to our documentation, please make any PRs to our docs repo or click on the Edit this page to be taken directly to the page.