> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/workspace/settings/notifications.md). # Notifications The notification settings in StepSecurity allow you to receive alerts about critical security events via email, Slack, or Microsoft Teams. These notifications help you stay informed about potential security risks in your workflows. ### Configuring Notifications
You can customize notification settings by specifying: #### **Notification Channels** In StepSecurity we support two integrations for notifications: **Slack** You can set up Slack notifications in one of two ways: 1. Webhook URL: Provide your Slack webhook URL. [Follow these instructions](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) to create a Slack webhook. 2. OAuth App: Configure the Slack App in your Admin Settings to enable OAuth-based notifications. **Follow this interactive demo to see how to setup Slack OAuth App:** {% embed url="" %} **Microsoft Teams** To integrate with Microsoft Teams, add a Teams webhook URL. [Follow these instructions](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet) to create a Teams webhook. ### **Notification Events** Select the security events you want to be notified about. Events are grouped below by the product area that raises them. {% hint style="info" %} Only one notification is sent per workflow for a given event. If the same workflow raises the same event again, no new notification is sent. {% endhint %} #### **Harden-Runner runtime detections** These events fire when Harden-Runner detects suspicious behavior during a workflow run. Each one corresponds to a detection type described in Detections. * Outbound traffic is blocked * Anomalous outbound call is discovered * Anomalous HTTPS outbound call is discovered * Source code file is overwritten * Secrets are detected in the build log * Secrets are detected in the build artifacts * Imposter commits are detected * A secret exfiltration attempt is detected * Suspicious network calls are detected * Suspicious process events are detected * Non-compliant artifacts are detected #### **GitHub Checks results** These events fire when a StepSecurity check fails on a pull request. See GitHub Checks for the difference between the three check types. * Baseline check failures are detected, for the Harden-Runner Baseline Check * Required check failures are detected, for StepSecurity Required Checks, which block merges on failure * Optional check failures are detected, for StepSecurity Optional Checks, which are advisory only #### **Workflow run policies** * A run policy is blocked, when a workflow run is blocked by a policy. See Workflow Run Policies. #### **Threat intelligence** * StepSecurity threat intel flags a compromised component Threat intel notifications cover the incidents surfaced in the Threat Center. When you enable this event, the current granularity setting appears beneath it. Click it to open the **Threat intel notifications** dialog and choose when your organization is notified:
| Option | Behavior | | ------------------------------ | --------------------------------------------------------------------------------------------------------- | | **All threat intel incidents** | Notify about every threat intel incident, whether or not your organization is affected. | | **Affected packages** | Notify only when your organization is affected by a compromised package, matched by name, at any version. | | **Exact version only** | Notify only when your organization uses the exact compromised version. | Choose **All threat intel incidents** if your security team tracks ecosystem-wide threats regardless of exposure. Choose **Affected packages** or **Exact version only** to narrow alerts to incidents that touch your own dependencies, with **Exact version only** producing the smallest set of alerts. Click **Done** to confirm your selection. #### **PAT Governance** These events fire when a personal access token violates your PAT Governance policy, or is nearing expiration. Configure the underlying thresholds (max age, over-scoped scopes, idle window, reminder bands) under Settings > Control Evaluation. * **A token exceeds its maximum age** - The token is older than the configured maximum age for its class (fine-grained and classic tokens have separate limits). * **A token has no expiration, or one beyond the allowed lifetime** - The token was created with no expiration, or with an expiration further out than the configured maximum age allows. * **An over-scoped token is detected** - A classic token carries a coarse scope such as repo, admin:org, or workflow, or a fine-grained token combines all-repository access with a write-level permission. * **A token sits unused past the idle limit** - The token shows no use for longer than the configured idle window. A never-used token is measured from when it was granted or authorized. * **A deactivated or removed user's token is detected** - The token's owner is no longer a member of the organization, has an unlinked SAML identity, or is suspended. * **A token is nearing expiration** - Sends a reminder before a token's expiration date. Bands default to 30, 7, and 1 days out, and are configurable. #### **File Exclusions** If there are specific files you do not want to trigger notifications (e.g., README.md, package-lock.json), you can list them in the Exempt Files text box. Wildcards (e.g., \*.md) are supported. ### Saving Your Preferences * Once you've configured the notification settings, click Save to apply your changes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.stepsecurity.io/workspace/settings/notifications.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.