Integrate Security Audit with GitHub Actions

You can integrate API 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 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@v3

    Note that the bit denoting the version (here @v3) changes with each major 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@v3
          with:
            api-token: ${{ secrets.API_TOKEN }}
  5. If you want, add the minimum audit score that the audited OpenAPI definitions must get from the audit for the action to succeed. If any API definitions score lower than the minimum score you set, the action fails. The default is 75:
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v3
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
  6. If you are an enterprise customer not accessing 42Crunch Platform at https://platform.42crunch.com, enter your platform URL. This step is optional and most users do not have to do this. If you are not sure what your platform URL is, contact our support.
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v3
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
            platform-url: https://<your platform URL here>
  7. By default, the level of detail in the logs that the action produces is INFO. If you want more or less detail, you can use log-level to specify the level of detail. The possible values are FATAL, ERROR, WARN, INFO, DEBUG):
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v3
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
            log-level: DEBUG
  8. If you want to automatically share any new API collections that the action creates with other users in your organization, add the variable share-everyone. The variable has two possible values:
    • READ_ONLY: Other users have read-only access
    • READ_WRITE: Other users have also write access

    If you do not define share-everyone at all, the API collections are not shared and remain private to you.

    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v3
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
            log-level: DEBUG
            share-everyone: READ_ONLY

    You can also change the sharing of the API collections later. For more details, see Sharing APIs and access level.

  9. If you want to include the issues that the action finds into your Code Scanning alerts in GitHub, add the parameter upload-to-code-scanning and set it to true:
    jobs:
      api_audit_job:
        runs-on: ubuntu-latest
        name: Audit OpenAPI files
        steps:
        ...
       - uses: 42Crunch/api-security-audit-action@v3
          with:
            api-token: ${{ secrets.API_TOKEN }}
            min-score: 85
            log-level: DEBUG
            share-everyone: READ_ONLY
            upload-to-code-scanning: true
  10. 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 PlatformBy default when running on branch, the plugin uses the naming convention <shortened-source-control-uri> Branch:<branch-name> for the created API collection, for example, 42Crunch/sample Branch:sample.

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

The action uses the build variables GITHUB_REPOSITORY and GITHUB_REF (branch) to get the details directly from your source control.

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.

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 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

By default when running on branch, the plugin uses the naming convention <shortened-source-control-uri> Branch:<branch-name> for the created API collection, for example, 42Crunch/sample Branch:sample. However, you can specify a different syntax for the new collections that the plugin uses by default.

  1. Go to the repository you want, and open the configuration file for the workflow for editing
  2. Add the variable default-collection-name to the action, 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.
  3. When ready, save your changes.

Next time you run the pipeline, the integration plugin 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 for the plugin

By default, the integration plugin uses the root directory of your repository as its starting point. However, you can also set a specific directory that the plugin will use as its root.

If you have configured 42c-conf.yaml for your plugin, make sure it is located in the root directory that you want the plugin to use. Otherwise, the configuration file is ignored.

  1. Go to the repository you want, and open the configuration file for the workflow for editing
  2. Add the variable root-directory to the to the action, and enter the path of the directory you want to use as the root directory.
  3. Save your changes.

Next time you run the pipeline, the integration plugin will start the discovery phase from the directory path you defined and check that directory and any subdirectories under it for OpenAPI files.