Document SBOM ingestion; also mentioned daemon ingestion

guac-SBOM-ingestion.md

@@ -0,0 +1,88 @@
+## SBOM Ingestion in GUAC
+
+### Overview
+
+Software Bill of Materials (SBOM) ingestion is essential in GUAC (Graph for Understanding Artifact Composition) to help track and analyze dependencies, vulnerabilities, and software supply chain metadata. This documentation explains how to ingest SBOMs in GUAC, covering:
+- **Supported formats and limitations**
+- **Ingestion methods**
+- **Daemon-mode ingestion**
+- **Manual vs. automatic ingestion** 
+
+---
+
+### Supported SBOM Formats
+
+GUAC supports a variety of SBOM formats, making it compatible with several tools and standards:
+- **SPDX**: A widely used open standard for software package metadata.
+- **CycloneDX**: An SBOM specification built for security use cases.
+- **Syft**: A tool generating SBOMs directly from container images and filesystems.
+
+**What is not supported**:
+- Proprietary SBOM formats that deviate from open standards.
+- Incomplete SBOMs without metadata on dependencies or vulnerabilities might have limited utility for ingestion.
+
+---
+
+### Ingestion Methods
+
+You can ingest SBOMs in GUAC using several approaches, each tailored to different needs:
+
+1. **Manual Ingestion**:
+   - Use the GUAC CLI to manually push SBOMs to the backend.
+   - Example:
+     ```bash
+     guac-cli ingest --file my-sbom.spdx.json
+     ```
+   - This method is ideal when working with specific files or testing new SBOMs locally.
+
+2. **Daemon-Mode Ingestion (Polling Collectors)**:
+   - When configured, GUAC operates in **daemon mode**, using collectors (like GCS) to poll for new SBOMs at regular intervals.
+   - **How to Enable Daemon Mode**:
+     - Set up a configuration file specifying the collector sources.
+     - Example of a collector config:
+       ```yaml
+       collectors:
+         - type: gcs
+           bucket: my-sbom-bucket
+           pollingInterval: 5m
+       ```
+   - Once activated, GUAC will **automatically fetch and ingest** SBOMs from the specified source.
+
+3. **Ingestion via APIs**:
+   - You can send SBOMs directly to GUAC using its API.
+   - Example API request:
+     ```bash
+     curl -X POST -F "[email protected]" http://guac-server/v0/ingest
+     ```
+
+---
+
+### Manual vs. Automated Ingestion: Clarification
+
+The **ChainLoop guide** mentions that ingestion must be performed **manually**, but this may refer to **initial configuration and setup** rather than operational ingestion. As clarified in **guacsec/guac#1005**, once properly configured, collectors (like GCS) **poll automatically** to fetch SBOMs periodically.
+
+Thus, while manual ingestion is possible (via CLI or API), **automatic ingestion via polling** is the recommended approach for continuous updates.
+
+---
+
+### Recommended Configuration for Daemon Mode
+
+To use daemon-mode ingestion effectively, ensure the following:
+1. **Install and configure** the appropriate collectors (e.g., GCS, GitHub, or local directory collectors).
+2. **Configure polling intervals** to balance between frequency and system load.
+3. **Verify connectivity** between GUAC and the data source to avoid ingestion delays.
+
+Example of starting GUAC in daemon mode:
+```bash
+guac-server --config /path/to/config.yaml --daemon
+```
+
+---
+
+### Conclusion
+
+SBOM ingestion in GUAC supports both **manual and automated** workflows:
+- **Manual ingestion** is suited for individual files and testing.
+- **Daemon-mode ingestion** allows for **automatic polling** from collectors like GCS.
+
+With both options available, GUAC can integrate seamlessly into various workflows, from CI/CD pipelines to periodic compliance checks.