diff --git a/.gitignore b/.gitignore index f9457e9d0..b5a759dbd 100644 --- a/.gitignore +++ b/.gitignore @@ -81,6 +81,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/img/ # PyBuilder .pybuilder/ diff --git a/docs/conf.py b/docs/conf.py index ada994778..d54608860 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,5 +92,6 @@ def download_images_from_toml(toml_file, image_dir): # ------------------------------------------------------------------- # Make database_sources.toml available as a static file at the site root # https://surfactant.readthedocs.io/en/latest/database_sources.toml +# Also include the demo.html page # ------------------------------------------------------------------- -html_extra_path = ["database_sources.toml"] +html_extra_path = ["database_sources.toml", "demo.html"] diff --git a/docs/demo.html b/docs/demo.html new file mode 100644 index 000000000..202a27569 --- /dev/null +++ b/docs/demo.html @@ -0,0 +1,1137 @@ + + + + + + Surfactant Interactive Demo + + + + +
+
+

πŸ”¬ Surfactant Interactive Demo

+

Generate Software Bills of Materials (SBOMs) directly in your browser

+
+ +
+
+

ℹ️ Getting Started

+
    +
  • This demo runs Surfactant using Pyodide (Python in WebAssembly)
  • +
  • Upload files or folders to analyze
  • +
  • Configure SBOM generation settings
  • +
  • Generate and download SBOMs in various formats
  • +
  • Note: Initial load may take a moment as dependencies are downloaded
  • +
  • Browser Note: Directory upload works best in Chrome, Edge, and other Chromium-based browsers
  • +
+
+ +
+ + + +
+ + +
+
+ +
+
πŸ“ Click to select files or drag and drop here
+ Supports multiple files and directories +
+ +
+
+ +
+ + +
+ +
+ + +
+ +
+

Generation Options

+
+ + +
+
+ + +
+
+ + +
+
+ +
+ + +
+ + + + +
+
+ +
+

Generated SBOM:

+
+ +
+
+ + +
+
+

Context Configuration

+
+ + +
+
+ + +
+ + +
+ +
+

Advanced Settings

+
+ + +
+
+ + +
+
+
+ + +
+
+

About Surfactant

+

+ Surfactant is a modular framework to gather file information and analyze dependencies for generating Software Bills of Materials (SBOMs). + It provides comprehensive insight into software composition, helping organizations understand their software supply chain. +

+

Features:

+
    +
  • Multiple output formats (CyTRICS, SPDX, CSV)
  • +
  • Support for various file types (PE, ELF, OLE, MSI)
  • +
  • Dependency analysis and relationship mapping
  • +
  • Extensible plugin architecture
  • +
  • Context-aware SBOM generation
  • +
+

Links:

+ +
+
+
+
+ + + + diff --git a/docs/index.md b/docs/index.md index 712f8552f..e1cc12a64 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,8 @@ Surfactant provides a modular framework to gather file information and analyze dependencies for generating an SBOM. +**[Try the Interactive Demo](demo.html)** - Generate SBOMs directly in your browser! + Some links to pages that may be useful are: [PyPI](https://pypi.org/project/Surfactant/) @@ -24,6 +26,7 @@ Some links to pages that may be useful are: :maxdepth: 2 self + interactive_demo getting_started basic_usage configuration_files diff --git a/docs/interactive_demo.md b/docs/interactive_demo.md new file mode 100644 index 000000000..488e4c08d --- /dev/null +++ b/docs/interactive_demo.md @@ -0,0 +1,79 @@ +# Interactive Demo + +Try Surfactant directly in your browser without any installation! + +## [πŸš€ Launch the Interactive Demo](demo.html) + +The Surfactant Interactive Demo allows you to: + +- **Upload Files**: Select files or directories from your computer to analyze +- **Generate SBOMs**: Create Software Bills of Materials in multiple formats (CyTRICS, SPDX, CSV) +- **Configure Settings**: Customize SBOM generation with various options +- **Manage Context**: Upload and download context configuration files +- **Instant Results**: See and download generated SBOMs immediately + +## Features + +### File Upload +- Drag and drop files or click to select +- Support for multiple files and directories +- Visual file list with size information + +### SBOM Generation +The demo supports generating SBOMs with the following options: + +- **Output Format**: Choose between CyTRICS (default), SPDX, or CSV +- **Skip Gather**: Skip the file gathering phase +- **Skip Relationships**: Don't generate relationship information +- **Skip Install Path**: Exclude install path information +- **Recorded Institution**: Add your organization name to the SBOM + +### Context Configuration +Manage context configurations directly in the browser: + +- Upload existing context configuration JSON files +- Edit context configurations in the built-in editor +- Download configurations to your computer +- Apply configurations to SBOM generation + +### Settings +Customize the SBOM generation process: + +- **Include All Files**: Include all files or only recognized types +- **Verbose Output**: Enable detailed output information + +## Technology + +The demo runs entirely in your browser using: + +- **Pyodide**: Python runtime compiled to WebAssembly +- **Surfactant**: Full Surfactant library installed from PyPI +- **Modern Web APIs**: File System Access API for file handling +- **Responsive Design**: Works on desktop and mobile devices + +## Privacy + +All processing happens locally in your browser. No files are uploaded to any server, ensuring your data remains private and secure. + +## Limitations + +Please note that the browser-based demo has some limitations compared to the full Surfactant installation: + +- First-time load may take longer as Surfactant and its dependencies are downloaded and installed +- Large files or directories may take longer to process due to browser resource constraints +- Some advanced features requiring native libraries may have limited functionality +- For production use, we recommend installing Surfactant locally + +## Getting Started + +1. Visit the [Interactive Demo](demo.html) +2. Click on "Select Files/Directory to Analyze" or drag and drop files +3. Configure your desired settings +4. Click "Generate SBOM" +5. Download your generated SBOM + +For full functionality and production use, please refer to the [Getting Started](getting_started.md) guide for local installation instructions. + +## Feedback + +If you encounter any issues or have suggestions for the demo, please [open an issue](https://github.com/LLNL/Surfactant/issues) on our GitHub repository.