{"id":20617792,"url":"https://github.com/cyclonedx/cyclonedx-gomod","last_synced_at":"2025-05-16T01:05:17.495Z","repository":{"id":38196302,"uuid":"345433007","full_name":"CycloneDX/cyclonedx-gomod","owner":"CycloneDX","description":"Creates CycloneDX Software Bill of Materials (SBOM) from Go modules","archived":false,"fork":false,"pushed_at":"2025-05-08T09:25:49.000Z","size":5752,"stargazers_count":156,"open_issues_count":37,"forks_count":27,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-16T01:05:11.113Z","etag":null,"topics":["bill-of-materials","bom","go-modules","golang","mbom","obom","owasp","saasbom","sbom","sbom-generator","software-bill-of-materials","vex"],"latest_commit_sha":null,"homepage":"https://cyclonedx.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CycloneDX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":["https://owasp.org/donate/?reponame=www-project-cyclonedx\u0026title=OWASP+CycloneDX"]}},"created_at":"2021-03-07T19:21:22.000Z","updated_at":"2025-05-15T06:32:03.000Z","dependencies_parsed_at":"2023-09-29T11:40:59.488Z","dependency_job_id":"db893af2-d4cb-4977-9443-0c16ec7cf194","html_url":"https://github.com/CycloneDX/cyclonedx-gomod","commit_stats":{"total_commits":560,"total_committers":10,"mean_commits":56.0,"dds":0.4821428571428571,"last_synced_commit":"e54760d8f6a1252608b24476c41d5e8e7ac6cb45"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-gomod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-gomod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-gomod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-gomod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CycloneDX","download_url":"https://codeload.github.com/CycloneDX/cyclonedx-gomod/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bill-of-materials","bom","go-modules","golang","mbom","obom","owasp","saasbom","sbom","sbom-generator","software-bill-of-materials","vex"],"created_at":"2024-11-16T12:05:59.013Z","updated_at":"2025-05-16T01:05:12.476Z","avatar_url":"https://github.com/CycloneDX.png","language":"Go","funding_links":["https://owasp.org/donate/?reponame=www-project-cyclonedx\u0026title=OWASP+CycloneDX"],"categories":[],"sub_categories":[],"readme":"# cyclonedx-gomod\n\n[![Build Status](https://github.com/CycloneDX/cyclonedx-gomod/actions/workflows/ci.yml/badge.svg)](https://github.com/CycloneDX/cyclonedx-gomod/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/CycloneDX/cyclonedx-gomod)](https://goreportcard.com/report/github.com/CycloneDX/cyclonedx-gomod)\n[![Go Reference](https://pkg.go.dev/badge/github.com/CycloneDX/cyclonedx-gomod.svg)](https://pkg.go.dev/github.com/CycloneDX/cyclonedx-gomod)\n[![Latest GitHub release](https://img.shields.io/github/v/release/CycloneDX/cyclonedx-gomod?sort=semver)](https://github.com/CycloneDX/cyclonedx-gomod/releases/latest)\n[![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](LICENSE)  \n[![Website](https://img.shields.io/badge/https://-cyclonedx.org-blue.svg)](https://cyclonedx.org/)\n[![Slack Invite](https://img.shields.io/badge/Slack-Join-blue?logo=slack\u0026labelColor=393939)](https://cyclonedx.org/slack/invite)\n[![Group Discussion](https://img.shields.io/badge/discussion-groups.io-blue.svg)](https://groups.io/g/CycloneDX)\n[![Twitter](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Follow)](https://twitter.com/CycloneDX_Spec)\n\n*cyclonedx-gomod* creates CycloneDX Software Bill of Materials (SBOM) from Go modules\n\n## Installation\n\nPrebuilt binaries are available on the [releases](https://github.com/CycloneDX/cyclonedx-gomod/releases) page.\n\n### Homebrew\n\n```shell\nbrew install cyclonedx/cyclonedx/cyclonedx-gomod\n```\n\n### From Source\n\n```shell\ngo install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest\n```\n\nBuilding from source requires Go 1.23.1 or newer.\n\n## Compatibility\n\n*cyclonedx-gomod* aims to produce SBOMs according to the latest CycloneDX specification, and currently supports up to [1.6](https://cyclonedx.org/docs/1.6/). \nYou can use the [CycloneDX CLI](https://github.com/CycloneDX/cyclonedx-cli#convert-command) to convert between multiple BOM formats or specification versions. \n\n## Usage\n\n```\nUSAGE\n  cyclonedx-gomod \u003cSUBCOMMAND\u003e [FLAGS...] [\u003cARG\u003e...]\n\ncyclonedx-gomod creates CycloneDX Software Bill of Materials (SBOM) from Go modules.\n\nMultiple subcommands are offered, each targeting different use cases:\n\n- SBOMs generated with \"app\" include only those modules that the target application\n  actually depends on. Modules required by tests or packages that are not imported\n  by the application are not included. Build constraints are evaluated, which enables\n  a very detailed view of what's really compiled into an application's binary.\n  \n- SBOMs generated with \"mod\" include the aggregate of modules required by all \n  packages in the target module. This optionally includes modules required by\n  tests and test packages. Build constraints are NOT evaluated, allowing for \n  a \"whole picture\" view on the target module's dependencies.\n\n- \"bin\" offers support for generating rudimentary SBOMs from binaries built with Go modules.\n\nDistributors of applications will typically use \"app\" and provide the resulting SBOMs\nalongside their application's binaries. This enables users to only consume SBOMs for\nartifacts that they actually use. For example, a Go module may include \"server\" and\n\"client\" applications, of which only the \"client\" is distributed to users. \nAdditionally, modules included in \"client\" may differ, depending on which platform \nit was compiled for.\n\nVendors or maintainers may choose to use \"mod\" for internal use, where it's too\ncumbersome to deal with many SBOMs for the same product. Possible use cases are: \n- Tracking of component inventory\n- Tracking of third party component licenses\n- Continuous monitoring for vulnerabilities\n\"mod\" may also be used to generate SBOMs for libraries.\n\nSUBCOMMANDS\n  app      Generate SBOMs for applications\n  bin      Generate SBOMs for binaries\n  mod      Generate SBOMs for modules\n  version  Show version information\n```\n\n### Subcommands\n\n#### `app`\n\n```\nUSAGE\n  cyclonedx-gomod app [FLAGS...] [MODULE_PATH]\n\nGenerate SBOMs for applications.\n\nIn order to produce accurate SBOMs, build constraints must be configured\nvia environment variables. These build constraints should mimic the ones passed\nto the \"go build\" command for the application.\n\nEnvironment variables that act as build constraints are:\n  - GOARCH       The target architecture (386, amd64, etc.)\n  - GOOS         The target operating system (linux, windows, etc.)\n  - CGO_ENABLED  Whether or not CGO is enabled\n  - GOFLAGS      Flags that are passed to the Go command (e.g. build tags)\n\nA complete overview of all environment variables can be found here:\n  https://pkg.go.dev/cmd/go#hdr-Environment_variables\n\nApplicable build constraints are included as properties of the main component.\n\nBecause build constraints influence Go's module selection, an SBOM should be generated\nfor each target in the build matrix.\n\nThe -main flag should be used to specify the path to the application's main package.\nIt must point to a directory within MODULE_PATH. If not set, MODULE_PATH is assumed.\n\nIn order to not only include modules, but also the packages within them,\nthe -packages flag can be used. Packages are represented as subcomponents of modules.\n\nBy passing -files, all files that would be included in a binary will be attached\nas subcomponents of their respective package. File versions follow the v0.0.0-SHORTHASH pattern,\nwhere SHORTHASH is the first 12 characters of the file's SHA1 hash.\nBecause files are subcomponents of packages, -files can only be used in conjunction with -packages.\nWhen -paths option is additionally enabled, each file would have a property with\na file path relative to its module root.\n\nLicenses detected via -licenses flag will, per default, be reported as evidence.\nThis is because it can not be guaranteed that the detected licenses are in fact correct.\nIn case analysis software ingesting the BOM generated by this tool can not yet handle\nevidences, detected licenses may be asserted using the -assert-licenses flag.\nFor documentation on the respective fields of the CycloneDX specification, refer to:\n  * https://cyclonedx.org/docs/1.4/json/#components_items_licenses\n  * https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses\n\nExamples:\n  $ GOARCH=arm64 GOOS=linux GOFLAGS=\"-tags=foo,bar\" cyclonedx-gomod app -output linux-arm64.bom.xml\n  $ cyclonedx-gomod app -json -output acme-app.bom.json -packages -files -licenses -main cmd/acme-app /usr/src/acme-module\n\nFLAGS\n  -assert-licenses=false       Assert detected licenses\n  -files=false                 Include files\n  -json=false                  Output in JSON\n  -disable-html-escape=false   Disable HTML escaping in JSON output\n  -licenses=false              Perform license detection\n  -main string                 Path to the application's main package, relative to MODULE_PATH\n  -noserial=false              Omit serial number\n  -output -                    Output file path (or - for STDOUT)\n  -output-version 1.6          Output spec verson (1.6, 1.5, 1.4, 1.3, 1.2, 1.1, 1.0)\n  -packages=false              Include packages\n  -paths=false                 Include file paths relative to their module root\n  -serial string               Serial number\n  -std=false                   Include Go standard library as component and dependency of the module\n  -verbose=false               Enable verbose output\n```\n\n#### `bin`\n\n```\nUSAGE\n  cyclonedx-gomod bin [FLAGS...] BINARY_PATH\n\nGenerate SBOMs for binaries.\n\nAlthough the binary is never executed by cyclonedx-gomod, it must be executable.\nThis is a requirement by the \"go version -m\" command that is used to provide this functionality.\n\nWhen license detection is enabled, all modules (including the main module)\nwill be downloaded to the module cache using \"go mod download\".\nFor the download of the main module to work, its version has to be provided\nvia the -version flag.\n\nLicenses detected via -licenses flag will, per default, be reported as evidence.\nThis is because it can not be guaranteed that the detected licenses are in fact correct.\nIn case analysis software ingesting the BOM generated by this tool can not yet handle\nevidences, detected licenses may be asserted using the -assert-licenses flag.\nFor documentation on the respective fields of the CycloneDX specification, refer to:\n  * https://cyclonedx.org/docs/1.4/json/#components_items_licenses\n  * https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses\n\nPlease note that data embedded in binaries shouldn't be trusted,\nunless there's solid evidence that the binaries haven't been modified\nsince they've been built.\n\nExample:\n  $ cyclonedx-gomod bin -json -output acme-app-v1.0.0.bom.json -version v1.0.0 ./acme-app\n\nFLAGS\n  -assert-licenses=false       Assert detected licenses\n  -json=false                  Output in JSON\n  -disable-html-escape=false   Disable HTML escaping in JSON output\n  -licenses=false              Perform license detection\n  -noserial=false              Omit serial number\n  -output -                    Output file path (or - for STDOUT)\n  -output-version 1.6          Output spec verson (1.6, 1.5, 1.4, 1.3, 1.2, 1.1, 1.0)\n  -serial string               Serial number\n  -std=false                   Include Go standard library as component and dependency of the module\n  -verbose=false               Enable verbose output\n  -version string              Version of the main component\n```\n\n#### `mod`\n\n```\nUSAGE\n  cyclonedx-gomod mod [FLAGS...] [MODULE_PATH]\n\nGenerate SBOMs for modules.\n\nLicenses detected via -licenses flag will, per default, be reported as evidence.\nThis is because it can not be guaranteed that the detected licenses are in fact correct.\nIn case analysis software ingesting the BOM generated by this tool can not yet handle\nevidences, detected licenses may be asserted using the -assert-licenses flag.\nFor documentation on the respective fields of the CycloneDX specification, refer to:\n  * https://cyclonedx.org/docs/1.4/json/#components_items_licenses\n  * https://cyclonedx.org/docs/1.4/json/#components_items_evidence_licenses\n\nExamples:\n  $ cyclonedx-gomod mod -licenses -type library -json -output bom.json ./cyclonedx-go\n  $ cyclonedx-gomod mod -test -output bom.xml ./cyclonedx-go\n\nFLAGS\n  -assert-licenses=false       Assert detected licenses\n  -json=false                  Output in JSON\n  -disable-html-escape=false   Disable HTML escaping in JSON output\n  -licenses=false              Perform license detection\n  -noserial=false              Omit serial number\n  -output -                    Output file path (or - for STDOUT)\n  -output-version 1.6          Output spec verson (1.6, 1.5, 1.4, 1.3, 1.2, 1.1, 1.0)\n  -serial string               Serial number\n  -std=false                   Include Go standard library as component and dependency of the module\n  -test=false                  Include test dependencies\n  -type application            Type of the main component\n  -verbose=false               Enable verbose output\n```\n\n### Examples 📃\n\nIn order to demonstrate what SBOMs generated with *cyclonedx-gomod* look like, \nas well as to give you an idea about the differences between the commands `app`, \n`mod` and `bin`, we provide example SBOMs for each command in the [`examples`](./examples) directory.\n\nThe whole process of generating these examples is encapsulated in [`Dockerfile.examples`](./Dockerfile.examples).  \nTo generate them yourself, simply execute the following command:\n\n```shell\n$ make examples\n```\n\n### GitHub Actions 🤖\n\nWe made a GitHub Action to help integrate *cyclonedx-gomod* into existing CI/CD workflows!  \nYou can find it on the GitHub marketplace: [*gh-gomod-generate-sbom*](https://github.com/marketplace/actions/cyclonedx-gomod-generate-sbom)\n\n### GoReleaser 🚀\n\nThe recommended way of integrating with [GoReleaser](https://goreleaser.com/) is via its [*sbom* feature](https://goreleaser.com/customization/sbom/).\nYou can find some example configurations for each *cyclonedx-gomod* command below, given the following [`builds`](https://goreleaser.com/customization/build/):\n\n```yaml\nbuilds:\n- env:\n  - CGO_ENABLED=0\n  goos:\n  - linux\n  - windows\n  - darwin\n  goarch:\n  - amd64\n  - arm64\n  tags:\n  - foo\n  - bar\n```\n\n```yaml\n# app command:\n# - generate a SBOM for each binary built\n# - provide build context via environment variables\n\nsboms:\n- documents:\n  - \"{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}.bom.json\"\n  artifacts: binary\n  cmd: cyclonedx-gomod\n  args: [\"app\", \"-licenses\", \"-json\", \"-output\", \"$document\", \"../\"]\n  env:\n  - GOARCH={{ .Arch }}\n  - GOOS={{ .Os }}\n  - GOFLAGS=-tags=foo,bar\n```\n\n```yaml\n# bin command:\n# - generate a SBOM for each binary built\n\nsboms:\n- documents:\n  - \"{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}.bom.json\"\n  artifacts: binary\n  cmd: cyclonedx-gomod\n  args: [\"bin\", \"-json\", \"-output\", \"$document\", \"$artifact\"]\n```\n\n```yaml\n# mod command:\n# - generate a single SBOM for the entire module\n\nsboms:\n- documents:\n  - bom.json\n  artifacts: any\n  cmd: cyclonedx-gomod\n  args: [ \"mod\", \"-licenses\", \"-std\", \"-json\", \"-output\", \"$document\", \"../\" ]\n```\n\nGoReleaser will execute `cmd`s in its `dist` directory, which is a subdirectory of the project root. \nBecause `app` and `mod` both expect the module's root directory as an argument, `../` must be provided.\n\n### Docker 🐳\n\n```shell\n$ docker run -it --rm \\\n    -v \"/path/to/mymodule:/usr/src/mymodule\" \\\n    -v \"$(pwd):/out\" \\\n    cyclonedx/cyclonedx-gomod:v1 mod -json -output /out/bom.json /usr/src/mymodule\n```\n\n\u003e The image is based on `golang:1.18-alpine`.  \n\u003e When using the `app` command, please keep in mind that the Go version may influence module selection.  \n\u003e We generally recommend using a [precompiled binary](https://github.com/CycloneDX/cyclonedx-gomod/releases) \n\u003e and running it in the same environment in which you're building your application in.\n\n### Library Usage\n\nStarting with `v1.2.0`, *cyclonedx-gomod* can be used as a library as well:\n\n```shell\ngo get -v github.com/CycloneDX/cyclonedx-gomod\n```\n\nRefer to the [documentation](https://pkg.go.dev/github.com/CycloneDX/cyclonedx-gomod) for details and examples.\n\n\u003e Be warned that *cyclonedx-gomod* is and will continue to be primarily a CLI tool.  \n\u003e While we'll only introduce breaking changes to the exposed APIs in accordance with semver,\n\u003e we will not invest in supporting older versions. If you intend on depending on our API,\n\u003e please assess if you'll be able to keep up. For example, we will move to the newest Go version\n\u003e shortly after its GA, and will almost definitely use backwards-incompatible features going forward.\n\n## Important Notes\n\n### Vendoring\n\nModules that use [vendoring](https://golang.org/ref/mod#go-mod-vendor) are, although in a limited manner, supported.  \nLimitations are as follows:\n\n* **No hashes.** Go doesn't copy all module files to the `vendor`, only those that are required to build\n  and test the main module. Because [module checksums](#hashes) consider almost all files in a module's directory though, \n  calculating accurate hashes from the `vendor` directory is not possible. As a consequence, SBOMs for modules that use\n  vendoring do not include component hashes.\n* **License detection may fail.** Go doesn't always copy license files when vendoring modules, which may cause license detection to fail.\n\n### Licenses\n\nThere is currently no standard way for developers to declare their module's license.  \nDetecting licenses based on files in a repository is a non-trivial task, which is why *cyclonedx-gomod*  \nuses [`go-license-detector`](https://github.com/go-enry/go-license-detector) to resolve module licenses.\n\nWhile `go-license-detector`'s license matching *may* be accurate most of the time, SBOMs should state facts.  \nThis is why detected licenses are included as [evidences](https://cyclonedx.org/news/cyclonedx-v1.3-released/#copyright-and-license-evidence), \nrather than the `licenses` field directly.\n\n\u003e Detected licenses may be *asserted* using the `-assert-licenses` flag. When provided,\n\u003e *cyclonedx-gomod* will use the `licenses` field, instead of `evidences`. This can be\n\u003e helpful when the generated BOM is pushed to an analysis tool that does not yet handle\n\u003e evidences.\n\n### Hashes\n\n*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).  \n[`vikyd/go-checksum`](https://github.com/vikyd/go-checksum#calc-checksum-of-module-directory) does a great job of\nexplaining what exactly that entails. In essence, the hash you see in an SBOM should be the same as in your `go.sum` file,\njust in a different format. This is because the CycloneDX specification enforces hashes to be provided in hex encoding,\nwhile Go uses base64 encoded values.\n\n### Version Detection\n\nFor the main module and local [replacement modules](https://golang.org/ref/mod#go-mod-file-replace), *cyclonedx-gomod* will perform version detection using Git:\n\n* If the `HEAD` commit is tagged and the tag is a valid [semantic version](https://golang.org/ref/mod#versions), that tag is used.\n* If `HEAD` is not tagged, a [pseudo version](https://golang.org/ref/mod#pseudo-versions) is generated.\n\n\u003e Please note that pseudo versions take the previous version into consideration.\n\u003e If your repository has been cloned with limited depth, *cyclonedx-gomod* may not be able to see any previous versions.\n\u003e For example, [actions/checkout@v2](https://github.com/actions/checkout/tree/v2.3.4#checkout-v2) clones repositories with `fetch-depth: 1` per default.\n\nAt the moment, no VCS other than Git is supported. If you need support for another VCS, please open an issue or submit a PR.\n\n## Copyright \u0026 License\n\nCycloneDX GoMod is Copyright (c) OWASP Foundation. All Rights Reserved.\n\nPermission to modify and redistribute is granted under the terms of the Apache 2.0 license.  \nSee the [LICENSE](./LICENSE) file for the full license.\n\n## Contributing\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/CycloneDX/cyclonedx-gomod)\n\nPull requests are welcome. But please read the\n[CycloneDX contributing guidelines](https://github.com/CycloneDX/.github/blob/master/CONTRIBUTING.md) first.\n\nIt is generally expected that pull requests will include relevant tests. Tests are automatically run against all\nsupported Go versions for every pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyclonedx%2Fcyclonedx-gomod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyclonedx%2Fcyclonedx-gomod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyclonedx%2Fcyclonedx-gomod/lists"}