Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
Sign-off-by: Sharan Gowda <[email protected]>
Updated the Readme file based on my understanding.
  • Loading branch information
@sharangowd
sharangowd authored Jul 16, 2021
1 parent 3248129 commit f9fb4c1
Showing 1 changed file with 84 additions and 60 deletions.
144 changes: 84 additions & 60 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
`spdx-sbom-generator`tool to help those in the community that want to generate SPDX Software Bill of Materials (SBOMs) with current package managers. It has a command line Interface (CLI) that lets you generate SBOM information, including components, licenses, copyrights, and security references of your software using SPDX v2.2 specification and aligning with the current known minimum elements from NTIA. It automatically determines which package managers or build systems are actually being used by the software.

`spdx-sbom-generator`is supporting the following package managers:

* GoMod (go)
* Cargo (Rust)
* Composer (PHP)
Expand All @@ -19,17 +19,33 @@
* Pipenv (Python)
* Gems (Ruby)

## Installation:
## Installation

You can download the following binaries and copy paste the application or binary in your cloned project on your local to generate the SPDX SBOM file. You need to execute the following in the command line tool:

```
./spdx-sbom-generator
```

The following binaries are available to download for various operating system:

* [macOS](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.7/spdx-sbom-generator-v0.0.7-darwin-amd64.tar.gz)
* [Linux (x64)](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.7/spdx-sbom-generator-v0.0.7-linux-amd64.tar.gz)
* [Windows (x64)](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.7/spdx-sbom-generator-v0.0.7-windows-amd64.zip)
* [Windows (x86)](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.7/spdx-sbom-generator-v0.0.7-windows-386.zip)
* [MacOS](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.10/spdx-sbom-generator-v0.0.10-darwin-amd64.tar.gz)
* [Linux (x64)](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.10/spdx-sbom-generator-v0.0.10-linux-amd64.tar.gz)
* [Windows (x64)](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.10/spdx-sbom-generator-v0.0.10-windows-amd64.zip)
* [Windows (x86)](https://github.com/spdx/spdx-sbom-generator/releases/download/v0.0.10/spdx-sbom-generator-v0.0.10-windows-386.zip)

***Note***: The `spdx-sbom-generator` CLI is under development. You may expect some breakages and stability issues with the current release. A stable version is under development and will be available to the open source community in the upcoming beta release.

## Available command Options
Run help:

Use the below command to view different options or flags related to SPDX SBOM generator:

```
./spdx-sbom-generator -h
```

The following different commands are listed when you use the help in the SPDX SBOM generator:

```BASH
./spdx-sbom-generator -h

Expand All @@ -49,6 +65,8 @@ Flags:

### Output Options

The following list supports various formats in which you can generate the SPDX SBOM file:

- `spdx` (Default format)

- `JSON` (In progress)
Expand All @@ -57,7 +75,8 @@ Flags:



Command output sample option:
Use the below command to generate the SPDX SBOM file in SPDX format:

```BASH
./spdx-sbom-generator -o /out/spdx/
```
Expand Down Expand Up @@ -131,6 +150,7 @@ $ docker run -it --rm \
```

## Data Contract

The interface requires the following functions:

```GO
Expand Down Expand Up @@ -182,26 +202,27 @@ type PluginMetadata struct {
### How to Generate Module Values
* `CheckSum`: We have built an internal method that calculates CheckSum for a given content (in bytes) using algorithm that is defined on `models.CheckSum`.
You now have an option to provide `Content` field for `models.CheckSum{}` and CheckSum will calculate automatically, but if you want to calculate CheckSum on your own
you still can provide `Value` field for `models.CheckSum{}`.
You now have an option to provide `Content` field for `models.CheckSum{}` and CheckSum will calculate automatically, but if you want to calculate CheckSum on your own
you still can provide `Value` field for `models.CheckSum{}`.
Also, you can generate a manifest from a given directory tree using utility/helper method `BuildManifestContent`, and that is what is used for gomod plugin as `Content` value.
### Interface Definitions
The following list provides the interface definitions:
* `GetVersion`: returns version of current project platform (development language) version i.e: go version
* `GetVersion`: Returns version of current project platform (development language) version i.e: go version
**Input**: None
**Input**: None
**Output**: Version in string format and error (null in case of successful process)
**Output**: version in string format and error (null in case of successful process)
* `GetMetadata`: Returns metadata of identify ecosystem pluging
* `GetMetadata`: returns metadata of identify ecosystem pluging
**Input**: None
**Input**: None
**Output**: Plugin metadata
**Output**: plugin metadata
```GO
PluginMetadata{
Name: "Go Modules",
Expand All @@ -210,48 +231,48 @@ PluginMetadata{
ModulePath: []string{"vendor"},
}
```
* `SetRootModule`: sets root package information base on path given
**Input**: The working directory to read the package from
* `SetRootModule`: Sets root package information base on path given
**Input**: The working directory to read the package from
**Output**: returns error
**Output**: Returns error
* `GetRootModule`: returns root package information base on path given
* `GetRootModule`: Returns root package information base on path given
**Input**: The working directory to read the package from
**Input**: The working directory to read the package from
**Output**: returns the Package Information of the root Module
**Output**: Returns the Package Information of the root Module
* `ListUsedModules`: fetches and lists all packages required by the project in the given project directory, this is a plain list of all used modules (no nested or tree view)
* `ListUsedModules`: Fetches and lists all packages required by the project in the given project directory, this is a plain list of all used modules (no nested or tree view)
**Input**: The working directory to read the package from
**Input**: The working directory to read the package from
**Output**: returns the Package Information of the root Module, and its dependencies in flatten format
**Output**: Returns the Package Information of the root Module, and its dependencies in flatten format
* `ListModulesWithDeps`: fetches and lists all packages (root and direct dependencies) required by the project in the given project directory (side-by-side), this is a one level only list of all used modules, and each with its direct dependency only (similar output to `ListUsedModules` but with direct dependency only)
* `ListModulesWithDeps`: Fetches and lists all packages (root and direct dependencies) required by the project in the given project directory (side-by-side), this is a one level only list of all used modules, and each with its direct dependency only (similar output to `ListUsedModules` but with direct dependency only)
**Input**: The working directory to read the package from
**Input**: The working directory to read the package from
**Output**: returns the Package Information of the root Module, and its direct dependencies
**Output**: Returns the Package Information of the root Module, and its direct dependencies
* `IsValid`: check if the project dependency file provided in the contract exists
* `IsValid`: Check if the project dependency file provided in the contract exists
**Input**: The working directory to read the package from
**Input**: The working directory to read the package from
**Output**: True or False
**Output**: True or False
* `HasModulesInstalled`: check whether the current project(based on given path) has the dependent packages installed
* `HasModulesInstalled`: Check whether the current project(based on given path) has the dependent packages installed
**Input**: The working directory to read the package from
**Input**: The working directory to read the package from
**Output**: True or False
**Output**: True or False
#### Module Structure JSON Example
The sample module structure JSON Code snippet is provided in the following code snippet:
```JSON

{
"Version": "v0.0.1-2019.2.3",
"Name": "honnef.co/go/tools",
Expand Down Expand Up @@ -311,17 +332,18 @@ For a more complete JSON example look at [modules.json](./examples/modules.json)
The following list provide the utility methods:
* `BuildManifestContent` walks through a given directory tree, and generates a content based on file paths
* `BuildManifestContent` : Walks through a given directory tree, and generates a content based on file paths
**Input**: Directory to walk through
**Input**: Directory to walk through
**Output**: Directory tree in bytes
**Output**: directory tree in bytes
* `GetLicenses`: Returns the detected license object
* `GetLicenses`: returns the detected license object
**Input**: The working directory of the package licenses
**Input**: The working directory of the package licenses
**Output**: The package license object
**Output**: The package license object
```GO
type License struct {
ID string
Expand All @@ -334,9 +356,9 @@ type License struct {
* `LicenseSPDXExists`: Check if the package license is a valid SPDX reference
**Input**: The package license
**Input**: The package license
**Output**: True or False
**Output**: True or False
### How to Register a New Plugin
Expand All @@ -352,23 +374,23 @@ To register for a new plugin, perform the following steps:
```
/pkg/modules/npm

```
3. Create a Handler file, for example: `handler.go`, and follow Data Contract section above. Define package name, and import section as explained in the following code snippet:
```
package npm

import (
"path/filepath"

"github.com/spdx/spdx-sbom-generator/pkg/helper"
"github.com/spdx/spdx-sbom-generator/pkg/models"
)

// rest of the file below

```
Expand All @@ -379,7 +401,7 @@ To register for a new plugin, perform the following steps:
type npm struct {
metadata models.PluginMetadata
}

```
Expand All @@ -398,7 +420,7 @@ To register for a new plugin, perform the following steps:
},
}
}

```
Expand All @@ -410,7 +432,7 @@ To register for a new plugin, perform the following steps:
func (m *npm) GetMetadata() models.PluginMetadata {
return m.metadata
}

// IsValid ...
func (m *npm) IsValid(path string) bool {
for i := range m.metadata.Manifest {
Expand All @@ -420,7 +442,7 @@ To register for a new plugin, perform the following steps:
}
return false
}

// HasModulesInstalled ...
func (m *npm) HasModulesInstalled(path string) error {
for i := range m.metadata.ModulePath {
Expand All @@ -430,37 +452,37 @@ To register for a new plugin, perform the following steps:
}
return errDependenciesNotFound
}

// GetVersion ...
func (m *npm) GetVersion() (string, error) {
output, err := exec.Command("npm", "--version").Output()
if err != nil {
return "", err
}

return string(output), nil
}

// SetRootModule ...
func (m *npm) SetRootModule(path string) error {
return nil
}

// GetRootModule ...
func (m *npm) GetRootModule(path string) (*models.Module, error) {
return nil, nil
}

// ListUsedModules...
func (m *npm) ListUsedModules(path string) ([]models.Module, error) {
return nil, nil
}

// ListModulesWithDeps ...
func (m *npm) ListModulesWithDeps(path string) ([]models.Module, error) {
return nil, nil
}

```
Expand All @@ -474,12 +496,13 @@ To register for a new plugin, perform the following steps:
npm.New(),
)
}

```
## How to Work With SPDX SBOM Generator
A **Makefile** for the `spdx-sbom-generator` is described below with ability to run, test, lint, and build the project binary for different platforms (Linux, Mac, and Windows).
Perform the following steps to work with SPDX SBOM Generator:
Expand Down Expand Up @@ -524,6 +547,7 @@ Perform the following steps to work with SPDX SBOM Generator:
Licensing
---------
This project’s source code is licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/spdx/spdx-sbom-generator/tree/main/LICENSES) for the full license text.
## Additional Information
Expand Down

0 comments on commit f9fb4c1

Please sign in to comment.