Integrate Security Audit with Tekton

You can integrate API Security Audit with your Tekton CI/CD system through a custom build task in the extension REST API Static Security Testing.

Before you start, make sure you have kubectl and a Tekton pipeline set up. For more details, see kubectl documentation and Tekton documentation.

You must have an account in 42Crunch Platform that REST API Static Security Testing can use to access Security Audit.

Create an API token

You must add an API token that REST API Static Security Testing uses to authenticate to Security Audit.

1. Log in to 42Crunch Platform, and click next to your username.
2. Select Tokens, and click Create new token.
3. Enter a unique and descriptive name for the token, such as Security Audit token.
4. Make sure the token type is API token, and in token access rights, select API Security Audit, List resources, and Delete resources.

   

5. Click Generate token.
6. Copy the token value, you will need it when you configure REST API Static Security Testing.

   

Add the API token to your Kubernetes secrets

Your Tekton pipeline must have access to the API token you just created so that it can use it to authenticate to run Security Audit. You can add the API token you just created in your Kubernetes secrets.

Always store all your tokens securely, for example, in Kubernetes Secrets, like other secrets you use! Treat tokens as you would other sensitive information, like your passwords.

1. Convert the token value you copied to base64 encoded format.

2. Create a YAML file with the following contents, and name it so you can identify it later, for example, secret.yaml:

   apiVersion: v1
   kind: Secret
   metadata:
       name: 42crunch-api-token
   type: Opaque
   data:
        X42C_API_TOKEN: "<the base64 encoded token>"

   Replace the placeholder with the token you encoded.

3. Run the following command to add the secret to your Kubernetes Secrets:

   kubectl apply -f secret.yaml

The API token is now added to your Kubernetes Secrets and your Tekton pipeline can authenticate to Security Audit.

Configure your Tekton pipeline

You can add the task REST API Static Security Testing as part of the workflow of your Tekton pipeline.

If you are new to Tekton, or want to test REST API Static Security Testing locally, you can find a self-contained sample in our GitHub repository that you can run, for example, in Minikube.

1. Install the build task to your Tekton CI/CD:

   kubectl apply -f https://api.hub.tekton.dev/v1/resource/tekton/task/42crunch-api-security-audit/0.2/raw

2. Find the Tekton pipeline where you want to add the plugin, and make sure that it already includes steps to access and fetch the directory that contains the OpenAPI definitions that you want to include in the audit.
3. Open pipeline.yaml for editing, and add the following to the parameters that the task requires to those of the pipeline:

   apiVersion: tekton.dev/v1beta1
   kind: Pipeline
   metadata:
     ...
   spec:
     params:
       ...
       - name: repo-url
         type: string
       - name: branch
         type: string
       - name: x42c_secret_name
         type: string
       ...

4. Go to the spot in the tasks where you want the audit to take place, and add the following:

   ...
   - name: audit
     runAfter: ["<replace with the list of preceding tasks>"]
     taskRef:
       name: 42crunch-api-security-audit
     workspaces:
       - name: workdir
         workspace: <replace with the workspace that contains the files to audit>
     params:
       - name: x42c_repository_url
         value: $(params.repo-url)
       - name: x42c_branch_name
         value: $(params.branch)
       - name: x42c_secret_name
         value: $(params.x42c_secret_name)
   ...

   This example assumes that the values come from pipeline-run.yaml instead of being hard-coded to the pipeline. The following is the minimum configuration that the pipeline requires to run the task successfully:

   Variable	Description
   x42c_repository_url	Source control repository URL. Used when naming the created API collection in 42Crunch Platform for the OpenAPI definitions it discovered. On subsequent runs, it synchronizes the contents of that API collection with the APIs in the referenced workspace.
   x42c_branch_name	Source control repository URL. Used when naming the created API collection in 42Crunch Platform.
   x42c_secret_name	Name of the secret you added for the API token so that the task can access42Crunch Platform. The default name (and the one used in this example) is 42crunch-api-token.

   REST API Static Security Testing assumes that the OpenAPI files come from a source control repository, so the parameters x42c_repository_url and either x42c_branch_name, x42c_tag_name, or x42c_pr_id are required. If you use x42c_pr_id, you must also include the variable x42c_pr_target_branch.

5. If you want, you can include the following optional parameters in pipeline.yaml, then save the file:

   Variable	Description
   x42c_min_score	The minimum audit score that the OpenAPI definitions must get from the audit for this CI/CD step to pass successfully. If any API definitions score lower than the minimum score you set, the CI/CD step fails. If not defined, the default value is 75. The fail-on criteria you set in the CI/CD plugin, such as the minimum score, are independent from the acceptance criteria defined in security quality gates (SQGs). This means that your CI/CD build can fail either because the criteria of the plugin are not met, the criteria of a SQG are not met, or both.
   x42c_platform_url	If you are an enterprise customer not accessing 42Crunch Platform at https://platform.42crunch.com, include this parameter and set your platform URL as its value. Most users do not need to specify this parameter, because it defaults to https://platform.42crunch.com. If you are not sure what your platform URL is, contact our support.
   x42c_log_level	The level of detail (FATAL, ERROR, WARN, INFO, DEBUG) in the logs that the image produces. If not defined, the default value is INFO.
   x42c_share_everyone	Are the API collections created in 42Crunch Platform automatically shared with other users in your organization. If you do not set the parameter, the API collections are not shared but remain private to you. The variable has two possible values: READ_ONLY: Other users have read-only access READ_WRITE: Other users have read and write access

6. If using pipeline-run.yaml, remember to include the parameters where you want to the values to change depending on the run, and save the file.
7. To test the task, run your pipeline.

REST API Static Security Testing now runs as part of your Tekton pipeline and will either succeed or fail depending on the minimum score. REST API Static Security Testing uploads all discovered OpenAPI definitions to the specified API collection in 42Crunch Platform. By default when running on branch, the plugin uses the naming convention <shortened-source-control-uri> Branch:<branch-name> for the created API collection, for example, 42Crunch/sample Branch:sample.

The API definitions in the collection show the filepaths they have in the repository:

REST API Static Security Testing prints a report of the run to provide you further details on how the CI/CD job went, including a link to each discovered API. You can click on the link to view the detailed audit report of the corresponding API in 42Crunch Platform.

Write summary of the plugin run in a file

If you want, you can set the plugin to write and store a report on the plugin run as a JSON file, so that it is easy, for example, to see and communicate the API UUIDs of the uploaded APIs.

This is not the audit report that provides details on the issues that Security Audit found in your APIs and how to remediate them, but a separate, optional summary providing some basic details on the APIs that the plugin processed. The full audit reports are not included in this summary, but are available in 42Crunch Platform.

1. Go to the pipeline you want, and open the pipeline configuration for editing.
2. Add the parameter x42c_json_report to the action, and enter the filename or path that you want to use for report file.

   ...
     params:
       - name: x42c_repository_url
         value: $(params.repo-url)
       - name: x42c_branch_name
         value: $(params.branch)
       - name: x42c_secret_name
         value: $(params.x42c_secret_name)
         ...
       - name: x42c_json_report
         value: <the filename or path for the report>
   ...

   The report is in JSON format, so ensure that you either specify .json as the file extension (as in test/myReport.json) or omit the extension completely (test/myReport).
   • If you specify only the filename, the plugin creates the file in the root directory that it is pointed to start from.
   • If you specify a path, the path must be under the root directory and all specified directories must exist. The plugin only generates the JSON file, not directories.

   The plugin does not delete or overwrite any summaries from previous runs, so if a file with the same name exists, you see an error. To avoid this, you can create a separate workspace for each pipeline pass, add a task to clear the workspace before starting, or include a variable to the filename (such as the build number or timestamp) to ensure that each filename is unique.

3. Save your changes.

Next time you run the pipeline, the integration writes a summary report as a JSON file in the location you specified. This report shows the details on discovered, such as:

• Filename
• API UUID assigned for the API when it was uploaded to 42Crunch Platform
• Audit score
• Did the pipeline task fail and if yes, why
• Any errors that occurred when processing the API

Fine-tune the plugin configuration

You can further fine-tune how the integration works by adding a configuration file called 42c-conf.yaml to the root directory of your source code repository where the CI/CD pipeline connects to. You can, for example:

• Configure the plugin to run in the collection mode, applying predefined settings and sharing with teams in your organization on any API collections that it creates.
• Control what happens in the discovery phase.
• Map OpenAPI files in your repository to API UUIDs of APIs in the platform.
• Specify fail_on conditions to define what the plugin reports as failures.

  The fail-on criteria you set in the CI/CD plugin, such as the minimum score, are independent from the acceptance criteria defined in security quality gates (SQGs). This means that your CI/CD build can fail either because the criteria of the plugin are not met, the criteria of a SQG are not met, or both.

You can specify different configurations for different branches, tags, or even pull requests. For more details, see the configuration examples in our Resources repository in GitHub.

Change the default collection name

You can specify a syntax for the new collections that the plugin uses by default, instead of simply naming the collection based on your source repository URL.

1. Open the pipeline you want for editing.
2. Add the parameter x42c_default_collection_name, and enter the syntax for the default collection name you want to use. You can use text (like foo), reference to parameters (${repository}), or a combination of the two (foo ${repository}). You can use the following parameters that are populated from your repository details:
   • repository: The full repository URL.
   • repo_short_path: A shortened path of the repository URL (the leading / and the trailing .git are omitted).
   • repo_hostname: The hostname from the repository URL.
   • branch_info:The syntax Branch:<branch name>, or an empty string if this information is not available.
   • tag_info: The syntax Tag:<tag name>, or an empty string if this information is not available.
   • pr_info: The syntax PR:<pr id>, or an empty string if this information is not available.
3. When ready, save your changes.

Next time you run the CI/CD pipeline, REST API Static Security Testing uses the syntax you defined and creates new API collections in 42Crunch Platform (if collections with the same names do not yet exist) where it loads the discovered APIs.

You can also define collection names for specific branches, tags, and pull requests using the property collection_name in the configuration file 42c-conf.yaml.

Set the root directory

By default, the integration plugin uses the root directory of your repository as its starting point. However, you can also set a specific directory that the plugin will use as its root.

If you have configured 42c-conf.yaml for your plugin, make sure it is located in the root directory that you want the plugin to use. Otherwise, the configuration file is ignored.

1. Go to the pipeline you want, and open the pipeline configuration for editing.
2. Add the parameter x42c-root-directory to the action, and enter the path of the directory you want to use as the root directory.
3. Save your changes.

Next time you run the pipeline, REST API Static Security Testing will start the discovery phase from the specified directory path and check that directory and any subdirectories under it for OpenAPI files.

Add tags to APIs

You do not have to wait till your OpenAPI definitions are in 42Crunch Platform to apply tags to them. If you have some tags that you know your APIs need, you can set those tags directly in the CI/CD plugin. The plugin then applies the tags to all new APIs it discovers. For more details, see Tags.

Tags consist of category:tag value pairs, and each tag always has a category it belongs to. Before you start, the categories you want to use must already exist in 42Crunch Platform.

If a tag category allows users to create tags in it, you do not necessarily have to go and create the tags beforehand — in this case, the CI/CD plugin can create any missing tags for you. However, if a tag category does not allow user-created tags, all tags you want to apply must exist before you run your pipeline, otherwise the build task fails. For more details, see Category settings.

1. Go to the pipeline you want, and open the pipeline configuration for editing.
2. Add the parameter x42c-api-tagsto the action, and list the tags that you want the plugin to apply to APIs it discovers. If applying multiple tags, separate each key-value pair with a space. For example, if you would want to apply a tag called foo from category1 and a tag called bar from category2, you would enter category1:foo category2:bar.

   ...
     params:
       - name: x42c_repository_url
         value: $(params.repo-url)
       - name: x42c_branch_name
         value: $(params.branch)
       - name: x42c_secret_name
         value: $(params.x42c_secret_name)
         ...
       - name: x42c_api_tags
         value: category1:foo category2:bar
   ...

   Category settings may restrict how you can use the tags from a category, such as how many tags from it you can apply to a single API. The CI/CD plugin cannot apply tags from a category that only allows organization administrators to apply tags.

3. Save your changes.

Next time you run the pipeline, the integration plugin will apply the tags you listed to all new APIs that it discovers in your repository before the APIs are audited. Only newly discovered APIs are tagged: the plugin does not apply tags to APIs it has already uploaded to 42Crunch Platform, nor to any APIs you might have mapped in your 42c-conf.yaml file.

If the CI/CD plugin cannot apply one or more of the tags you have listed, either because the category does not exist or the category settings prevent the plugin from applying using it or creating any missing tags, the plugin fails the build task. If this happens, you can:

• Remove the tags that cause the failure from the plugin configuration.
• Ask you organization administrators to change the settings of the tag categories that are causing the problem.
• Ask your organization administrators to create any missing tags that you need.

Tags created through the CI/CD plugin do not have descriptions, but organization administrators can update the tags to add one.

Use SQG criteria instead of plugin configuration

By default, the integration plugin configuration defines when the CI/CD task passes or fails, and there are some default values that the plugin uses if nothing else is specified. However, if you are using security quality gates (SQGs) in 42Crunch Platform for quality control, you might prefer SQGs to determine when the CI/CD task passes or fails. In this case, you can set the plugin to skip the locally defined fail-on conditions (such as minimum score, format validity, or forbidden issues) and only use those defined in the SQGs.

1. Go to the pipeline you want, and open the pipeline configuration for editing.
2. Add the parameter x42c-skip-local-checks to the action, and set that to true:

   ...
     params:
       - name: x42c_repository_url
         value: $(params.repo-url)
       - name: x42c_branch_name
         value: $(params.branch)
       - name: x42c_secret_name
         value: $(params.x42c_secret_name)
         ...
       - name: x42c_skip_local_checks
         value: true
   ...

3. Save your changes.

Next time you run the pipeline, the plugin will only check the status of all SQGs applied to the APIs it found in the repository when deciding if the build passes or fails, and ignore any fail-on conditions defined in the plugin itself, including the default plugin configuration.

Stop the plugin from failing a pipeline

Sometimes you might want the CI/CD plugin just to report the found issues, not block the pipeline from continuing. For example, your repository might have plenty of APIs in early stages of their lifecycle, or you have just introduced the CI/CD plugin to the pipeline and need time to adjust to the set quality criteria. In this case, you can temporarily switch off all fail-on conditions that the CI/CD plugin would impose on a CI/CD job. The plugin keeps reporting on the discovered APIs but does not block the pipeline from proceeding to subsequent stages.

Switching off the fail-on conditions in the CI/CD plugin means that the plugin will cease to work as a quality control as it will never prevent potential problems in your APIs. We recommend that you use this option only after a careful consideration and only for a limited time. Remember to remove this setting from the plugin as soon as possible.

1. Go to the pipeline you want, and open the pipeline configuration for editing.
2. Add the parameter x42c_ignore_failures to the action, and set that to true:

   ...
     params:
       - name: x42c_repository_url
         value: $(params.repo-url)
       - name: x42c_branch_name
         value: $(params.branch)
       - name: x42c_secret_name
         value: $(params.x42c_secret_name)
         ...
       - name: x42c_ignore_failures
         value: true
   ...

3. Save your changes.

Next time you run the pipeline, the integration plugin runs normally, uploading each discovered API definition and its audit report to 42Crunch Platform, but does not fail the CI/CD job because of the audit results or SQG status. However, the plugin still produces logs as per usual, so you can check them to see the status of the discovered APIs.

Ignore network errors

If you are worried that issues in connectivity — such as in the rare case of the CI/CD plugin not being able to communicate to 42Crunch Platform — could unduly hinder an important CI/CD pipeline by causing it to fail, you can set the plugin to ignore connectivity issues.

Setting the CI/CD plugin to ignore network errors lessens the plugin's effectivity as a quality control, because the task does not stop the CI/CD pipeline even though it could not complete successfully due to a connectivity issue. This means that APIs that have quality or security issues in their OpenAPI definitions could slip through upon a successful CI/CD job. We recommend that you use this option only after a careful consideration.

1. Go to the pipeline you want, and open the pipeline configuration for editing.
2. Add the parameter x42c-ignore-network-errors to the action, and set that to true:

   ...
     params:
       - name: x42c_repository_url
         value: $(params.repo-url)
       - name: x42c_branch_name
         value: $(params.branch)
       - name: x42c_secret_name
         value: $(params.x42c_secret_name)
         ...
       - name: x42c_ignore_network_errors
         value: true
   ...

3. Save your changes.

Next time you run the pipeline, if the integration plugin encounters a connectivity issue, it does not fail the CI/CD job and the pipeline proceed to subsequent steps. Errors that cannot be definitively deemed to be connectivity issues will still cause the plugin to fail the job. You can check the logs that the plugin produces to see if any errors occurred.