CoreCCI

An unofficial CircleCI orb providing extended core functionality to your CI pipelines.

• Enhanced Checkout Command

  • FIPS Support
    The built-in CircleCI checkout command fails in certain jobs when FIPS mode is enabled. CircleCI generates ED25519 deploy keys by default, which are not FIPS compliant. When using newer container images such as rockylinux:9 or ubi:9 in these FIPS-enabled environments, the code checkout fails. This does not appear to be an issue on the public cloud version at app.circleci.com, as FIPS mode depends on the underlying host configuration, which doesn't appear to be enabled on CircleCI servers. The issue will definitely be present in self-hosted CircleCI instances that are running in environments maintained to comply with NIST SP 800-171 or DoD CMMC requirements. This orb therefore provides a custom checkout command that allows you to use custom ECDSA keys until this issue is resolved by CircleCI.

  • Hardened Encryption
    This orb was also built to eventually adhere to the NSA's Commercial National Security Algorithm Suite (CNSA) 2.0, using the cryptographic algorithms recommended for use with SSH by RFC-9212. One exception allowing ecdsa-sha2-nistp256 is still present to support GitHub integration, as documented here. The goal is for this orb to eventually be fully CNSA-2.0 compliant. We use the following parameters when checking code out using ssh:

    • Ciphers: aes256-gcm@openssh.com
    • FingerprintHash: sha384
    • KexAlgorithms: ecdh-sha2-nistp384
    • HostKeyAlgorithms: ecdsa-sha2-nistp384,ecdsa-sha2-nistp256,rsa-sha2-512 (exception made)

  • Blazing Fast Shallow Checkouts
    Many organizations have enormous git respositories that have built up over the course of more than a decade, to include monorepos that host multiple services or applications. CircleCI's built-in checkout command for these repositories can often take a ridiculous amount of time. This orb provides a shallow checkout command to pull source code for the current head commit only, with a depth of 1. This allows for extremely fast checkouts when using massive repositories as compared to the built-in checkout command. For example, one of my repositories saw the duration of code checkouts fall from ~20-35 seconds to ~2 seconds.

  • Easy Submodule Checkouts
    The checkout command includes convenience parameters to checkout all submodules, as this is such a common use case. The submodules can also be checked out with a shallow option to improve checkout speeds.

  • Auto-Configure Git
    Because the checkout command is effectively responsible for configuring SSH, this orb offers the option to subsequently auto-configure git to use SSH over HTTPS. This is especially useful when using Go in private repositories, as go mod download utilizes git under the hood. Using an SSH key associated a service user means you won't need a special context with GITHUB_TOKEN or GH_ENTERPRISE_TOKEN in order to download Go dependencies.

  • Auto-Install SSH & Git
    The checkout command is reliant upon git and ssh. If not installed, this orb provides an option to automatically install the necessary packages before proceeding.

• Persist to S3 command
  After many years of working with CircleCI, I also observed that the persist_to_workspace command could also suck up tons of time, especially to tar and un-tar files. Many companies also persist certain release artifacts to an S3 storage for long-term storage. This orb therefore offers a persist_to_s3 command as a convenience command. Development of this feature is still in progress.

First, generate a FIPS compliant SSH key using ecdsa-sha2-nistp384, per NSA guidance in CNSA Suite 2.0.

ssh-keygen -t ecdsa -b 384 -C github_<repo_name>

In your GitHub repository settings, click Deploy Keys on the left sidebar, and then press the "Add deploy key" button. Paste in your SSH public key. If you didn't change the default output location while running the previous command, you can find it using cat ~/.ssh/id_ecdsa. The file contents should begin with ecdsa-sha2-nistp384.

Navigate the project settings for your application within the CircleCI app. On the left hand sidebar, click SSH keys. Under Additional SSH Keys, add a new key for github.com (or your self-hosted GitHub Enterprise Server domain).

Avoid pressing the "Add deploy key" button, as it will automatically generate one using ED25519, which will not work in FIPS mode. This is the reason why we're using the "additional SSH keys" section as a workaround, allowing us to manage the process ourselves.

The app will display the fingerprint of the key you just added. Place this fingerprint in your CircleCI config file as a parameter to the corecci/checkout command:

  version: 2.1

  orbs:
    corecci: juburr/corecci@0.4.0

  jobs:
    ubi9_fips_job:
      docker:
        - image: registry.access.redhat.com/ubi9/ubi:9.5
      resource_class: small
      steps:
        - corecci/checkout:
            depth: "shallow"
            fingerprint: "SHA256:1wS2Fom3QTXyH5G2DS88+II0U9ajqGKOeq1wBA740Fc"
            submodules: "recursive-shallow"

  workflows:
    use-my-orb:
      jobs:
        - corecci/ubi9_fips_job:
            filters:
              tags:
                only: /.*/