WuppieFuzz GitHub Action

This is a GitHub Action that allows you to fuzz test a REST API exposed by your software. This action automates the process of running the WuppieFuzz fuzzer against your program under test, generating a detailed report of the fuzzing results.

Prerequisites

Before using this action, ensure the following:

1. Docker Container: Build a Docker container for your software that exposes the REST API you want to test.
2. OpenAPI Specification: Provide an OpenAPI specification file in YAML format (openapi.yml) that describes your API.

How to Use

You can use this action in your GitHub workflows to run WuppieFuzz against your program under test. The action provides several inputs to configure the fuzzing process.

Inputs

• openapi_spec: Path to the OpenAPI specification file. Default: openapi.yml

• docker_container: Name of the Docker container to run your program under test. Default: vampi:latest

• container_port: Internal port on which the container serves the API. Default: 5000

• host_port: Host port on which the fuzzer accesses the API. Default: 5000

• timeout: Time-out in seconds for the fuzzing campaign. Default: 60

• extra_args: Extra arguments to pass to WuppieFuzz. Default: ''

Outputs

The action generates a fuzzing report as an artifact. This report is stored in a directory named WuppieFuzz/reports/ and can be downloaded from the workflow run summary.

Example Workflow

Below is an example of how to use this action in a GitHub workflow. It assumes you have a Dockerfile that packages your software in a docker container, and exposes the API at port 8080.

name: Fuzz Test REST API

on:
  push:
    branches:
      - main

jobs:
  fuzz-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build Docker Image
        run: docker build -t your-docker-container .

      - name: Run WuppieFuzz
        uses: ./ # Use the WuppieFuzz action from this repository
        with:
          openapi_spec: 'path/to/your/openapi.yml'
          docker_container: 'your-docker-container'
          container_port: 8080
          host_port: 8080

Fuzzing Report

The fuzzing report generated by WuppieFuzz is stored as an artifact. This report includes a database that can be visualized using the Grafana dashboard available in the WuppieFuzz Dashboard repository.

To view the results:

1. Download the artifact from the workflow run summary.
2. Use the Grafana dashboard to load and analyze the fuzzing results.

Notes

Ensure that the Docker container is properly configured to expose the API on the specified container_port. The OpenAPI specification file should accurately describe the API endpoints to maximize the effectiveness of the fuzzing process. For more information about WuppieFuzz and its capabilities, visit the WuppieFuzz repository.