Custom Engines

Overview

This section explains the process of how to add your own Custom Engine to the GuardRails set of engines in order to use it as a part of your scans.

Understand the Custom Engine structure

The Custom Engine skeleton example can be seen here. This repository is a Custom Engine generator that you can use to create your own engine and its README contains all the information needed to create your Custom Engine.

Send the generated Custom Engine zip file to our team

In order to submit your own Custom Engine you first need to send it to our team, so that we can validate the structure, the output format and push the engine Docker image onto our registry.

Important: if you skip this step, you might end up submitting an engine that won't work and this can cause issues with the scan process.

You can also pre-validate your Custom Engine output structure by using this repository. More information on how to use the validator can be found in the README page.

Import the Custom Engine using our API

Until we release our second version that will streamline the import process in our Dashboard, you can import new engines with our API. You can access any API endpoint by following the steps described on: GuardRails API Usage Guide. You will need to use your API Key to do the following:

To upload/import your Custom Engine you will have to execute a request to our /v2/engines/custom endpoint. This endpoint requires:

• Query Parameters:
  • login: this is the name of your account that is the owner account of the custom engine. All custom engines require an associated owner account.
  • provider: this will be login's account provider, which can be either github, gitlab or bitbucket. This 2 parameters will be used to identify the owner account of your custom engine. You must have permissions on this account, which means that the user that leverages the API Key to get a JWT Token must be a user with admin access to this account on the specified provider. The account owner doesn't matter. You can choose a GitLab account as the Custom Engine owner and run this engine over your GitHub or Bitbucket accounts.
• Authorization:
  • Bearer token: The JWT Token you got from following the previous step (described here: GuardRails API Usage Guide).
• Body:
  • enctype: "multipart/form-data" - This is used to upload your Custom Engine as a compressed zip file.
  • engine: The file parameter name with the value @path/to/local/file, remember that we only accept .zip files.

This is how you can import your custom engine using curl:

curl --request POST -H 'Accept: application/json' -H 'Authorization: Bearer {JWT_TOKEN}' -F 'engine=@path/to/engine/engine-name.zip' https://{API_BASE_URL}/v2/engines/custom?login={OWNER_ACCOUNT_LOGIN}&provider={OWNER_ACCOUNT_PROVIDER}

• JWT_TOKEN: The token you got using your API Key.
• API_BASE_URL The GuardRails API base url, normally it would be api.guardrails.io, but if you're using the GuardRails Enterprise on-premise version, it will be a different one. Note: for on-premise deployments the API port is not 443, but 1444.
• OWNER_ACCOUNT_LOGIN: The owner account login/name.
• OWNER_ACCOUNT_PROVIDER: The owner account provider.

Note: Make sure you don't change the engine parameter name where you set the file's path.

Example case:

curl --request POST -H 'Accept: application/json' -H "Authorization: Bearer **************" -F 'engine=@~/Downloads/detect-sensitive-artifacts-master.zip' https://api.guardrails.io/v2/engines/custom\?login\=guardrailsio\&provider\=github

Ensuring that the Custom Engine are executed

There are a few considerations before our scans decide whether to run your Custom Engine:

1. runForLanguages: After we detected the languages of your repository, scans will check that your Custom engine runForLanguages value is one of those detected languages. So, if for example, you set "runForLanguages": "javascript" and our scan detects the javascript language on your repo, then the scans won't filter your custom engine on this step, otherwise, it will be already skipped on this step.

2. Account type: Custom Engines are available for GuardRails Enterprise on-premise accounts or for Business plan accounts. So if your account is not one of these 2 types, or you downgraded your plan from Business, the scans will skip the Custom Engine and it won't be executed.

3. allowFor: Scans will check that the accounts related to the repository that the scan is being executed for are configured on the allowFor attribute of your Custom Engine manifest file. This means that if the scan is running over repository-A, which belongs to orgname-A (on GitHub) and your allowFor includes "providers": { "github": ["orgname-A", ...] } then your Custom Engine will be run. Otherwise it will be skipped and won't be executed.

4. Your account or repository bundles configuration: You can add or remove your Custom Engine from your GuardRails Configuration. If your configuration is set to automatic (no configuration file in your repository and automatic bundle detection on your account) your Custom Engine will be executed at this point. If you don't have an automatic configuration and your bundles doesn't include your Custom Engine, then it will be skipped and won't be executed.