Ethiack GitLab CI/CD Component

Integration of Ethiack's Public API with GitLab CI/CD.

---

Introduction • Credentials Setup • Usage • License

Introduction

This GitLab CI/CD component facilitates the integration of Ethiack's Public API (API docs) for launching scans through GitLab pipelines. By using this library, you can seamlessly incorporate Ethiack's security scanning capabilities into your GitLab workflows, enhancing your CI/CD pipeline with automated security testing.

(back to top)

Credentials Setup

Using Ethiack's API - and, therefore, this CI/CD component - requires authentication using an API Key and API Secret, which can be retrieved in Ethiack's Portal settings page. These credentials must be available as environment variables ETHIACK_API_KEY and ETHIACK_API_SECRET, repectively, whenever the shared library is used.

In your project, go to Settings » CI/CD » Variables and add variables ETHIACK_API_KEY and ETHIACK_API_SECRET with your API Key and API Secret, respectively.

Example configuration (API Key)

Add variable

Type: Variable (default)
Environments: [Select accordingly]

Flags

☑ Protect variable
☑ Mask variable
☑ Expand variable reference

Description (optional): Ethiack API Key Key: ETHIACK_API_KEY
Value: [YOUR API KEY]

Example configuration (API Secret)

Add variable

Type: Variable (default)
Environments: [Select accordingly]

Flags

☑ Protect variable
☑ Mask variable
☑ Expand variable reference

Description (optional): Ethiack API Secret Key: ETHIACK_API_SECRET
Value: [YOUR API SECRET]

Caution

Ensure that the Mask Variable option is enabled in both variables to avoid them being displayed in plain text in the logs.

Note

If the keys of these secrets do not match the ones provided above, it is necessary to define (export) explicitly the environment variables ETHIACK_API_KEY and ETHIACK_API_SECRET in the respective CI/CD pipeline step.

(back to top)

Usage

Note

This shared library is fundamentally a wrapper around Ethiack's Public API, using Ethiack's Job Manager Package. For more information, see the API docs and refer to the later package.

Example: Launching a job and waiting for its conclusion

This pipeline launches a scan for the domain https://example.ethiack.com and waits until it finishes (cf. --wait flag). If vulnerabilities with severity medium or higher are found, the success of the job is interpreted as failing, and this pipeline step will exit with a non-zero status code (cf. --fail flag).

include:
  - component: gitlab.com/ethiack/gitlab-cicd-component/ethiack-job-manager@main
    inputs:
      stage: test
      command: launch
      url: https://ethiack.com
      args: --wait --fail --severity medium

Example: Checking the success of a job.

This pipeline checks the success of a job. It will fail if the respective job has finished and vulnerabilities with severity equal or above high were found.

include:
  - component: gitlab.com/ethiack/gitlab-cicd-component/ethiack-job-manager@main
    inputs:
      stage: test
      command: success
      uuid: https://ethiack.com
      args: --severity high --fail

Note

For retrieving the success of a job without exiting the pipeline, simply provide the flag --no-fail instead of --fail in the previous example.

Available commands

This shared component supports every command provided by Ethiack's Job Manager Package. This includes, but is not necessarily limited to, the commands:

Command	Description	Required Inputs
check	Check if a URL is valid and a job can be submitted	url
launch	Launch a job and, optionally, wait for it to finish.	url
info	Retrieve information about a job.	uuid
list	List all jobs for the organization.	-
status	Retrieve the status of a job.	uuid
success	Retrieve the success of a job.	uuid
await	Wait for a job to finish.	uuid
cancel	Cancel a queued or running job.	uuid

Required Inputs

The url input refers to the target Uniform Resource Locator (URL) of the service for which the command is run.

The uuid input refers to the Universal Unique Identifier (UUID) of the job for which the command is run.

Optional Arguments

The behaviour of these commands can be customized with flags and additional parameters provided inn the args: variable in the CI/CD pipeline step (e.g., the --fail and --severity flags in the examples above). For more information regarding the available options and flags for each command, please refer to the Job Manager Package.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)