{"id":19561374,"url":"https://github.com/secmon-lab/alertchain","last_synced_at":"2025-04-27T00:31:15.544Z","repository":{"id":45191992,"uuid":"385270439","full_name":"secmon-lab/alertchain","owner":"secmon-lab","description":"Simple SOAR (Security Orchestration, Automation and Response) framework integrated with OPA/Rego","archived":false,"fork":false,"pushed_at":"2025-04-16T22:53:46.000Z","size":1397,"stargazers_count":23,"open_issues_count":7,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-26T07:08:33.783Z","etag":null,"topics":["opa","rego","security-tools","soar"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/secmon-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-12T14:11:09.000Z","updated_at":"2025-01-19T20:20:37.000Z","dependencies_parsed_at":"2025-01-14T00:34:23.209Z","dependency_job_id":null,"html_url":"https://github.com/secmon-lab/alertchain","commit_stats":null,"previous_names":["secmon-lab/alertchain","m-mizutani/alertchain"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secmon-lab%2Falertchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secmon-lab%2Falertchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secmon-lab%2Falertchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secmon-lab%2Falertchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/secmon-lab","download_url":"https://codeload.github.com/secmon-lab/alertchain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251072279,"owners_count":21532004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["opa","rego","security-tools","soar"],"created_at":"2024-11-11T05:11:13.783Z","updated_at":"2025-04-27T00:31:15.532Z","avatar_url":"https://github.com/secmon-lab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlertChain\n\nAlertChain is a simple SOAR (Security Orchestration, Automation, and Response) framework that leverages [OPA](https://github.com/open-policy-agent/opa) (Open Policy Agent) to enhance security management.\n\n![AlertChain Diagram](https://user-images.githubusercontent.com/605953/232273906-a3df56fb-3201-4336-b897-e327e8d49981.jpg)\n\n## Motivation\n\nSecurity Orchestration, Automation, and Response (SOAR) is a platform designed for automating the detection, analysis, and response of security events. In order to enable automated event analysis and rapid response in SOAR systems, it is essential to execute automated security procedures and policies.\n\nBy utilizing OPA and Rego, a SOAR system can flexibly apply a set of user-defined policies to maintain the security of applications and systems. This approach simplifies the process of updating or changing security policies and ensures a more accurate policy application. Moreover, the Rego language is flexible and expressive, making it easy to add or modify policies.\n\n## Concept\n\nAlertChain is a versatile software that accepts structured event data through HTTP or other means, and then determines its actions based on policies written in Rego.\n\n### Action\n\nActions, the basic units of operation, are primarily implemented within AlertChain using Go code. For example, there is an action called [chatgpt.comment_alert](pkg/action/chatgpt/README.md#chatgptcomment_alert) which creates an issue on GitHub. Users can define any number of actions in a configuration written in Rego, each of which needs a unique ID.\n\n### Policy\n\nThere are two main types of policies in AlertChain, Alert Policy and Action Policy.\n\n1. **Alert Policy**: Responsible for determining whether the incoming event data from external sources should be treated as an alert or not. For example, when receiving notifications from external services, you may want to handle only alerts related to specific categories, or you may want to exclude events that meet certain conditions (such as specific users or hosts). The Alert Policy can be used to achieve these goals by excluding certain events or including only specific events as alerts.\n2. **Action Policy**: Determines the appropriate response for detected alerts. For example, when an issue is detected on a cloud instance, the response may differ depending on the type of alert or the elements involved in the alert, such as stopping the instance, restricting the instance's communication, or notifying an administrator. You may also want to retrieve reputation information from external services and adjust the response accordingly. The Action Policy is responsible for defining and controlling these response procedures.\n\nOverall, AlertChain provides a flexible and powerful framework for handling structured event data and determining appropriate actions based on user-defined policies.\n\n### Test\n\nAlertChain is an advanced tool that not only allows you to detect alerts through Alert Policies but also enables you to intentionally execute actions using Action Policies. For more information on how to test these features, please refer to the [Test](./docs/test.md) documentation.\n\n## Usage\n\nTo install AlertChain, run the following command:\n\n```bash\n$ go install github.com/secmon-lab/alertchain@latest\n```\n\nTo get started with AlertChain, please refer to the [Getting Started](./docs/getting_started.md) documentation.\n\nOther more documentations is here.\n\n- [Policy](docs/policy.md)\n- [Actions](./pkg/action/README.md)\n- [Test](docs/test.md)\n- [Deployment](docs/deployment.md)\n- [Authorization](docs/authz.md)\n\n## Example\n\nIn this example, we will demonstrate how AlertChain operates using an event detected by AWS GuardDuty. The policies and data used in this example can be found in the [examples](./examples/basic) directory.\n\n### 1. Write Alert Policy\n\nFirst, prepare an Alert Policy to detect alerts from the input event data.\n\n**policy/alert.rego**\n```rego\npackage alert.aws_guardduty\n\nalert[res] {\n\tf := input.Findings[_]\n\tstartswith(f.Type, \"Trojan:\")\n\tf.Severity \u003e 7\n\n\tres := {\n\t\t\"title\": f.Type,\n\t\t\"source\": \"aws\",\n\t\t\"description\": f.Description,\n\t\t\"attrs\": [{\n\t\t\t\"key\": \"instance ID\",\n\t\t\t\"value\": f.Resource.InstanceDetails.InstanceId,\n\t\t}],\n\t}\n}\n```\n\nThis example alert policy is designed for [AWS GuardDuty](https://docs.aws.amazon.com/cli/latest/reference/guardduty/get-findings.html#examples). The alert evaluates GuardDuty event data based on the following criteria:\n\n- The finding type has a \"Trojan:\" prefix,\n- The severity is greater than 7, and\n- If these conditions are met, a new alert is created\n\nAdditionally, this policy stores the detected instance's ID as a Attribute, allowing it to be used in a subsequent Action.\n\n### 2. Write Action Policy\n\nNext, prepare an Action Policy. In this example, the action requests a summary and recommended response for the alert from [ChatGPT](https://platform.openai.com/docs/guides/chat), and posts the result to a Slack channel.\n\n**policy/action.rego**\n```rego\npackage action\n\nrun contains res if {\n\tinput.alert.source == \"aws\"\n\tres := {\n\t\t\"id\": \"ask-gpt\",\n\t\t\"uses\": \"chatgpt.comment_alert\",\n\t\t\"args\": {\"secret_api_key\": input.env.CHATGPT_API_KEY},\n\t}\n}\n\nrun contains res if {\n\tgtp := input.called[_]\n\tgtp.id == \"ask-gpt\"\n\n\tres := {\n\t\t\"id\": \"notify-slack\",\n\t\t\"uses\": \"slack.post\",\n\t\t\"args\": {\n\t\t\t\"secret_url\": input.env.SLACK_WEBHOOK_URL,\n\t\t\t\"channel\": \"alert\",\n\t\t\t\"body\": gtp.result.choices[0].message.content,\n\t\t},\n\t}\n}\n```\n\nAction policies are triggered by writing `run` rules. In this case, the first rule is triggered when the `source` of the alert is set to `aws` by the Alert Policy. The `uses` field specifies the Action Name to be executed. The `chatgpt.comment_alert` action requires a `secret_api_key` argument to access ChatGPT via API. The API key is retrieved from the `input.env` environment variables, and the action is executed to make a query to ChatGPT.\n\nThe second rule is triggered only if an action with the ID `ask-gpt` has already been executed. The `called` field contains not only information about the executed action but also its result. The result of the query to ChatGPT is retrieved and set as the `body` field, and a message is posted to Slack.\n\n### 3. Run AlertChain as server\n\nAfter preparing these files, you can start AlertChain using the following command:\n\n```bash\n$ alertchain -d policy serve\n```\n\nNow, let's create an alert using AWS GuardDuty event data (guardduty.json):\n\n**guardduty.json**\n```json\n{\n    \"Findings\": [\n        {\n            \"Type\": \"Trojan:EC2/DriveBySourceTraffic!DNS\",\n            \"Region\": \"us-east-1\",\n            \"Severity\": 8,\n            (snip)\n        }\n    ]\n}\n```\n\nTo send the event data to the AlertChain API endpoint, use this command:\n\n```bash\n$ curl -XPOST http://127.0.0.1:8080/alert/aws_guardduty -d @guardduty.json\n```\n\nUpon receiving the data, AlertChain performs the following actions:\n\n1. Evaluates the event data using the alert policy and creates a new alert\n2. Evaluates the `action` policy with the new alert, executes `chatgpt.comment_alert`.\n3. Evaluate the `action` policy again with not only the alert but also results of executed action, and executes `slack.post` next\n4. Evaluate the `action` policy again and no action is triggered. Then stop workflow for the alert\n\nFinally, we can find a Slack message as shown below:\n\n\u003cimg width=\"680\" src=\"https://user-images.githubusercontent.com/605953/236592991-f2411b46-501d-4a4f-9a0d-ff7cf2defc84.png\"\u003e\n\n## License\n\nApache License 2.0","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecmon-lab%2Falertchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecmon-lab%2Falertchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecmon-lab%2Falertchain/lists"}