diff --git a/credible/dapp-incidents.mdx b/credible/dapp-incidents.mdx index 2351ea4..a7e63c3 100644 --- a/credible/dapp-incidents.mdx +++ b/credible/dapp-incidents.mdx @@ -5,6 +5,22 @@ description: 'View incidents prevented by the Credible Layer' Incidents show when transactions were dropped because they violated assertions protecting contracts. This happens when a transaction that interacted with an assertion-protected contract was dropped by the [Enforcer](/credible/glossary#assertion-enforcer) because it caused an assertion to revert. +## How Incidents Are Grouped + +An incident represents the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window. + +**Why group transactions into incidents?** + +- An attacker may craft multiple transactions that all violate the same assertion—these represent the same logical attack +- One hour is a reasonable estimate for how long an attack attempt might last +- After one hour without violations, a new invalidation likely indicates a different attack and creates a new incident + +This grouping ensures you receive meaningful alerts without being spammed by repeated notifications for the same security event. + + +This is our initial approach to incident grouping and may be refined based on user feedback. + + ## Incidents View Access incidents from the **Incidents** tab in the dApp navigation bar. This shows a limited view of all incidents across all networks: @@ -57,9 +73,7 @@ You can also set up external alerts via webhooks: - **Slack Integration**: Configure Slack webhooks to receive incident notifications in your Slack channels - **PagerDuty Integration**: Configure PagerDuty webhooks to receive incident notifications - -Detailed setup instructions for Slack and PagerDuty integrations will be available in a dedicated documentation page. - +See [Integrations](/credible/dapp-integrations) for setup instructions. ## Use Cases diff --git a/credible/dapp-integrations.mdx b/credible/dapp-integrations.mdx new file mode 100644 index 0000000..38a39e3 --- /dev/null +++ b/credible/dapp-integrations.mdx @@ -0,0 +1,163 @@ +--- +title: 'Incident Notifications' +description: 'Configure Slack and PagerDuty to receive real-time incident notifications' +--- + +Set up Slack and PagerDuty integrations to receive notifications when [assertion incidents](/credible/dapp-incidents) occur in your Credible Layer projects. + +## Accessing Integration Settings + +1. Navigate to your project in the Credible Layer dashboard +2. Go to **Settings** in the navigation bar +3. Select **Slack** or **PagerDuty** from the "Integrations" section + + + Adding Notification Integration + + +## Slack Integration + +The Slack integration sends formatted incident notifications to a channel of your choice using Slack's Incoming Webhooks. + + + +1. In the Credible Layer Settings page, click **Create a Slack App** +2. This opens Slack's app creation page with a pre-filled manifest. No manual configuration needed +3. Select the workspace where you want to receive notifications +4. Click **Create** + + + +1. In your newly created Slack app, go to **Features → Incoming Webhooks** +2. Toggle **Activate Incoming Webhooks** to **On** +3. Click **Add New Webhook to Workspace** +4. Select the channel where you want incident notifications +5. Click **Allow** + + + +After authorizing, you'll see your new webhook URL: + +``` +https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX +``` + +Copy this URL. + + + +1. Return to Credible Layer Settings → Slack tab +2. Paste your webhook URL in the input field +3. Click **Save** + + + +1. After saving, click **Send Test Notification** +2. Verify the message arrives in your selected Slack channel + + + +## PagerDuty Integration + +The PagerDuty integration creates incidents in PagerDuty when assertion violations occur, using the Events API v2. + + + +1. In PagerDuty, navigate to **Services → Service Directory** +2. Select an existing service or create a new one +3. Go to the **Integrations** tab +4. Click **Add Integration** +5. Search for and select **Events API v2** +6. Click **Add** + + + +After adding the integration, you'll see the **Integration Key** (also called Routing Key). This is a 32-character alphanumeric string. Copy this key. + + +Click the **PagerDuty Integration Guide** button in the Credible Layer Settings page for direct access to PagerDuty's official documentation. + + + + +1. Go to Credible Layer Settings → PagerDuty tab +2. Paste your 32-character routing key in the input field +3. Click **Save** + + + +1. After saving, click **Send Test Notification** +2. Verify the incident appears in your PagerDuty service + + + +## What Gets Notified + +Both integrations send notifications when [assertion incidents](/credible/dapp-incidents) occur. Notifications include: + +- Project name and affected contract +- Network/chain information +- Transaction details (hash, block number) +- Assertion violation reason +- Direct link to view the incident in the dashboard + +## How Incidents Are Grouped + +You receive one notification per incident, not per transaction. An incident is defined as an assertion being invalidated within a one-hour time window. + +If an attacker crafts multiple transactions that all violate the same assertion, these are grouped into a single incident since they represent the same logical attack. After one hour without violations, a new invalidation creates a new incident. + +This prevents notification spam while ensuring you're alerted to distinct security events. See [Incidents](/credible/dapp-incidents#how-incidents-are-grouped) for more details. + + +This grouping logic is our initial approach and may be refined based on user feedback. + + +## Managing Integrations + +### Updating a Webhook or Key + +Paste a new URL or key and click **Save**. The old configuration is replaced. + +### Removing an Integration + +1. Scroll to the bottom of the integration card +2. Click **Remove Integration** +3. Confirm the removal + + +Removing an integration stops all notifications but does not delete historical data. You can reconfigure at any time. + + +## Troubleshooting + +| Issue | Solution | +| --- | --- | +| Slack webhook URL rejected | Ensure the URL starts with `https://hooks.slack.com/services/` | +| PagerDuty key rejected | Verify the key is exactly 32 alphanumeric characters | +| Test notification not received | Check that the integration is correctly configured in Slack/PagerDuty | +| No notifications on incidents | Verify the integration shows as "configured" in Settings | + +## Security + +- Webhook URLs and routing keys are stored securely and never displayed in full after saving +- Only project managers can configure integrations +- Test notifications are rate-limited to prevent abuse + +## Next Steps + + + + Learn about incident monitoring + + + Manage your projects + + + Explore the full dApp + + + Create assertions for your contracts + + + diff --git a/credible/glossary.mdx b/credible/glossary.mdx index 757eba5..c7aeb87 100644 --- a/credible/glossary.mdx +++ b/credible/glossary.mdx @@ -159,6 +159,11 @@ The transparent and public nature of all assertions deployed on PCL. Since asser ## Prevention +### Incident +A security event representing the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window. This grouping treats repeated attempts to exploit the same vulnerability as a single logical attack. + +Learn more: [Incidents](/credible/dapp-incidents) + ### Revert What happens at the EVM/Solidity level when an assertion function detects that a transaction violates the rules defined in the assertion. When an assertion reverts, it signals that the transaction would result in an undesired state. The sidecar detects this revert and notifies the sequencer that the transaction should be dropped. diff --git a/docs.json b/docs.json index a01646a..65c19f2 100644 --- a/docs.json +++ b/docs.json @@ -72,6 +72,7 @@ "credible/invariant-to-assertion", "credible/store-submit-assertions", "credible/deploy-assertions-dapp", + "credible/dapp-integrations", "credible/accelerate-with-ai" ] }, diff --git a/images/add-notification-integration-credible-dapp.webp b/images/add-notification-integration-credible-dapp.webp new file mode 100644 index 0000000..b02366c Binary files /dev/null and b/images/add-notification-integration-credible-dapp.webp differ