Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Getting Started with Red Hat Trusted Application Pipeline

Red Hat Trusted Application Pipeline 1.3

Learn how to get started with Red Hat Trusted Application Pipeline.

Red Hat Trusted Application Pipeline Documentation Team

Abstract

This document provides instructions about using ready-to-use software templates for building applications that are infused with secure supply chain features, such as signatures, attestations, Software Bill of Materials (SBOM), SLSA verification, CVE scanning, and release policy guardrails.

Preface

With RHTAP, you embark on a journey that transcends traditional security measures, integrating cutting-edge solutions and a DevSecOps CI/CD framework from inception to deployment. This proactive strategy accelerates developer onboarding, process acceleration, and the embedding of security from the beginning.

Chapter 1. Development workflow

The development workflow involves creating, updating, securing, and deploying applications. It also allows integration with various repositories, container registries, and CI/CD tools for flexibility.

StepDescription

Install RHTAP

Install RHTAP to enable secure and efficient DevSecOps workflows.

Create an application

Use pre-built templates to create an application. These templates are customizable and include pipelines and configurations to simplify the development process. When creating an application you can choose:

  • GitHub (default), Gitlab, or Bitbucket for repositories
  • Quay (default) or Jfrog Artifactory for registries
  • Tekton (default), GitHub Actions, Jenkins CI, or GitLab CI for CI/CD workflows
Note

If you select Bitbucket, GitLab CI, or Jenkins CI during application setup, you must configure these tools to trigger pipeline runs.

Update an application

Push updates to your application code. The pipeline automatically processes and secures the changes.

View security insights

Pipeline runs provide a visual representation of all tasks, offering insights into security checks and compliance.

Deploy an application

Promote your application from Development to Staging and then to Production environments.

(Optional) Customize templates and pipelines

Modify templates and pipelines to meet your organization’s specific requirements.

Next step

Chapter 2. Building an application with sample software templates

RHTAP’s ready-to-use software templates include default integrations with key technologies to secure and optimize your development experience:

  • ACS (Advanced Cluster Security): Identifies and mitigates vulnerabilities early in the development process, strengthening your application from inception to deployment.
  • Quay: Serves as a secure harbor for your container images, continuously scanning for vulnerabilities to keep your containerized applications safe.
  • Tekton Pipelines: Automates your build and deployment processes, providing a CI/CD framework that integrates seamlessly into your SDLC and accelerates your path to production.
  • GitOps: Maintains your infrastructure and application configurations in Git repositories, ensuring consistent and automated deployment across all environments.

Additionally, RHTAP supports the development and containerization of applications in popular programming languages such as Java, Python, Node.js, and Go.

Note

After installing RHTAP, cluster administrators can customize the Red Hat Developer Hub portal with specific templates and enhancements. However, before customization, cluster administrators should familiarize themselves with the available software and pipeline templates through this guide. Understanding these templates is key to grasping how RHTAP supports a secure supply chain, laying the groundwork for any subsequent customization.

2.1. Setting the stage

  • Ensure you have successfully installed RHTAP.

  • Log in to Red Hat Developer Hub (RHDH) using the link provided by RHTAP installer at the end of the installation process.

2.2. Building an application

On the RHDH portal, select Create, and then select a suitable template. For example, Quarkus Java - Trusted Application Pipeline.

Building an application or microservice for your developers in RHDH using the templates offered by RHTAP involves three main steps:

  • Provide application information
  • Provide application repository information
  • Provide deployment information
Providing application information
  1. In the Name field, provide an application name. Your name may incorporate lowercase letters (a-z), numbers (0-9), and dashes (-), but it must start and end with a lowercase alphanumeric character. Examples of valid names are my-name or abc-123, and the length should range from 1 to 63 characters.
  2. From the Owner dropdown list, select an appropriate RHDH component owner for this application. The default value is user:guest, which appears if no specific owner is registered in the system. If you have not registered an owner, retain the default user:guest selection. You can replace guest with your username to personalize ownership of the application.
  3. Select Next. The system displays the Application Repository Information form.
Providing application repository information

  1. From the Host Type dropdown list, select a repository host type:

    • GitHub
    • GitLab
    • Bitbucket
  2. In the Repository Name field, enter a repository name using A-Z, a-z, 0-9, underscore (_), and dashes (-). The system uses this name for the repository it creates on the host repository server.
  3. In the Repository Owner field, specify the username, organization name, or project within an organization that owns the Git repository. For example, in Bitbucket, you can find your username by navigating to Personal Bitbucket settings.

  4. In the Repository Server field, specify the repository server:

    If you select the Host typeDescription

    GitHub

    The field is pre-populated with github.com. However, you can enter your on-premises host URL without the HTTP protocol and without the .git extension. For example, github-github.apps.cluster-ljg9z.sandbox219.opentlc.com.

    GitLab

    The field is pre-populated with gitlab.com. However, you can enter your on-premises host URL without the HTTP protocol and without the .git extension. For example, gitlab-gitlab.apps.cluster-ljg9z.sandbox219.opentlc.com.

    Bitbucket

    The field is pre-populated with bitbucket.org.

  5. In the Repository Default Branch field, specify the default branch for your repository. The default is main, but you can specify a different branch name.

  6. For Bitbucket only:

    1. In the Workspace field, enter the name of your workspace that contains your project.
    2. In the Project field, enter the project key. The project key is located next to the project name in Bitbucket.

  7. From the CI Provider dropdown list, select the continuous integration (CI) tool that the system uses to build, test, and deploy the application:

    For Host typeAvailable CI providers

    Bitbucket

    • Jenkins (SLSA 2)
    • Tekton (SLSA 3)

    GitHub

    • Jenkins (SLSA 2)
    • Github Actions (SLSA 2) (Technology Preview)
    • Tekton (SLSA 3)

    GitLab

    • Jenkins (SLSA 2)
    • GitLab CI (SLSA 2)
    • Tekton (SLSA 3)
    Important

    After you complete creating an application:

    • If you select Bitbucket as a source repository and Tekton as CI, you must add webhook in Bitbucket.
    • If you select GitLab CI, you must configure the required secrets.
    • If you select Jenkins, you must add your application to Jenkins.
  8. Select Next. The system displays the Deployment Information form.
Providing deployment information
  1. In the Image Registry field, specify the on-premises image registry URL without the HTTP protocol. Support registries include Quay (for example, quay.io) and JFrog Artifactory (for example, tssc.jfrog.io).
  2. In the Image Organization field, enter the image organization for the image registry you provided in the Step 1.

  3. In the Image Name field, enter an image name using only lowercase letters, digits, and separators. Separators include a period (.), up to two underscores (_), or one or more hyphens (-). For example, my-app_1.2.

    Note

    You must ensure that the name does not start or end with a separator.

  4. In the Deployment Namespace field, enter the prefix for the namespaces or cluster where you intend to deploy your application. The system creates the namespaces as rhtap-app-development, rhtap-app-stage, and rhtap-app-prod.

    Note

    rhtap-app is the default deployment namespace prefix. Cluster administrators can customize this prefix. For instructions on how to customize the default deployment namespace prefix, refer to Customizing sample software templates.

  5. Select Review to review all the information that you added.

  6. Select Create. RHTAP initiates automated tasks to set up your application’s infrastructure and deployment pipeline, including:

    • Repository Creation and Configuration: Creates a new repository in your specified hosting service, including the GitOps repository and the source repository.
    • Argo CD Integration: Creates and configures Argo CD resources to orchestrate the deployment of your application across specified namespaces.
    • Namespace Creation: Generates namespaces for development, staging, and production environments.
    • Pipeline Definition: Adds a pipeline definition, providing a "Pipelines as Code" model for building, testing, and deploying your application.

2.3. Reviewing application

After creating an application using RHTAP, you can review its components, source code, GitOps configurations, and associated documentation.

Quick analysis

For a quick review, click the links displayed on the "Run of …​" page. These links provide access to important resources such as:

  • Source repositories
  • GitOps repositories

Comprehensive analysis

For a detailed analysis, follow these steps:

  • Select Open Component in catalog or navigate to the Catalog, where your newly created application is listed.

  • Examining source code:

    1. Go to the Overview tab and select View Source to open the repository containing your application’s source code.

  • Reviewing deployment history:

    1. In the Overview tab, navigate to the Deployment summary section to review the application’s deployment across namespaces. Select any Argo CD app to view deployment details in Argo CD, or click a commit ID from the Revision column to review changes in GitLab or GitHub.

  • Reviewing GitOps repository:

    1. On the Overview tab, use the Kind dropdown to select Resource and find the relevant GitOps repository.
    2. Select View Source to examine the GitOps configurations directly. Alternatively, for a broader overview including technical documentation, select View TechDocs from the Catalog section and then choose the GitOps repository under Home > Repository.

  • Reviewing documentation:

    1. From the Overview tab, select View Tech Docs. This opens the technical documentation for your application, providing detailed insights into its features, configuration steps, and usage.

2.4. (Optional) Unregistering application

This process removes the application’s source and GitOps repository from your catalog and resource view, essentially hiding it. The application remains functional within the cluster. You can re-register unregistered applications at any time.

  1. Navigate to the Catalog and select the component that you want to unregister.

  2. Select vertical three-dot menu associated with the component, and then select Unregister entity. The system displays a confirmation dialog box.

    unregister
  3. Select Unregister Location. This removes the application’s Git repository from your catalog view.
  4. Navigate to the Catalog, from the Kind drop down list, select Resource, and then unregister the corresponding GitOps resource.

  5. Remove the application from the cluster, by running the following command: 

    oc delete application your-app-name-app-of-apps -n rhtap 1
    1
    Replace rhtap with your namespace if different, and your-app-name with the name of your application.

Next steps

Chapter 3. Updating code and viewing security insights

After building your component with RHTAP, update your code and review the security insights.

3.1. Updating code

  1. Go to the Catalog and select the component that you want to modify.

  2. On the Overview tab, select the View Source tab to open your project in GitLab or GitHub.

    1. You can also select View Tech Docs to review your project’s documentation. The documentation source is in the docs directory in your repository. Updates to these files trigger a pipeline run, which refreshes the Tech Docs.

  3. Make changes to your code.

    1. Clone your repository.
    2. Modify your application. For example, update technical docs, or index.html.
    3. Commit and push your changes.
    Note
    • You can also use GitLab or GitHub UI, to directly update your code within the web interface.
    • For GitLab users only: You have to set up webhooks and secrets in GitLab to automatically trigger pipeline run upon code updates. For information on setting up webhooks and secrets in GitLab, see Setting up GitLab for Security Integrations.

3.2. Viewing the pipeline run

  1. Open RHDH, navigate to the Catalog, and select the modified component.
  2. Select the CI tab to view the pipeline run details.
  3. (Optional) Select the CD tab to gain insights into deployments managed by ArgoCD and GitOps.
  4. (Optional) Select the Topology tab to visualize your application’s deployment within the development namespace.

3.3. Viewing security insights

The system automatically triggers an on-push pipeline when you update your code and push changes. By default, RHTAP uses a standard build pipeline for containerized deployment meeting Software Artifacts (SLSA) level 3 specifications.

Figure 3.1. A successful pipeline run

pipeline run

The pipeline run performs the following tasks:

  • init: Configures rebuild flags, authentication, and creates an image repository secret.
  • clone-repository: Clones the repository to prepare for the build.

  • build-container:

    • Creates a container image from the source code using Buildah and pushes it to a registry.
    • Generates a Software Bill of Materials (SBOM) to document all components and dependencies.
    • Publishes security artifacts like image signatures and attestations.
  • update-deployment: Updates the GitOps repository to deploy the new image.
  • acs tasks: Runs security checks to ensure compliance with policies.
  • show-sbom: Lists all software components and libraries for transparency.
  • summary: Cleans up resources and provides a summary of the pipeline run.
Note

Click any task in a pipeline run to view logs.

3.3.1. Advanced Cluster Security tasks

ACS tasks in the pipeline succeed only if you have installed and configured ACS during the RHTAP installation process. If ACS is not installed or configured, pipeline skips these tasks.

Note

Figure 3.2. The ACS tasks in the pipeline run

acs tasks

The pipeline includes three ACS tasks that use roxctl to perform security checks:

  • roxctl image scan - Identifies components and vulnerabilities in the image and returns results in the JSON format.
  • roxctl image check - Verifies build-time security violations in the image. For example, policy such as 'No log4j allowed' or restrictions against including curl, wget, or package managers in production images.
  • roxctl deployment check - Checks for build-time and deploy-time security violations in the YAML deployment files.
Visualizing ACS reports

In RHDH, under the CI tab, the Pipeline Runs section displays detailed task reports in a structured pop-up interface. The pop-up includes:

  • Advanced Cluster Security (conditionally shown on the availability of ACS tasks): Displays individual tabs for all the ACS tasks, summarizing identified security issues.
  • Others: Provides results from the PipelineRun, for example, IMAGE_URL, and IMAGE_DIGEST. This section displays only if multiple sections (for example, Enterprise Contract or {RHACSLongName}) are available in the pop-up.

To view ACS reports:

  1. Select Catalog and select the component you want to review.

  2. Select the CI tab > Actions column > View output icon and review the detailed ACS reports for the selected component.

    Figure 3.3. The detailed ACS reports

    acs report
    Note

    If you have the required permissions, you can manage vulnerabilities, policies, and review detailed vulnerability reports for a specific image in the ACS console. For more information, see Viewing the dashboard.

Interpreting ACS reports

Reports from ACS tasks provide security insights that are critical for maintaining a strong security posture.

Here’s an example of interpreting roxctl image scan (Image Scan) reports. Use the same approach for roxctl image check (Image Check) and roxctl deployment check (Deployment Check) reports.

  • Vulnerability Breakdown: ACS categorize detected vulnerabilities by severity (Critical, Important, Moderate, Low), status (fixable, non-fixable), and offer a summary of the scan results. This categorization includes the total number of vulnerabilities and components analyzed, alongside specific Common Vulnerabilities and Exposures (CVEs) identified.

  • Details Provided: For each identified vulnerability, the report includes:

    • CVE ID: A unique identifier for the vulnerability.
    • Severity: The level of threat posed by the vulnerability.
    • Component: The software component affected by the vulnerability.
    • Component Version: The version of the affected component.
    • Remediation Suggestions: Recommendations for addressing the vulnerability, including the version in which the vulnerability is fixed, if applicable.

3.3.2. Understanding SBOM

The show-sbom task creates a list of all software libraries used in the application. This helps identify vulnerabilities and assess security impacts.

Figure 3.4. The show-sbom task in the pipeline run

sbom
Viewing SBOM

Procedures

  1. Select Catalog and select a component.

  2. Select the CI tab and then select the link icon for the show-sbom task. The system displays the SBOM task logs. Review the SBOM in your browser and search for vulnerabilities such as log4j.

    Figure 3.5. The SBOM details

    show sbom
Downloading an SBOM in the CLI

Prerequisites

  • You have installed the Cosign CLI tool.
  • The build-container and show-sbom tasks ran successfully.

Procedures

  1. Expand the successful pipeline run and select the show-summary task.

  2. Search and copy the SBOM image URL, and run the following command on your terminal.

    Example cosign command

    $ cosign download sbom <the-sbom-url-you-copied>

    1. (Optional) Save the output to a file for detailed analysis:

      Example cosign command

      $ cosign download sbom <the-sbom-url-you-copied> > sbom.txt

Interpreting SBOMs

The SBOM includes information about each library used in your project, such as:

  • The source of the library, author or publisher
  • The library name
  • The library version
  • The license type

This information helps ensure individual libraries are safely-sourced, updated, and compliant.

Example SBOM

{
    "bomFormat": "CycloneDX",
    "specVersion": "1.4",
    "serialNumber": "urn:uuid:89146fc4-342f-496b-9cc9-07a6a1554220",
    "version": 1,
    "metadata": {
        ...
    },
    "components": [
        {
            "bom-ref": "pkg:pypi/flask@2.1.0?package-id=d6ad7ed5aac04a8",
            "type": "library",
            "author": "Armin Ronacher <armin.ronacher@active-4.com>",
            "name": "Flask",
            "version": "2.1.0",
            "licenses": [
                {
                    "license": {
                        "id": "BSD-3-Clause"
                    }
                }
            ],
            "cpe": "cpe:2.3:a:armin-ronacher:python-Flask:2.1.0:*:*:*:*:*:*:*",
            "purl": "pkg:pypi/Flask@2.1.0",
            "properties": [
                {
                    "name": "syft:package:foundBy",
                    "value": "python-package-cataloger"
                    ...

Next steps

Chapter 4. Deploying application and view security insights

Deploy applications using Argo CD in OpenShift GitOps to enable continuos deployment. Argo CD uses your Git repository as a single source of truth for infrastructure configurations. Updates to the repository trigger deployments across development, staging, and production environments.

Note

The procedures provide an example deployment workflow. Customize it to fit your organization’s requirements.

4.1. Promoting a build to a pre-production or production environment

Promote a build by updating the GitOps repository through a pull request (PR).

  1. In RHDH, select Catalog.
  2. From the Kind dropdown list, select Resource, and then select a GitOps repository.
  3. Open the Overview tab and select View Source to access the repository.

  4. (Optional) Alternatively, select Catalog, open the Overview tab, and select View TechDocs.

    1. In the Home > Repository section, select the GitOps repository.

  5. Clone your GitOps repository.

    Note

    Ensure that the local clone is up-to-date.

  6. Create a new branch.
  7. Navigate to the component/<app-name>/overlays directory, which contains subdirectories for development, stage, and prod.

  8. Follow these steps to promote the application:

    To move your applicationDo this

    From development to stage environment

    1. Open th development/deployment-patch.yaml file and copy the container image URL. For example, quay.io/<username>/imageName:imageHash.
    2. Open the stage/deployment-patch.yaml file and replace the container image URL with the one you copied.
    Note

    To include additional configuration changes (for example, replicas), copy them from the development/deployment-patch.yaml file to the stage/deployment-patch.yaml file.

    From stage to production environment

    1. Open the stage/deployment-patch.yaml file and copy the containers image URL. For example, quay.io/<username>/imageName:imageHash.
    2. Open the prod/deployment-patch.yaml file and replace container image URL with the one you copied.
    Note

    To include additional configuration changes (for example, replicas), copy them from the stage/deployment-patch.yaml file to the prod/deployment-patch.yaml file.

  9. Commit and push your updates.

  10. Create a PR to start a promotion pipeline. The pipeline validates the changes against Red Hat Enterprise Contract (Enterprise Contract) policies.

    1. Check the pipeline run in the CI tab of RHDH.
  11. Merge the PR to trigger Argo CD, which applies the changes and promotes the build to the next environment.

Verification

  • Use the Topology tab in RHDH to confirm the application distribution across namespace.
  • Use CD tab to view deployment details, including the status, updates, commit message (for example, Promote stage to prod), and container image changes.

4.2. Viewing security insights

The promotion pipeline includes several tasks to ensure secure and compliant deployments. The pipeline tasks include:

  • git-clone: Clones the repository into the workspace using the git-clone task.
  • gather-deploy-images: Extracts the container images from deployment YAML files for validation.
  • verify-enterprise-contract: Validates the container images using Enterprise Contract (EC) policies and Sigstore’s cosign tool.
  • deploy-images: Deploys validates images to the target environment.
  • download-sbom-from-url-in-attestations: Retrieves SBOMs for images by downloading OCI blobs referenced in image attestations.
  • upload-sbom-to-trustification: Uploads SBOMs to Trustification using the BOMbastic API.

4.2.1. Enterprise contract task

The Enterprise Contract (EC) is a suite of tools designed to maintain software supply chain security. It helps maintain the integrity of container images by verifying that they meet defined requirements before being promoted to production. If an image does not comply with the set policies, the EC generates a report identifying the issues that must be resolved.

The Red Hat Trusted Application Pipeline build process utilizes Tekton Chains to generate signed in-toto attestation of the build pipeline. These attestation cryptographically verify the build’s integrity. The EC then evaluates the build against defined policies, ensuring it complies with the organizational security standards.

Interpreting compliance reports

EC compliance reports provide detailed insights into application security and adherence to policies. Here’s how to understand these reports:

  • Policy compliance overview: Displays the checks performed, their status, (success, warning, or failure) , and messages explaining warnings or failures.

  • Details provided: Policy reports detail:

    • Successful checks: Lists the policies that passed validation.
    • Warnings and failures: Highlights policies that triggered warnings or failed checks, with explanations.
    • Rule compliance: Shows how the application adheres to individual policy rules, such as source code references or attestation validations.

Figure 4.1. The EC report

enterprise contract
Using compliance insights

The insights from EC compliance reports help prioritize security and compliance tasks:

  • Review policy compliance: Ensure your application meets standards such as Supply Chain Levels for Software Artifacts (SLSA). Address any compliance gaps based on the recommendations in the report.
  • Streamline review: Use filters in the reports to focus on critical issues, enabling a faster and more efficient review process.

Additional resources





Revised on 2024-12-13 16:47:25 UTC

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.