{"id":22989176,"url":"https://github.com/cookpad/deepalert","last_synced_at":"2025-08-13T20:33:49.259Z","repository":{"id":41543204,"uuid":"183713223","full_name":"cookpad/deepalert","owner":"cookpad","description":"Serverless SOAR (Security Orchestration, Automation and Response) framework for automatic inspection and evaluation of security alert","archived":false,"fork":false,"pushed_at":"2023-06-01T19:53:25.000Z","size":681,"stargazers_count":46,"open_issues_count":8,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T06:04:38.964Z","etag":null,"topics":["aws","go","security","serverless","soar"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cookpad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2019-04-27T01:15:14.000Z","updated_at":"2025-03-12T21:18:29.000Z","dependencies_parsed_at":"2024-06-19T00:07:07.695Z","dependency_job_id":"c1973e1b-0bc5-4b08-bf2b-2bbf0e3cb795","html_url":"https://github.com/cookpad/deepalert","commit_stats":{"total_commits":158,"total_committers":2,"mean_commits":79.0,"dds":"0.13291139240506333","last_synced_commit":"8a03d214d588f652d60f0fc4d9be63845744b0af"},"previous_names":["deepalert/deepalert"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cookpad/deepalert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Fdeepalert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Fdeepalert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Fdeepalert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Fdeepalert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cookpad","download_url":"https://codeload.github.com/cookpad/deepalert/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookpad%2Fdeepalert/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270305842,"owners_count":24562109,"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","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aws","go","security","serverless","soar"],"created_at":"2024-12-15T04:16:39.621Z","updated_at":"2025-08-13T20:33:48.966Z","avatar_url":"https://github.com/cookpad.png","language":"Go","readme":"# DeepAlert\n\nServerless SOAR (Security Orchestration, Automation and Response) framework for automatic inspection and evaluation of security alert.\n\n## Overview\n\nDeepAlert receives a security alert that is event of interest from security view point and responses the alert automatically. DeepAlert has 3 parts of automatic response.\n\n- **Inspector** investigates entities that are appeared in the alert including IP address, Domain name and store a result: reputation, history of malicious activities, associated cloud instance and etc. Following components are already provided to integrate with your DeepAlert environment. Also you can create own inspector to check logs that is stored into original log storage or log search system.\n- **Reviewer** receives the alert with result(s) of Inspector and evaluate severity of the alert. Reviewer should be written by each security operator/administrator of your organization because security policies are differ from organization to organization.\n- **Emitter** finally receives the alert with result of Reviewer's severity evaluation. After that, Emitter sends external integrated system. E.g. PagerDuty, Slack, Github Enterprise, etc. Also automatic quarantine can be configured by AWS Lambda function.\n\n![Overview](https://user-images.githubusercontent.com/605953/76850323-80914100-688a-11ea-9c9a-96030094af2c.png)\n\n## Deployment\n\n### Prerequisite\n\n- Tools\n  - `aws-cdk` \u003e= 1.75.0\n  - `go` \u003e= 1.14\n  - `node` \u003e= 14.7.0\n  - `npm` \u003e= 6.14.9\n- Credential\n  - AWS CLI credential to deploy CloudFormation. See [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) for more detail.\n\n### Configure your stack\n\nAt first, you need to create AWS CDK repository and install deepalert as a npm module.\n\n```bash\n$ mkdir your-stack\n$ cd your-stack\n$ cdk init --language typescript\n$ npm i @deepalert/deepalert\n```\n\nThen, edit `./bin/your-stack.ts` as following.\n\n```ts\n#!/usr/bin/env node\nimport 'source-map-support/register';\nimport * as cdk from '@aws-cdk/core';\nimport { DeepAlertStack } from '@deepalert/deepalert';\n\nconst app = new cdk.App();\nnew DeepAlertStack(app, 'YourDeepAlert', {});\n```\n\n### Deploy your stack\n\n```bash\n$ cdk deploy\n```\n\n## Alerting\n\n### Alert data schema\n\n```json\n{\n  \"detector\": \"your-anti-virus\",\n  \"rule_name\": \"detected malware\",\n  \"rule_id\": \"detect-malware-by-av\",\n  \"alert_key\": \"xxxxxxxx\",\n  \"timestamp\": \"2006-01-02T15:03:04Z\",\n  \"attributes\": [\n    {\n      \"type\": \"ipaddr\",\n      \"key\": \"IP address of detected machine\",\n      \"value\": \"10.2.3.4\",\n      \"context\": [\n        \"local\",\n        \"client\"\n      ],\n    },\n  ]\n}\n```\n\n\n- `detector`: Subject name of monitoring system\n- `rule_id`: Machine readable rule identity\n- `timestamp`: Detected timestamp\n- `rule_name` (optional): Human readable rule name\n- `alert_key` (optional): Alert aggregation key if you need\n- `attributes` (optional): List of `attribute`\n  - `type`: Choose from `ipaddr`, `domain`, `username`, `filehashvalue`, `json` and `url`\n  - `key`: Label of the value\n  - `value`: Actual value\n  - `context`: One or multiple tags describe context of the attribute. See `AttrContext` in [alert.go](alert.go)\n\n### Emit alert via API\n\n`apikey.json` is created in CWD when running `cdk deploy` and it has `X-API-KEY` to access deepalert API.\n\n```bash\n$ export AWS_REGION=ap-northeast-1 # set your region\n$ export API_KEY=`cat apikey.json  | jq '.[\"X-API-KEY\"]' -r`\n$ export API_ID=`aws cloudformation describe-stack-resources --stack-name YourDeepAlert | jq -r '.StackResources[] | select(.ResourceType == \"AWS::ApiGateway::RestApi\") | .PhysicalResourceId'`\n$ curl -X POST \\\n  -H \"X-API-KEY: $API_KEY\" \\\n  https://$API_ID.execute-api.$AWS_REGION.amazonaws.com/prod/api/v1/alert \\\n  -d '{\n  \"detector\": \"your-anti-virus\",\n  \"rule_name\": \"detected malware\",\n  \"rule_id\": \"detect-malware-by-av\",\n  \"alert_key\": \"xxxxxxxx\"\n}'\n```\n\n\n### Emit alert via SQS\n\n```bash\n$ export QUEUE_URL=`aws cloudformation describe-stack-resources --stack-name YourDeepAlert | jq -r '.StackResources[] | select(.LogicalResourceId | startswith(\"alertQueue\")) | .PhysicalResourceId'`\n$ aws sqs send-message --queue-url $QUEUE_URL --message-body '{\n  \"detector\": \"your-anti-virus\",\n  \"rule_name\": \"detected malware\",\n  \"rule_id\": \"detect-malware-by-av\",\n  \"alert_key\": \"xxxxxxxx\"\n}'\n```\n\n\n### Build and deploy Reviewer\n\nSee examples and deploy it as Lambda Function.\n\n- Inspector example: [./examples/inspector](./examples/inspector)\n- Emitter example: [./examples/emitter](./examples/inspector)\n\n## Development\n\n### Architecture\n\n![architecture overview](https://user-images.githubusercontent.com/605953/103391370-8677ba80-4b5c-11eb-8b96-d44e1d3263a5.png)\n\n\n### Unit Test\n\n```\n$ go test ./...\n```\n\n### Integration Test\n\nMove to `./test/workflow/` and run below. Then deploy test stack and execute integration test.\n\n```bash\n$ npm i\n$ make deploy\n$ make test\n```\n\n## License\n\nMIT License\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcookpad%2Fdeepalert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcookpad%2Fdeepalert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcookpad%2Fdeepalert/lists"}