42crunch/docker-api-security-audit repository overview

⁠Generic Docker image for 42Crunch REST API Static Security Testing

The Docker image for 42Crunch REST API Static Security Testing lets you add an automatic static application security testing (SAST) task to your CI/CD pipelines. The image creates a Docker container and checks your OpenAPI definition files for their quality and security.

This Docker image is powered by 42Crunch API Security Audit⁠. Security Audit performs a static analysis of the API definition that includes more than 300+ checks on best practices and potential vulnerabilities on how the API defines authentication, authorization, transport, and data coming in and going out.

As a result of the security testing, your APIs get an audit score, with 100 points meaning the most secure, best defined API. By default, the threshold score for the container to successfully terminate is 75 points for each audited API, but you can change the minimum score in the container configuration.

API contracts must follow the OpenAPI Specification (OAS) (formely Swagger). Both OAS v2 and v3, and both JSON and YAML formats are supported.

You can create a free 42Crunch account at https://platform.42crunch.com/register⁠, and then configure the container.

⁠Discover APIs

By default, the container locates all OpenAPI files in the current working directory of the container and submits them for static security testing. You can include or exclude specific paths from the discovery phase and can omit the discovery phase completely by adding a configuration file 42c-conf.yaml in the root of your repository and specifying rules for the discovery phase. For more details, see the documentation⁠.

All discovered APIs are uploaded to an API collection in 42Crunch Platform. The container uses number of environment variables (described below) to show the repository and the branch/tag/PR name from where the API collection originated from. During the subsequent container runs, the APIs in the collection are kept in sync with the changes in your repository.

⁠Fine-tune the container

You can add a configuration file 42c-conf.yaml in the root of your repository, and to fine-tune the success/failure criteria. For example, you can choose on whether to accept invalid API contracts, or define a cut-off on a certain level of issue severity.

You can define different configuration for different branches/tags/PRs in your repository. You can use the full name of the branch (for example, master) or a wildcard (for example, release-*) when designating which branch the configuration applies to.

⁠Performing audit using Docker command line

This is the minimal command line for docker which allows to audit all OpenAPI files located in a directory on a local file system.

The container assumes that the files come from a source control repository, and repository URL and branch/tag/PR info must always be provided. This information is used to create or find (for a subsequent runs) the API collection on 42Crunch Platform.

docker run \
  -v <OPENAPI-FILES-DIR>:/workspace \
  -e X42C_REPOSITORY_URL=https://github.com/mycompany/my-openapi-repo \
  -e X42C_API_TOKEN=<TOKEN> \
  -e X42C_BRANCH_NAME=master \
  42crunch/docker-api-security-audit:v3

⁠Variables

(*) = required variable.

(**) = either one of these must be set. if X42C_PR_ID is set, X42C_PR_TARGET_BRANCH must be set as well.

⁠Prerequisites

Create an API token in 42Crunch Platform.

⁠Support

The image is maintained by [email protected]⁠. If you run into an issue, or have a question not answered here, you can create a support ticket at support.42crunch.com⁠.

If you’re reporting an issue, do include:

• The version tag of the image
• Relevant logs and error messages
• Steps to reproduce the issue