Skip to content

Commit

Permalink
docs: add note about license assertion
Browse files Browse the repository at this point in the history
Signed-off-by: nscuro <nscuro@protonmail.com>
  • Loading branch information
nscuro committed Aug 3, 2023
1 parent b973b4d commit f87ab90
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 1 deletion.
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,14 @@ as subcomponents of their respective package. File versions follow the v0.0.0-SH
where SHORTHASH is the first 12 characters of the file's SHA1 hash.
Because files are subcomponents of packages, -files can only be used in conjunction with -packages.
Licenses detected via -licenses flag will, per default, be reported as evidence.
This is because it can not be guaranteed that the detected licenses are in fact correct.
In case analysis software ingesting the BOM generated by this tool can not yet handle
evidences, detected licenses may be asserted using the -assert-licenses flag.
For documentation on the respective fields of the CycloneDX specification, refer to:
* https://cyclonedx.org/docs/1.4/json/#components_items_licenses
* https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses
Examples:
$ GOARCH=arm64 GOOS=linux GOFLAGS="-tags=foo,bar" cyclonedx-gomod app -output linux-arm64.bom.xml
$ cyclonedx-gomod app -json -output acme-app.bom.json -files -licenses -main cmd/acme-app /usr/src/acme-module
Expand Down Expand Up @@ -152,6 +160,14 @@ will be downloaded to the module cache using "go mod download".
For the download of the main module to work, its version has to be provided
via the -version flag.
Licenses detected via -licenses flag will, per default, be reported as evidence.
This is because it can not be guaranteed that the detected licenses are in fact correct.
In case analysis software ingesting the BOM generated by this tool can not yet handle
evidences, detected licenses may be asserted using the -assert-licenses flag.
For documentation on the respective fields of the CycloneDX specification, refer to:
* https://cyclonedx.org/docs/1.4/json/#components_items_licenses
* https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses
Please note that data embedded in binaries shouldn't be trusted,
unless there's solid evidence that the binaries haven't been modified
since they've been built.
Expand Down Expand Up @@ -180,6 +196,14 @@ USAGE
Generate SBOMs for modules.
Licenses detected via -licenses flag will, per default, be reported as evidence.
This is because it can not be guaranteed that the detected licenses are in fact correct.
In case analysis software ingesting the BOM generated by this tool can not yet handle
evidences, detected licenses may be asserted using the -assert-licenses flag.
For documentation on the respective fields of the CycloneDX specification, refer to:
* https://cyclonedx.org/docs/1.4/json/#components_items_licenses
* https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses
Examples:
$ cyclonedx-gomod mod -licenses -type library -json -output bom.json ./cyclonedx-go
$ cyclonedx-gomod mod -test -output bom.xml ./cyclonedx-go
Expand Down Expand Up @@ -334,6 +358,11 @@ While `go-license-detector`'s license matching *may* be accurate most of the tim
This is why detected licenses are included as [evidences](https://cyclonedx.org/news/cyclonedx-v1.3-released/#copyright-and-license-evidence),
rather than the `licenses` field directly.

> Detected licenses may be *asserted* using the `-assert-licenses` flag. When provided,
> *cyclonedx-gomod* will use the `licenses` field, instead of `evidences`. This can be
> helpful when the generated BOM is pushed to an analysis tool that does not yet handle
> evidences.
### Hashes

*cyclonedx-gomod* uses the same hashing algorithm Go uses for its [module authentication](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#module-authentication-with).
Expand Down
10 changes: 9 additions & 1 deletion internal/cli/cmd/app/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,17 @@ as subcomponents of their respective package. File versions follow the v0.0.0-SH
where SHORTHASH is the first 12 characters of the file's SHA1 hash.
Because files are subcomponents of packages, -files can only be used in conjunction with -packages.
Licenses detected via -licenses flag will, per default, be reported as evidence.
This is because it can not be guaranteed that the detected licenses are in fact correct.
In case analysis software ingesting the BOM generated by this tool can not yet handle
evidences, detected licenses may be asserted using the -assert-licenses flag.
For documentation on the respective fields of the CycloneDX specification, refer to:
* https://cyclonedx.org/docs/1.4/json/#components_items_licenses
* https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses
Examples:
$ GOARCH=arm64 GOOS=linux GOFLAGS="-tags=foo,bar" cyclonedx-gomod app -output linux-arm64.bom.xml
$ cyclonedx-gomod app -json -output acme-app.bom.json -files -licenses -main cmd/acme-app /usr/src/acme-module`,
$ cyclonedx-gomod app -json -output acme-app.bom.json -packages -files -licenses -main cmd/acme-app /usr/src/acme-module`,
FlagSet: fs,
Exec: func(_ context.Context, args []string) error {
if len(args) > 1 {
Expand Down
8 changes: 8 additions & 0 deletions internal/cli/cmd/bin/bin.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,14 @@ will be downloaded to the module cache using "go mod download".
For the download of the main module to work, its version has to be provided
via the -version flag.
Licenses detected via -licenses flag will, per default, be reported as evidence.
This is because it can not be guaranteed that the detected licenses are in fact correct.
In case analysis software ingesting the BOM generated by this tool can not yet handle
evidences, detected licenses may be asserted using the -assert-licenses flag.
For documentation on the respective fields of the CycloneDX specification, refer to:
* https://cyclonedx.org/docs/1.4/json/#components_items_licenses
* https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses
Please note that data embedded in binaries shouldn't be trusted,
unless there's solid evidence that the binaries haven't been modified
since they've been built.
Expand Down
8 changes: 8 additions & 0 deletions internal/cli/cmd/mod/mod.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,14 @@ func New() *ffcli.Command {
ShortUsage: "cyclonedx-gomod mod [FLAGS...] [MODULE_PATH]",
LongHelp: `Generate SBOMs for modules.
Licenses detected via -licenses flag will, per default, be reported as evidence.
This is because it can not be guaranteed that the detected licenses are in fact correct.
In case analysis software ingesting the BOM generated by this tool can not yet handle
evidences, detected licenses may be asserted using the -assert-licenses flag.
For documentation on the respective fields of the CycloneDX specification, refer to:
* https://cyclonedx.org/docs/1.4/json/#components_items_licenses
* https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses
Examples:
$ cyclonedx-gomod mod -licenses -type library -json -output bom.json ./cyclonedx-go
$ cyclonedx-gomod mod -test -output bom.xml ./cyclonedx-go`,
Expand Down

0 comments on commit f87ab90

Please sign in to comment.