Integrate Security Audit with CI/CD using a Docker image

You can integrate API Security Audit with your CI/CD system through a Docker image for REST API Static Security Testing.

You must have an account in 42Crunch Platform that REST API Static Security Testingcan use to access Security Audit. If you do not yet have an account, click here to sign up.

Create an API token for the Docker image

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 API tokens, and click Create new token.
  3. Enter a unique and descriptive name for the token, such as Security Audit token.
  4. In token access rights, select API Security Audit, List resources, and Delete resources.

    A screenshot of Create API Token Wizard with the required access rights marked as selected.

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

    Create API Token Wizard showing the generated token and the buttons for showing the token value and copying it.

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.

Add the Docker image to your CI/CD pipeline

If your CI/CD system supports Docker, you can create scripts to pull and run the Docker image for REST API Static Security Testing as part of the workflow of your CI/CD pipeline.

Before you start, make sure you have Docker installed and configured so that your CI/CD system can use it. For more details on Docker, see Docker documentation.

  1. Identify the spot in your CI/CD workflow where you want to include the audit, and make sure that before that your CI/CD specifies a directory containing all the OpenAPI definitions that you want to include in the audit. You need to mount this directory as a volume to the Docker container so that REST API Static Security Testing can access the files.
  2. Create the Docker command for running the Docker image for REST API Static Security Testing. The following is the minimum that is required to audit all OpenAPI files located in a directory that mounted as a volume to the container:

    docker run \
      -v <the path to the OpenAPI definitions>:/workspace \
      -e X42C_API_TOKEN=<reference to the token you created and stored securely> \
      -e X42C_REPOSITORY_URL=<your source control repository URL> \
      -e X42C_BRANCH_NAME=<your branch (for example, main)> \
      42crunch/docker-api-security-audit:v3

    REST API Static Security Testing uses the X42C_ environment variables for the name of the API collection it creates 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 mounted directory.

    The container assumes that the OpenAPI files come from a source control repository, so the variables 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.

  3. If you want, you can include the following optional environment variables in your command.
    VariableDescription
    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 in the Docker command, the default value is 75.

    X42C_PLATFORM_URL

    If you are an enterprise customer not accessing 42Crunch Platform at https://platform.42crunch.com, include this variable with your platform URL as its value.

    Most users do not need to specify this variable in the Docker command, 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 in the Docker command, 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 the variable is not included in the Docker command, 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 also write access

    You cannot share API collections if your account belongs to the free community organization. In this case, make sure this setting is off.

  4. When your Docker command is ready, include it as part of your CI/C pipeline in the spot you wan To test Docker command, run your workflow.

REST API Static Security Testing now runs in a Docker container as part of your CI/CD 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:

An example screenshot showing the collection the build task created in 42Crunch Platform.

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

The example screenshot shows the Petstore API imported to 42Crunch Platform from CI/CD, showing the filepath the API definition file has 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.

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:

  • 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.
  • Control what happens in the discovery phase.

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 Docker command on your CI/CD workflow for editing.
  2. Add the environment variable X42C_DEFAULT_COLLECTION_NAME to the Docker command, and enter the syntax for the default collection name you want to use. You can use text (like foo), reference to variables (${repository}), or a combination of the two (foo ${repository}). You can use the following variables 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.
    docker run \
      -v <the path to the OpenAPI definitions>:/workspace \
      -e X42C_API_TOKEN=<reference to the token you created and stored securely> \
      -e X42C_REPOSITORY_URL=<your source control repository URL> \
      -e X42C_BRANCH_NAME=<your branch (for example, main)> \
      -e X42C_DEFAULT_COLLECTION_NAME='foo ${repository}' \
      42crunch/docker-api-security-audit:v3
  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, REST API Static Security Testing uses the root of the mounted volume as its starting point. However, you can also set a subdirectory to be used as the root directory.

Makes sure that the directory you want to use is mounted as a volume in your command. If you have configured 42c-conf.yaml for your plugin, make sure it is located in the new root directory that you want REST API Static Security Testing to use. Otherwise, the configuration file is ignored.

  1. Open the Docker command on your CI/CD workflow for editing.
  2. Add the variable X42C_ROOT_DIRECTORY to the Docker command, and enter the path of the directory you want to use as the root directory.
    docker run \
      -v <the path to the OpenAPI definitions>:/workspace \
      -e X42C_API_TOKEN=<reference to the token you created and stored securely> \
      -e X42C_REPOSITORY_URL=<your source control repository URL> \
      -e X42C_BRANCH_NAME=<your branch (for example, main)> \
      -e X42C_ROOT_DIRECTORY=<the path to the new root directory> \
      42crunch/docker-api-security-audit:v3
  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.