Learn how to integrate Endor Labs with third party services. Endor Labs provides several out of the box integrations for continuous monitoring, ticketing, and messaging workflows in your environment.
This is the multi-page printable view of this section. Click here to print.
Endor Labs integrations
- 1: Set up continuous monitoring with GitHub
- 2: Set up Jenkins pipeline for supervisory scans
- 3: Set up custom package repositories
- 4: Set up Jira integration with Endor Labs
- 5: Set up integrations using webhooks
- 6: Set up Vanta integration with Endor Labs
- 7: Set up email integration
- 8: Set up Slack integration
1 - Set up continuous monitoring with GitHub
Endor Labs provides a GitHub App that continuously monitors users’ projects for security and operational risk. You can use the GitHub App to selectively scan your repositories for SCA, secrets, RSPM, or CI/CD tools.
Getting started with the GitHub App
To get started with the Endor Labs GitHub App, follow these steps:
- Review the prerequisites
- Install the GitHub App in your organization
- (Optional) If you use private software dependencies, configure package manager integrations.
- Review your projects as they are scanned.
Prerequisites for GitHub App
Before installing and scanning projects with Endor Labs GitHub App, make sure you have:
- A GitHub cloud account and organization. If you don’t have one, create one using github.com.
- Administrative permissions to your GitHub organization. Installing the Endor Labs GitHub App in your organization requires approval or permissions from your GitHub organizational administrator. If you don’t have the permissions, use the command line utility,
endorctl
, while you wait for the approval. - Endor Labs GitHub App requires read permissions to Dependabot alerts, actions, administration, checks, code, commit statuses, issues, metadata, packages, pull requests, repository hooks, and security events. It does not need write access to any resources.
Install the GitHub App
To automatically scan repositories using the GitHub App:
-
Sign in to Endor Labs.
-
Choose Projects and click Add Project.
-
From GITHUB, choose GitHub App
-
Click Install GitHub App.
-
You will be redirected to GitHub to install the GitHub App. Select Install.
-
Select a user to authorize the app.
-
Select the organization in which you want to install the app.
-
Select whether to install and authorize Endor Labs on all your repositories or select the specific repositories that you wish to scan.
-
Review the permissions required for Endor Labs and click Install and Authorize.
-
Choose a namespace and click Next.
-
Based on your license, select and enable from the following list of available scanners and click Continue.
- SCA- Perform software composition analysis.
- CI/CD - Scan the repository and identify all the CI/CD tools used in the repository.
- RSPM - Scan the repository for misconfigurations.
- Secret - Scan the repository for exposed secrets.
-
Click Continue. You have successfully installed the GitHub App.
Endor Labs GitHub App scans your repositories every 24 hours and reports any new findings or changes to release versions of your code.
Manage GitHub Apps on Endor Labs
You can edit or delete the GitHub App integrations.
- Sign in to Endor Labs.
- Navigate to Manage and select Integrations.
- Choose a GitHub App integration and click the ellipsis on the right side, and select Edit Integration.
- Based on your license, select and enable from the available list of scanners and click Save. The changes are applicable from the next scanning cycle.
- Use Reset to clear your selection.
- To delete a GitHub App integration, click the ellipsis on the right side, and select Delete Integration.
- To manually trigger a scan, click Rescan Org. Endor Labs GitHub App scans your repositories every 24 hours, use Rescan Org to manually trigger a scan at any time.
Technical limitations of the GitHub App
The Endor Labs GitHub App provides visibility across a GitHub organization, but it has technical limitations that do not account for the unique requirements of your application. Here are some of these limitations:
Bill of materials variance
The Endor Labs GitHub App approximates software package builds to create a bill of materials and perform static analysis on your software dependencies. This requires building packages with specific versions of the package manager and runtime environment.
If there are differences in the build environment, it can result in variances in the bill of materials. For the most accurate information, use Endor Labs CLI as a post-build step in your software delivery process.
Factors contributing to variances in the bill of materials include:
- The time a software package was built
- The version of a software package manager
- The type of package manager being used
- The version of the runtime environment a package is installed on
Custom package build steps
Endor Labs requires executing custom build steps outside of standard package manager commands to build software packages and get an accurate bill of materials and perform static analysis. Sometimes, a complete bill of materials may not be generated or static analysis may not be performed.
Custom resource profiles
Large applications may require significant memory allocations to perform static analysis on a package. The services scanning the GitHub App use 16GB of memory by default. Applications that require more memory may not obtain vulnerability prioritization information using the GitHub App. Scan large applications in a CI environment using a runner with sufficient resource allocations.
Authentication for private software components
Private software components hosted in an internal package repository may require authentication credentials to create a complete bill of materials or perform static analysis.
If your authentication information to your private package repository is hosted outside of the repository, you will need to configure a package manager integration. See Set up package manager integration for more details.
2 - Set up Jenkins pipeline for supervisory scans
Use the Endor Labs Jenkins pipeline to scan all the repositories in your organization and view consolidated findings. This pipeline runs on your organization’s Jenkins infrastructure and enables administrators to run organization-level supervisory scans easily. It is designed to work in GitHub Cloud and GitHub enterprise server environments.
The Jenkins pipeline carries out the following actions:
- Pulls the Endor Labs Docker image required to perform the scan.
- Synchronizes GitHub organization repositories to a specified namespace on the Endor Labs platform.
- Retrieves the project list or the GitHub repositories for the given tenant’s namespace.
- Groups the projects into batches to optimize scan execution.
- Runs endorctl scans on each batch of projects simultaneously.
Scan the repositories in your organization
The Jenkins Pipeline script is available in the github-org-scan-docker.groovy
file. To scan the repositories in your organization:
- Generate Endor Labs API credentials
- Configure GitHub cloud or GitHub enterprise server credentials
- Configure the Jenkins job
Configure GitHub credentials
Configure the required credentials needed to access GitHub and Endor Labs in the Jenkins pipeline script. You can configure these values from the Jenkins user interface.
GITHUB_TOKEN
: Enter the GitHub token that has permission to access all the repositories in the organization.ENDOR_LABS_API_KEY
: Enter the Endor Labs API key that you generated.ENDOR_LABS_API_SECRET
: Enter the Endor Labs API secret generated while creating the Endor Labs API key.
Configure GitHub cloud credentials
Configure the following GitHub cloud parameters in the Jenkins pipeline script.
Required Parameters for GitHub cloud
AGENT_LABEL
: This is a string parameter. Enter the label used to identify the Jenkins agents. The Jenkins job will run on the agents that have this label.GITHUB_ORG
: This is a string parameter. Enter the organization name in GitHub.ENDOR_LABS_NAMESPACE
: This is a string parameter. The namespace of your organization tenant in Endor Labs.
Optional Parameters for GitHub cloud
ENDOR_LABS_API
: This is a string parameter. This is only required if the tenant namespace is configured on the Endor Labs staging environment.ADDITIONAL_ARGS
: This is a string parameter. Use this field to pass any additional parameter to theendorctl
scan.NO_OF_THREADS
: This is a string parameter. Enter the number of Jenkins agents that can be used in parallel for theendorctl
scan. If you have 10 Jenkins agents configured with the givenAGENT_LABEL
, you can enter this value as 9, 1 agent is used for the main job. If not specified, this value defaults to 5.ENDORCTL_VERSION
: This is a string parameter. Specify the version of theendorctl
Docker container. Defaults to the latest version.SCAN_TYPE
: This is a string parameter. Set this togit
to scan commits orgithub
to fetch info from the GitHub API. Defaults to [git
,analytics
].SCAN_SUMMARY_OUTPUT_TYPE
: This is a string parameter. Use this field to set the desired output format. Supported formats: json, yaml’, table, summary. Defaults to table.LOG_LEVEL
: This is a string parameter. Use this field to set the log level of the application. Defaults to info.LOG_VERBOSE
: This is a string parameter. Use this field to make the log verbose.LANGUAGES
: This is a string parameter. Use this field to set programming languages to scan. Supported languages:c#
,go
,java
,javascript
,php
,python
,ruby
,rust
,scala
,typescript
. Defaults to all supported languages.ADDITIONAL_ARGS
: This is a string parameter. Use this field to pass any additional parameters to the endorctl scan.
Configure GitHub enterprise server credentials
Configure the following GitHub enterprise server parameters in the Jenkins pipeline script.
Required Parameters for GitHub enterprise server
AGENT_LABEL
–> This is a string parameter. Enter the label used to identify the Jenkins agents. The Jenkins job will run on the agents that have this label.GITHUB_ORG
–> This is a string parameter. Enter the organization name in GitHub.ENDOR_LABS_NAMESPACE
–> This is a string parameter. The namespace of your organization tenant in Endor Labs.GITHUB_API_URL
–> This is a string parameter. Enter the API URL of the GitHub enterprise server. This is normally in the form of<FQDN of GitHub Enterprise Server>/api/v3
. For example, https://ghe.endorlabs.in/api/v3
Optional Parameters for GitHub enterprise server
-
ENDOR_LABS_API
: This is a string parameter. This is only required if the tenant namespace is configured on the Endor Labs staging environment. -
GITHUB_DISABLE_SSL_VERIFY
: This is a boolean parameter. This should be used when you want to skip SSL Verification while cloning the repository. -
GITHUB_CA_CERT
: This is a multi-line string parameter. This should be used to provide the content of the CA Certificate (PEM format) of the SSL Certificate used on the GitHub Enterprise Server. -
PROJECT_LIST
: This is a multi-line string parameter. This should be used to provide a list of projects to scan. -
SCAN_TYPE
: This is a string parameter. Set this togit
to scan commits orgithub
to fetch info from the GitHub API. Defaults to [git
,analytics
]. -
SCAN_SUMMARY_OUTPUT_TYPE
: This is a string parameter. Use this field to set the desired output format. Supported formats: json, yaml*, table, summary. Defaults to table. -
LOG_LEVEL
: This is a string parameter. Use this field to set the log level of the application. Defaults to info. -
LOG_VERBOSE
: This is a string parameter. Use this field to generate verbose logs. -
LANGUAGES
: This is a string parameter. Use this field to set programming languages to scan. Supported languages:c#
,go
,java
,javascript
,php
,python
,ruby
,rust
,scala
,typescript
. Defaults to all supported languages. -
ADDITIONAL_ARGS
: This is a string parameter. Use this field to pass any additional parameters to the endorctl scan. -
PROJECT_LIST
: This is a multi-line string parameter. List of projects to scan. Even though all projects are synchronized, scans run only on the provided projects. -
SCAN_PROJECTS_BY_LAST_COMMIT
: This is a string parameter. This parameter is used to filter projects based on the date of the last commit. Enter a number (integer) value for this parameter. The value of 0 means that projects won’t be filtered based on last commit date. Any positive integer is used to calculate the duration in which a commit will add the project for further scanning. If a project did not have a commit in that interval, it will be skipped. If a proper SSL Certificate (a certificate issued by a well-known CA) is not used for Github Enterprise, thesync-org
command will fail and won’t be able to fetch the projects or repositories to scan from the GitHub enterprise server. You can use this field to provide the list of projects or repositories to scan one per line. For example:https://github-test.endorlabs.in/pse/vuln_rust_callgraph.git https://github-test.endorlabs.in/pse/vulnerable-golang.git https://github-test.endorlabs.in/pse/java-javascript-vulnerable-repo.git https://github-test.endorlabs.in/pse/multi-lang-repo.git
-
EXCLUDE_PROJECTS
This is a multi-line string parameter.: Use this parameter to list projects or repositories to exclude from the scan. -
NO_OF_THREADS
–> This is a string parameter. Enter the number of Jenkins agents that can be used in parallel for theendorctl
scan. If you have 10 Jenkins agents configured with the givenAGENT_LABEL
, you can enter this value as 9. If not specified, this value defaults to 5.
Configure the Jenkins job
Use the following procedure to configure the Jenkins pipeline and scan the repositories in your organization.
- Sign in to Jenkins
- Configure an Endor Labs API Key and GitHub credentials correctly for your environment.
- Click + New Item, to create a new Jenkins job.
- Enter the name of the new pipeline
- Select Pipeline and click OK.
- Select This project is parameterised and add the parameters based on your requirements.
- From the Pipeline section, for Definition, select Pipeline script from SCM
- For SCM select Git
- For the Repository URL, enter either
git@github.com:endorlabs/jenkins-org-scan.git
orhttps://github.com/endorlabs/jenkins-org-scan.git
. - For Credentials, enter the credentials required for cloning the repository entered in the previous step.
- In Branches to build, enter
*/main
. - For Script Path, enter
github-org-scan-docker.groovy
. - Select Lightweight checkout.
- Click Save.
The Jenkins pipeline is highly customizable and adaptable to various GitHub environments and scanning requirements. It streamlines the process of running endorctl scans on your repositories efficiently.
3 - Set up custom package repositories
Suppose your software components are private and are hosted in an internal package repository. In that case, you must provide authentication credentials to the registry, to create a complete bill of materials or perform static analysis.
You must set up custom package repositories if:
- Your software package isn’t scanned as part of a post-build or install step
- You are using the Endor Labs GitHub App
- you are implementing scans across your environment for quick visibility
- Authentication information to your private package repository is hosted outside of the repository
Configure package manager integrations
Endor Labs integrates with your self-hosted package repositories and source control systems to give you visibility into your environment. Package manager integrations allow users to simplify scanning using custom repositories.
Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully.
-
Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files.
-
Package manager integrations allow you to set custom registries for each package ecosystem and the priority of each registry for scanning.
To set up a package manager integration:
- Under Manage, select Integrations.
- Select the package manager configuration you’d like to customize and click Connect
- In the upper right-hand corner, select Add Package Manager.
- Input a package manager URL for your given package registry.
- If a package registry is authenticated select Authenticate to this registry and enter a set of credentials that will be used to authenticate to the package registry.
- Select Add Package Manager.
If you would like to delete a package manager integration, click the trash can icon at the far right of the integration.
Change package manager integration priority
Package manager integrations allow you to set the priority of each package registry used by a package managers in your tenant namespace. This defines the location from which a package manager looks when it attempts to resolve dependencies for a software package.
To change the package manager integration priority:
- Click and hold the integration you would like to change the priority of.
- Drag the integration to the priority spot that is most frequently used by your organization.
Package manager integrations
The following support matrix details support for package manager integrations:
Language | Ecosystem | Supported |
---|---|---|
Java | Maven (mvn:// ) |
Supported |
JavaScript | npm (npm:// ) |
Supported |
Python | PyPI (pypi:// ) |
Supported |
Ruby | Gem (gem:// ) |
Supported |
PHP | Composer (composer:// ) |
Supported |
.NET/C# | nuget (nuget:// ) |
Supported |
4 - Set up Jira integration with Endor Labs
Integrate Endor Labs with Jira and automatically create Jira tickets in specific projects when configured policies are violated. This integration automates the process of generating Jira tickets within your organization’s existing security workflow. This integration is supported on Jira Cloud.
To integrate Endor Labs with Jira:
- Generate Jira API token
- Configure Jira Integration on Endor Labs
- Associate an action policy with a Jira notification
Generate Jira API token
Generate Jira API credentials that you want to use to sign in to Endor Labs.
Note: It is recommended that the Jira account used for this integration includes only the following set of minimum required permissions.
- Create Issues
- Transition Issues
- Assign Issues
- Resolve Issues
- Add Comments
- Sign into your Jira account.
- Navigate to your Jira profile.
- Under API tokens, click Create API Token.
- Enter a concise label to distinguish your token and click Create.
- Click Copy to clipboard, and have the token handy to enter in the Endor Labs application.
Note: The token cannot be viewed after closing the form. Copy it to a secure location and have it handy. Do not share the token.
Configure Jira Integration on Endor Labs
Set up Jira integration on the Endor Labs application.
-
Sign in to Endor Labs.
-
From the sidebar, navigate to Integrations.
-
Under Notifications, click Manage for Jira.
-
Click Add Notification Integrations.
-
Enter a name and description for the integration.
-
Enter a Jira user name. The user account is displayed as the reporter for all the tasks or bugs created in Jira for this notification.
Note: It is recommended to create a new user account for receiving Jira notifications from Endor Labs.
-
In API Key, enter the API token that you generated from Jira.
-
In Jira URL, enter the HTTPS endpoint of your Jira instance.
-
In PROJECT Key, enter the project key in which you want to create the Jira notifications. The project key is the prefix of the bug or task ID. For example, if the project key is ABC, the task or bug is created with ID in the format ABC-xxx.
-
Select the ISSUE TYPE as a Task or a Bug.
-
In LABELS, enter a label and associate it with your Jira notifications.
-
Click Add Notification Integration.
Manage Endor Labs Jira notifications
You can view and manage the Endor Labs Jira notifications created for a project.
- From the sidebar, navigate to Integrations.
- Under Notifications, click Manage for Jira.
- To edit a notification, click the vertical ellipsis and choose Edit Notification Integration.
- To delete a notification, click the vertical ellipsis dots and choose Delete Notification Integration.
Associate an action policy with a Jira notification
Users can create action policies to execute a recommended action when a policy is violated. For example, if there is a license compliance violation, you can create a Jira ticket and notify the required personnel.
While creating an action policy, configure the following settings:
- Select Choose an Action as Send Notification.
- From SELECT NOTIFICATION TARGETS, choose the Jira integration notification that you created.
- Choose an Aggregation type for Jira notifications. Choose Project to trigger a single notification for all findings, or choose Dependency to trigger multiple notifications for every dependency. See Create an action policy for more details.
A parent ticket is created with the selected issue type, either Task or Bug. The parent ticket includes the project name. Each identified dependency is grouped under a dedicated sub-ticket. The sub-ticket includes both the project name and dependency name. Findings without any dependency are grouped in a separate sub-ticket. During future scans, the existing sub-ticket status is updated or resolved. If a new dependency is found, a new sub-ticket is created.
View Jira ticket details
Users can view the created Jira ticket details on the Endor Labs application. Users have the ability to observe specific information such as the status of tickets (whether they are open or closed), the associated action policy, the number of violations, and other important details. This aids in seamless troubleshooting and identification of both unresolved and resolved issues.
- From the Endor Labs application, navigate to Manage and click Notifications.
- Navigate across the Open, Resolved, or All tabs to view the issues listed under them.
- You can view specific details such as created date of the ticket, the name of the policy, the name of the project, the number of violations, and any labels associated with the projects.
- Choose a notification and click the vertical three dots on the far right side and choose:
- Dismiss Notification: Clear this notification if it is no longer valid. It will be marked in grey.
- Show Details: View the Jira ticket number and you can also navigate to Jira.
- Go to Policy: View configuration details of the policy that created this Jira ticket.
5 - Set up integrations using webhooks
Webhooks enable real-time communication between different systems or applications over the internet. They allow one application to send data to another application as soon as a specific event or a trigger occurs.
Use webhooks to integrate Endor Labs with applications such as Slack, Microsoft Teams or more, and instantly get notified about projects if your configured policies are violated.
When events are triggered, Endor Labs sends HTTPS POST requests to URLs of your configured events, with all the information you need.
Configure a webhook integration
Set up a custom integration with Endor Labs webhooks.
- Sign in to Endor Labs and click Integrations from the sidebar.
- Navigate to Webhooks under Notifications and click Add.
- Click Add Notification Integration.
- Enter a name and description for this integration.
- Enter the URL endpoint for the webhooks.
- Enter the authentication method such as API Key, Basic, or None.
- Enter the details for the authentication method such as USERNAME, PASSWORD, or API KEY. Make sure the API Key has required permissions to post messages using webhook.
- To ensure integrity, de-select Disable HMAC Integration Check and enter the HMAC Shared Key. The Hash-Based Message Authentication Code (HMAC) ensures the authenticity of a message using a cryptographic hash function and a secret key. The HMAC signature is passed as a header in the HTTP request.
- Click Add Notification Integration.
Endor Labs webhook payload
Endor Labs provides the following webhook payload, that you can customize for your needs.
Name | Description |
---|---|
data.message |
Brief message about the number of findings discovered for a project |
data.project_url |
Link to the scanned project in the Endor Labs application |
data.policy.name |
Name of the violated policy that triggered the notification |
data.policy.url |
Link to the violated policy in the Endor Labs application |
data.findings |
Complete list of findings |
data.findings[].uuid |
Unique identifier of the finding |
data.findings[].description |
Brief description of the finding |
data.findings[].severity |
Severity of the finding |
data.findings[].dependency [CONDITIONAL] |
Name of dependency that caused the policy violation. This field is only present for findings that have a dependency associated. For example, vulnerability findings |
data.findings[].package [CONDITIONAL] |
The version of the package in the project that imported the dependency causing the policy violation. This field is only present for findings that have a package version associated with them. For example, vulnerability findings |
data.findings[].repositoryVersion [CONDITIONAL] |
Repository version of the project that triggered the policy violation. This field is only present for findings that have a repository version associated with them. For example, secrets findings |
data.findings[].findingURL |
Link to the finding in the Endor Labs application |
Example:
See the following example for a sample notification payload.
{
"data": {
"message": "6 findings discovered for project endorlabs/monorepo",
"projectURL": "https://localhost:8082/t/endor/projects/65e5b83466145505541d9664",
"policy": {
"name": "Webhook vuln",
"url": "https://localhost:8082/t/endor/policies/actions?filter.default=Webhook+vuln"
},
"findings": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
"severity": "FINDING_LEVEL_MEDIUM",
"dependency": "semver@7.5.0",
"package": "endorlabs-vscode-extension@1.5.0",
"findingURL": "https://localhost:8082/t/endor/findings/6614ec9141aef3ab8e90ed80"
},
{
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
"severity": "FINDING_LEVEL_MEDIUM",
"dependency": "semver@7.3.8",
"package": "endorlabs-vscode-extension@1.5.0",
"findingURL": "https://localhost:8082/t/endor/findings/6614ec9141aef3ab8e90ed81"
},
{
"uuid": "550e8400-e29b-41d4-a716-446655440002",
"description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
"severity": "FINDING_LEVEL_MEDIUM",
"dependency": "semver@5.7.1",
"package": "endorlabs-vscode-extension@1.5.0",
"findingURL": "https://localhost:8082/t/endor/findings/6614ec9141aef3ab8e90ed82"
},
{
"uuid": "550e8400-e29b-41d4-a716-446655440003",
"description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
"severity": "FINDING_LEVEL_MEDIUM",
"dependency": "semver@6.3.0",
"package": "endorlabs-vscode-extension@1.5.0",
"findingURL": "https://localhost:8082/t/endor/findings/6614ec9141aef3ab8e90ed83"
}
]
}
}
Use Endor Labs webhooks to integrate with Slack
If you use Slack as a collaborative tool, integrate Slack channels using webhooks in Endor Labs to publish notifications as messages in the respective channels.
- Configure a webhook integration
- Endor Labs webhook payload
- Use Endor Labs webhooks to integrate with Slack
Create incoming webhooks in Slack
Create an incoming webhook to your Slack channel to enable Endor Labs to post notifications in the channel. The webhook provides a unique URL which is used to integrate the channel in Endor Labs. To send messages into Slack using incoming webhooks, see Slack Integration.
If you have already created an incoming webhook in the channel, copy the unique URL and integrate the channel in Endor Labs.
Customize webhook notification templates
Endor Labs provides you with a default template with standard information that will be included in the webhook message. You can use the default template or you can choose to edit and customize this template to fit your organization’s specific requirements. You can also create your own custom templates using Go Templates.
- Sign into Endor Labs and navigate to Manage>Integrations
- Look for Slack under Notifications.
- Click Manage to view the list of configured notification integrations.
- Choose one and click the ellipsis on the right side, and click Edit Template.
- Make required changes to any of the following templates and click Save Template.
- Open - This template is used when new notifications are raised.
- Update - This template is used when an existing notification is updated, such as, when some findings for the notification are changed.
- Resolve - This template is used when all the findings reported by the notification are resolved.
- Click Restore to Default to revert the changes.
- Use the download icon on the top right corner to download this template.
- Use the copy icon to copy the information in the template.
Data model
To create custom templates for Webhook notifications, you must understand the data supplied to the template.
See the protobuf specification NotificationData
message used for the templates.
syntax = "proto3";
package internal.endor.ai.endor.v1;
import "google/protobuf/wrappers.proto";
import "spec/internal/endor/v1/finding.proto";
import "spec/internal/endor/v1/notification.proto";
import "spec/internal/endor/v1/package_version.proto";
import "spec/internal/endor/v1/project.proto";
import "spec/internal/endor/v1/repository_version.proto";
option go_package = "github.com/endorlabs/monorepo/src/golang/spec/internal.endor.ai/endor/v1";
option java_package = "ai.endor.internal.spec";
// The statistics for findings in a notification.
message FindingStats {
// The total number of findings for a notification.
google.protobuf.UInt32Value num_total_findings = 1;
google.protobuf.UInt32Value num_total_critical_severity_findings = 2;
google.protobuf.UInt32Value num_total_high_severity_findings = 3;
google.protobuf.UInt32Value num_total_medium_severity_findings = 4;
google.protobuf.UInt32Value num_total_low_severity_findings = 5;
// The number of new findings for a notification as compared to the previous scan.
google.protobuf.UInt32Value num_new_findings = 6;
google.protobuf.UInt32Value num_new_critical_severity_findings = 7;
google.protobuf.UInt32Value num_new_high_severity_findings = 8;
google.protobuf.UInt32Value num_new_medium_severity_findings = 9;
google.protobuf.UInt32Value num_new_low_severity_findings = 10;
// The number of findings for a notification that was resolved in latest scan.
google.protobuf.UInt32Value num_resolved_findings = 11;
}
// The data supplied to notification templates while rendering.
message NotificationData {
// The raw notification object.
Notification raw_notification = 1;
// The name of the project.
google.protobuf.StringValue project_name = 2;
// The name of the violated policy that triggered the notification.
google.protobuf.StringValue policy_name = 3;
// The Git reference of the project that was scanned.
google.protobuf.StringValue ref_name = 4;
// The project URL.
google.protobuf.StringValue project_url = 5;
// The map of finding UUIDs to finding objects.
map<string, internal.endor.ai.endor.v1.Finding> findings_map = 6;
// The map of finding UUIDs to corresponding parent package version objects.
map<string, internal.endor.ai.endor.v1.PackageVersion> package_version_map = 7;
// The map of finding UUIDs to corresponding parent project objects.
map<string, internal.endor.ai.endor.v1.Project> project_map = 8;
enum NotificationType {
NOTIFICATION_TYPE_UNSPECIFIED = 0;
// Notification type when a notification is created.
NOTIFICATION_TYPE_CREATE = 1;
// Notification type when a notification is updated.
NOTIFICATION_TYPE_UPDATE = 2;
// Notification type when a noticiation is resolved.
NOTIFICATION_TYPE_RESOLVED = 3;
}
NotificationType type = 9;
// The project to which the notification is associated.
internal.endor.ai.endor.v1.Project project = 10;
// The map of finding UUIDs to the correcponding parent repository version objects.
map<string, internal.endor.ai.endor.v1.RepositoryVersion> repository_version_map = 11;
// The project URL in Endor Labs UI.
google.protobuf.StringValue project_app_url = 12;
// The policy URL in Endor Labs UI.
google.protobuf.StringValue policy_app_url = 13;
FindingStats finding_stats = 14;
// The map of package version UUIDs to package version names.
map<string, string> package_version_name_map = 15;
}
To understand Project, Finding, PackageVersion and RepositoryVersion definitions used in this protobuf specification, see:
- Project resource kind
- Finding resource kind
- PackageVersion resource kind
- RepositoryVersion resource kind
See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys.
// FuncMap contains the additional functions that are available to notification templates.
var FuncMap = func(h *NotificationTemplate) template.FuncMap {
return template.FuncMap{
"now": func() string {
now := time.Now()
utc := now.UTC()
return utc.Format("01-02-2006 15:04:05")
},
// csvFileName generates the filename for the CSV attachment for Jira.
"csvFileName": GetJiraAttachmentFilename,
// findingURL returns the URL for the given finding.
"findingURL": h.getFindingURL,
// toCSV converts the given string to a CSV format.
"toCSV": toCSV,
// findingLevelSlackEmoji returns the slack emoji for the given finding based on severity.
"findingLevelSlackEmoji": GetSlackEmojiForSeverity,
// packageName returns the user facing name of the package.
"packageName": func(p *endorpb.PackageVersion) string {
return lib.GetUserFacingName(p.GetMeta().GetName().GetValue())
},
// filteredFindingsURL returns the URL to view findings with the given uuids
"filteredFindingsURL": common.GetFilteredFindingsURL,
// increment increments the given integer by 1.
"increment": func(i int) int {
return i + 1
},
}
}
Webhook handler example for Slack
Create a webhook handler or a cloud function to receive webhook requests generated by Endor Labs, authorize the request, and post messages to your Slack channel.
See the following code sample hosted as a cloud function or a webhook handler.
// Package p contains an HTTP Cloud Function.
package p
import (
"encoding/json"
"fmt"
"html"
"io"
"io/ioutil"
"bytes"
"log"
"net/http"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"strings"
wrapperspb "google.golang.org/protobuf/types/known/wrapperspb"
)
// Struct representation of default webhook payload from Endor Lab's notification.
type WebhookMessage {
Data Payload `json:"data"`
}
type Payload struct {
Message string `json:"message"`
ProjectUrl string `json:"projectURL"`
Policy Policy `json:"policy"`
Findings []Finding `json:"findings"`
}
type Finding struct {
Uuid string `json:"uuid"`
Description string `json:"description"`
Severity string `json:"severity"`
Dependency string `json:"dependency,omitempty"`
Package string `json:"package,omitempty"`
RepositoryVersion string `json:"repositoryVersion,omitempty"`
FindingUrl string `json:"findingURL"`
}
type Policy struct {
Name string `json:"name"`
Url string `json:"url"`
}
// HelloWorld deserializes the default webhook payload from the notification object,
// formats it into a format that Slack supports and send the message to Slack via webhook.
func HelloWorld(w http.ResponseWriter, r *http.Request) {
var d WebhookMessage
if err := json.NewDecoder(r.Body).Decode(&d); err != nil {
switch err {
case io.EOF:
log.Printf("success")
return
default:
log.Printf("json.NewDecoder: %v", err)
http.Error(w, http.StatusText(http.StatusBadRequest), http.StatusBadRequest)
return
}
}
// Perform the HMAC sign to make sure that the request is not tampered with.
hmacSign := ""
for headerName, headerValues := range r.Header {
if headerName == "X-Endor-Hmac-Signature" {
if headerValues[0] == "" {
http.Error(w, "hmac empty", http.StatusUnauthorized)
return
}
hmacSign = headerValues[0]
}
}
receivedMessage := d.Message
// Secret configured in Endor
secretKey := "Secret"
// Validate the HMAC
isValid := validateHMAC(receivedMessage, hmacSign, secretKey)
// Process the result
if isValid {
fmt.Fprint(w, html.EscapeString("success"))
} else {
http.Error(w, "unauthorized, something changed", http.StatusUnauthorized)
return
}
textToSlack := fmt.Sprintf("%s which violates policy %s", d.Data.Message, d.Data.Policy.Name)
sendMessageToSlack(textToSlack)
}
func validateHMAC(receivedMessage, receivedHMAC, secretKey string) bool {
// Create a new HMAC hasher using the SHA-256 hash function and the secret key
mac := hmac.New(sha256.New, []byte(secretKey))
// Write the received message to the HMAC hasher
mac.Write([]byte(receivedMessage))
// Calculate the HMAC value
expectedHMAC := mac.Sum(nil)
// Convert the expected HMAC to a hexadecimal string
expectedHMACString := hex.EncodeToString(expectedHMAC)
// Compare the expected HMAC with the received HMAC (ignoring case)
return strings.EqualFold(receivedHMAC, expectedHMACString)
}
func sendMessageToSlack(msg string) {
// Replace this url with the url hook from the Slack App
url := "https://slack.webhook"
payload := []byte(`{"text": "Hey there are findings in project https://github.com/endorlabs/python-deps.git which violates policy DemoNotification"}`)
req, err := http.NewRequest("POST", url, bytes.NewBuffer(payload))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response body:", err)
return
}
}
6 - Set up Vanta integration with Endor Labs
Vanta enables organizations to manage risk by automating compliance and streamlining security reviews. Integrate Vanta with Endor Labs to view security findings in real-time and accelerate your security audit processes.
To integrate Endor Labs with Vanta:
Create an application in Vanta
Create an application in Vanta so that Endor Labs can authenticate and export vulnerability findings to Vanta. The app requires connectors.self:write-resource
and connectors.self:read-resource scopes
to export vulnerabilities.
- Sign in to Vanta as an Administrator.
- Click Settings on the top navigation bar.
- Select Developer Console.
- Click Create.
- Select Build Integrations.
- Enter a name and description for your application.
- Select the App Visibility as Private and click Create.
- Select the Application Category as Vulnerability Scanner.
- Click Generate Client Secret to generate the OAuth client secret.
OAuth Client ID appears. Copy the OAuth Client ID and the client secret and have them handy. You must enter this data in Endor Labs to configure the Vanta integration.
- Click Save.
Create resources in Vanta
To successfully ingest security data and create notifications, map the Endor Labs attributes to resource types in Vanta.
-
Sign in to Vanta.
-
Navigate to Settings and click Developer Console.
-
Select your application and click Resources.
-
Click Create Resource and create the following resources to successfully map Endor Labs data into Vanta.
- Enter the Resource Type as
Vulnerable Component
(mandatory) and select the Base Resource Type as VulnerableComponent. - Enter the Resource Type as
Package Vulnerability
(optional) and select the Base Resource Type as PackageVulnerabilityConnectors. - Enter the Resource Type as
Static Code Analysis
(optional) and select the Base Resource Type as StaticAnalysisCodeVulnerabilityConnectors.
Provide the Static Code Analysis resource type if you want to export exposed secrets in your first party code to Vanta.
You can view the schema generated for all the resource types.
- Enter the Resource Type as
Copy the Resource ID of the generated resources and have them handy. You must enter this data in Endor Labs to configure the Vanta integration.
Configure Vanta integration
Set up Endor Labs integration with Vanta.
Prerequisites: Make sure you have the client ID, client secret, and the resource IDs from Vanta handy.
- Sign in to Endor Labs and click Integrations from the sidebar.
- Under Notifications, click Add for Vanta.
- Click Add Notification Integration.
- Enter a name and description for this integration.
- Enter the CLIENT ID and CLIENT SECRET that you generated on Vanta.
- Under Vanta Resources, enter the Resource IDs for VULNERABILITY COMPONENT, PACKAGE VULNERABILITY, and STATIC CODE ANALYSIS VULNERABILITY from Vanta.
Note
Vulnerable Component is mandatory. You must enter either one of the Package Vulnerability or Static Code Analysis Vulnerability resource types. - Click Add Notification Integration.
Associate an action policy with a Vanta notification
Users can create action policies to execute a recommended action when a policy is violated. For example, if there is a critical or high vulnerability, those vulnerabilities are exported to Vanta to ensure compliance adherence.
While creating an action policy, configure the following settings:
- Select Choose an Action as Send Notification.
- From SELECT NOTIFICATION TARGETS, choose the Vanta integration notification that you created.
- Choose an Aggregation type for notifications. For integrating with Vanta, we recommend you choose Project.
- From Assign Scope, include the project tags in INCLUSIONS to apply this policy to a project.
See Create an action policy for more details.
Manage Vanta notification targets in Endor Labs
You can view and manage the Endor Labs Vanta notification targets created for a project.
- From the sidebar, navigate to Manage > Integrations.
- Under Notifications, click Manage for Vanta. You can view all your created notification targets for Vanta.
- To edit a notification target, click the vertical ellipsis and choose Edit Notification Integration.
- To delete a notification target, click the vertical ellipsis dots and choose Delete Notification Integration.
Run a scan
Run the endorctl scan on your configured projects. See endorctl scan commands for more information.
Findings exported to Vanta
Endor Labs sends the following findings to Vanta:
- third-party open-source vulnerabilities
- secrets exposed in the first-party code
These findings are exported as Package Vulnerabilities and Static Code Analysis Vulnerabilities in Vanta. They are associated with a Vulnerable Component (that is the Repository Version) in Vanta.
Exporting findings generated on the Git repository security posture of an organization are not supported.
View findings in Vanta
View Endor Labs’ findings in Vanta and take remedial actions.
- Sign in to Vanta.
- Select Tests to view notifications.
- Select the integration that you created in the Integration filter to view notifications from Endor Labs.
- Select a notification to view all findings associated with the Endor Labs policy.
- Click on a finding to view more details in Endor Labs.
For example, if you create an action policy to notify critical vulnerabilities and configure it to a Vanta notification target, you can see the exports as Critical vulnerabilities identified in code repositories are addressed under Tests in Vanta. The test classifications are based on the severity of the exported findings.
7 - Set up email integration
Integrate your email address with Endor Labs and automatically receive policy violations as email notifications.
Configure email integration
To configure an email integration, follow these steps:
- Sign in to Endor Labs and click Integrations from the left sidebar.
- Navigate to Email under Notifications and click Add.
- Click Add Notification Integration.
- Specify a name and description for this integration.
- Enter email addresses separated by commas in EMAIL ADDRESSES.
- Click Add Notification Integration.
Associate an action policy with the email notification
Users can create action policies to send an email notification when the conditions of a given policy are met. For example, if there is a critical or high vulnerability, send an email notification.
While creating an action policy, configure the following settings:
- Select Choose an Action as Send Notification.
- From SELECT NOTIFICATION TARGETS, choose the email integration notification that you created.
- Choose an Aggregation type for notifications.
- Choose Project to group and send the findings related to a project in one email.
- Choose Dependency to send individual email messages for every dependency.
- From Assign Scope, include the project tags in INCLUSIONS to apply this policy to a project.
See Create an action policy for more details.
Customize email notification templates
Endor Labs provides a default template with standard information that will be included in the email. You can use the default template or you can choose to edit and customize this template to fit your organization’s specific requirements. You can also create custom templates using Go Templates.
- Sign in to Endor Labs and navigate to Manage > Integrations.
- Look for Email under Notifications.
- Click Manage to view the list of configured notification integrations.
- Choose a notification integration and click the ellipsis on the right side, and click Edit Template.
- Make required changes to any of the following templates and click Save Template.
- Open - This template is used when new notifications are raised.
- Update - This template is used when an existing notification is updated, such as, when some findings for the notification are changed.
- Resolve - This template is used when all the findings reported by the notification are resolved.
- Click Restore to Default to revert the changes.
- Use the download icon on the top right corner to download this template.
- Use the copy icon to copy the information in the template.
Data model
To create custom templates for email notifications, you must understand the data supplied to the template.
See the EmailData
message used for Open and Update templates.
// EmailData contains mappings for findings and package versions that is to be published as
// an email. It also contains the NotificationData object in the payload.
type EmailData struct {
Payload *endorpb.NotificationData
PackageVersionFindingMapping map[string]map[string][]string
PackageVersionMap map[string]*endorpb.PackageVersion
APIURL string
APPURL string
FromAddress string
}
See the ResolvedEmailData
message used for Resolve template.
// ResolvedEmailData contains the data that's acessible in the resolved email template.
type ResolvedEmailData struct {
APIURL string
APPURL string
Project *endorpb.Project
Policy *endorpb.Policy
ProjectName string
}
See the following protobuf specification for the NotificationData
message referenced by EmailData
.
syntax = "proto3";
package internal.endor.ai.endor.v1;
import "google/protobuf/wrappers.proto";
import "spec/internal/endor/v1/finding.proto";
import "spec/internal/endor/v1/notification.proto";
import "spec/internal/endor/v1/package_version.proto";
import "spec/internal/endor/v1/project.proto";
import "spec/internal/endor/v1/repository_version.proto";
option go_package = "github.com/endorlabs/monorepo/src/golang/spec/internal.endor.ai/endor/v1";
option java_package = "ai.endor.internal.spec";
// The statistics for findings in a notification.
message FindingStats {
// The total number of findings for a notification.
google.protobuf.UInt32Value num_total_findings = 1;
google.protobuf.UInt32Value num_total_critical_severity_findings = 2;
google.protobuf.UInt32Value num_total_high_severity_findings = 3;
google.protobuf.UInt32Value num_total_medium_severity_findings = 4;
google.protobuf.UInt32Value num_total_low_severity_findings = 5;
// The number of new findings for a notification as compared to the previous scan.
google.protobuf.UInt32Value num_new_findings = 6;
google.protobuf.UInt32Value num_new_critical_severity_findings = 7;
google.protobuf.UInt32Value num_new_high_severity_findings = 8;
google.protobuf.UInt32Value num_new_medium_severity_findings = 9;
google.protobuf.UInt32Value num_new_low_severity_findings = 10;
// The number of findings for a notification that was resolved in latest scan.
google.protobuf.UInt32Value num_resolved_findings = 11;
}
// The data supplied to notification templates while rendering.
message NotificationData {
// The raw notification object.
Notification raw_notification = 1;
// The name of the project.
google.protobuf.StringValue project_name = 2;
// The name of the violated policy that triggered the notification.
google.protobuf.StringValue policy_name = 3;
// The Git reference of the project that was scanned.
google.protobuf.StringValue ref_name = 4;
// The project URL.
google.protobuf.StringValue project_url = 5;
// The map of finding UUIDs to finding objects.
map<string, internal.endor.ai.endor.v1.Finding> findings_map = 6;
// The map of finding UUIDs to corresponding parent package version objects.
map<string, internal.endor.ai.endor.v1.PackageVersion> package_version_map = 7;
// The map of finding UUIDs to corresponding parent project objects.
map<string, internal.endor.ai.endor.v1.Project> project_map = 8;
enum NotificationType {
NOTIFICATION_TYPE_UNSPECIFIED = 0;
// Notification type when a notification is created.
NOTIFICATION_TYPE_CREATE = 1;
// Notification type when a notification is updated.
NOTIFICATION_TYPE_UPDATE = 2;
// Notification type when a noticiation is resolved.
NOTIFICATION_TYPE_RESOLVED = 3;
}
NotificationType type = 9;
// The project to which the notification is associated.
internal.endor.ai.endor.v1.Project project = 10;
// The map of finding UUIDs to the correcponding parent repository version objects.
map<string, internal.endor.ai.endor.v1.RepositoryVersion> repository_version_map = 11;
// The project URL in Endor Labs UI.
google.protobuf.StringValue project_app_url = 12;
// The policy URL in Endor Labs UI.
google.protobuf.StringValue policy_app_url = 13;
FindingStats finding_stats = 14;
// The map of package version UUIDs to package version names.
map<string, string> package_version_name_map = 15;
}
To understand Project, Finding, PackageVersion and RepositoryVersion definitions that are used in this protobuf specification, see:
- Project resource kind
- Finding resource kind
- PackageVersion resource kind
- RepositoryVersion resource kind
See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys.
// EmailTemplateFuncs contains the functions that are available in the email template.
var EmailTemplateFuncs = template.FuncMap{
"now": func() string {
now := time.Now()
utc := now.UTC()
return utc.Format("01-02-2006 15:04:05")
},
// findingURL returns the URL for the finding.
"findingURL": func(f *endorpb.Finding, apiURL string) string {
findingURL, err := common.GetFindingURL(apiURL, f)
if err != nil {
return ""
}
return findingURL
},
"getGitImage": func(url string) string {
if strings.HasPrefix(url, "https://github.com") {
return "github.png"
}
if strings.HasPrefix(url, "https://gitlab.com") {
return "gitlab.png"
}
return "default_host.png"
},
"getProjectURL": func(p *endorpb.Project, apiURL string) string {
projectURL, err := common.GetProjectURL(apiURL, p)
if err != nil {
return ""
}
return projectURL
},
"getPackageVersionURL": func(p *endorpb.PackageVersion, apiURL string) string {
packageVersionURL, err := common.GetPackageVersionURL(apiURL, p)
if err != nil {
return ""
}
return packageVersionURL
},
"getFindingLevel": func(f *endorpb.Finding) string {
return f.GetSpec().GetLevel().String()
},
"isPatchAvailable": func(f *endorpb.Finding) bool {
for _, tag := range f.GetSpec().GetFindingTags() {
if tag == endorpb.FindingTags_FINDING_TAGS_FIX_AVAILABLE {
return true
}
}
return false
},
"getPackageEcosystem": func(p *endorpb.PackageVersion) string {
if p == nil {
return "unspecified"
}
offset := len("ECOSYSTEM_")
ecosystem := p.GetSpec().GetEcosystem().String()[offset:]
ecosystem = strings.ToLower(ecosystem)
return ecosystem
},
}
Run a scan
Run the endorctl scan on your configured projects. See endorctl scan commands for more information. You can view email notifications of policy violations in your inbox.
8 - Set up Slack integration
Integrate Endor Labs with Slack and automatically receive policy violations as notifications in your Slack channels. If you are using Slack for team communication and notifications, this integration helps you to seamlessly integrate Endor Labs into your organization’s existing workflows.
Create incoming webhooks in Slack
Create an incoming webhook to your Slack channel to enable Endor Labs to post notifications in the channel. The Incoming Webhook provides a unique URL to integrate your Slack channel in Endor Labs.
Note
We recommend you designate a channel in your Slack workspace for receiving Endor Labs notifications and create an incoming webhook for that channel.To create incoming webhooks in Slack:
- Create a Slack app for Endor Labs or use an existing app.
- Click Create New App.
- Choose From Scratch and Enter a name for the app, for example, Endor Labs.
- Select your workspace and click Create App
- You can enter basic, install, or display information for your Endor Labs app in Slack.
- In Display Information, you can upload a logo and customize App colours to distinguish the Endor Labs App on the Slack workspace.
- Click Save Changes.
- Navigate to Features, select Incoming Webhooks, and toggle Activate Incoming Webhooks.
- Refresh the page and click Add New Webhook to Workspace.
- Select a channel to receive Endor Labs findings in Post to, then select Authorize. If you need to add the incoming webhook to a private channel, you must first be in that channel.
- From Settings, copy the webhook URL under Webhook URLs for Your Workspace. Keep this URL handy to enter in Endor Labs.
For details on creating incoming webhooks in Slack, see Slack Integration.
Configure Slack integration
To configure Slack integration, follow these steps:
- Sign in to Endor Labs and click Integrations from the left sidebar.
- Navigate to Slack under Notifications and click Add.
- Click Add Notification Integration.
- Specify a name and description for this integration.
- Enter webhook URL copied from Slack in Incoming Webhook.
- Click Add Notification Integration.
Associate an action policy with a Slack notification
Users can create action policies to send a Slack notification when the conditions of a given policy are met. For example, if there is a critical or high vulnerability, send the findings to Slack.
While creating an action policy, configure the following settings:
- Select Choose an Action as Send Notification.
- From SELECT NOTIFICATION TARGETS, choose the Slack integration notification that you created.
- Choose an Aggregation type for notifications.
- Choose Project to group and send the findings related to a project in one message. You can see the top 3 findings by their severity level.
- Choose Dependency to send individual messages for every dependency. You can see the top 3 findings by their severity level.
- From Assign Scope, include the project tags in INCLUSIONS to apply this policy to a project.
See Create an action policy for more details.
Manage Slack notification targets in Endor Labs
You can view and manage the Endor Labs Slack notification targets created for a project.
- From the sidebar, navigate to Manage > Notifications.
- Under Notifications, click Manage for Slack. You can view all your created notification targets for Slack.
- To edit a notification target, click the vertical ellipsis and choose Edit Notification Integration.
- To delete a notification target, click the vertical ellipsis dots and choose Delete Notification Integration.
Customize Slack notification templates
Endor Labs provides a default standard template with standard information that will be included in the Slack message. You can use the default template or you can choose to edit and customize this template to fit your organization’s specific requirements. You can also create custom templates using Go Templates.
- Sign in to Endor Labs and navigate to Manage>Integrations.
- Look for Slack under Notifications.
- Click Manage to view the list of configured notification integrations.
- Choose one and click the ellipsis on the right side, and click Edit Template.
- Make required changes to any of the following templates and click Save Template.
- Open - This template is used when new notifications are raised.
- Update - This template is used when an existing notification is updated, such as, when some findings for the notification are changed.
- Click Restore to Default to revert the changes.
- Use the download icon on the top right corner to download this template.
- Use the copy icon to copy the information in the template.
Data model
To create custom templates for Slack messages, you must understand the data supplied to the template.
See the protobuf specification NotificationData
message used for the templates.
syntax = "proto3";
package internal.endor.ai.endor.v1;
import "google/protobuf/wrappers.proto";
import "spec/internal/endor/v1/finding.proto";
import "spec/internal/endor/v1/notification.proto";
import "spec/internal/endor/v1/package_version.proto";
import "spec/internal/endor/v1/project.proto";
import "spec/internal/endor/v1/repository_version.proto";
option go_package = "github.com/endorlabs/monorepo/src/golang/spec/internal.endor.ai/endor/v1";
option java_package = "ai.endor.internal.spec";
// The statistics for findings in a notification.
message FindingStats {
// The total number of findings for a notification.
google.protobuf.UInt32Value num_total_findings = 1;
google.protobuf.UInt32Value num_total_critical_severity_findings = 2;
google.protobuf.UInt32Value num_total_high_severity_findings = 3;
google.protobuf.UInt32Value num_total_medium_severity_findings = 4;
google.protobuf.UInt32Value num_total_low_severity_findings = 5;
// The number of new findings for a notification as compared to the previous scan.
google.protobuf.UInt32Value num_new_findings = 6;
google.protobuf.UInt32Value num_new_critical_severity_findings = 7;
google.protobuf.UInt32Value num_new_high_severity_findings = 8;
google.protobuf.UInt32Value num_new_medium_severity_findings = 9;
google.protobuf.UInt32Value num_new_low_severity_findings = 10;
// The number of findings for a notification that was resolved in latest scan.
google.protobuf.UInt32Value num_resolved_findings = 11;
}
// The data supplied to notification templates while rendering.
message NotificationData {
// The raw notification object.
Notification raw_notification = 1;
// The name of the project.
google.protobuf.StringValue project_name = 2;
// The name of the violated policy that triggered the notification.
google.protobuf.StringValue policy_name = 3;
// The Git reference of the project that was scanned.
google.protobuf.StringValue ref_name = 4;
// The project URL.
google.protobuf.StringValue project_url = 5;
// The map of finding UUIDs to finding objects.
map<string, internal.endor.ai.endor.v1.Finding> findings_map = 6;
// The map of finding UUIDs to corresponding parent package version objects.
map<string, internal.endor.ai.endor.v1.PackageVersion> package_version_map = 7;
// The map of finding UUIDs to corresponding parent project objects.
map<string, internal.endor.ai.endor.v1.Project> project_map = 8;
enum NotificationType {
NOTIFICATION_TYPE_UNSPECIFIED = 0;
// Notification type when a notification is created.
NOTIFICATION_TYPE_CREATE = 1;
// Notification type when a notification is updated.
NOTIFICATION_TYPE_UPDATE = 2;
// Notification type when a noticiation is resolved.
NOTIFICATION_TYPE_RESOLVED = 3;
}
NotificationType type = 9;
// The project to which the notification is associated.
internal.endor.ai.endor.v1.Project project = 10;
// The map of finding UUIDs to the correcponding parent repository version objects.
map<string, internal.endor.ai.endor.v1.RepositoryVersion> repository_version_map = 11;
// The project URL in Endor Labs UI.
google.protobuf.StringValue project_app_url = 12;
// The policy URL in Endor Labs UI.
google.protobuf.StringValue policy_app_url = 13;
FindingStats finding_stats = 14;
// The map of package version UUIDs to package version names.
map<string, string> package_version_name_map = 15;
}
To understand Project, Finding, PackageVersion and RepositoryVersion definitions used in this protobuf specification, see:
- Project resource kind
- Finding resource kind
- PackageVersion resource kind
- RepositoryVersion resource kind
See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys.
// FuncMap contains the additional functions that are available to notification templates.
var FuncMap = func(h *NotificationTemplate) template.FuncMap {
return template.FuncMap{
"now": func() string {
now := time.Now()
utc := now.UTC()
return utc.Format("01-02-2006 15:04:05")
},
// csvFileName generates the filename for the CSV attachment for Jira.
"csvFileName": GetJiraAttachmentFilename,
// findingURL returns the URL for the given finding.
"findingURL": h.getFindingURL,
// toCSV converts the given string to a CSV format.
"toCSV": toCSV,
// findingLevelSlackEmoji returns the slack emoji for the given finding based on severity.
"findingLevelSlackEmoji": GetSlackEmojiForSeverity,
// packageName returns the user facing name of the package.
"packageName": func(p *endorpb.PackageVersion) string {
return lib.GetUserFacingName(p.GetMeta().GetName().GetValue())
},
// filteredFindingsURL returns the URL to view findings with the given uuids
"filteredFindingsURL": common.GetFilteredFindingsURL,
// increment increments the given integer by 1.
"increment": func(i int) int {
return i + 1
},
}
}
Run a scan
Run the endorctl scan on your configured projects. See endorctl scan commands for more information.
View notifications in Slack
View Endor Labs’ findings in Slack and take remedial actions.
- Sign in to Slack and view the notifications on the configured channel.
- You can view the top 3 findings by their severity level. Click View All to see all the findings in Endor Labs.