Metadata-Version: 2.1
Name: corpus-replicator
Version: 1.1.1
Home-page: https://github.com/MozillaSecurity/corpus-replicator
Author: Tyson Smith
Author-email: twsmith@mozilla.com
Maintainer: Mozilla Fuzzing Team
Maintainer-email: fuzzing@mozilla.com
License: MPL 2.0
Keywords: automation corpus fuzz fuzzing security test testing
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: PyYAML
Provides-Extra: dev
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: tox ; extra == 'dev'

Corpus Replicator
=================
[![Task Status](https://community-tc.services.mozilla.com/api/github/v1/repository/MozillaSecurity/corpus-replicator/main/badge.svg)](https://community-tc.services.mozilla.com/api/github/v1/repository/MozillaSecurity/corpus-replicator/main/latest)
[![Matrix](https://img.shields.io/badge/dynamic/json?color=green&label=chat&query=%24.chunk[%3F(%40.canonical_alias%3D%3D%22%23fuzzing%3Amozilla.org%22)].num_joined_members&suffix=%20users&url=https%3A%2F%2Fmozilla.modular.im%2F_matrix%2Fclient%2Fr0%2FpublicRooms&style=flat&logo=matrix)](https://riot.im/app/#/room/#fuzzing:mozilla.org)
[![PyPI](https://img.shields.io/pypi/v/corpus-replicator)](https://pypi.org/project/corpus-replicator)

Corpus Replicator is a corpus generation tool that enables the creation of multiple
unique output files based on templates. The primary intended use case is the
creation of a seed corpus that can be used by fuzzers. Support for additional output
formats can be added via the creation of `Recipes`. If a desired format is unsupported,
support can be added via the creation of a `CorpusGenerator`.

The goal is to create an efficient corpus that maximizes code coverage and minimizes
file size. Small unique files that execute quickly are preferred.

Currently four media types can be generated `animation`, `audio`, `image` and
`video`.

Requirements
------------

Corpus Replicator relies on [FFmpeg](https://ffmpeg.org/).

Installation
------------
```
pip install corpus-replicator
```

Example
-------

This is an example `recipe` file.

```yaml
# "base" contains required entries and default flags
base:
  codec: "h264"       # name of the codec
  container: "mp4"    # container/file extension
  library: "libx264"  # name of library
  medium: "video"     # supported medium
  tool: "ffmpeg"      # name of supported tool
  default_flags:
    encoder:          # "encoder" flag group
      ["-c:v", "libx264"]
    resolution:       # "resolution" flag group
      ["-s", "320x240"]

# variations allow flags to be added and overwritten
# one file will be generated for each entry in a flag group
variation:
  resolution:         # flag group - overwrites default flag group in "base"
  - ["-s", "640x480"]
  - ["-s", "32x18"]
  - ["-s", "64x64"]
  monochrome:         # flag group - adds new flag group
  - ["-vf", "monochrome"]
```

Running the recipe will generate a corpus:
```
$ corpus-replicator example.yml video -t test
Generating templates...
1 recipe(s) will be used with 1 template(s) to create 4 file(s).
Generating 4 'video/libx264/h264/mp4' file(s) using template 'test'...
Optimizing corpus, checking for duplicates...
Done.
```

Resulting corpus:
```
$ ls generated-corpus/
video-h264-libx264-test-monochrome-00.mp4
video-h264-libx264-test-resolution-01.mp4
video-h264-libx264-test-resolution-00.mp4
video-h264-libx264-test-resolution-02.mp4
```

A more complex corpus can be generated by using multiple `Recipes` and `Templates` at
once.

Recipes are stored in [src/corpus_replicator/recipes](/src/corpus_replicator/recipes/).
