Getting Started

Prerequisites

  • A GitHub repository (how-to)
  • A GitOps engine (e.g. Argo CD) is installed and configured to listen on a directory of the repository
  • To enforce policy compliance in the cluster, OPA Gatekeeper must be installed. See the policies reference for details.

GitHub App Installation

To access repositories Syncier Security Tower GitHub application needs to be granted permissions. This is how it's done:

  1. Go to Syncier Security Tower on the GitHub Marketplace
  2. Select an appropriate plan and click the green install button and then confirm your choice on the next screen
  3. Select repositories that should be accessed by Syncier Security Tower and click "Install"
  4. After you've been redirected to Syncier Security Tower, click on "Authorize" to log in with your GitHub account

Jumpstart with Template Repository

The fastest way to create a cluster repository in your account that works well with Syncier Security Tower is following these steps:

  1. Go to https://github.com/securitytower/cluster-template
  2. Click on the button "Use this template"
  3. Select an "Owner" (there are multiple entries if you have access to different GitHub organizations) Select an account / organizations where you installed Syncier Security Tower.
  4. The "Repository name" is up to you. However, we follow the convention to start the name with cluster- if the repository represents a Kubernetes cluster.
  5. The remaining settings are optional. "Include all branches" is not necessary as we only work on the main branch.
  6. Click the button "Create repository from template"

If you installed Syncier Security Tower only to specific repositories, make sure to give the GitHub app access to this one, too. Then, you should see your new cluster on https://app.securitytower.io.

Cluster Configuration

If you have not instantiated the template repository of the previous section, you will need to create a directory in the root of the target repository with the name .securitytower. In order to define a cluster, a yaml file must exist in the .securitytower directory with at least the following content:

apiVersion: securitytower.io/v1alpha1
kind: Cluster
metadata:
  name: example-cluster # cluster name
spec:
  policies:
    path: path/to/policies # directory in the default branch of the cluster repository

Now go to app.securitytower.io to see if you configured everything correctly. After logging in and authorizing the GitHub App you should see the cluster you just set up appear in the list.

This reference page contains additional information about cluster configuration.

Application Configuration

Application stages can be used to track and propagate application versions across multiple repositories.

To configure application stages you need to create a .yaml file (e.g. example_application.yaml) inside the .securitytower directory of the repository with the following content:

apiVersion: securitytower.io/v1alpha1
kind: Application
metadata:
  name: example-application # application name
spec:
  stages:
    - name: example-app-production
      resources:
        repository: https://github.com/example/example-production
        revision: master # git branch name
        path: cluster/namespaces/example-app
      targetNamespace: example-app
      previousStage: example-app-staging
    - name: example-app-staging
      resources:
        repository: https://github.com/securitytower/example-staging
        revision: master
        path: cluster/namespaces/example-app
      targetNamespace: example-app

In this example, the Application example-app has the two stages example-app-staging and example-app-production. You can create any number of stages with any complexity.

After that the Application should appear in the Application section of Syncier Security Tower. If you used the template repository, please make sure that all configuration files in the .securitytower directory are updated with the correct repository URLs. Note that all references in Application configs must be updated, when changing the cluster name.

This reference page contains additional information about application configuration.