Merge pull request #226 from bact/patch-1

Include FSCT3 information in README
spdx · Dec 18, 2024 · 40b68cc · 40b68cc
2 parents 9304036 + 29f6a53
commit 40b68cc
Showing 1 changed file with 81 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,23 @@
+# NTIA Conformance Checker
+
 [![Build Status](https://github.com/spdx/ntia-conformance-checker/workflows/build/badge.svg)](https://github.com/spdx/ntia-conformance-checker/actions)
 ![CodeQL](https://github.com/spdx/ntia-conformance-checker/actions/workflows/codeql.yml/badge.svg)
 [![PyPI version](https://badge.fury.io/py/ntia-conformance-checker.svg)](https://badge.fury.io/py/ntia-conformance-checker)
 [![Pylint Version](https://img.shields.io/badge/linting-pylint-yellow)](https://badge.fury.io/py/ntia-conformance-checker)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/spdx/ntia-conformance-checker/badge)](https://scorecard.dev/viewer/?uri=github.com/spdx/ntia-conformance-checker)
 
-# NTIA Conformance Checker
+This tool determines whether a [SPDX](https://spdx.dev/) software bill of
+materials (SBOM) document contains informational items as required by a
+certain specification.
 
-This tool determines whether a [SPDX](https://spdx.dev/) software bill of materials (SBOM) document contains the National Telecommunications and Information Administration (NTIA) ["minimum elements."](https://www.ntia.doc.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) The mapping of the NTIA elements required data fields to the SPDX specification can be found [here](https://spdx.github.io/spdx-spec/v2.3/how-to-use/#k22-mapping-ntia-minimum-elements-to-spdx-fields).
+Currently, the only supported specification is the
+2021 National Telecommunications and Information Administration (NTIA)
+["minimum elements."][ntia]
+The mapping of the NTIA elements required data fields to the SPDX 2.3
+specification can be found [here][ntia-spdx23].
 
 The minimum elements include:
+
 - Supplier Name
 - Component Name
 - Version of the Component
@@ -17,90 +26,130 @@ The minimum elements include:
 - Author of SBOM Data
 - Timestamp
 
-As defined by the NTIA, the minimum elements are "the essential pieces that support basic SBOM functionality and will serve as the foundation for an evolving approach to software transparency."
+As defined by the NTIA, the minimum elements are
+"the essential pieces that support basic SBOM functionality and will serve as
+the foundation for an evolving approach to software transparency."
+
+Checking the conformance with 2024 Framing Software Component Transparency
+(FSCT3) ["Baseline Attributes"][fsct3] is *experimental and under development*.
+The mapping of FSCT3 Baseline Attributes to ISO/IEC 5962:2021 (SPDX 2.2.1) and
+SPDX 3.0 can be found at Section 2.5 of the FSCT3 document.
+
+In addition to information similar to NTIA minimum elements,
+FSCT3 also requires these Baseline Attributes:
+
+- License
+- Copyright Holder
 
 ## Installation
 
-*Installation Method #1*: Install from the [Python Package Index (PyPI)](https://pypi.org/project/ntia-conformance-checker/) with `pip`.
+*Installation Method #1*:
+Install from the [Python Package Index (PyPI)][pypi] with `pip`.
 
 `pip install ntia-conformance-checker`
 
-*Installation Method #2*: Install locally. Clone the repo and install dependencies using the following commands:
+*Installation Method #2*: Install locally.
+Clone the repo and install dependencies using the following commands:
 
 ```bash
 git clone https://github.com/spdx/ntia-conformance-checker.git
 cd ntia-conformance-checker
 pip install .
 ```
 
-The tool requires Python 3 (3.8+). It is recommended to use a virtual python environment especially
-if you are using different versions of python. `virtualenv` is a tool for setting up virtual python environments which
-allows you to have all the dependencies for the tool set up in a single environment, or have different environments set
-up for testing using different versions of Python.
+The tool requires Python 3 (3.8+).
+It is recommended to use a virtual python environment especially
+if you are using different versions of python.
+`virtualenv` is a tool for setting up virtual python environments which
+allows you to have all the dependencies for the tool set up in a single
+environment, or have different environments set up for testing using different
+versions of Python.
 
 ## CLI Usage
 
 ```text
-Usage: ntia-checker [OPTIONS]
+Usage: sbomcheck [OPTIONS]
 
 Options:
   --file TEXT            The file to be parsed
-  --output [print|json]  Output format  [default: print]
-  -v, --verbose          Use verbose printing
+  --comply [fsct3-min|ntia]
+                         Specify which compliance standard to check against
+                         - fsct3-min: FSCT3 Baseline Attributes-Minimum Expected
+                         - ntia: NTIA minimum elements
+                         [default: ntia]
+  --output [html|json|print|quiet]
+                         Output format  [default: print]
   --output_path TEXT     Filepath for optionally storing output.
+  --skip-validation      Specify whether to skip validation
+  -v, --verbose          Use verbose printing
+  --version              Display version of ntia-conformance-checker
   -h, --help             Show this message and exit.
 ```
 
 The user can then analyze a particular file:
 
 ```bash
-ntia-checker --file sbom.json
+sbomcheck --file sbom.json
 ```
 
 To generate the output in machine-readable JSON, run:
 
 ```bash
-ntia-checker --file sbom.spdx --output json
+sbomcheck --file sbom.spdx --output json
 ```
 
 ## Usage as a Library
 
 `ntia-conformance-checker` can also be imported as a library. For example:
 
 ```python
+from ntia_conformance_checker import SbomChecker
 
-import ntia_conformance_checker as ntia
+sbom_checker = SbomChecker("SBOM_filepath")
 
-sbom = ntia.SbomChecker("SBOM_filepath")
-
-print(sbom.ntia_minimum_elements_compliant)
+print(sbom_checker.compliant)
 ```
 
-Additional properties and methods associated with `SbomChecker()` can be found in [`sbom_checker.py`](ntia_conformance_checker/sbom_checker.py).
+Additional properties and methods can be found in `BaseChecker` class
+at [`base_checker.py`](ntia_conformance_checker/base_checker.py).
+Specific properties and methods for a particular specification can be found
+at the checker for that specification. For example, `NTIAChecker` class
+at [`ntia_checker.py`](ntia_conformance_checker/ntia_checker.py).
 
-# History
+## History
 
-This is the result of an initial [Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com/) contribution in 2022 by
+This is the result of an initial
+[Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com/)
+contribution in 2022 by
 [@linynjosh](https://github.com/linynjosh) and is maintained
 by a community of SPDX adopters and enthusiasts.
 
-# License
+## License
+
+[Apache-2.0](./LICENSE)
 
-[Apache-2.0](LICENSE)
+## Dependencies
 
-# Dependencies
+- [spdx-tools](https://pypi.org/project/spdx-tools/) used for parsing the
+  SPDX SBOM.
 
-* [spdx-tools](https://pypi.org/project/spdx-tools/) used for parsing the SPDX SBOM.
+## Support
 
-# Support
+- Submit issues, questions or feedback at
+  <https://github.com/spdx/ntia-conformance-checker/issues>
+- Join the discussion on <https://lists.spdx.org/g/spdx-tech> and
+  <https://spdx.dev/participate/tech/>
 
-* Submit issues, questions or feedback at https://github.com/spdx/ntia-conformance-checker/issues
-* Join the discussion on https://lists.spdx.org/g/spdx-tech and https://spdx.dev/participate/tech/
+## Contributing
 
-# Contributing
+Contributions are very welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md)
+for instructions on how to contribute to the codebase.
 
-Contributions are very welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on how to contribute to the codebase.
+## Further help
 
-# Further help
+Check out the [frequently asked questions](./FAQ.md) document.
 
-Check out the [frequently asked questions](FAQ.md) document.
+[ntia]: https://www.ntia.gov/report/2021/minimum-elements-software-bill-materials-sbom
+[ntia-spdx23]: https://spdx.github.io/spdx-spec/v2.3/how-to-use/#k22-mapping-ntia-minimum-elements-to-spdx-fields
+[fsct3]: https://www.cisa.gov/resources-tools/resources/framing-software-component-transparency-2024
+[pypi]: https://pypi.org/project/ntia-conformance-checker/