Skip to main content

Package

In the context of our application of CI/CD pipelines for cloud-based infrastructures, "bundles" play a crucial role. We will detail what they are, how they work and why they are essential for our user community.

What are Packages?​

Packages are essentially sets of predefined configurations that users can share within the community. These packages contain everything needed to configure and run a specific part or a complete CI/CD pipeline. Each package includes two main components:

Templates handlebars: These templates are configuration templates for different stages or aspects of a CI/CD pipeline. They are highly customizable and allow users to define how specific tasks will be executed, such as code integration, testing, deployment, security analysis and more. Handlebars, being a flexible template engine, facilitates the creation of complex configurations in a more accessible and manageable way.

Form Configuration JSON file: This file is the heart of the package. Defines the structure and fields of the dynamic form that users will use to customize the Handlebars template. The JSON details such things as field names, data types, default values, validation rules, and more. This allows users to tailor the package to their specific needs without having to dive deep into the technical details of pipeline configuration.

Package creation​

The packages have the following structure, this structure is the minimum necessary for the system to be able to process the package.

  • README.md
  • config.json
  • tempplates
    • template1.hbs
    • template2.hbs
    • ....

To create a package we can use the generator created with Yeoman, for this we need to install it globally with the following command:

npm install -g yo
npm install -g @opensecdevops/generator-osdo

Once installed, we can create a package with the following command:

yo @opensecdevops/osdo

The generator will ask us a series of questions to generate the package, once finished, we will have the necessary structure to be able to publish the package.

Structure of config.son​

To generate the form, a file named config.json must be created with the following fields

  • name: "Laravel CI" - Package name.
  • version: "1.0.0" - current version of the package.
  • description: "Laravel CI for gitlab" - Short description, specifies that it is for CI/CD in GitLab.
  • homepage: "https//opensecdevops.com" - Project website.
  • repository: Fields for relevant links, currently empty.
  • type: "pipeline or infrastructure" - Indicates what type of package it is.
  • license: "MIT" - Type of license under which the tool is distributed.
  • author: "Rafael Otal" - Name of the author of the tool.
  • template: "gitlab-ci" - Specifies the main template file.
  • file: ".gitlab-ci.yml" - Displayed name that the file must have.
  • language: "yaml" - Indicates the format of the file generated for code highlighting.
  • blocks: Defines different components or "blocks" that can be used in a pipeline.
    • template: Identifies the specific template to be used (e.g., "defectdojo", "composer").
    • name: Descriptive name of the block (such as "Defect Dojo Engagement", "Composer").
    • description: Description of what this block does.
    • info: Additional field for information
    • dependencies: The name of the template of another block on which it depends.
    • fields: Defines specific fields that can be configured for each block.
      • type: Type of field (text, switch, select).
      • name: Name of the field, which is used in the configuration.
      • label: User-readable label of the field.
      • rules: Validation rules for this field, those of robust-validator are used.
      • default: Default value of the field.
      • options: If the field is a selection field, defines the available options.
        • id: used for searches and control
        • label: the text to display
        • value: the actual value
        • dependencies: The name of the template of another block on which it depends.
    • extra: Additional information, such as associated script files and their paths.
      • "language": "bash" - Indicates the format of the file generated for code highlighting.
      • "file": "defectdojo-finding.sh", Name that will be shown that the file has to have.
      • "route": ".gitlab-ci", (Optional) if it is concatenated to the beginning of the name
      • dependencies: The name of the template of another block on which it depends.
      • template: Identifies the specific template to be used (e.g., "defectdojo", "composer").
information

The dependency option can be at block, switch or select level.

warning

Dependencies cannot be removed in the form if there is a block that needs them.

Template generation​

The templates must be located in the templates folder and are rendered with the template engine Handlebars.

The template receives an object with the following structure:

note
{
  "gitleaks": {
    allow_failure: false,
    artifacts: false
    image: 2
    image_value: "zricethezav/gitleaks@sha256:fd2b5cab12b563d2cc538b14631764a1c25577780e3b7dba71657d58da45d9d9"
    job_name: "gitleaks"
  } 
}

Distribution​

To add packages to the platform, it is necessary to publish them in a Git repository. At the moment, only packages hosted on gitlab.com are accepted.

After registering and adding the GitLab API token, you will be able to import your package. The system will automatically search for the most recent tag and incorporate it into the system. If any problems with the JSON structure or missing templates are detected, the package will be notified and will not be published until these errors are corrected.