cyclonedx_bom/
lib.rs

1/*
2 * This file is part of CycloneDX Rust Cargo.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *
16 * SPDX-License-Identifier: Apache-2.0
17 */
18
19//! The `cyclonedx-bom` library provides JSON and XML serialization and deserialization of Software
20//! Bill-of-Materials (SBOM) files.
21//!
22//! [CycloneDX](https://cyclonedx.org/) is a lightweight SBOM specification that is easily created,
23//! human and machine readable, and simple to parse.
24//!
25//! The library is intended to enable developers to:
26//!
27//! - Construct SBOM documents that conform the CycloneDX specification
28//! - Parse and validate JSON and XML SBOM documents
29//! - Perform modifications to BOM documents (e.g. merging multiple BOMs using a variety of
30//!   algorithms)
31//!
32//! ## Read and validate an SBOM
33//!
34//! Given an input implements [std::io::Read], parse the value into a
35//! [`Bom`](crate::models::bom::Bom) and then use the [`Validate`](crate::validation::Validate)
36//! trait to ensure that it is a valid BOM.
37//!
38//! ```rust
39//! use cyclonedx_bom::prelude::*;
40//!
41//! let bom_json = r#"{
42//!   "bomFormat": "CycloneDX",
43//!   "specVersion": "1.3",
44//!   "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
45//!   "version": 1
46//! }"#;
47//! let bom = Bom::parse_from_json_v1_3(bom_json.as_bytes()).expect("Failed to parse BOM");
48//!
49//! let validation_result = bom.validate();
50//! assert!(validation_result.passed());
51//! ```
52//!
53//! ## Create and output an SBOM
54//!
55//! Given an output implements [std::io::Write], output the [`Bom`](crate::models::bom::Bom) as
56//! JSON.
57//!
58//! ```rust
59//! use cyclonedx_bom::prelude::*;
60//! use cyclonedx_bom::models::{
61//!     tool::{Tool, Tools},
62//! };
63//!
64//! let bom = Bom {
65//!     serial_number: Some(
66//!         UrnUuid::new("urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79".to_string())
67//!             .expect("Failed to create UrnUuid"),
68//!     ),
69//!     metadata: Some(Metadata {
70//!         tools: Some(Tools::List(vec![Tool {
71//!             name: Some(NormalizedString::new("my_tool")),
72//!             ..Tool::default()
73//!         }])),
74//!         ..Metadata::default()
75//!     }),
76//!     ..Bom::default()
77//! };
78//!
79//! let mut output = Vec::<u8>::new();
80//!
81//! bom.output_as_json_v1_3(&mut output)
82//!     .expect("Failed to write BOM");
83//! let output = String::from_utf8(output).expect("Failed to read output as a string");
84//! assert_eq!(
85//!     output,
86//!     r#"{
87//!   "bomFormat": "CycloneDX",
88//!   "specVersion": "1.3",
89//!   "version": 1,
90//!   "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
91//!   "metadata": {
92//!     "tools": [
93//!       {
94//!         "name": "my_tool"
95//!       }
96//!     ]
97//!   }
98//! }"#
99//! );
100//! ```
101//!
102//! ## Library design notes
103//!
104//! ### Correctness
105//!
106//! The library is designed to perform a "best-effort" processing of CycloneDX SBOM documents. This
107//! is accomplished by having a library-facing interface that does not allow the programmer to
108//! construct invalid documents, but does have a more lax internal representation to accommodate
109//! invalid SBOM documents from other sources that are parsed by the library. The enums in the
110//! `models` module demonstrate this pattern. They include an `Unknown-X` variant, which should not
111//! be created manually, but might occur as a result of parsing a SBOM.
112//!
113//! In order to be confident that you are working with valid data, the library provides a
114//! [`Validate`](crate::validation::Validate) trait to enable you to find invalid data in a parsed
115//! SBOM. An example of this can be seen in the "Read and validate an SBOM" code snippet.
116//!
117//! ### Prelude
118//!
119//! The library provides a prelude (similar to the [Rust Standard Library's prelude](https://doc.rust-lang.org/std/prelude/index.html)) to make it easier to use the code. The prelude contains commonly used types and traits. To use this in your library, include the following code snippet:
120//!
121//! ```
122//! use cyclonedx_bom::prelude::*;
123//! ```
124
125pub mod errors;
126pub mod external_models;
127pub mod models;
128pub mod prelude;
129pub mod validation;
130
131mod specs;
132mod utilities;
133mod xml;
cyclonedx_bom/lib.rs

cyclonedx_bom/
lib.rs
