Feature Request: Add Step-by-Step Guide for Generating CycloneDX JSON Files

[lightningRalf]

Hi Sunshine maintainers,

I'm opening this issue to suggest the inclusion of a step-by-step guide within the documentation for generating CycloneDX JSON files that work seamlessly with Sunshine, producing well-defined views like the provided sample. This will significantly help users (including myself) quickly get started and avoid common pitfalls.

Proposed Guide:

The primary goal is to assist users in generating a CycloneDX JSON file from a requirements.txt (Python example), and optionally add vulnerability data. Here's a concise guide:

1. Set up Python Environment:

python3 -m venv venv
source venv/bin/activate  # On Linux/macOS
venv\Scripts\activate    # On Windows

2. Install cyclonedx-bom:

pip install cyclonedx-bom

3. (Optional) If you don't have it, Create a requirements.txt file (or have an existing one):

pip install requests
pip freeze > requirements.txt

4. Generate the CycloneDX SBOM file (requirements-output.json):

cyclonedx-bom -r requirements.txt -o requirements-output.json

5. (Optional) Add Vulnerability Data using dependency-check:

• Download dependency-check from https://owasp.org/www-project-dependency-check/#:~:text=Download%20the%20Latest%20Release

• Unzip the downloaded file in a folder.

• Execute the command:
  bash ./dependency-check/bin/dependency-check.sh --scan requirements-output.json --format JSON --out ./requirements-output-with-vulns

• Rename ./requirements-output-with-vulns/dependency-check-report.json to requirements-output-with-vulns.json.

6. Use Sunshine:
* Web Version:
1. Go to https://cyclonedx.github.io/Sunshine/
2. Upload requirements-output-with-vulns.json.
* CLI Version:
1. Save sunshine.py locally.
2. Run:
bash python sunshine.py -i requirements-output-with-vulns.json -o output.html
3. Open output.html in a browser.

Important Notes:

• bom-ref: Ensure this ID is unique for each component. The pattern <component name>@<component version> is very common and expected by Sunshine.
• components Array: Include details for all components, including name, version, type, and licenses.
• dependencies Array: Include dependencies between the components using ref and dependsOn.
• vulnerabilities Array: Include vulnerability information, using id, affects and ratings.
• Metadata: The "metadata" section is optional, but it is used by sunshine to define the application root component. It is very useful.
• Manual Adjustments: Depending on the complexity of the project and how tools generate the SBOM, it might be necessary to manually adjust the generated JSON file. In particular, bom-ref and dependencies might need to be manually tweaked to get the correct dependency graph.
• Log output: Check the log output in the page if some error occurs.

Rationale:

• Accessibility: This guide focuses on tools and steps accessible to many developers, including those familiar with Python.
• Reproducibility: By following this guide, users should be able to generate similar output to the sample provided in the repository.
• Actionable Steps: The commands are concrete and copy-pastable, minimizing user effort.
• Tool Selection: Using cyclonedx-bom to generate SBOMs and dependency-check to add vulnerability data is a good starting point.

Adding this guide to the README or documentation would greatly enhance the usability of Sunshine.

Thank you for your time and consideration!