Skip to content

Verified Publisher Program

Overview

The Verified Publisher (VP) program expands Iron Bank’s container ecosystem by allowing trusted vendors to contribute prebuilt images while maintaining security and compliance. This process has lived in a beta testing phase and is invite-only until the program's general release. All Iron Bank processes remain the same except for the fact that these images are not built in the pipeline and are rather pulled into the pipeline as a passthrough. Although not built in the pipeline, all images are still upheld to Iron Bank's scanning and scoring standards, providing attestation provenance for downstream users while allowing them the flexibility to utlize vetted and scanned commercial container images.

Visibility

The VP image stored in Registry1 and its corresponding Gitlab project can be made public or private depending on the vendor's requirements.

Note: currently, regardless of private or public status, the image and scan results will be shown in the Iron Bank Front End (IBFE) and Vulnerability Assessment Tracker (VAT).

Project Structure

Required Folder Structure:

container-project
│ 
├── hardening_manifest.yaml        (required)
├── images.yaml                    (required)
├── LICENSE                        (required)
├── README.md                      (required)
├── LICENSEs/                      (directory to be created if needed)
├── READMEs/                       (directory to be created if needed)
├── documentation/                 (directory to be created if needed)
└── .gitlab/                       (created by default)

Note: Do not submit source code to the repository. Additional directories can be included if necessary.

Required Branching Structure:

master (the published version of the application)
├── development (the application version being submitted to be hosted)
    └── feature branches

Note: In order for your application and version to be published in Registry1, it must be merged to master. Under our current process, a member of the container analysis team will perform the merge into development. The merge into master will only be performed by the security team. It is your responsibility to ensure your application is fully completed and can be tracked via your Gitlab issue for your container.

Required Components

1. hardening_manifest.yaml file

Contributors will need a hardening_manifest.yaml file in the root of the project repository which provides details about the maintainers. No other information is required.

Example hardening_manifest.yaml 

maintainers:
- name: John Doe
  email: "johndoe@example.com"
  username: "j.doe"

apiVersion: v1
name: ""
tags: []
args: {}
labels: {}
resources: []

2. images.yaml file

Contributors will need a images.yaml file in the root of the project repository which provides list of images and their metadata.

The list of images must associate under a key which corresponds to the project namespace in Registry1.

Each image entry uses these fields in this order:

  1. name (required)
    • The name of the source image to publish in Registry1.
  2. remote (required)
    • The image reference (URI) from source registry.
  3. tags (required)
    • The image tags to apply for the image published in Registry1.
  4. keywords (optional)
    • The category labels displayed in IBFE.
  5. license (optional)
    • Uses specified LICENSE file under ./LICENSEs folder.
    • Otherwise, use root license file as default.
    • The corresponding LICENSE displays in IBFE.
  6. readme (optional)
    • Uses specified README.md file under ./READMEs folder.
    • Otherwise, use root README as default.
    • The corresponding README displays in IBFE.

You may include additional comments in images.yaml as you see fit.

Example images.yaml 

# Images in the 'my-vp' key publish to the 'my-vp' project in Registry1
my-vp: # Required
  - name: vendor-registry.com/foo/bar/apache # Required
    remote: vendor-registry.com/apache:latest # Required
    tags: ["3", "latest"] # Required
    keywords: ["httpd", "apache"] # Optional: Displays on IBFE
    license: apache_license.md # Optional: Displays on IBFE
    readme: apache_readme.md # Optional: Displays on IBFE

  - name: vendor-registry.com/foo/bar/nginx
    remote: vendor-registry.com/nginx:12-slim
    tags: ["12-slim", "latest"] 
    license: nginx_license.md
    readme: nginx_readme.md

  - name: vendor-registry.com/foo/bar/redis
    remote: vendor-registry.com/redis:8
    tags: ["8"]

3. LICENSE

There must be a root LICENSE file. This file is used as the default license. You may include additional LICENSE files under LICENSEs\ directory. Each image entry in images.yaml has an optional field called license where you can specify a custom LICENSE. If not specified, that image will use the root LICENSE by default. This determines which LICENSE is used and displayed in IBFE.

Your license file must be specifically called LICENSE and must be in plain text. If you are submitting a PDF version of the license, you can submit it as-is but your LICENSE file must specifically refer to it and both files must be included within your container.

If you have an opensource container, include the opensource license. If you have a container for a commercial product, please indicate in your README.md the kind of license required to run your product in addition to providing a copy of the license/EULA.

4. README.md

There must be a root README.md file. This file is used as the default documentation and will be displayed in GitLab. You may include additional README files under READMEs\ directory. Each image entry in images.yaml has an optional field called readme where you can specify a custom README. If not specified, that image will use the root README by default. This also determines which README is used and display in IBFE.

A README.md should include, at minimum:

    a) An overview of what the container is used for

    b) Instructions on launching/running the container. Iron Bank containers are specifically meant to run on Kubernetes for production deployments and not on Docker Swarm, CLI or other environments; therefore, Kubernetes instructions are required. Any instructions for environments outside of Kubernetes will likely be rejected.

Additional details can be specified within your README.md file as you see fit.

5. Documentation directory

Aside from the README, any additional documentation should be placed into a documentation directory in the root of the project.

Automating Updates with Renovate

Refer to Automating Updates to learn about Renovate.

Below is a Renovate template adapted for VP projects. Each image entry in images.yaml is checked for updates by renovate-bot daily, specifically the image tag in remote and first element of tags. The image tag in remote must appear before and match with the first element of tags in order to update correctly. Otherwise, only the image tag in remote is updated. Once renovate-bot finds all image updates, a MR is created for the VP project where it can manually be reviewed and merged. To implement this feature, reach out to your customer onboarding contact to start the process.

{
    "assignees": ["@USER-TO-ASSIGN"],
    "baseBranches": ["master"],
    "automerge": false,
    "regexManagers": [
      {
        "fileMatch": ["^images\\.yaml$"],
        "matchStrings": [ 
          "remote:\\s*(?<depName>[^:]+):(?<currentValue>[^\\s]+)",
          "remote:\\s*(?<depName>[^:]+):[^\n]+[\\s\\S]*?tags:[\\[\"'\\s*-]*(?<currentValue>[^'\",\n]+)"
        ],
        "datasourceTemplate": "docker"
      }
    ],
    "packageRules": [ 
      { 
        "groupName": "all to latest", 
        "groupSlug": "all", 
        "matchManagers": ["regex"], 
        "matchDatasources": ["docker"],
        "commitMessageExtra": ""
      } 
    ]
  }