README.md

title	path	category
Developer Guide	docs/developer-guide	develop

Extending secureCodeBox

Developing the SCB Operator

Prerequisites

Golang

The operator is written in Golang. To build the operator you will need to install Go.

Minikube or Kind

For local development we recommend to use Minikube or kind. If you are using MacOS or Windows you can also use the kubernetes cluster included within Docker for Mac/Windows. All of these tools will enable you to run a local kubernetes cluster on your development machine.

Operating Your Local Kubernetes Cluster

To operate your (local) Kubernetes cluster you will need to install kubectl and helm

macOS

For macOs simply use Homebrew to install all the tools:

brew cask install docker
brew install go helm

After that start the Docker.app and go to it's settings and start Kubernetes.

Minio

For your local development you will need a S3 compatible storage. We would recommend to use Minio inside a Podman or docker container.

If You Want to Use Podman

podman run \
  --name minio \
  -p 9000:9000 \
  minio/minio \
  server /data

If You Want to Use Docker

docker container run \
  --name minio \
  -p 9000:9000 \
  -d \
  --rm \
  minio/minio \
  server /data

In the Minio management GUI you will need to add a new bucket for the operator. The default credentials for your minio instance are minioadmin:minioadmin. You might change those. Go to the management UI at http://localhost:9000/ and add a new bucket. After creating your bucket you will need to specify some environment variables to enable the operator to use the bucket. For that export these variables:

export S3_ACCESS_KEY="your-minio-access-key"
export S3_SECRET_KEY="your-minio-secret-key"
export S3_BUCKET="name-of-your-bucket"
export S3_USE_SSL="false" # This ensures that the operator will connect even without HTTPS
export S3_ENDPOINT="127.0.0.1:9000"

You can save time by using direnv to export these variables in your project. If you use direnv just add a file .s3_credentials with your Minio credentials.

Build and Run the Operator

To build an run the operator you can simply execute make in the operator directory of this repository:

cd operator
make

This will produce the operator as bin/manager. If you wonder why the operator is named manager (the resulting binary). The reason for that is in Kubernetes a combination of more than one controller is called controller-manager or short manager. In contrast operator is created by the community to name a controller-manager which controls custom resources and hence we use custom resources. (see https://book.kubebuilder.io/ for further information)

To run the operator locally you can simply execute make run in the operator directory of this repository:

NOTICE: You will need to uninstall the operator with helm -n securecodebox-system uninstall securecodebox-operator from your local cluster, if you've installed it via helm. Unless both operators try to work on the same cluster which may cause unexpected behavior.

cd operator
make run

How to add a New Security Scanner

ScanType Definition

✍ Following...

Parsing SDK

1. Install the dependencies npm install
2. Update the parser function here: ./parser/parser.js
3. Update the parser tests here: ./parser/parser.test.js
4. Run the test suite: npm test

How to Integrate a New Hook

✍ Following...

HookType Definition

✍ Following...

Hook SDK

✍ Following...

Guidelines

✍ Following...

Coding Guidelines

✍ Following...

JSON

We're using snake_case (lower case) for json attributes. If an enum type is used as attribute its converted to lower case. If it's an value it's always used UPPERCASE. This is to hold the attribute api consistent, but make sure Enums are recognized as enums.

{
    "id": "e18cdc5e-6b49-4346-b623-28a4e878e154",
    "name": "Open mysql Port",
    "description": "Port 3306 is open using tcp protocol.",
    "category": "Open Port",
    "osi_layer": "NETWORK",
    "severity": "INFORMATIONAL",
    "attributes": {
      "protocol": "tcp",
      "port": 3306,
      "service": "mysql",
      "mac_address": null,
      "start": "1520606104",
      "end": "1520606118",
      "ip_address": "127.0.0.1",
      "state": "open"
    },
    "location": "tcp://127.0.0.1:3306"
  }