Skip to content

Latest commit

 

History

History
110 lines (80 loc) · 4.35 KB

getting_started.md

File metadata and controls

110 lines (80 loc) · 4.35 KB

Getting Started

This is a guide to help you get started with AlertChain.

Prerequisites

Install tools

Integration services

AlertChain requires alert event sender. Currently, AlertChain supports only HTTP endpoint as an alert event receiver. You can use the following services to send alert events to AlertChain:

Create a new policy repository

You can create a new policy repository by alertchain new command.

$ alertchain new
11:19:40.442 INFO Copy file path=".gitignore"
11:19:40.442 INFO Copy file path="Dockerfile"
11:19:40.443 INFO Copy file path="Makefile"
11:19:40.443 INFO Copy file path="policy/action/main.rego"
11:19:40.443 INFO Copy file path="policy/alert/main.rego"
11:19:40.443 INFO Copy file path="policy/alert/main_test.rego"
11:19:40.444 INFO Copy file path="policy/alert/testdata/your_schema/event.json"
11:19:40.444 INFO Copy file path="policy/authz/http.rego"
11:19:40.444 INFO Copy file path="policy/play/test.rego"
11:19:40.444 INFO Copy file path="scenario/data/event.json"
11:19:40.444 INFO Copy file path="scenario/env.libsonnet"
11:19:40.444 INFO Copy file path="scenario/my_first_scenario.jsonnet"

This command creates directories and new sample files.

Customize the setting files and policies

Alert Policy

Alert policies is for determination if the input event is acceptable alert or not. You can customize the alert policy by editing policy/alert/main.rego.

package alert.your_schema

alert contains {
	"title": input.name,
	"description": "Your description here",
	"source": "your_source",
	"namespace": input.key,
} if {
	input.severity == ["HIGH", "CRITICAL"][_]
}

This is an example of alert policy. It assumes the event data is like following:

{
  "name": "my_event",
  "key": "value",
  "severity": "HIGH"
}
  • your_schema is for identification of alert data schema. When AlertChain receives event via /alert/raw/your_schema (raw event) or /alert/pubsub/your_schema (Google Cloud Pub/Sub), the policy is triggered.
  • input is a structured data that is same with the input event data.
  • alert is a rule to determine if the input event is acceptable alert or not. If the alert "contains"

Please see Alert Policy document for more details.

Action Policy

Action policy is a rule of workflow for detected alerts. You can customize the action policy by editing policy/action/main.rego.

The sample action policy is for creating an issue in GitHub repository.

  1. Create a GitHub App and install it to the target repository.
  2. Set the GitHub App ID, installation ID, owner, repository name, and private key to the action policy.

You can see more details in Action Policy document.

End-to-end test with play command

You can test the alert and action policies with the play command. play command simulates the alert event and executes the action policy and output the result into JSON files.

% alertchain play -d ./policy -s ./scenario -o ./policy/play/output
13:13:15.141 INFO loading policy package="alert" path="./policy"
13:13:15.143 INFO loading policy package="action" path="./policy"
13:13:15.146 INFO starting alertchain with play mode scenario dir="./scenario" output dir="./policy/play/output" targets=[]
13:13:15.147 INFO Done scenario id=my_first_scenario
% tree ./policy/play/output/
./policy/play/output/
├── my_first_scenario
│   └── data.json
└── result.json

2 directories, 2 files

Please see test document for more details.

By the way, the default template has Makefile to test both of the policies.