Skip to content

Commit 6e5b1ee

Browse files
ysyneuysyneu
authored
Merge pull request #1001 from flashcatcloud/feat/securityscorecard-test
docs: add SecurityScorecard alert integration (test)
2 parents 148f072 + baedff8 commit 6e5b1ee

4 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1718,6 +1718,7 @@
17181718
"zh/on-call/integration/alert-integration/alert-sources/pulseway",
17191719
"zh/on-call/integration/alert-integration/alert-sources/lacework",
17201720
"zh/on-call/integration/alert-integration/alert-sources/pgdash",
1721+
"zh/on-call/integration/alert-integration/alert-sources/securityscorecard",
17211722
"zh/on-call/integration/alert-integration/alert-sources/uptimeobserver",
17221723
"zh/on-call/integration/alert-integration/alert-sources/rbltracker",
17231724
"zh/on-call/integration/alert-integration/alert-sources/dash0",
@@ -3354,6 +3355,7 @@
33543355
"en/on-call/integration/alert-integration/alert-sources/pulseway",
33553356
"en/on-call/integration/alert-integration/alert-sources/lacework",
33563357
"en/on-call/integration/alert-integration/alert-sources/pgdash",
3358+
"en/on-call/integration/alert-integration/alert-sources/securityscorecard",
33573359
"en/on-call/integration/alert-integration/alert-sources/uptimeobserver",
33583360
"en/on-call/integration/alert-integration/alert-sources/rbltracker",
33593361
"en/on-call/integration/alert-integration/alert-sources/dash0",

‎en/on-call/integration/alert-integration/alert-sources/securityscorecard.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "SecurityScorecard alert integration"
3+
description: "Send SecurityScorecard score changes, new issues and breach events to Flashduty On-call with the Rule Builder Send a web request action."
4+
keywords: ["alert integration", "SecurityScorecard", "security rating", "Rule Builder", "webhook", "execution_id"]
5+
---
6+
7+
Use the **Send a web request** action of a SecurityScorecard Rule Builder rule to send Scorecard events to Flashduty On-call. Each time the rule runs, SecurityScorecard sends one POST request, and Flashduty creates one alert for it.
8+
9+
SecurityScorecard sends an event once, when it happens, and sends no recovery notification, so these alerts do not recover on their own. Turn on the auto-resolve timeout in the channel, as described in [Alerts do not recover](#alerts-do-not-recover).
10+
11+
<div className="hide">
12+
13+
## In Flashduty On-call
14+
---
15+
16+
You can obtain an integration push URL in either of the following ways.
17+
18+
### Use a dedicated integration
19+
20+
1. In the Flashduty console, select **Channel** and open a channel
21+
2. Select **Settings** → **Integrations** → **Dedicated integrations**, then click **Add an integration**
22+
3. Select **SecurityScorecard** and click **Save**
23+
4. Open the generated integration card and copy the **Push URL**
24+
25+
### Use a shared integration
26+
27+
1. In the Flashduty console, go to **Integration Center → Alert events**
28+
2. Select **SecurityScorecard** and enter an integration name
29+
3. Configure the default route and choose a channel. You can add more rules under **Routes** after the integration is created
30+
4. Click **Save** and copy the generated **Push URL**
31+
32+
</div>
33+
34+
## Configure SecurityScorecard
35+
---
36+
37+
Rule Builder requires a paid SecurityScorecard plan, and each user can create up to 25 rules.
38+
39+
<Steps>
40+
<Step title="Create a rule">
41+
42+
1. Sign in to the SecurityScorecard platform, go to **Automation** → **Rule Builder**, and click **Create Rule** (in the older interface: avatar in the upper-right corner → **My Settings** → **Rules**)
43+
2. Select **Events** so the rule runs when an event occurs
44+
3. Enter a rule name, for example `Flashduty: vendor score drop`
45+
4. Choose the Scorecards the rule monitors: your organization's Scorecard, a single Scorecard, or a portfolio
46+
5. Choose the triggering event, for example the overall score dropping below a threshold, a new issue of a given severity, or a reported breach
47+
48+
</Step>
49+
50+
<Step title="Add the Send a web request action">
51+
52+
1. Select **Send a web request** as the action
53+
2. Paste the full Flashduty push URL, including the `integration_key` parameter, as the URL. SecurityScorecard only sends to HTTPS URLs and does not support custom headers, so `integration_key` must stay in the URL
54+
3. Review the rule and click **Save**
55+
56+
From then on, every run of the rule sends one POST to that URL with a JSON body containing `trigger`, `execution_id`, `scorecard_id` and `domain`.
57+
58+
</Step>
59+
60+
<Step title="Verify">
61+
62+
Rule Builder has no button that sends a test request. SecurityScorecard evaluates Scorecard events once a day, and the rule runs after an event meets its conditions. To verify right away, simulate an event with the SecurityScorecard API [Simulate Actions](https://securityscorecard.readme.io/docs/simulate-actions) (include the rule's `rule_id` in the request) and check that the alert arrives in Flashduty. The simulation creates a real alert; close it by hand afterwards.
63+
64+
</Step>
65+
</Steps>
66+
67+
## Alert Key
68+
---
69+
70+
Flashduty computes the Alert Key from `execution_id`, `scorecard_id` and `trigger.type`. The SecurityScorecard article [Rule Builder: Webhooks](https://support.securityscorecard.com/hc/en-us/articles/360058429271-Rule-Builder-Webhooks) defines `execution_id` as the unique identifier of one rule execution, and it stays the same when a failed request is retried. A retry of the same execution therefore merges into the same alert, and every other rule execution becomes its own alert.
71+
72+
When a request has no `execution_id`, Flashduty generates a random Alert Key and every request becomes a new alert. A request without `trigger.type` returns a parameter error.
73+
74+
## Severity
75+
---
76+
77+
| Event (`trigger.type`) | Condition | Flashduty severity |
78+
| :--- | :--- | :--- |
79+
| Breach (`breach_reported`) | | Critical |
80+
| New issues (`new_issues`) | `trigger.severity` is `high` or `critical` | Critical |
81+
| New issues (`new_issues`) | `trigger.severity` is `medium`, absent or an unrecognized value | Warning |
82+
| New issues (`new_issues`) | `trigger.severity` is `low`, `info` or `informational` | Info |
83+
| Score change (`grade_drop`) and any other event type | | Warning |
84+
85+
## Field mapping
86+
---
87+
88+
| Flashduty | SecurityScorecard field |
89+
| :--- | :--- |
90+
| Title | Event type and `domain` (`scorecard_id` when `domain` is absent), for example `SecurityScorecard score change: example.com (score 54)`, `SecurityScorecard new issues: example.com (2 issue types)`, `SecurityScorecard breach reported: example.com`; other event types read `SecurityScorecard <trigger.type>: <domain>` |
91+
| Description | Event type, `domain`, `trigger.score`, `trigger.severity`, the active / departed / resolved count of each issue type, and the breach description |
92+
| Labels | `trigger_type` (also as `check`), `domain` (also as `resource`), `scorecard_id`, `execution_id`, `score`, `selected`, `issue_severity`, `issue_types`, and for breach events `breach_root_cause`, `breach_company`, `breach_records_lost`, `breach_type` |
93+
94+
The `retries` and `webhooks` (responses of earlier webhooks in the rule) fields are not copied to the alert. SecurityScorecard marks this request body as beta; if the structure of the issue or breach details changes, Flashduty ignores the parts it cannot parse and still creates the alert.
95+
96+
## Alerts do not recover
97+
---
98+
99+
Score changes, new issues and breaches are one-shot events, and SecurityScorecard sends no recovery notification. Turn on [auto-resolve timeout](/en/on-call/channel/create-edit) in the channel that receives this integration. 24 hours is a reasonable start; adjust it to how long your team takes to handle security rating events.
100+
101+
## Troubleshooting
102+
---
103+
104+
<AccordionGroup>
105+
<Accordion title="The rule ran but no alert arrives">
106+
107+
Check that the rule action is **Send a web request** and the URL is the full push URL starting with `https://`. SecurityScorecard evaluates events once a day, so a rule does not run at the moment a Scorecard changes. A score rule fires only when the change is greater than the configured value, not equal to it.
108+
109+
</Accordion>
110+
111+
<Accordion title="You receive an [Action Required] Failed Webhook Request email">
112+
113+
SecurityScorecard retries on network errors and 5xx responses and emails the rule owner when the request still fails after 36 hours. Check that the push URL is complete and that the integration has not been deleted.
114+
115+
</Accordion>
116+
117+
<Accordion title="Flashduty returns a parameter error">
118+
119+
The request body must be JSON of at most 1 MiB with a non-empty `trigger.type`, and the `integration_key` in the push URL must belong to a SecurityScorecard integration.
120+
121+
</Accordion>
122+
</AccordionGroup>
123+
124+
For the meaning of every field, see [Receive event notifications with webhooks](https://securityscorecard.readme.io/docs/receive-event-notifications-with-webhooks) in the SecurityScorecard docs.

‎integration-docs/src/doc-map.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ export const docMap = {
103103
Pulseway: `${alertBase}/pulseway.mdx`,
104104
Lacework: `${alertBase}/lacework.mdx`,
105105
PgDash: `${alertBase}/pgdash.mdx`,
106+
Securityscorecard: `${alertBase}/securityscorecard.mdx`,
106107
Fivetran: `${alertBase}/fivetran.mdx`,
107108
Cato: `${alertBase}/cato.mdx`,
108109
Aikido: `${alertBase}/aikido.mdx`,

‎zh/on-call/integration/alert-integration/alert-sources/securityscorecard.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "SecurityScorecard 告警集成"
3+
description: "通过 Rule Builder 的 Send a web request 动作，将 SecurityScorecard 的评分变化、新问题和数据泄露事件同步到 Flashduty On-call。"
4+
keywords: ["告警集成", "SecurityScorecard", "安全评级", "Rule Builder", "Webhook", "execution_id"]
5+
---
6+
7+
通过 SecurityScorecard Rule Builder 规则中的 **Send a web request** 动作，将评分卡（Scorecard）上的事件同步到 Flashduty On-call。规则每触发一次，SecurityScorecard 发送一个 POST 请求，Flashduty 为其创建一条告警。
8+
9+
SecurityScorecard 的事件只在发生时发送一次，没有对应的恢复通知，因此告警不会自动恢复。请在协作空间中开启超时自动关闭，见下文 [告警不会恢复](#告警不会恢复)。
10+
11+
<div className="hide">
12+
13+
## 在 Flashduty On-call
14+
---
15+
16+
您可通过以下两种方式获取集成推送地址，任选其一即可。
17+
18+
### 使用专属集成
19+
20+
1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
21+
2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
22+
3. 选择 **SecurityScorecard**，点击 **保存**
23+
4. 打开生成的集成卡片，复制 **推送地址**
24+
25+
### 使用共享集成
26+
27+
1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
28+
2. 选择 **SecurityScorecard**，填写集成名称
29+
3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
30+
4. 点击 **保存**，复制生成的 **推送地址**
31+
32+
</div>
33+
34+
## 在 SecurityScorecard 中配置
35+
---
36+
37+
Rule Builder 需要 SecurityScorecard 付费套餐，每个用户最多创建 25 条规则。
38+
39+
<Steps>
40+
<Step title="新建规则">
41+
42+
1. 登录 SecurityScorecard 平台，进入 **Automation** → **Rule Builder**，点击 **Create Rule**（旧版界面在右上角头像 → **My Settings** → **Rules** 中）
43+
2. 选择 **Events**，让规则在事件发生时运行
44+
3. 填写规则名称，例如 `Flashduty: vendor score drop`
45+
4. 选择规则监控的评分卡：本组织的评分卡、单个评分卡或某个 Portfolio
46+
5. 选择触发事件，例如总分降到某个阈值以下、出现指定严重程度的新问题、报告数据泄露
47+
48+
</Step>
49+
50+
<Step title="添加 Send a web request 动作">
51+
52+
1. 动作选择 **Send a web request**
53+
2. URL 粘贴 Flashduty 集成的完整推送地址，含 `integration_key` 参数。SecurityScorecard 只向 HTTPS 地址发送，且不支持自定义请求头，`integration_key` 必须放在 URL 中
54+
3. 检查规则后点击 **Save**
55+
56+
保存后，规则每次触发都会向该地址发送一次 POST，请求体为包含 `trigger`、`execution_id`、`scorecard_id`、`domain` 的 JSON。
57+
58+
</Step>
59+
60+
<Step title="验证">
61+
62+
Rule Builder 没有发送测试请求的按钮。SecurityScorecard 每天评估一次评分卡事件，规则在事件满足条件后运行。要立即验证，可以使用 SecurityScorecard API 的 [Simulate Actions](https://securityscorecard.readme.io/docs/simulate-actions)（请求中带上规则的 `rule_id`）模拟一次事件，确认 Flashduty 收到对应告警。模拟会产生一条真实告警，验证后请手动关闭。
63+
64+
</Step>
65+
</Steps>
66+
67+
## Alert Key
68+
---
69+
70+
Flashduty 使用 `execution_id`、`scorecard_id` 和 `trigger.type` 计算 Alert Key。SecurityScorecard 的 [Rule Builder: Webhooks](https://support.securityscorecard.com/hc/en-us/articles/360058429271-Rule-Builder-Webhooks) 说明，`execution_id` 是一次规则执行的唯一标识，请求失败重试时保持不变。因此同一次执行的重试会合并到同一条告警，不同的规则执行各自成为独立告警。
71+
72+
请求中缺少 `execution_id` 时，Flashduty 生成随机 Alert Key，每个请求都是一条新告警。缺少 `trigger.type` 时返回参数错误。
73+
74+
## 告警等级
75+
---
76+
77+
| 事件（`trigger.type`） | 条件 | Flashduty 等级 |
78+
| :--- | :--- | :--- |
79+
| 数据泄露（`breach_reported`） | | Critical |
80+
| 新问题（`new_issues`） | `trigger.severity` 为 `high` 或 `critical` | Critical |
81+
| 新问题（`new_issues`） | `trigger.severity` 为 `medium`、缺省或无法识别的值 | Warning |
82+
| 新问题（`new_issues`） | `trigger.severity` 为 `low`、`info` 或 `informational` | Info |
83+
| 评分变化（`grade_drop`）及其他事件类型 | | Warning |
84+
85+
## 字段映射
86+
---
87+
88+
| Flashduty | SecurityScorecard 字段 |
89+
| :--- | :--- |
90+
| 标题 | 事件类型和 `domain`（缺省时用 `scorecard_id`），例如 `SecurityScorecard score change: example.com (score 54)`、`SecurityScorecard new issues: example.com (2 issue types)`、`SecurityScorecard breach reported: example.com`；其他事件类型为 `SecurityScorecard <trigger.type>: <domain>` |
91+
| 描述 | 事件类型、`domain`、`trigger.score`、`trigger.severity`、每种问题的 active / departed / resolved 数量、泄露描述 |
92+
| 标签 | `trigger_type`（同时写入 `check`）、`domain`（同时写入 `resource`）、`scorecard_id`、`execution_id`、`score`、`selected`、`issue_severity`、`issue_types`，以及数据泄露事件的 `breach_root_cause`、`breach_company`、`breach_records_lost`、`breach_type` |
93+
94+
请求中的 `retries` 和 `webhooks`（前序 Webhook 的响应）不写入告警。SecurityScorecard 将该请求体标注为 beta，问题和泄露详情的结构变化时，Flashduty 忽略无法解析的部分，仍然创建告警。
95+
96+
## 告警不会恢复
97+
---
98+
99+
评分变化、新问题和数据泄露都是一次性事件，SecurityScorecard 不会发送恢复通知。请在接收该集成的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，建议 24 小时，并按团队处理安全评级事件的时效调整。
100+
101+
## 排查问题
102+
---
103+
104+
<AccordionGroup>
105+
<Accordion title="规则触发了但没有收到告警">
106+
107+
确认规则的动作是 **Send a web request**，URL 是完整的推送地址且以 `https://` 开头。SecurityScorecard 每天评估一次事件，规则不会在评分卡变化的当下立即运行。只有分数变化超过规则设置的分值时才会触发，等于该分值不触发。
108+
109+
</Accordion>
110+
111+
<Accordion title="收到 [Action Required] Failed Webhook Request 邮件">
112+
113+
SecurityScorecard 在网络错误或 5xx 响应时重试，36 小时后仍失败会给规则所有者发送该邮件。请检查推送地址是否完整、集成是否已被删除。
114+
115+
</Accordion>
116+
117+
<Accordion title="Flashduty 返回参数错误">
118+
119+
请求体必须是不超过 1 MiB 的 JSON，且 `trigger.type` 非空。推送地址中的 `integration_key` 必须属于一个 SecurityScorecard 集成。
120+
121+
</Accordion>
122+
</AccordionGroup>
123+
124+
更多字段含义请参阅 SecurityScorecard 文档中的 [Receive event notifications with webhooks](https://securityscorecard.readme.io/docs/receive-event-notifications-with-webhooks)。

0 commit comments

Comments
 (0)