Slack
Send Aegis notifications to a Slack channel, and let people look up the
compliance overview, open risks and active incidents from Slack with the
/aegis command.
The Slack connector links Aegis to one Slack workspace through a Slack app that
your organisation creates and owns. Once it is authorised, Aegis posts
notifications to a channel you choose, and anyone in the workspace can type
/aegis to see a short summary from Aegis without leaving Slack.
Each organisation has one Slack configuration.
At a glance
| Direction |
Out of Aegis (notifications) and into Aegis (the
/aegis command).
|
|---|---|
| What it sends |
Notifications to the Default Channel set on the
connector page or, when that field is blank, to the channel picked
while installing the app in Slack.
|
| What the command returns |
/aegis status, /aegis risks,
/aegis incidents and /aegis help read from
Aegis; they do not change anything. Risks stay in
Risks and incidents in
Incidents.
|
| Credentials and permissions |
A Slack app (client ID, client secret and signing secret) with the
scopes listed on the connector page, the redirect, slash-command and
interactivity addresses from the connector page, then
Authorize with Slack.
|
| When it runs | At the moment a notification is sent or the command is used. It does not sync on a schedule. |
| Set it up |
/connectors/slack, by an Admin or Manager, where the
Slack connector module is switched on for your organisation.
|
Who uses it
-
Admin and
Manager open
/connectors/slack, save the credentials, authorise the app, test the connection, send a test message and disconnect the connector. - Contributor and Viewer cannot open the page; Aegis shows an access-denied screen instead. They still receive notifications in the Slack channel when they switch Slack on in their notification preferences.
-
Anyone in the Slack workspace can use
/aegisonce the app is installed. The command is not tied to an Aegis account, so treat the channel and workspace as the audience for what it shows.
What’s on this screen
Open Connectors and choose Slack. The page reads from
top to bottom:
-
A breadcrumb (
Connectors / Slack) and the headingSlack Connectorwith a one-line description. -
Configuration— a blueRequired Slack App Scopesbox, a yellowSlash Command Setupbox with the two request addresses to paste into Slack, then the fieldsClient ID(required),Client Secret,Signing SecretandDefault Channel:, and theSave Configurationbutton. -
Connection Status— a coloured dot with the state (Not Tested,Authorization Required,Testing...,ConnectedorConnection Failed) and the buttons that fit that state. -
Test NotificationswithSend Test Message— shown only while the connection status isConnected. -
Disconnect connectorwith a redDisconnectbutton — shown once a configuration exists, to people allowed to delete connectors. -
Three reference panels:
Setup Instructions(eight numbered steps, including the full redirect, slash-command and interactivity addresses for your Aegis),Available Slash CommandsandNotification Features.
The screenshots for this guide were taken with a role that cannot open the Slack connector page (it shows the access-denied screen), so this chapter describes the screen in words. The labels above are the ones the page shows.
Prepare the Slack app
Do this in Slack first, with the Aegis page open beside it so you can copy the addresses.
-
Create a Slack app at
api.slack.com/apps. Slack opens the app’sBasic Informationpage. -
Under
OAuth & Permissions, add the scopes the Aegis page lists:chat:write,commands,incoming-webhookandchannels:read. Set the redirect URL to the/api/connectors/slack/callbackaddress shown inSetup Instructions. -
Create a slash command named
/aegiswhose request URL is the/api/connectors/slack/commandsaddress from theSlash Command Setupbox. -
Turn on
Interactivityand set its request URL to the/api/connectors/slack/eventsaddress from the same box. -
Copy the
Client ID,Client SecretandSigning Secretfrom the app’sBasic Informationpage. You enter them in Aegis next.
Save the configuration
-
Paste the client ID into
Client ID.Save Configurationstays unavailable until this field has a value. -
Paste the client secret and the signing secret into
Client SecretandSigning Secret. Both fields hide what you type. After a save they show********; leave them blank later to keep the stored secrets. -
Optionally type a channel in
Default Channel:, for example#security-alerts. Leave it blank to use the channel you pick when installing the app. -
Select
Save Configuration. TheConnection Statuschanges toAuthorization Required, an orange note says OAuth authorisation is required to connect to Slack, and anAuthorize with Slackbutton appears.
Authorise and test the connection
-
Select
Authorize with Slack. Slack’s install screen opens; choose the workspace and the channel for notifications, then allow the app. -
Slack sends you back to
/connectors/slack. The connector is now markedConnected, and the status panel offersTest ConnectionandRe-authorize. If anything goes wrong on the way back, Aegis returns you to theConnectorsoverview instead. -
Select
Test Connection. The dot showsTesting..., then eitherConnectedwith a greenConnected to Slackbox naming the team and channel, orConnection Failedwith the reason. When Slack no longer accepts the stored token, the status returns toAuthorization Required; authorise again. -
With the status
Connected, selectSend Test MessageunderTest Notifications. Aegis posts “Test message from Aegis” to the channel picked during the install and shows a confirmation.
The test message goes to the channel chosen during the Slack install, not to
Default Channel:. If no install channel was recorded, Aegis can
still show the success confirmation without posting anything. Look in Slack
to be sure the message arrived.
Use the /aegis command
Once the app is installed, anyone in the workspace can type these in any channel the app can see. Aegis answers in Slack.
| Command | What it shows |
|---|---|
/aegis status |
The compliance overview and key metrics. |
/aegis risks |
Top open risks by severity. |
/aegis incidents |
Active incidents. |
/aegis help |
The list of commands. Any other word after /aegis also
shows this list.
|
Disconnect Slack
-
In
Disconnect connector, selectDisconnect. A confirmation asks whether to disconnect Slack and explains that the configuration and credentials are deleted. -
Confirm with
Disconnect. Aegis deletes the stored configuration and credentials and returns you to theConnectorsoverview. Records already in Aegis stay where they are, and you can configure the connector again later.
Good to know
- Every request from Slack is checked with the signing secret; a request without a valid signature is refused. Until a signing secret is saved, Slack requests are refused too.
- A notification goes to Slack only for people who switched Slack on in their notification preferences. It is posted in the shared channel, not sent as a direct message, so everyone in that channel can read it.
- Slack notifications stop while the Slack connector module is switched off for your organisation, even if a configuration is still stored.
- Each connection test updates the connector’s status: a failed test leaves the connector marked as failed with its reason until a later test succeeds, and a successful test is also written to the audit log.
Tips and limits
-
Default Channel:is the one destination for every Slack notification. Its hint says it can be overridden per notification, but notifications do not currently choose their own channel. -
Aegis also contains handlers for Slack shortcuts (create a risk, create an
incident, search) and for
@Aegismentions. The setup on this page does not ask for the shortcuts or for the event subscription and scope a mention needs, and in the current release the shortcut forms do not open. Do not rely on creating risks or incidents from Slack; create them in Aegis. -
After a successful test, the
Connection Statuspanel also lists the slash commands; in this release the descriptions next to them may appear as untranslated text. TheAvailable Slash Commandspanel lower on the page shows the same commands with readable descriptions. -
If Slack shows the app as removed, or tokens were revoked, use
Re-authorizerather than saving the configuration again.
Where this connects
Each person chooses Slack in their preferences — see
Notifications and
Settings. The
Connectors overview lists every connector and its
status. For Microsoft Teams, see Teams; for
other destinations, see Webhooks. The
/aegis command reads from Risks and
Incidents, and connector tests appear in the
Audit log.