Integrate Security Audit with GitHub Actions

You can integrate API Contract Security Audit in GitHub Actions through a custom action REST API Static Security Testing.

You must have an account in 42Crunch Platform that the action in GitHub Actions can use to access Security Audit. If you do not yet have an account, click here to sign up.

For more details on GitHub Actions, see GitHub Actions documentation.

Create an API token for the action

You must add an API token that the action 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 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 REST API Static Security Testing.

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

Add a secret for the API token

Before you add the actions to your GitHub Actions workflow, you must add the API token you created as a secured repository variable.

  1. Log in to GitHub, and go to the main page of your repository.
  2. Click Settings > Secrets > Add a new secret.
  3. Enter the following:
    • Name: API_TOKEN
    • Value: The value of the API token you created

    An example screenshot of adding a secret in GitHub. The API token is shown as dots in the value field.

  4. Click Add secret.

You have now created the secret that your workflow can use to authenticate to Security Audit. Depending on how you store the secrets, you can use the same secret in multiple workflows or even repositories. For more details, see GitHub documentation on secrets.

Add the action to your GitHub Actions workflow

To run the action, you must add it as a job in your workflow.

  1. In GitHub, go to the repository you want.
  2. Locate the configuration file for the workflow where you want to add the action (for example, .github/actions/workflow/main.yml, and open it for editing. If you don't yet have a workflow, create one.
  3. Under steps, add the latest version of the action REST API Static Security Testing:
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
        - uses: 42Crunch/api-security-audit-action@v1

    Note that the bit denoting the version (here @v1) changes with each version of the plugin.

  4. Point the action to the secret API_TOKEN that you added:
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
        - uses: 42Crunch/api-security-audit-action@v1
          with:
            api-token: ${{ secrets.API_TOKEN }}
  5. If you want, add the minimum API score that the audited OpenAPI definitions must get from the audit for the action to succeed. If any API definitions scores lower than the minimum score you set, the action will fail. The default is 75:
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v1
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
  6. If you want, define the API collection where the discovered OpenAPI definitions are stored. By default, the action will use the name github:
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v1
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
            collection-name: GitHub Actions test collection

    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 action creates the collection.
    • If the API collection with the specified name does already exist, the action first removes any existing API definitions (along with their UUIDs) from that collection before storing the discovered OpenAPI definitions in it. Each discovered API definition also gets a new API UUID on the platform.

    The plugin always starts by clearing the API collection you specify for it. Removing APIs and their API UUIDS also permanently removes any information tied to the API UUIDs, such as previous audit reports, scan reports, or protection configuration and logs. For more details on how to avoid this, see Mapping OpenAPI files to APIs in the platform.

  7. Click Commit to save your changes to the workflow. To test the action, run your workflow.

The action will either succeed or fail depending on the minimum score. The summary of the run in the workflow reports provides you further details on how the job went.

The action uploads all discovered OpenAPI definitions to the specified API collection in 42Crunch Platform:

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

The report of the run includes 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.

A screenshot of a report of the action. The report shows the links to the audit reports of APIs that the action discovered and audited.

You can further fine-tune how the integration plugin works by adding a configuration file called 42c-conf.yaml to the root level of your source code repository where the CI/CD pipeline connects to. For example:

  • Map OpenAPI files 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.

For more details, see the configuration examples in our Resources repository in GitHub.