diff --git a/README.md b/README.md index 81dbd804dac4382b168a58099616399fbf8d0403..a3e6f9bb71c3b991aa0edabb13d78b788bcf0dd3 100644 --- a/README.md +++ b/README.md @@ -1,171 +1,163 @@ # SBOM-TOOL -English | [简体中文](./README_zh.md) - -SBOM-TOOL is a ctl tool that generates software bill of materials (SBOM) for software projects through source code warehouse, code fingerprint, construction environment, artifact information, artifact content, dependency construction and other dimensional information. -## Feature - -### Information collection -- Collect source code engineering information, including warehouse address, version information, etc. -- Collect and generate code fingerprints -- Collecting engineering construction depends on environmental information -- Collect the dependent components built by the project -- Collect the final artifact package information -- Collect artifact content information, including file name type, check code, etc. -### SBOM document -- Assemble SBOM documents -- Standard format conversion，support domestic XSPDX, SPDX and other specifications, support JSON, TagValue and other formats -- Canonical format check，support domestic XSPDX, SPDX and other specifications, support JSON, TagValue and other formats - -## Code fingerprint generation ability - -| language | Is it supported| -|---------------|---------------------| -| `C/C++` | yes | -| `Java` | yes | -| `C#` | yes | -| `Dart` | yes | -| `Golang` | yes | -| `Javascript` | yes | -| `Objective-C` | yes | -| `Php` | yes | -| `Python` | yes | -| `Ruby` | yes | -| `Rust` | yes | -| `Swift` | yes | -| `Lua` | yes | - - -## Dependent packet scanning capability -Configuration file parsing and binary package parsing related to the following programming languages are now supported, and more programming languages will be supported step by step. - -| Package Type | Package Manager | Parsing file | support dependency graph | -|-------------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -| `maven` | [Maven](https://maven.apache.org) | | yes | -| `maven` | [Gradle](https://gradle.org) | | yes | -| `conan` | [Conan](https://conan.io) | | yes | -| `npm` | [NPM](https://www.npmjs.com) | | no | -| `npm` | [Yarn](https://yarnpkg.com) | | yes | -| `npm` | [PNPM](https://pnpm.io/) | | yes | -| `golang` | [Go Module](https://go.dev/ref/mod) | | yes | -| `golang` | [Glide](https://github.com/Masterminds/glide) | | no | -| `golang` | [GoDep](https://github.com/tools/godep) | | no | -| `golang` | [Dep](https://github.com/golang/dep) | | no | -| `golang` | [GVT](https://github.com/FiloSottile/gvt) | | no | -| `pypi` | [PIP](https://pip.pypa.io) | | yes | -| `pypi` | [Poetry](https://python-poetry.org) | | yes | -| `conda` | [Conda](https://conda.io) | | no | -| `composer` | [Composer](https://getcomposer.org) | | no | -| `cargo` | [Cargo](https://doc.rust-lang.org/cargo) | | yes | -| `carthage` | [Carthage](https://github.com/Carthage/Carthage) | | no | -| `swift` | [SwiftPM](https://www.swift.org/package-manager) | | no | -| `cocoapods` | [Cocoapods](https://cocoapods.org) | | yes | -| `gem` | [Gem](https://rubygems.org) | | yes | -| `nuget` | [NuGet](https://www.nuget.org) | | yes | -| `pub` | [Pub](https://pub.dev) | | yes | -| `rpm` | [RPM](https://rpm-packaging-guide.github.io) | | no | -| `deb` | [DEB](https://deb.debian.org/debian) | | no | -| `lua` | [LuaRocks](https://luarocks.org) | | no | -| `bower` | [Bower](https://bower.io) | | no | - - - -## Architecture -![SBOM-TOOL architecture](./docs/img/arch.png) - - - -## Installation -1. Download source code compilation(`go 1.18` or above is required) - ```shell - git clone git@gitee.com:JD-opensource/sbom-tool.git - cd sbom-tool - make + +## 功能特性 + +### 信息采集 +- 收集源代码信息 +- 采集依赖包 +- 制品信息采集 + +### SBOM文档 +- 生成SBOM文档 +- 组装SBOM文档 +- 转换SBOM文档格式 +- 验证SBOM文档格式 +- 修改SBOM文档属性 + +### 代码指纹生成能力 +- 支持多种语言的代码指纹生成，包括Java、C++、Dart、Go、JavaScript、PHP、Python、Ruby、Rust、Swift等 +- 支持计算代码指纹之间的距离，用于代码相似性分析 + +### 依赖包扫描能力 +- 支持多种语言的依赖包扫描，包括Maven、Gradle、npm、Yarn、Cargo、Conan、Conda、Golang、Cocoapods、Composer、Nuget、Pub、Pypi、LuaRocks、Bower等 + +## 软件架构 +![SBOM-TOOL整体架构](docs/img/arch.png) + +## 下载安装 + +### 使用源码编译安装 +1. 安装Go 1.18及以上版本 +2. 克隆仓库： + ```bash + git clone https://gitee.com/JD-opensource/sbom-tool.git ``` - Generate program binaries for various system architectures by default - - Linux X86_64：sbom-tool-linux-amd64 - - Linux arm64：sbom-tool-linux-arm64 - - Windows X86_64：sbom-tool-windows-amd64.exe - - Windows arm64：sbom-tool-windows-arm64.exe - - MacOS amd64: sbom-tool-darwin-amd64 - - MacOS arm64: sbom-tool-darwin-arm64 - -Or install via go install - ```shell - go install gitee.com/JD-opensource/sbom-tool/cmd/sbom-tool@latest +3. 编译： + ```bash + cd sbom-tool + make build ``` -Or install via downloading the binary: [SBOM-TOOL Releases](https://gitee.com/JD-opensource/sbom-tool/releases) -## Subcommands - - -| subcommand | function | -|---------------|--------------------| -| `help` | Help about any command | -| `artifact` | collect artifact information | -| `assembly` | assembly sbom document from document segments | -| `completion` | Generate the autocompletion script for the specified shell | -| `convert` | convert sbom document format | -| `env` | build environment info| -| `fingerprint` | generate code fingerprint | -| `generate` | generate sbom document | -| `package` | collect package dependencies | -| `source` | collect source code information | -| `validate` | validate sbom document format | -| `info` | get tool introduction information | -| `modify` | modify sbom document properties| - -## Parameter description - -|Parameters | Short parameter | describe | Use exampl | -| --------- |------|-----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------| -| `--log-level ` | | log level (`debug`、`info`、`warn`、`error`) | `--log-level info` | -| `--log-path ` | | log output path (default "$home/sbom-tool/sbom-tool.log") | `--log-path /tmp/sbom.log` | -| `--quiet ` | `-q` | no console output | `--quiet`
`-q` | -| `--ignore-dirs` | | dirs to ignore, skip all dot dirs, split by comma. sample: node_modules,logs | `--ignore-dirs log,logs` | -| `--language` | `-l` | programming language (Currently supported:`java`，`cpp`)(Default “*”) | `--language java`
`-l cpp` | -| `--parallelism` | `-m` | number of parallelism(Default `8`) | `--parallelism 4`
`-m 9` | -| `--output` | `-o` | output file，The result file is produced in the current directory by default. | `--output /tmp/sbom.json` | -| `--src` | `-s` | project source directory(use project root if empty) (default ".") | `--src /tmp/sbomtool/src/` | -| `--path` | `-p` | Specify the project project home directory; the assemble subcommand is used to specify the temporary document path for each phase | `--path /tmp/sbomtool/` | -| `--dist ` | `-d` | distribution directory (default ".") | `--dist /tmp/sbomtool/bin/` | -| `--format` | `-f` | Specify SBOM document format(Currently supported:`xspdx-json`、`spdx-json`、`spdx-tagvalue` )(Default `spdx-json`) | `--format xspdx-json`
`-f spdx-json` | -| `--input` | `-i` | Specify the SBOM document as input | `--input /tmp/sbom.jsom` | - -## SBOM Document specification and format - -| specification | format | SBOM document format | status | -|:--------------|:-----------|:-----------------|:----| -| `XSPDX` | `JSON` | `xspdx-json` | Supported | -| `SPDX` | `JSON` | `spdx-json` | Supported | -| `SPDX` | `TagValue` | `spdx-tagvalue` | Supported | -## User guide -Generate code fingerprints only based on the source code path - -```shell -sbom-tool fingerprint -m 4 -s ${src_path} -o fingerprint.json --ignore-dirs .git -``` -Generate an SBOM document and specify the format +### 使用Makefile构建 +```bash +make build +``` -```shell -sbom-tool generate -m 4 -p ${project_path} -s ${src_path} -d ${dist_path} -o sbom.spdx.json -f spdx-json --ignore-dirs .git -n ${name} -v ${version} -u ${supplier} -b ${namespace} +## 子命令说明 + +| 子命令 | 功能 | +|--------|------| +| `artifact` | 收集制品信息 | +| `assembly` | 从文档片段组装SBOM文档 | +| `completion` | 为指定shell生成自动补全脚本 | +| `convert` | 转换SBOM文档格式 | +| `env` | 收集构建环境信息 | +| `fingerprint` | 生成代码指纹 | +| `generate` | 生成SBOM文档 | +| `package` | 收集依赖包 | +| `source` | 收集源代码信息 | + +## 参数说明 + +### 全局参数 +| 参数 | 简写 | 说明 | 示例 | +|------|------|------|------| +| `--collectors` | `-c` | 启用的包收集器（默认为`*`） | `--collectors maven,npm` | +| `--dist` | `-d` | 制品目录（默认为`./dist`） | `--dist /path/to/dist` | +| `--extract` | `-x` | 提取文件（仅适用于单个zip/rpm/deb文件） | `--extract` | +| `--format` | `-f` | SBOM文档格式（默认为`spdx-json`） | `--format spdx-json` | +| `--input` | `-i` | 指定输入的SBOM文档 | `--input /path/to/sbom` | +| `--output` | `-o` | 输出SBOM文件 | `--output sbom.spdx.json` | +| `--path` | `-p` | 项目根路径（默认为`.`） | `--path /path/to/project` | +| `--parallelism` | `-m` | 并行度（默认为8） | `--parallelism 4` | +| `--language` | `-l` | 指定语言（示例：java,cpp）（默认为`*`） | `--language java` | +| `--name` | `-n` | 包名 | `--name app` | +| `--namespace` | `-b` | 文档命名空间基础URI | `--namespace https://example.com/sbom` | +| `--skip` | | 跳过某些阶段（source/package/artifact） | `--skip source` | +| `--src` | `-s` | 项目源代码目录（默认为`.`） | `--src /path/to/source` | +| `--supplier` | `-u` | 制品供应商 | `--supplier company` | + +### 子命令特定参数 +#### `artifact` +- `--artifact` - 收集制品信息 + +#### `assembly` +- `--path` - 指定各阶段临时文档路径 + +#### `convert` +- `--original` - 指定原始SBOM文档格式 +- `--format` - 指定目标SBOM文档格式 + +#### `generate` +- `--ignore-dirs` - 忽略的目录（默认忽略所有点开头的目录） + +#### `package` +- `--collectors` - 指定启用的包收集器 + +#### `source` +- `--ignore-dirs` - 忽略的源代码目录 + +## SBOM文档规范与格式 + +| 规范 | 格式 | SBOM文档格式 | 是否支持 | +|------|------|----------------|---------| +| `XSPDX` | `JSON` | `xspdx-json` | 已支持 | +| `SPDX` | `JSON` | `spdx-json` | 已支持 | +| `SPDX` | `TagValue` | `spdx-tagvalue` | 已支持 | + +## 使用示例 + +### 生成SBOM文档 +```bash +sbom-tool generate -m 4 -p /path/to/project -s /path/to/source -d /path/to/dist -l java -o sbom.spdx.json -f spdx-json --ignore-dirs .git -n app -v 1.0 -u company -b https://example.com/sbom/xxx ``` -Get tool introduction information +### 转换SBOM文档格式 +```bash +sbom-tool convert -i /path/to/sbom -g xspdx-json -f spdx-json -o sbom.spdx.json +``` -```shell -sbom-tool info +### 验证SBOM文档格式 +```bash +sbom-tool validate -i /path/to/sbom -f spdx-json -o result.json ``` -See [document](docs/en-US/user-guide.md) for details. +### 修改SBOM文档属性 +```bash +sbom-tool modify -i /path/to/sbom -f spdx-json -o sbom.spdx.json +``` -## Development guide -See for details [Development guide documentation](docs/en-US/development-guide.md) +### 收集源代码信息 +```bash +sbom-tool source -m 4 -s /path/to/source -l java -o source.json --output-mode singlefile --ignore-dirs .git +``` -## Problem feedback & contact us -If you encounter problems in use, you are welcome to submit ISSUE to us. +### 收集依赖包 +```bash +sbom-tool package -m 4 -p /path/to/project -c maven,npm -o package.json +``` -## How to Contribute -SBOM-TOOL is a open source software component analysis tool, look forward to your contribution. +### 收集制品信息 +```bash +sbom-tool artifact -m 4 -d /path/to/dist -o artifact.json -n app -v 1.0 -u company +``` -## License -This project is licensed under **MulanPSL2** - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +## 开发指南 +- 开发环境：Go 1.18+ +- 开发工具：cobra、viper、zap +- 代码规范：遵循Go语言编码规范 +- 日志输出：使用zap日志库 +- 测试要求：单元测试覆盖率不低于80% + +## 问题反馈&联系我们 +- 问题反馈请提交Issue +- 联系邮箱：tim@demo.com + +## 如何贡献 +1. Fork仓库 +2. 创建新分支 +3. 提交代码 +4. 创建Pull Request + +## 许可证 +该项目遵循[Mulan PSL v2](LICENSE)开源协议。 \ No newline at end of file