Integrate Security Audit with Azure Pipelines

You can integrate API Contract Security Audit in Microsoft Azure Pipelines through a custom build task in the extension REST API Static Security Testing.

NoteYou must have an account in 42Crunch Platform that the build task in Azure Pipelines can use to access Security Audit. If you do not yet have an account, click here to sign up.

For more details on Azure Pipelines, see Azure Pipelines documentation.

Create an API token for the build task

You must add an API token that the build task uses to authenticate to Security Audit.

  1. Log in to 42Crunch Platform, and click your profile.
  2. Click Settings > API Tokens, and click Create New Token.
  3. Enter a unique and descriptive name for the token, such as CI_CD token.
  4. In token access rights, select API Contract 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 the task on the pipeline.

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

Add the build task to your Azure pipeline

To run the build task, you must add it to your Azure pipeline.

  1. Log in to your Azure DevOps account.
  2. If your organization in Azure DevOps does not yet have the extension REST API Static Security Testing installed, install it from Visual Studio Marketplace. This needs to be done only once for each organization: once the task is installed, it is available for the whole organization.
  3. Go to the pipeline where you want to add the build task, and click Edit. The file azure-pipelines.yml opens.
  4. Click the cursor under steps where you want to add the build task, and then find and click on the task called 42CrunchAPI Contract Security Audit.
  5. Click Variables > New variable.
  6. Create the variable 42C_API_TOKEN where the value is the API token you created for the build task, and mark it as a secret, then click OK. The token is stored in the secrets of your Azure pipeline.

    Screenshot of creating a new variable in Azure Pipelines. The name of the created variable is 42C_API_TOKEN, the value is hidden, and the option to keep the value secret has been selected.

  7. Choose the API collection where the discovered OpenAPI definitions are stored. By default, the build task will use the repository name combined with the branch name:

    Screenshot of adding the build task to the pipeline.

    You can leave the name as the default one, or enter a name you want.

    • If the API collection with the specified name does not exist in your organization in 42Crunch Platform, the build task creates the collection.
    • If the API collection with the specified name does already exist, the build task first removes any existing API definitions (along with their IDs) from that collection before storing the discovered OpenAPI definitions in it. Each discovered API definition also gets a new ID on the platform.
  8. Enter the minimum API score that the audited OpenAPI definitions must get from the audit for the build task to succeed. If any API definitions scores lower than the minimum score you set, the build task will fail. The default is 75.
  9. Click Add. The build task is added to your pipeline and you can see its definition under steps in azure-pipelines.yml.
  10. Click Save to save your changes to the pipeline. To test the build task, run your Azure pipeline.

The build task will either succeed or fail depending on the minimum score. The summary of the run in the pipeline jobs provides you further details on how the job went.

The task 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 logs of the run include the URL of each discovered API in the platform. You can copy the URL and paste it to your browser to view the detailed audit report of the corresponding API.

A screenshot of a job log for the audit phase of the build task. The log shows the URLs to the audit reports of five APIs that the build task discovered and audited.

Fine-tune the build task

In addition to the basic configuration in azure-pipelines.yml, you can further refine how your build task works by adding a configuration file to the root of your repository.

  1. Add a file called 42c-conf.yaml to the root level of your source code repository where the pipeline connects to.
  2. Open the file for editing and paste in the following sample code:
    audit:
      # map filenames to IDs of APIs already in 42Crunch Platform
      mapping:
        foo/bar/petstore-v3.json: a193b82d-5833-47f8-81d2-cfc4fe175914
    
      # define what files to check in discovery phase OpenAPI files
      # exclude directories from the search
      # disable the whole discovery phase by specifying 'discovery: false'  
      discovery:
        search:
          - '**/*.json'
          - '**/*.yaml'
          - '**/*.yml'
          - '!node_modules/**'
    
      # specify more fail conditions to be checked in addition to the minimum score
       fail_on:
        # fail if the API does not have a valid OpenAPI definition
        invalid_contract: true
    
        # fail if any issues with the defined severity or higher are detected
        # possible severity levels: critical, high, medium, low, info 
        severity: medium
  3. Under mapping, you can map IDs (here a193b82d-5833-47f8-81d2-cfc4fe175914) of APIs that you have in another API collection in 42Crunch Platform to OpenAPI files in your source code repository (here foo/bar/petstore-v3.json). When the build runs, this replaces the API definition associated with the mapped ID with the contents of the OpenAPI file from your repository.

    NoteMake sure that do not accidentally overwrite things in the API definition you want to keep. If you map a file in your repository to an API ID in 42Crunch Platform, the build will replace all contents in the file associated with that ID. Any changes that are not reflected in the OpenAPI file in your repository are lost from the platform.

    The task always cleans the API collection you have specified to be used before starting the discovery phase, so you cannot map APIs in your repository to the IDs in that API collection.

  4. Under discovery, you can control what kind of files the build checks during the discovery phase:
    • By default, the task checks any .json, .yaml, and .yml files in any directory in your repository for OpenAPI definitions. If all your APIs are in a particular directory, or have a particular name pattern, you can refine the paths in search conditions to match. The task will then only check the defined file paths during the discovery.
    • To exclude directories (like directories with plenty of JSON or YAML files that are not API definitions) from the discovery phase, you can list the directories preceded by !. In the example, the directory node_modules is excluded from discovery phase.
  5. Under fail_on, you can refine what kind of audit results cause the task to fail:
    • invalid_contract: By default, this is set to true. The task fails if any of the audited APIs does not have a valid OpenAPI definition. If you set this to false, the task allows APIs that do not have a valid OpenAPI definition.
    • severity: The severity limit for found issues. If the audit finds any issues of this severity or higher, the task fails.
  6. When you are ready, save the file and push it to your repository.

Pushing changes to your repository triggers your CI/CD pipeline, and you can see how the configuration you added changes the behavior and the results of the build.