Updates to documentation (#482)

Co-authored-by: Sebastian Gomez <segomez@microsoft.com>
microsoft · Jan 17, 2024 · 206dbb6 · 206dbb6
1 parent d251a5f
commit 206dbb6
Show file tree

Hide file tree

Showing 3 changed files with 195 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -102,6 +102,22 @@ Each SBOM has a unique namespace that uniquely identifies the SBOM, we generate
 
 A more detailed list of available CLI arguments for the tool can be found [here](docs/sbom-tool-arguments.md)
 
+### SBOM Validation
+
+With an SBOM file in hand, use the tool to validate the output file with the command:
+
+```
+sbom-tool validate -b <drop path> -o <output path> -mi SPDX:2.2
+```
+
+This sample command provides the minimum mandatory arguments required to validate an SBOM:
+     `-b` should be the path same path used to generate the SBOM file.
+     In this scenario, the tool will default to searching for an SBOM at the `<drop path>\_manifest\spdx_2.2\manifest.spdx.json` path. 
+     `-o` is the output path where the tool should write the results to.
+     `-mi` is the ManifestInfo, which provides the user's desired name and version of the manifest format.
+
+Currently only SPDX2.2 is supported.
+
 ## Integrating SBOM tool to your CI/CD pipelines.
 
 You can follow these guides to integrate the SBOM tool into your CI/CD pipelines 

diff --git a/docs/building-from-source.md b/docs/building-from-source.md
@@ -1,9 +1,9 @@
 # Building the SBOM tool from source code.
 
-The SBOM tool is a cross-platform, C#-based tool compiled using the  Microsoft .NET 6 cross-platform, open-source developer platform. Follow the instructions provided which will guide the user in building the sbom tool from the source file.
+The SBOM tool is a cross-platform, C#-based tool compiled using the  Microsoft .NET 8 cross-platform, open-source developer platform. Follow the instructions provided which will guide the user in building the sbom tool from the source file.
 
 ## Prerequisites
-* Download and install [Dotnet SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) version 6.0.400 or later.
+* Download and install [Dotnet SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) version 8.0.100 or later.
 * Clone this GitHub repo (see steps to clone repo [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)).
 * A text editor or integrated development environment (IDE) such as [Visual Studio Code](https://code.visualstudio.com) or [Visual Studio](https://visualstudio.microsoft.com).
 
@@ -42,7 +42,38 @@ dotnet build
 Users can run the sbom tool using this command which contains the minimum required set of paramaters:
 
 ```
-dotnet run --project src/Microsoft.Sbom.Tool generate -- -b <drop path> -bc <build components path> -pn <package name> -pv <package version> -ps <company name> -nsb <namespace uri base>
+dotnet run --project src/Microsoft.Sbom.Tool generate -b <drop path> -bc <build components path> -pn <package name> -pv <package version> -ps <company name> -nsb <namespace uri base>
+```
+
+## Building on ARM based devices running OSX
+
+The sbom-tool targets both .NET 6 and .NET 8 therefore it is possible to produce binaries for both. We have seen issues when attempting to run the tool using the .NET 6 binaries ([#223](https://github.com/microsoft/sbom-tool/issues/223)) so for these scenarios we recommend targeting .NET 8. You can do this by following these steps:
+
+The following command will produce a dll that can be executed on ARM based devices running OSX and can be modified to suit your needs:
+
+```
+ dotnet publish src/Microsoft.Sbom.Tool/Microsoft.Sbom.Tool.csproj --configuration Release --output bin --runtime osx-arm64 -p:TargetFramework=net8.0 -p:SelfContained=true -p:OFFICIAL_BUILD=true -p:MinVerVersionOverride=1.8.0 -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:IncludeAllContentForSelfExtract=true -p:DebugType=None -p:DebugSymbols=false
+```
+
+After running this command you can execute the tool like this:
+
+```
+./bin/Microsoft.Sbom.Tool generate -b ~/tmp/sbom-tool/ -bc ~/tmp/sbom-tool/ -pn TestProject -pv 1.2.3 -ps Microsoft
+```
+
+
+## Using Dotnet Publish
+
+Because of our multi-targeting, a target framework must be specified when using the dotnet publish command:
+
+Either
+
+```
+dotnet publish -f net8.0
+```
+Or
+```
+dotnet publish -f net6.0
 ```
 
 ## Building using Codespaces

diff --git a/docs/feature-overview.md b/docs/feature-overview.md
@@ -0,0 +1,145 @@
+# Feature Overview
+
+## Files Section
+The files section of the SBOM is generated by traversing and listing all the directories and files found the on the `BuildDropPath` provided to the tool. The tool uses this list of files and generates an SPDXID, a SHA1 hash, and a SHA256 hash. Here's an example:
+
+```
+"files": [
+    {
+      "fileName": "./sbom-tool-win-x64.exe",
+      "SPDXID": "SPDXRef-File--sbom-tool-win-x64.exe-E55F25E239D8D3572D75D5CDC5CA24899FD4993F",
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "56624d8ab67ac0e323bcac0ae1ec0656f1721c6bb60640ecf9b30e861062aad5"
+        },
+        {
+          "algorithm": "SHA1",
+          "checksumValue": "e55f25e239d8d3572d75d5cdc5ca24899fd4993f"
+        }
+      ],
+      "licenseConcluded": "NOASSERTION",
+      "licenseInfoInFiles": [
+        "NOASSERTION"
+      ],
+      "copyrightText": "NOASSERTION"
+    }
+  ]
+```
+
+## Packages Section
+
+The packages section of the generated SBOM will use the [component detection](https://github.com/microsoft/component-detection) libraries to scan the project's `BuildComponentPath` and determine what packages are being used in the project. The sbom-tool will attempt to add additional information to this section wherever possible either through the [ClearlyDefinedApi](https://github.com/clearlydefined/clearlydefined) or via our own custom implementations (Note: At the time of writing, in order to enable populating these fields both the `-pm` and `-li` arguments must be set to `true`). This table displays the ecosystems and additional properties that the tool makes an attempt to populate.
+
+Note: These are not the only entries found in the packages section. To view a full list of properties of an individual package please visit our sample document [here](https://github.com/microsoft/sbom-tool/blob/main/samples/manifest.spdx.json).
+
+| Ecosystem | Detection Mechanism | Requirements | License Concluded (Via ClearlyDefinedApi) | License Declared | Supplier
+| - | - | - | - | - | - |
+| Cargo | <ul><li>Cargo.lock (v1, v2, v3)</li></ul> | - | ✔ | ✔ (Via RustCli detector) | ✔ |
+| Ruby | <ul><li>gemfile.lock</li></ul> | - | ✔ | ✔ | ✔ |
+| Pip (Python) | <ul><li>setup.py</li><li>requirements.txt</li><li>*setup=distutils.core.run_setup({setup.py}); setup.install_requires*</li><li>dist package METADATA file</li></ul> | <ul><li>Python 2 or Python 3</li><li>Internet connection</li></ul> | ✔ | ✔ | ✔ |
+| Maven | <ul><li>pom.xml</li></ul> | <ul><li>Maven</li></ul> | ✔  | ✔ | ✔ |
+| NPM | <ul><li>package.json</li></ul> | - | ✔ | ✔ | ✔ |
+| NuGet | <ul><li>project.assets.json</li><li>*.nupkg</li><li>*.nuspec</li><li>packages.config</li><li>nuget.config</li></ul> | - | ✔ | ✔ | ✔ |
+| Linux (Debian, Alpine, Rhel, Centos, Fedora, Ubuntu)| <ul><li>(via [syft](https://github.com/anchore/syft))</li></ul> | - | ✔ | - | ✔ |
+| CocoaPods | <ul><li>podfile.lock</li></ul> | - | ✔ | - | - |
+| Conda (Python) | <ul><li>conda-lock.yml</li><li>*.conda-lock.yml</li></ul> | - | - | - | - |
+| Gradle | <ul><li>*.lockfile</li></ul> | <ul><li>Gradle 7 or prior using [Single File lock](https://docs.gradle.org/6.8.1/userguide/dependency_locking.html#single_lock_file_per_project)</li></ul> | - | - | - |
+| Go | <ul><li>*go list -m -json all*</li><li>*go mod graph* (edge information only)</li></ul>Fallback</br><ul><li>go.mod</li><li>go.sum</li></ul> | <ul><li>Go 1.11+ (will fallback if not present)</li></ul> | - | - | - |
+| Yarn (v1, v2) | <ul><li>package.json</li><li>yarn.lock</li></ul> | - | - | - | - |
+| Pnpm | <ul><li>shrinkwrap.yaml</li><li>pnpm-lock.yaml</li></ul> | - | - | - | - |
+| Poetry (Python) | <ul><li>poetry.lock</li><ul> | - | - | - | - |
+
+Example:
+
+```
+"packages": [
+    {
+      "name": "Microsoft.VisualStudio.Threading.Analyzers",
+      "SPDXID": "SPDXRef-Package-CCB741BD164B5B2F9771AD784B281D62BDB0E0707EE703E76AF22BFFB4503941",
+      "downloadLocation": "NOASSERTION",
+      "filesAnalyzed": false,
+      "licenseConcluded": "MIT",
+      "licenseDeclared": "MIT",
+      "copyrightText": "NOASSERTION",
+      "versionInfo": "17.7.30",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:nuget/Microsoft.VisualStudio.Threading.Analyzers@17.7.30"
+        }
+      ],
+      "supplier": "Organization: Microsoft"
+    }
+]
+```
+
+
+## External References Section
+
+When the sbom-tool detects an SPDX2.2 SBOM inside of the project it's currently trying to generate an SBOM for, it will list it in the files section as well as add an entry to the `ExternalDocumentRefs` section of the SBOM. Here's an example:
+
+```
+ "files": [
+    {
+      "fileName": "./manifest.spdx.json",
+      "SPDXID": "SPDXRef-File--manifest.spdx.json-9E563530C733C814FC04FF5C61D8DC9FB4FD29CB",
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "63789f7d621728cb197dcc5655d7b18ab35f825b596496e633b61291cfa00f4b"
+        },
+        {
+          "algorithm": "SHA1",
+          "checksumValue": "9e563530c733c814fc04ff5c61d8dc9fb4fd29cb"
+        }
+      ],
+      "licenseConcluded": "NOASSERTION",
+      "licenseInfoInFiles": [
+        "NOASSERTION"
+      ],
+      "copyrightText": "NOASSERTION",
+      "fileTypes": [
+        "SPDX"
+      ]
+    },
+ ]
+```
+
+```
+"externalDocumentRefs": [
+    {
+      "externalDocumentId": "DocumentRef-TEST.GIT-bd801c3b7553a08b6874d6bc129203c5a8a95a04-f3bca9cb-67f5-1320-d17e-188a244fc472-1.0-9e563530c733c814fc04ff5c61d8dc9fb4fd29cb",
+      "spdxDocument": "https://sbom.microsoft/TEST.GIT/bd801c3b7553a08b6874d6bc129203c5a8a95a04/f3bca9cb-67f5-1320-d17e-188a244fc472/1.0/fa0d13e3-0136-4cc8-af85-622c04063a0f",
+      "checksum": {
+        "algorithm": "SHA1",
+        "checksumValue": "9e563530c733c814fc04ff5c61d8dc9fb4fd29cb"
+      }
+    }
+  ]
+```
+
+## Additional Properties
+
+At the end of the SBOM you can find some additional properties that can be used as metadata to describe the SBOM itself. Here's an example of what these properties look like:
+
+```
+ "spdxVersion": "SPDX-2.2",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "test 1",
+  "documentNamespace": "https://spdx.org/spdxdocs/sbom-tool-2.2.3-preview.0.1-d05da109-fdf8-479e-8a40-9efacd439647/test/1/c5lYxP0T1EyYvj3i5lru3w",
+  "creationInfo": {
+    "created": "2024-01-16T20:29:58Z",
+    "creators": [
+      "Organization: test",
+      "Tool: Microsoft.SBOMTool-2.2.3-preview.0.1"
+    ]
+  },
+  "documentDescribes": [
+    "SPDXRef-RootPackage"
+  ]
+```
+
+Properties such as the organization or name are supplied via arguments to the tool. The full list of arguments can be found [here](https://github.com/microsoft/sbom-tool/blob/main/docs/sbom-tool-arguments.md).