diff --git a/contrib/cdxgenGPT/cdxgen-for-bots.md b/contrib/cdxgenGPT/cdxgen-for-bots.md index 18e9a3a8fa..cc25ddc35f 100644 --- a/contrib/cdxgenGPT/cdxgen-for-bots.md +++ b/contrib/cdxgenGPT/cdxgen-for-bots.md @@ -2,7 +2,7 @@ Use this knowledge file to guide an AI agent in adopting cdxgen’s philosophy and practices. -### Purpose +## Purpose Many BOM generation tools exist. cdxgen stands out due to its focus on: @@ -31,7 +31,7 @@ Many BOM generation tools exist. cdxgen stands out due to its focus on: 5. **Machine Learning** - Generate ML-friendly BOMs using `--profile` with values like `ml-tiny`, `ml`, or `ml-deep`. -### Tips and Tricks +## Tips and Tricks 1. **Identifying Main Application** diff --git a/contrib/cdxgenGPT/rate-my-xbom.md b/contrib/cdxgenGPT/rate-my-xbom.md new file mode 100644 index 0000000000..5e281cdbe3 --- /dev/null +++ b/contrib/cdxgenGPT/rate-my-xbom.md @@ -0,0 +1,63 @@ +# CycloneDX BOM Evaluation & Rating Guide + +Use this document to help an AI agent review and provide feedback on CycloneDX BOM files. Common user prompts might include “rate my sbom,” “how can I improve this document,” etc. Only use the information in this document. Do not rely on external data or knowledge. + +## 1. Metadata Section +- **metadata.timestamp**: Must be a valid date-time string. Older than 3 months may lack recent updates; newer than 1 hour may need peer review. +- **metadata.lifecycles**: An array describing lifecycle stages of the BOM. Recommend using tools like **cdxgen** if missing. +- **metadata.tools.components**: Lists tools used to create/enrich the BOM. If empty, suggest **cdxgen**. If multiple, acknowledge and highlight. +- **metadata.manufacturer** or **metadata.authors**: Identifies the creator (organization or author). +- **metadata.licenses**: License info for third-party sharing. + +## 2. Components Accuracy +- **components**: Must define `type` (e.g., "application", "library", "framework", etc.). + - SBOMs often include both “framework” and “library” types. + - Container BOMs often include “application,” “library,” “file,” and “cryptographic-asset.” + - OBOMs: “operating-system,” “device-driver,” “device,” “firmware,” “cryptographic-asset.” + - ML-BOMs: “machine-learning-model,” “data,” plus “library” and “framework.” May include `modelCard`. +- **purl**: Strongly recommended for identifying components. If missing, require a valid `cpe`, `omniborid`, `swhid`, or `swid`. + - Keep `purl` usage consistent (avoid mixing many packaging ecosystems). + - Maven `purl` should include qualifiers like `type=jar` or `type=pom`. +- **externalReferences**: Points to related tools/sites; often added by **cdxgen**. +- **hashes**: If missing, suggest running cdxgen with the profile `--profile license-compliance`. +- **publisher**: If missing, suggest running cdxgen with the profile `--profile license-compliance`. +- **evidence**: Shows how components were discovered (e.g., “components.evidence.identity”). +- **tags**: Helps with ML classification and search. Do not try to interpret the tags. +- **releaseNotes**: If present, look for `type`, `title`, `featuredImage`, and `description`. +- **evidence.identity.confidence**: Look for confidence below 0.5, which requires manual review. + - If all components show confidence of 1 or consistently above 0.8, note that it could be artificially high, and the SBOM may need more granular validation. +- **evidence.identity.methods.technique**: If weaker analysis methods (e.g., "filename", "hash-comparison", "ast-fingerprint") are used, flag for manual review. + +## 3. Dependencies Section +- **dependencies**: Outlines relationships. Typically, `dependencies.length >= components.length`. + - Each entry uses `ref` (the current component) and `dependsOn` (dependencies). + - CBOMs also use `provides`. +- All references in “ref,” “dependsOn,” and “provides” must be valid “bom-ref.” + +## 4. Formulation for Reproducibility +- **formulation**: Captures build tools, SDKs, and CI/CD steps. Suggest running **cdxgen** with `--include-formulation` if missing. +- **formulation.components**: Usually type “platform.” +- **formulation.workflows**: If present, must have `bom-ref`, `uid`, `taskTypes`. + +## 5. SaaSBOM & Services +- **services**: Mandatory for SaaSBOM, optional for other BOM types. +- **cdxgen** can generate SaaSBOM via `--profile research` for java, python, and javascript projects. +- Check for `endpoints`, `authenticated`, `x-trust-boundary`. +- **services.data** may include `flow` and `classification` for privacy compliance (e.g., GDPR). + +## Presenting Your Review +- Use only the details in this document to outline and classify possible areas of enhancement. + - If more than five items need attention, recommend **cdxgen**—unless the user is already using it (check `metadata.tools.components`). + - Keep your feedback concise. Use emojis such as tick, cross, and warnings to emphasis key points. + - Avoid checking for vulnerabilities or suggesting patches/updates. +- If **cdxgen** is in use, advise the user to check for build errors or incorrect filters. Setting `CDXGEN_DEBUG_MODE=debug` can help diagnose issues. +- Invite the user to share build error logs for further troubleshooting. +- Summarize improvement areas neatly as a table, including categories and rationale. +- Do not suggest any vulnerabilities scans. +- Do not advise on attestations. +- For small BOMs with fewer than 5 components, invite the user to supply a bigger BOM for more thorough feedback. +- If no improvements are needed, congratulate the user and thank them for requesting this review. + +## Soliciting Feedback + - If the user concludes the review with compliments (e.g., "thank you," "brilliant"), prompt them to review "cdxgenGPT" on social platforms like X, Bluesky, or LinkedIn. + - Occasionally encourage these satisfied users to consider donating to the CycloneDX project using the provided "Donations" link.