opossum-file

This is a library implementing operations around files readable by OpossumUI.

Current State

Supports the conversion from the following file formats to .opossum:

• .opossum itself
• ScanCode (json)
• OWASP Dependency Scan (json)
• more to come...

License

Apache-2.0

Getting Started

You find the latest release here. We offer prebuilt binaries for Linux, MacOS and Windows.

Alternatively, or to get the cutting-edge version, you can clone the repository and run the code yourself. See Development below for installation instructions.

How to Use

Command-line usage

The CLI uses subcommands. The main command just displays all available subcommands

Usage: opossum-file [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  generate  Generate an Opossum file from various other file formats.

generate

Usage: opossum-file generate [OPTIONS]

  Generate an Opossum file from various other file formats. If multiple files
  are provided, they are merged into a single output file.

  Currently supported input formats:
    - ScanCode (json)
    - Opossum
    - OWASP Dependency Scan (json)

Options:
  --opossum PATH         Specify a path to a .opossum file that you would like
                         to include in the final output. Option can be
                         repeated.
  --scan-code-json PATH  Specify a path to a .json file generated by ScanCode
                         that you would like to include in the final output.
                         Option can be repeated.
  --owasp-json PATH      Specify a path to a .json file generated by OWASP
                         dependency scan that you would like to include in the
                         final output. Option can be repeated.
  -o, --outfile TEXT     The file path to write the generated opossum document
                         to. If appropriate, the extension ".opossum" is
                         appended. If the output file already exists, it is
                         overwritten.  [default: output.opossum]
  --help                 Show this message and exit.

Development

Setting up the environment

1. Install uv, if you haven't already.
2. Clone the repository.
3. Run uv sync to install dependencies.
4. Run uv run pre-commit install to install the pre-commit hooks.

Execution

To execute the code directly (i.e. without building it), use

uv run opossum-file [OPTIONS] COMMAND [ARGS]...

Code quality tooling

To lint and test your changes, run

uv run task verify

Each PR is required to pass these checks, so it is a good idea to run these commands locally before submitting your PR.

Using

uv run task verify-fix 

allows to autofix as many problems as possible.

For an overview of all tasks run

uv run task --list

Note: This project uses faker for testing. By default, every test runs with a different seed. To fix the seed, just adapt the line in faker_setup.py (without committing).

Build

To build, run

uv run python build.py opossum-file

This will create a self-contained executable file dist/opossum-file (dist/opossum-file.exe on Windows).

Creating a new release

Note: You will need the "maintain" role in order to create a new release.

1. Go to the GitHub releases page and use the UI to create a new release.
2. The tag should have the format "opossum-file-$YEAR-$MONTH-$DAY" (in case of an Nth release on the same day "opossum-file-$YEAR-$MONTH-$DAY.N").
3. The title of the release equals the tag.
4. Click the button "Generate release notes" to get the description for the release. Then, remove all the contributions from @renovate which are just dependency upgrades.
5. Click "Publish release". This will trigger the CI/CD pipeline which will build the release for all three OSs and upload the artifacts to the release.