diff --git a/README.md b/README.md index e69d761..d60597c 100644 --- a/README.md +++ b/README.md @@ -320,7 +320,7 @@ drogonsec/ │ ├── engine/ # SAST rules engine (20+ languages) │ ├── leaks/ # Secret detection engine │ ├── sca/ # Dependency analysis engine -│ ├── reporter/ # Text/JSON/SARIF/HTML reporters +│ ├── reporter/ # Text/JSON/SARIF/HTML/CycloneDX reporters │ ├── ai/ # AI remediation engine (Ollama + Cloud) │ └── config/ # Types and configuration └── rules/ # YAML rule definitions (community-extensible) diff --git a/docs/branch-monitoring.md b/docs/branch-monitoring.md index 06c7ef9..c4752fe 100644 --- a/docs/branch-monitoring.md +++ b/docs/branch-monitoring.md @@ -370,7 +370,7 @@ jobs: | `--tls-cert` | — | PEM certificate for HTTPS | | `--tls-key` | — | PEM private key for HTTPS | | `--interval` | `5m` | Poll interval (min `30s`) | -| `--format` | `text` | `text`, `json`, `sarif`, `html` | +| `--format` | `text` | `text`, `json`, `sarif`, `html`, `cyclonedx` | | `--output` | stdout | Base path for report files | | `--severity` | `LOW` | Minimum severity to report | | `--workers` | `4` | Parallel scan workers | diff --git a/docs/index.md b/docs/index.md index 2953108..b713e63 100644 --- a/docs/index.md +++ b/docs/index.md @@ -53,6 +53,7 @@ Inspired by Horusec, Drogonsec is its modern, actively maintained successor with - **CWE** — Common Weakness Enumeration mapping on every finding - **CVSS 3.1** — Severity scoring for accurate risk prioritization - **SARIF 2.1** — Native integration with GitHub Security and Azure DevOps +- **CycloneDX 1.5** — SBOM export for Grype, Trivy, and Dependency-Track --- @@ -89,7 +90,7 @@ drogonsec/ │ ├── engine/ # SAST rules engine (20+ languages) │ ├── leaks/ # Secret detection engine │ ├── sca/ # Dependency analysis engine -│ ├── reporter/ # Text / JSON / SARIF / HTML reporters +│ ├── reporter/ # Text / JSON / SARIF / HTML / CycloneDX reporters │ ├── ai/ # AI remediation (Ollama OSS + Cloud) │ └── config/ # Types and configuration └── rules/ # YAML rule definitions (community-extensible) diff --git a/docs/modules.md b/docs/modules.md index 6ca3409..be33b40 100644 --- a/docs/modules.md +++ b/docs/modules.md @@ -107,6 +107,21 @@ CVSS : 7.5 OWASP : A03:2025 - Software Supply Chain Failures ``` +### SBOM Export (CycloneDX) + +The dependency inventory the SCA engine builds can be exported as a +[CycloneDX](https://cyclonedx.org) 1.5 Software Bill of Materials, so it can be +consumed by Grype, Trivy, and Dependency-Track: + +```bash +drogonsec scan . --format cyclonedx --output sbom.json +``` + +Each dependency becomes a CycloneDX component with a Package URL (purl). The v1 +SBOM is a flat component list; the transitive dependency graph and SPDX output +are planned for a later release. See [Usage → Output Formats](usage.md#output-formats) +for details. + --- ## Leaks Engine — Secret Detection diff --git a/docs/security.md b/docs/security.md index dc6025b..da77582 100644 --- a/docs/security.md +++ b/docs/security.md @@ -108,7 +108,7 @@ Auto-detecting a local Ollama requires more than `HTTP 200` on port `11434` — ## Report Output Permissions -When `--output ` is used for `text`, `json`, `sarif`, or `html` reports, the file is created with mode `0600` (user-only). Reports embed vulnerable code snippets, matched secrets, and AI remediation text; on shared CI runners or workstations they should not be world-readable by default. If you need the report to be readable by other accounts, adjust the permissions after generation. +When `--output ` is used for `text`, `json`, `sarif`, `html`, or `cyclonedx` reports, the file is created with mode `0600` (user-only). Reports embed vulnerable code snippets, matched secrets, and AI remediation text; on shared CI runners or workstations they should not be world-readable by default. If you need the report to be readable by other accounts, adjust the permissions after generation. --- diff --git a/docs/usage.md b/docs/usage.md index a719e29..9e43664 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -88,7 +88,7 @@ Always pass your API key via `AI_API_KEY` environment variable. ## Output Formats -Drogonsec supports four output formats, suited for different workflows: +Drogonsec supports five output formats, suited for different workflows: | Format | Flag | Use Case | |---|---|---| @@ -96,6 +96,7 @@ Drogonsec supports four output formats, suited for different workflows: | JSON | `--format json` | SIEM, automation, further processing | | HTML | `--format html` | Shareable reports, management presentations | | SARIF | `--format sarif` | GitHub Security tab, Azure DevOps | +| CycloneDX | `--format cyclonedx` | SBOM for Grype, Trivy, Dependency-Track | ```bash # JSON report @@ -106,8 +107,54 @@ drogonsec scan . --format html --output report.html # SARIF for GitHub Security integration drogonsec scan . --format sarif --output results.sarif + +# CycloneDX SBOM (Software Bill of Materials) +drogonsec scan . --format cyclonedx --output sbom.json +``` + +> **Tip:** for machine formats (`json`, `sarif`, `cyclonedx`) always pass +> `--output`, so the scan's progress output stays on the terminal and the file +> receives only the clean document. + +### CycloneDX SBOM + +The `cyclonedx` format exports a [CycloneDX](https://cyclonedx.org) 1.5 JSON +Software Bill of Materials of the dependencies discovered by the SCA engine. Each +dependency becomes a component with a Package URL (purl), so the output is +directly consumable by Grype, Trivy, and Dependency-Track. + +Supported ecosystems and their purl types: npm, pypi, golang, maven, gem +(rubygems), composer (packagist), pub. + +```bash +drogonsec scan . --format cyclonedx --output sbom.json ``` +Example output (truncated): + +```json +{ + "bomFormat": "CycloneDX", + "specVersion": "1.5", + "serialNumber": "urn:uuid:cadae14d-aa47-44...", + "version": 1, + "metadata": { + "timestamp": "2026-06-23T12:00:00Z", + "tools": { "components": [ { "type": "application", "name": "DrogonSec Security Scanner", "version": "0.1.0" } ] }, + "component": { "type": "application", "name": "myproject" } + }, + "components": [ + { "type": "library", "bom-ref": "pkg:npm/lodash@4.17.15", "name": "lodash", "version": "4.17.15", "purl": "pkg:npm/lodash@4.17.15" } + ] +} +``` + +> **Scope:** the SBOM is a flat component inventory. The SCA engine resolves +> manifests rather than full lockfiles, so the transitive dependency graph is +> not yet expressed. Transitive resolution and SPDX output are planned for a +> later release. The SBOM is derived from the SCA engine, so do not combine it +> with `--no-sca`. + --- ## Controlling Severity diff --git a/internal/cli/monitor.go b/internal/cli/monitor.go index e7e407c..1e59094 100644 --- a/internal/cli/monitor.go +++ b/internal/cli/monitor.go @@ -86,7 +86,7 @@ func init() { monitorCmd.Flags().StringVar(&monInterval, "interval", "5m", "polling interval: e.g. 30s, 5m, 1h (min: 30s)") // Scan output flags (mirrors scan command for familiarity). - monitorCmd.Flags().StringVarP(&monFmt, "format", "f", "text", "output format: text, json, sarif, html") + monitorCmd.Flags().StringVarP(&monFmt, "format", "f", "text", "output format: text, json, sarif, html, cyclonedx") monitorCmd.Flags().StringVarP(&monOutput, "output", "o", "", "output file base path (branch + timestamp appended per scan)") monitorCmd.Flags().StringVar(&monSeverity, "severity", "LOW", "minimum severity to report: LOW, MEDIUM, HIGH, CRITICAL") monitorCmd.Flags().IntVar(&monWorkers, "workers", 4, "number of parallel scan workers")