Deployment

A Github Action is available to use in your Github workflows. You can find the source code for it at, https://github.com/runreveal/detection-sync-action (opens in a new tab).

Tokens and Workspace

To use the action you will need to store your generated API token and workspace ID in your Github account to be used as variables in the action. It is recommended to store your API token as a secret so that it remains hidden.

To generate an API token navigate to your RunReveal settings page (opens in a new tab), and scroll down to Generate New Token.

Give the token a name and set the role as cibot. This will allow the workflow to edit detections but make no other changes to your account.

Copy the token value and save it for later you will need to add it into your repo settings.

You will also need to save your workspace ID that will be referenced in the workflows. This can also be found on your RunReveal settings page under the item labeled Your workspace’s unique identifier.

Workflows

In your Git repo include a directory called .github/workflows in the root of your repo. In this folder you can include the yaml files for your Github workflows, below are examples of two that we use to verify and sync our detections.

# This workflow will run when a new PR is created merging into the main branch.
# It will perform the dry-run command and verify the yaml is valid for your detections.
name: Test Detections
 
# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  pull_request:
    branches: [ main ]
 
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
 
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    name: Sync RunReveal Detections
 
    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v4
 
      - name: sync-runreveal-detections
        uses: runreveal/detection-sync-action@v2
        with:
          directory: ./detections
          token: ${{ secrets.RUNREVEAL_TOKEN }}
          workspace: ${{ secrets.RUNREVEAL_WORKSPACE }}
          dry-run: true

# This workflow will run when a commit is pushed to the main branch.
name: Sync
 
# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
 
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
 
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    name: Sync RunReveal Detections
 
    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v4
 
      - name: sync-runreveal-detections
        uses: runreveal/detection-sync-action@v2
        with:
          directory: ./detections
          token: ${{ secrets.RUNREVEAL_TOKEN }}
          workspace: ${{ secrets.RUNREVEAL_WORKSPACE }}

Update the token and workspace inputs with the names that you used when creating your secrets/variables.

These workflows assume all detections are stored in a subdirectory called detections.

As of now, you can only sync one directory per workspace. Any detections that are managed by detection as code and are not listed in your directory will be automatically removed from your account.

Github Repo Secrets

Navigate to the settings page for your repo and go to Secrets and variables -> Actions.

Under the secrets tab, you can create a New repository secret. Your name should be the value that you used in your workflow, in our example we used RUNREVEAL_TOKEN and RUNREVEAL_WORKSPACE. We would create two new secrets with those names and paste the appropriate values that we saved from earlier.

Commit Detections

You are now ready to start uploading your detections. Make a commit to the repo containing all of your detections under the directory listed in your workflow, in our example that would be ./detections/.

An important note about the flow of detection as code.

If you exported all of your workspace's detections using the runreveal detections export cli command or from the UI, then uploading those detections will give an error as there will be a naming collision.

In order to allow Github actions to work as expected you will need to run the command runreveal detections sync -d ./detections -o, the -o flag will override all detections that have a matching name regardless where that detection is being managed from.

Uploading Detections Enrichments