Code Security Integrations

Code Security supports integrations with:

• Slack for communication

• Jira to open tickets and start your workflow based on the issue which was detected by Code Security

• Monday to create items and start your workflow based on the issue which was detected by Code Security

• Pager Duty for alerts management

• Custom webhooks

• Events Webhook integration

All the integration settings are global. You can also define a team-level integration except for Custom webhooks.

To open the Code Security Integrations menu:

1. From the left toolbar, click Code Security.

2. From the second toolbar from the left, click Settings.

3. From the Settings toolbar, click Integrations.

Slack Integration

1. Create a Slack app.

2. Enable incoming webhooks.

3. Copy your webhook URL, paste in the field

For more information, see the Slack documentation.

Jira Integration

You can use Spectral to scan your Jira environment. To connect your Jira account, you must have:

• Jira domain URL

• Jira admin/user email

• Jira API Token, you can view how to get the key here

For more information and configuration instructions, see Code Security Integration with Jira.

Confluence Integration

You can use Spectral to scan the content in a Confluence instance. The integration uses a Lambda function in AWS Amazon® Web Services. Public cloud platform that offers global compute, storage, database, application and other cloud services. and a webhook in Confluence. For more information, see Code Security Integration with Confluence .

Monday Integration

Global Integration

To set the integrations globally, and connect your Monday account, you require the Monday API Token. To obtain the key, click here.

Upon successful integration, the Monday account domain is presented at the top of the Monday integration section.

Team level Integration

You can set a default Monday workspace for a team. By choosing a workspace for your teams, this workspace is prioritized in the workspaces list, while creating a Monday item.

Create an Item

You can create a Monday item, in a specific Monday board, from the issues table (Code/Log/Host/Productivity/Asset quick view). The workspaces list is sorted by:

If the asset of the selected issue is mapped to a team, and a Monday workspace is configured for this team. This workspace is on the top of the workspaces list.

If the user belongs to one or more teams, the workspaces that are configured for these teams is presented at the top of the list.

Additional Fields

You can get the same view in Monday as in Spectral by adding these fields:

• Severity > (severity, text/label)

• asset > (asset, text)

• content > (content, text)

• firstSeen > (first seen, date)

The additional fields are presented in the create item form - with no edit option.

Comparison of Events Webhook Integration and Custom Webhook Features

Custom Webhook Integration

You can configure Code Security to send notifications through a Custom Webhook Integratoin.

An account administrator can configure custom webhook integrations in the Settings screen > Integrations tab.

How a Custom Webhook Integration Works

1. You enter the webhook URL.

2. Code Security generates a token for the integration. You cannot change this token.

3. Code Security uses the token to sign every notification using HMAC with SHA 256 encryption.

4. Code Security sends notifications to the webhook URL as a POST request (JSON JavaScript Object Notation. A lightweight data interchange format. enconded). The request must be 200 OK.

This is an example of the POST request that Spectral sends to the webhook URL. It is in an open API schema:

issues:
                type: array
                items:
                type: object
                properties:
                assetId:
                type: string
                title: Asset id
                description: The asset in which this issue has been discovered
                detectorId:
                type: string
                title: Detector id
                description: The detector id
                detectorName:
                type: string
                title: Detector name
                description: The detector description
                severity:
                type: string
                title: Severity
                description: The severity of this issue (error / warning / info)
                uri:
                type: string
                title: URI
            description: View the issue in your source code via this uri

This is a sample of the content:

{
                issues: [
                {
                assetId: 'github.com/maggie/jelly-sandwich',
                detectorId: 'SENF026',
                detectorName: 'Ruby On Rails secret token configuration file',
                severity: 'error',
                uri: 'https://github.com/maggie/jelly-sandwich/blob/ae556dbaa9a8ce4e37a5fe9e95b7823eff79f379/config/initializers/secret_token.rb#L7'
                },
                {
                assetId: 'github.com/maggie/jelly-sandwich',
                detectorId: 'CLD001',
                detectorName: 'Visible AWS Key',
                severity: 'error',
                uri: 'https://github.com/maggie/jelly-sandwich/blob/ae556dbaa9a8ce4e37a5fe9e95b7823eff79f379/db/secret2#L4'
                },
                ]
            }

Verifying the Notification

The signature can be found in the x-spectral-signature header. An extra layer of security is added by using the timestamp (ISO format) to create the signature hash.

To sign the content, [TIMESTAMP]_[SECRET-TOKEN] is used.

To make sure the request has not replayed, you can verify the x-spectral-signature header in the request is in the last 5 seconds, for example. You can verify the signature using:

// NodeJS example
                import crypto from 'crypto'

                const verifySignature = (signature, signatureToken, timestamp, payload) => {
                const calculatedSignature = crypto
                .createHmac('sha256', `${timestamp}_${signatureToken}`)
                .update(payload)
                .digest('hex')
    
                return (signature === calculatedSignature)
            }

You can verify your implementation:

verifySignature('108a388872e723c0b4be83a0b37abb5a55f9a89c17209c47bb11e8064ccd811d', 'myverysecrettoken', '0', 'bar') // returns true

Events Webhook Integration

The Events Webhook Integration feature allows users to receive notifications when the state of an issue or asset changes. This feature ensures that users are promptly informed about updates, facilitating better monitoring and management of their resources. To reduce the number of events, Spectral combines related events.

Event Payloads

This section describes the structure of event payloads for changes in issues or assets, and for ingest completion.

All events include the name of the event and the id or ids of the resource and the time of the event. To retrieve all the data associated with these resource IDs, see the Spectral API documentation.

Changes in Issue or Asset

When an issue or asset changes, Spectral creates an event with these fields:

{
                "name": String,
                "ids": [String],
                "time": YYYY-MM-DDTHH:mm:ss.SSSZ
            }

Ingest Completion

After Spectral finishes the ingest process, it creates an event with this payload:

{
                "name": String,
                "id": String,
                "issues_deleted_count": number,
                "issues_created_count": number,
                "issues_updated_count": number,
                "issues_resolved_count": number,
                "time": YYYY-MM-DDTHH:mm:ss.SSSZ
            }

Testing Your Webhook Integration

You can send a test notification to your webhook endpoint to simulate an event.

To test your webhook integration:

1. In the Integrations page, scroll to the section for the integration (for example: the Custom Webhook Global Integration section)

2. Click Test.

   A popup message shows you the test results.

Verifying a Signature for a Webhook Integration

The signature appears in the x-spectral-signature header.

Spectral uses a timestamp in ISO format to create the signature hash. Spectral uses this token to create the signature: [TIMESTAMP]_[SECRET-TOKEN].

You can use the timestamp to make sure that Spectral does not send duplicate information.

This is an example of code to verify the signature:

// NodeJS example
                import crypto from 'crypto'

                const verifySignature = (signature, signatureToken, timestamp, payload) => {
                const calculatedSignature = crypto
                .createHmac('sha256', `${timestamp}_${signatureToken}`)
                .update(payload)
                .digest('hex')
    
                return (signature === calculatedSignature)
            }

This is an example of code to verify the implementation:

verifySignature('108a388872e723c0b4be83a0b37abb5a55f9a89c17209c47bb11e8064ccd811d', 'myverysecrettoken', '0', 'bar') // returns true