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.

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, 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.

# Combined workflow for testing and syncing RunReveal detections
name: RunReveal Detections CI
 
on:
  # Trigger on push to main branch affecting detections/
  push:
    branches: [main]
    paths:
      - "detections/**"
  # Trigger on pull requests to main affecting detections/
  pull_request:
    branches: [main]
    paths:
      - "detections/**"
  # Allow manual triggering from the Actions tab
  workflow_dispatch:
 
jobs:
  # Always test detections on PRs and pushes to main
  test-detections:
    name: Test Detections
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: test-runreveal-detections
        uses: runreveal/detection-sync-action@v2
        with:
          directory: ./detections
          token: ${{ secrets.RUNREVEAL_TOKEN }}
          workspace: ${{ secrets.RUNREVEAL_WORKSPACE }}
          dry-run: true
 
  # Only sync detections after test passes, and only on push to main or manual dispatch
  sync-detections:
    name: Sync RunReveal Detections
    needs: [test-detections]
    if: |
      (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - 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