From 66c78d44aff07d60195f5812999a90195f82eb93 Mon Sep 17 00:00:00 2001 From: Alex Goodman Date: Mon, 10 Nov 2025 16:29:06 -0500 Subject: [PATCH] Document additional json schema fields (#4356) * add documentation to key fields Signed-off-by: Alex Goodman * regenerate json schema Signed-off-by: Alex Goodman --------- Signed-off-by: Alex Goodman --- schema/json/schema-16.0.42.json | 237 +++++++++++++------- schema/json/schema-latest.json | 237 +++++++++++++------- syft/format/syftjson/model/document.go | 17 +- syft/format/syftjson/model/file.go | 84 +++++-- syft/format/syftjson/model/linux_release.go | 77 +++++-- syft/format/syftjson/model/package.go | 32 ++- syft/format/syftjson/model/relationship.go | 14 +- syft/format/syftjson/model/source.go | 29 ++- syft/pkg/alpm.go | 1 + syft/pkg/microsoft.go | 7 +- syft/pkg/npm.go | 1 + 11 files changed, 509 insertions(+), 227 deletions(-) diff --git a/schema/json/schema-16.0.42.json b/schema/json/schema-16.0.42.json index e27d96039..247969bc4 100644 --- a/schema/json/schema-16.0.42.json +++ b/schema/json/schema-16.0.42.json @@ -130,7 +130,8 @@ "description": "Digests contains file content hashes for integrity verification" } }, - "type": "object" + "type": "object", + "description": "AlpmFileRecord represents a single file entry within an Arch Linux package with its associated metadata tracked by pacman." }, "ApkDbEntry": { "properties": { @@ -433,16 +434,19 @@ "CPE": { "properties": { "cpe": { - "type": "string" + "type": "string", + "description": "Value is the CPE string identifier." }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source where this CPE was obtained or generated from." } }, "type": "object", "required": [ "cpe" - ] + ], + "description": "CPE represents a Common Platform Enumeration identifier used for matching packages to known vulnerabilities in security databases." }, "ClassifierMatch": { "properties": { @@ -747,19 +751,23 @@ "Descriptor": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the name of the tool that generated this SBOM (e.g., \"syft\")." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the version of the tool that generated this SBOM." }, - "configuration": true + "configuration": { + "description": "Configuration contains the tool configuration used during SBOM generation." + } }, "type": "object", "required": [ "name", "version" ], - "description": "Descriptor describes what created the document as well as surrounding metadata" + "description": "Descriptor identifies the tool that generated this SBOM document, including its name, version, and configuration used during catalog generation." }, "Digest": { "properties": { @@ -1285,58 +1293,71 @@ "File": { "properties": { "id": { - "type": "string" + "type": "string", + "description": "ID is a unique identifier for this file within the SBOM." }, "location": { - "$ref": "#/$defs/Coordinates" + "$ref": "#/$defs/Coordinates", + "description": "Location is the file path and layer information where this file was found." }, "metadata": { - "$ref": "#/$defs/FileMetadataEntry" + "$ref": "#/$defs/FileMetadataEntry", + "description": "Metadata contains filesystem metadata such as permissions, ownership, and file type." }, "contents": { - "type": "string" + "type": "string", + "description": "Contents is the file contents for small files." }, "digests": { "items": { "$ref": "#/$defs/Digest" }, - "type": "array" + "type": "array", + "description": "Digests contains cryptographic hashes of the file contents." }, "licenses": { "items": { "$ref": "#/$defs/FileLicense" }, - "type": "array" + "type": "array", + "description": "Licenses contains license information discovered within this file." }, "executable": { - "$ref": "#/$defs/Executable" + "$ref": "#/$defs/Executable", + "description": "Executable contains executable metadata if this file is a binary." }, "unknowns": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Unknowns contains unknown fields for forward compatibility." } }, "type": "object", "required": [ "id", "location" - ] + ], + "description": "File represents a file discovered during cataloging with its metadata, content digests, licenses, and relationships to packages." }, "FileLicense": { "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value is the raw license identifier or text as found in the file." }, "spdxExpression": { - "type": "string" + "type": "string", + "description": "SPDXExpression is the parsed SPDX license expression." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the license type classification (e.g., declared, concluded, discovered)." }, "evidence": { - "$ref": "#/$defs/FileLicenseEvidence" + "$ref": "#/$defs/FileLicenseEvidence", + "description": "Evidence contains supporting evidence for this license detection." } }, "type": "object", @@ -1344,18 +1365,22 @@ "value", "spdxExpression", "type" - ] + ], + "description": "FileLicense represents license information discovered within a file's contents or metadata, including the matched license text and SPDX expression." }, "FileLicenseEvidence": { "properties": { "confidence": { - "type": "integer" + "type": "integer", + "description": "Confidence is the confidence score for this license detection (0-100)." }, "offset": { - "type": "integer" + "type": "integer", + "description": "Offset is the byte offset where the license text starts in the file." }, "extent": { - "type": "integer" + "type": "integer", + "description": "Extent is the length of the license text in bytes." } }, "type": "object", @@ -1363,30 +1388,38 @@ "confidence", "offset", "extent" - ] + ], + "description": "FileLicenseEvidence contains supporting evidence for a license detection in a file, including the byte offset, extent, and confidence level." }, "FileMetadataEntry": { "properties": { "mode": { - "type": "integer" + "type": "integer", + "description": "Mode is the Unix file permission mode in octal format." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the file type (e.g., \"RegularFile\", \"Directory\", \"SymbolicLink\")." }, "linkDestination": { - "type": "string" + "type": "string", + "description": "LinkDestination is the target path for symbolic links." }, "userID": { - "type": "integer" + "type": "integer", + "description": "UserID is the file owner user ID." }, "groupID": { - "type": "integer" + "type": "integer", + "description": "GroupID is the file owner group ID." }, "mimeType": { - "type": "string" + "type": "string", + "description": "MIMEType is the MIME type of the file contents." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the file size in bytes." } }, "type": "object", @@ -1397,7 +1430,8 @@ "groupID", "mimeType", "size" - ] + ], + "description": "FileMetadataEntry contains filesystem-level metadata attributes such as permissions, ownership, type, and size for a cataloged file." }, "GithubActionsUseStatement": { "properties": { @@ -1545,7 +1579,8 @@ "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "IDLikes represents a list of distribution IDs that this Linux distribution is similar to or derived from, as defined in os-release ID_LIKE field." }, "JavaArchive": { "properties": { @@ -1974,28 +2009,34 @@ "License": { "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value is the raw license identifier or expression as found." }, "spdxExpression": { - "type": "string" + "type": "string", + "description": "SPDXExpression is the parsed SPDX license expression." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the license type classification (e.g., declared, concluded, discovered)." }, "urls": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "URLs are URLs where license text or information can be found." }, "locations": { "items": { "$ref": "#/$defs/Location" }, - "type": "array" + "type": "array", + "description": "Locations are file locations where this license was discovered." }, "contents": { - "type": "string" + "type": "string", + "description": "Contents is the full license text content." } }, "type": "object", @@ -2005,7 +2046,8 @@ "type", "urls", "locations" - ] + ], + "description": "License represents software license information discovered for a package, including SPDX expressions and supporting evidence locations." }, "LinuxKernelArchive": { "properties": { @@ -2130,64 +2172,84 @@ "LinuxRelease": { "properties": { "prettyName": { - "type": "string" + "type": "string", + "description": "PrettyName is a human-readable operating system name with version." }, "name": { - "type": "string" + "type": "string", + "description": "Name is the operating system name without version information." }, "id": { - "type": "string" + "type": "string", + "description": "ID is the lower-case operating system identifier (e.g., \"ubuntu\", \"rhel\")." }, "idLike": { - "$ref": "#/$defs/IDLikes" + "$ref": "#/$defs/IDLikes", + "description": "IDLike is a list of operating system IDs this distribution is similar to or derived from." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the operating system version including codename if available." }, "versionID": { - "type": "string" + "type": "string", + "description": "VersionID is the operating system version number or identifier." }, "versionCodename": { - "type": "string" + "type": "string", + "description": "VersionCodename is the operating system release codename (e.g., \"jammy\", \"bullseye\")." }, "buildID": { - "type": "string" + "type": "string", + "description": "BuildID is a build identifier for the operating system." }, "imageID": { - "type": "string" + "type": "string", + "description": "ImageID is an identifier for container or cloud images." }, "imageVersion": { - "type": "string" + "type": "string", + "description": "ImageVersion is the version for container or cloud images." }, "variant": { - "type": "string" + "type": "string", + "description": "Variant is the operating system variant name (e.g., \"Server\", \"Workstation\")." }, "variantID": { - "type": "string" + "type": "string", + "description": "VariantID is the lower-case operating system variant identifier." }, "homeURL": { - "type": "string" + "type": "string", + "description": "HomeURL is the homepage URL for the operating system." }, "supportURL": { - "type": "string" + "type": "string", + "description": "SupportURL is the support or help URL for the operating system." }, "bugReportURL": { - "type": "string" + "type": "string", + "description": "BugReportURL is the bug reporting URL for the operating system." }, "privacyPolicyURL": { - "type": "string" + "type": "string", + "description": "PrivacyPolicyURL is the privacy policy URL for the operating system." }, "cpeName": { - "type": "string" + "type": "string", + "description": "CPEName is the Common Platform Enumeration name for the operating system." }, "supportEnd": { - "type": "string" + "type": "string", + "description": "SupportEnd is the end of support date or version identifier." }, "extendedSupport": { - "type": "boolean" + "type": "boolean", + "description": "ExtendedSupport indicates whether extended security or support is available." } }, - "type": "object" + "type": "object", + "description": "LinuxRelease contains Linux distribution identification and version information extracted from /etc/os-release or similar system files." }, "Location": { "properties": { @@ -2283,7 +2345,7 @@ "product_id", "kb" ], - "description": "MicrosoftKbPatch is slightly odd in how it is expected to map onto data." + "description": "MicrosoftKbPatch represents a Windows Knowledge Base patch identifier associated with a specific Microsoft product from the MSRC (Microsoft Security Response Center)." }, "NixDerivation": { "properties": { @@ -3014,7 +3076,8 @@ "type": "object", "required": [ "integrity" - ] + ], + "description": "PnpmLockResolution contains package resolution metadata from pnpm lockfiles, including the integrity hash used for verification." }, "PortageDbEntry": { "properties": { @@ -3501,22 +3564,28 @@ "Relationship": { "properties": { "parent": { - "type": "string" + "type": "string", + "description": "Parent is the ID of the parent artifact in this relationship." }, "child": { - "type": "string" + "type": "string", + "description": "Child is the ID of the child artifact in this relationship." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the relationship type (e.g., \"contains\", \"dependency-of\", \"ancestor-of\")." }, - "metadata": true + "metadata": { + "description": "Metadata contains additional relationship-specific metadata." + } }, "type": "object", "required": [ "parent", "child", "type" - ] + ], + "description": "Relationship represents a directed relationship between two artifacts in the SBOM, such as package-contains-file or package-depends-on-package." }, "RpmArchive": { "properties": { @@ -3863,17 +3932,20 @@ "Schema": { "properties": { "version": { - "type": "string" + "type": "string", + "description": "Version is the JSON schema version for this document format." }, "url": { - "type": "string" + "type": "string", + "description": "URL is the URL to the JSON schema definition document." } }, "type": "object", "required": [ "version", "url" - ] + ], + "description": "Schema specifies the JSON schema version and URL reference that defines the structure and validation rules for this document format." }, "SnapEntry": { "properties": { @@ -3911,21 +3983,28 @@ "Source": { "properties": { "id": { - "type": "string" + "type": "string", + "description": "ID is a unique identifier for the analyzed source artifact." }, "name": { - "type": "string" + "type": "string", + "description": "Name is the name of the analyzed artifact (e.g., image name, directory path)." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the version of the analyzed artifact (e.g., image tag)." }, "supplier": { - "type": "string" + "type": "string", + "description": "Supplier is supplier information, which can be user-provided for NTIA minimum elements compliance." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the source type (e.g., \"image\", \"directory\", \"file\")." }, - "metadata": true + "metadata": { + "description": "Metadata contains additional source-specific metadata." + } }, "type": "object", "required": [ @@ -3935,7 +4014,7 @@ "type", "metadata" ], - "description": "Instead, the Supplier can be determined by the user of syft and passed as a config or flag to help fulfill the NTIA minimum elements." + "description": "Source represents the artifact that was analyzed to generate this SBOM, such as a container image, directory, or file archive." }, "SwiftPackageManagerLockEntry": { "properties": { diff --git a/schema/json/schema-latest.json b/schema/json/schema-latest.json index e27d96039..247969bc4 100644 --- a/schema/json/schema-latest.json +++ b/schema/json/schema-latest.json @@ -130,7 +130,8 @@ "description": "Digests contains file content hashes for integrity verification" } }, - "type": "object" + "type": "object", + "description": "AlpmFileRecord represents a single file entry within an Arch Linux package with its associated metadata tracked by pacman." }, "ApkDbEntry": { "properties": { @@ -433,16 +434,19 @@ "CPE": { "properties": { "cpe": { - "type": "string" + "type": "string", + "description": "Value is the CPE string identifier." }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source where this CPE was obtained or generated from." } }, "type": "object", "required": [ "cpe" - ] + ], + "description": "CPE represents a Common Platform Enumeration identifier used for matching packages to known vulnerabilities in security databases." }, "ClassifierMatch": { "properties": { @@ -747,19 +751,23 @@ "Descriptor": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the name of the tool that generated this SBOM (e.g., \"syft\")." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the version of the tool that generated this SBOM." }, - "configuration": true + "configuration": { + "description": "Configuration contains the tool configuration used during SBOM generation." + } }, "type": "object", "required": [ "name", "version" ], - "description": "Descriptor describes what created the document as well as surrounding metadata" + "description": "Descriptor identifies the tool that generated this SBOM document, including its name, version, and configuration used during catalog generation." }, "Digest": { "properties": { @@ -1285,58 +1293,71 @@ "File": { "properties": { "id": { - "type": "string" + "type": "string", + "description": "ID is a unique identifier for this file within the SBOM." }, "location": { - "$ref": "#/$defs/Coordinates" + "$ref": "#/$defs/Coordinates", + "description": "Location is the file path and layer information where this file was found." }, "metadata": { - "$ref": "#/$defs/FileMetadataEntry" + "$ref": "#/$defs/FileMetadataEntry", + "description": "Metadata contains filesystem metadata such as permissions, ownership, and file type." }, "contents": { - "type": "string" + "type": "string", + "description": "Contents is the file contents for small files." }, "digests": { "items": { "$ref": "#/$defs/Digest" }, - "type": "array" + "type": "array", + "description": "Digests contains cryptographic hashes of the file contents." }, "licenses": { "items": { "$ref": "#/$defs/FileLicense" }, - "type": "array" + "type": "array", + "description": "Licenses contains license information discovered within this file." }, "executable": { - "$ref": "#/$defs/Executable" + "$ref": "#/$defs/Executable", + "description": "Executable contains executable metadata if this file is a binary." }, "unknowns": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Unknowns contains unknown fields for forward compatibility." } }, "type": "object", "required": [ "id", "location" - ] + ], + "description": "File represents a file discovered during cataloging with its metadata, content digests, licenses, and relationships to packages." }, "FileLicense": { "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value is the raw license identifier or text as found in the file." }, "spdxExpression": { - "type": "string" + "type": "string", + "description": "SPDXExpression is the parsed SPDX license expression." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the license type classification (e.g., declared, concluded, discovered)." }, "evidence": { - "$ref": "#/$defs/FileLicenseEvidence" + "$ref": "#/$defs/FileLicenseEvidence", + "description": "Evidence contains supporting evidence for this license detection." } }, "type": "object", @@ -1344,18 +1365,22 @@ "value", "spdxExpression", "type" - ] + ], + "description": "FileLicense represents license information discovered within a file's contents or metadata, including the matched license text and SPDX expression." }, "FileLicenseEvidence": { "properties": { "confidence": { - "type": "integer" + "type": "integer", + "description": "Confidence is the confidence score for this license detection (0-100)." }, "offset": { - "type": "integer" + "type": "integer", + "description": "Offset is the byte offset where the license text starts in the file." }, "extent": { - "type": "integer" + "type": "integer", + "description": "Extent is the length of the license text in bytes." } }, "type": "object", @@ -1363,30 +1388,38 @@ "confidence", "offset", "extent" - ] + ], + "description": "FileLicenseEvidence contains supporting evidence for a license detection in a file, including the byte offset, extent, and confidence level." }, "FileMetadataEntry": { "properties": { "mode": { - "type": "integer" + "type": "integer", + "description": "Mode is the Unix file permission mode in octal format." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the file type (e.g., \"RegularFile\", \"Directory\", \"SymbolicLink\")." }, "linkDestination": { - "type": "string" + "type": "string", + "description": "LinkDestination is the target path for symbolic links." }, "userID": { - "type": "integer" + "type": "integer", + "description": "UserID is the file owner user ID." }, "groupID": { - "type": "integer" + "type": "integer", + "description": "GroupID is the file owner group ID." }, "mimeType": { - "type": "string" + "type": "string", + "description": "MIMEType is the MIME type of the file contents." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the file size in bytes." } }, "type": "object", @@ -1397,7 +1430,8 @@ "groupID", "mimeType", "size" - ] + ], + "description": "FileMetadataEntry contains filesystem-level metadata attributes such as permissions, ownership, type, and size for a cataloged file." }, "GithubActionsUseStatement": { "properties": { @@ -1545,7 +1579,8 @@ "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "IDLikes represents a list of distribution IDs that this Linux distribution is similar to or derived from, as defined in os-release ID_LIKE field." }, "JavaArchive": { "properties": { @@ -1974,28 +2009,34 @@ "License": { "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value is the raw license identifier or expression as found." }, "spdxExpression": { - "type": "string" + "type": "string", + "description": "SPDXExpression is the parsed SPDX license expression." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the license type classification (e.g., declared, concluded, discovered)." }, "urls": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "URLs are URLs where license text or information can be found." }, "locations": { "items": { "$ref": "#/$defs/Location" }, - "type": "array" + "type": "array", + "description": "Locations are file locations where this license was discovered." }, "contents": { - "type": "string" + "type": "string", + "description": "Contents is the full license text content." } }, "type": "object", @@ -2005,7 +2046,8 @@ "type", "urls", "locations" - ] + ], + "description": "License represents software license information discovered for a package, including SPDX expressions and supporting evidence locations." }, "LinuxKernelArchive": { "properties": { @@ -2130,64 +2172,84 @@ "LinuxRelease": { "properties": { "prettyName": { - "type": "string" + "type": "string", + "description": "PrettyName is a human-readable operating system name with version." }, "name": { - "type": "string" + "type": "string", + "description": "Name is the operating system name without version information." }, "id": { - "type": "string" + "type": "string", + "description": "ID is the lower-case operating system identifier (e.g., \"ubuntu\", \"rhel\")." }, "idLike": { - "$ref": "#/$defs/IDLikes" + "$ref": "#/$defs/IDLikes", + "description": "IDLike is a list of operating system IDs this distribution is similar to or derived from." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the operating system version including codename if available." }, "versionID": { - "type": "string" + "type": "string", + "description": "VersionID is the operating system version number or identifier." }, "versionCodename": { - "type": "string" + "type": "string", + "description": "VersionCodename is the operating system release codename (e.g., \"jammy\", \"bullseye\")." }, "buildID": { - "type": "string" + "type": "string", + "description": "BuildID is a build identifier for the operating system." }, "imageID": { - "type": "string" + "type": "string", + "description": "ImageID is an identifier for container or cloud images." }, "imageVersion": { - "type": "string" + "type": "string", + "description": "ImageVersion is the version for container or cloud images." }, "variant": { - "type": "string" + "type": "string", + "description": "Variant is the operating system variant name (e.g., \"Server\", \"Workstation\")." }, "variantID": { - "type": "string" + "type": "string", + "description": "VariantID is the lower-case operating system variant identifier." }, "homeURL": { - "type": "string" + "type": "string", + "description": "HomeURL is the homepage URL for the operating system." }, "supportURL": { - "type": "string" + "type": "string", + "description": "SupportURL is the support or help URL for the operating system." }, "bugReportURL": { - "type": "string" + "type": "string", + "description": "BugReportURL is the bug reporting URL for the operating system." }, "privacyPolicyURL": { - "type": "string" + "type": "string", + "description": "PrivacyPolicyURL is the privacy policy URL for the operating system." }, "cpeName": { - "type": "string" + "type": "string", + "description": "CPEName is the Common Platform Enumeration name for the operating system." }, "supportEnd": { - "type": "string" + "type": "string", + "description": "SupportEnd is the end of support date or version identifier." }, "extendedSupport": { - "type": "boolean" + "type": "boolean", + "description": "ExtendedSupport indicates whether extended security or support is available." } }, - "type": "object" + "type": "object", + "description": "LinuxRelease contains Linux distribution identification and version information extracted from /etc/os-release or similar system files." }, "Location": { "properties": { @@ -2283,7 +2345,7 @@ "product_id", "kb" ], - "description": "MicrosoftKbPatch is slightly odd in how it is expected to map onto data." + "description": "MicrosoftKbPatch represents a Windows Knowledge Base patch identifier associated with a specific Microsoft product from the MSRC (Microsoft Security Response Center)." }, "NixDerivation": { "properties": { @@ -3014,7 +3076,8 @@ "type": "object", "required": [ "integrity" - ] + ], + "description": "PnpmLockResolution contains package resolution metadata from pnpm lockfiles, including the integrity hash used for verification." }, "PortageDbEntry": { "properties": { @@ -3501,22 +3564,28 @@ "Relationship": { "properties": { "parent": { - "type": "string" + "type": "string", + "description": "Parent is the ID of the parent artifact in this relationship." }, "child": { - "type": "string" + "type": "string", + "description": "Child is the ID of the child artifact in this relationship." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the relationship type (e.g., \"contains\", \"dependency-of\", \"ancestor-of\")." }, - "metadata": true + "metadata": { + "description": "Metadata contains additional relationship-specific metadata." + } }, "type": "object", "required": [ "parent", "child", "type" - ] + ], + "description": "Relationship represents a directed relationship between two artifacts in the SBOM, such as package-contains-file or package-depends-on-package." }, "RpmArchive": { "properties": { @@ -3863,17 +3932,20 @@ "Schema": { "properties": { "version": { - "type": "string" + "type": "string", + "description": "Version is the JSON schema version for this document format." }, "url": { - "type": "string" + "type": "string", + "description": "URL is the URL to the JSON schema definition document." } }, "type": "object", "required": [ "version", "url" - ] + ], + "description": "Schema specifies the JSON schema version and URL reference that defines the structure and validation rules for this document format." }, "SnapEntry": { "properties": { @@ -3911,21 +3983,28 @@ "Source": { "properties": { "id": { - "type": "string" + "type": "string", + "description": "ID is a unique identifier for the analyzed source artifact." }, "name": { - "type": "string" + "type": "string", + "description": "Name is the name of the analyzed artifact (e.g., image name, directory path)." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the version of the analyzed artifact (e.g., image tag)." }, "supplier": { - "type": "string" + "type": "string", + "description": "Supplier is supplier information, which can be user-provided for NTIA minimum elements compliance." }, "type": { - "type": "string" + "type": "string", + "description": "Type is the source type (e.g., \"image\", \"directory\", \"file\")." }, - "metadata": true + "metadata": { + "description": "Metadata contains additional source-specific metadata." + } }, "type": "object", "required": [ @@ -3935,7 +4014,7 @@ "type", "metadata" ], - "description": "Instead, the Supplier can be determined by the user of syft and passed as a config or flag to help fulfill the NTIA minimum elements." + "description": "Source represents the artifact that was analyzed to generate this SBOM, such as a container image, directory, or file archive." }, "SwiftPackageManagerLockEntry": { "properties": { diff --git a/syft/format/syftjson/model/document.go b/syft/format/syftjson/model/document.go index c1cb0e381..5bfbcdf06 100644 --- a/syft/format/syftjson/model/document.go +++ b/syft/format/syftjson/model/document.go @@ -35,14 +35,23 @@ func (d *Document) UnmarshalJSON(data []byte) error { return nil } -// Descriptor describes what created the document as well as surrounding metadata +// Descriptor identifies the tool that generated this SBOM document, including its name, version, and configuration used during catalog generation. type Descriptor struct { - Name string `json:"name"` - Version string `json:"version"` + // Name is the name of the tool that generated this SBOM (e.g., "syft"). + Name string `json:"name"` + + // Version is the version of the tool that generated this SBOM. + Version string `json:"version"` + + // Configuration contains the tool configuration used during SBOM generation. Configuration interface{} `json:"configuration,omitempty"` } +// Schema specifies the JSON schema version and URL reference that defines the structure and validation rules for this document format. type Schema struct { + // Version is the JSON schema version for this document format. Version string `json:"version"` - URL string `json:"url"` + + // URL is the URL to the JSON schema definition document. + URL string `json:"url"` } diff --git a/syft/format/syftjson/model/file.go b/syft/format/syftjson/model/file.go index 87b4754e4..cfe89e71e 100644 --- a/syft/format/syftjson/model/file.go +++ b/syft/format/syftjson/model/file.go @@ -10,25 +10,55 @@ import ( "github.com/anchore/syft/syft/license" ) +// File represents a file discovered during cataloging with its metadata, content digests, licenses, and relationships to packages. type File struct { - ID string `json:"id"` - Location file.Coordinates `json:"location"` - Metadata *FileMetadataEntry `json:"metadata,omitempty"` - Contents string `json:"contents,omitempty"` - Digests []file.Digest `json:"digests,omitempty"` - Licenses []FileLicense `json:"licenses,omitempty"` - Executable *file.Executable `json:"executable,omitempty"` - Unknowns []string `json:"unknowns,omitempty"` + // ID is a unique identifier for this file within the SBOM. + ID string `json:"id"` + + // Location is the file path and layer information where this file was found. + Location file.Coordinates `json:"location"` + + // Metadata contains filesystem metadata such as permissions, ownership, and file type. + Metadata *FileMetadataEntry `json:"metadata,omitempty"` + + // Contents is the file contents for small files. + Contents string `json:"contents,omitempty"` + + // Digests contains cryptographic hashes of the file contents. + Digests []file.Digest `json:"digests,omitempty"` + + // Licenses contains license information discovered within this file. + Licenses []FileLicense `json:"licenses,omitempty"` + + // Executable contains executable metadata if this file is a binary. + Executable *file.Executable `json:"executable,omitempty"` + + // Unknowns contains unknown fields for forward compatibility. + Unknowns []string `json:"unknowns,omitempty"` } +// FileMetadataEntry contains filesystem-level metadata attributes such as permissions, ownership, type, and size for a cataloged file. type FileMetadataEntry struct { - Mode int `json:"mode"` - Type string `json:"type"` + // Mode is the Unix file permission mode in octal format. + Mode int `json:"mode"` + + // Type is the file type (e.g., "RegularFile", "Directory", "SymbolicLink"). + Type string `json:"type"` + + // LinkDestination is the target path for symbolic links. LinkDestination string `json:"linkDestination,omitempty"` - UserID int `json:"userID"` - GroupID int `json:"groupID"` - MIMEType string `json:"mimeType"` - Size int64 `json:"size"` + + // UserID is the file owner user ID. + UserID int `json:"userID"` + + // GroupID is the file owner group ID. + GroupID int `json:"groupID"` + + // MIMEType is the MIME type of the file contents. + MIMEType string `json:"mimeType"` + + // Size is the file size in bytes. + Size int64 `json:"size"` } type auxFileMetadataEntry FileMetadataEntry @@ -82,17 +112,31 @@ type sbomImportLegacyFileMetadataEntry struct { Size int64 `json:"Size"` } +// FileLicense represents license information discovered within a file's contents or metadata, including the matched license text and SPDX expression. type FileLicense struct { - Value string `json:"value"` - SPDXExpression string `json:"spdxExpression"` - Type license.Type `json:"type"` - Evidence *FileLicenseEvidence `json:"evidence,omitempty"` + // Value is the raw license identifier or text as found in the file. + Value string `json:"value"` + + // SPDXExpression is the parsed SPDX license expression. + SPDXExpression string `json:"spdxExpression"` + + // Type is the license type classification (e.g., declared, concluded, discovered). + Type license.Type `json:"type"` + + // Evidence contains supporting evidence for this license detection. + Evidence *FileLicenseEvidence `json:"evidence,omitempty"` } +// FileLicenseEvidence contains supporting evidence for a license detection in a file, including the byte offset, extent, and confidence level. type FileLicenseEvidence struct { + // Confidence is the confidence score for this license detection (0-100). Confidence int `json:"confidence"` - Offset int `json:"offset"` - Extent int `json:"extent"` + + // Offset is the byte offset where the license text starts in the file. + Offset int `json:"offset"` + + // Extent is the length of the license text in bytes. + Extent int `json:"extent"` } type intOrStringFileType struct { diff --git a/syft/format/syftjson/model/linux_release.go b/syft/format/syftjson/model/linux_release.go index a544c250c..6482890fb 100644 --- a/syft/format/syftjson/model/linux_release.go +++ b/syft/format/syftjson/model/linux_release.go @@ -4,28 +4,67 @@ import ( "encoding/json" ) +// IDLikes represents a list of distribution IDs that this Linux distribution is similar to or derived from, as defined in os-release ID_LIKE field. type IDLikes []string +// LinuxRelease contains Linux distribution identification and version information extracted from /etc/os-release or similar system files. type LinuxRelease struct { - PrettyName string `json:"prettyName,omitempty"` - Name string `json:"name,omitempty"` - ID string `json:"id,omitempty"` - IDLike IDLikes `json:"idLike,omitempty"` - Version string `json:"version,omitempty"` - VersionID string `json:"versionID,omitempty"` - VersionCodename string `json:"versionCodename,omitempty"` - BuildID string `json:"buildID,omitempty"` - ImageID string `json:"imageID,omitempty"` - ImageVersion string `json:"imageVersion,omitempty"` - Variant string `json:"variant,omitempty"` - VariantID string `json:"variantID,omitempty"` - HomeURL string `json:"homeURL,omitempty"` - SupportURL string `json:"supportURL,omitempty"` - BugReportURL string `json:"bugReportURL,omitempty"` - PrivacyPolicyURL string `json:"privacyPolicyURL,omitempty"` - CPEName string `json:"cpeName,omitempty"` - SupportEnd string `json:"supportEnd,omitempty"` - ExtendedSupport bool `json:"extendedSupport,omitempty"` + // PrettyName is a human-readable operating system name with version. + PrettyName string `json:"prettyName,omitempty"` + + // Name is the operating system name without version information. + Name string `json:"name,omitempty"` + + // ID is the lower-case operating system identifier (e.g., "ubuntu", "rhel"). + ID string `json:"id,omitempty"` + + // IDLike is a list of operating system IDs this distribution is similar to or derived from. + IDLike IDLikes `json:"idLike,omitempty"` + + // Version is the operating system version including codename if available. + Version string `json:"version,omitempty"` + + // VersionID is the operating system version number or identifier. + VersionID string `json:"versionID,omitempty"` + + // VersionCodename is the operating system release codename (e.g., "jammy", "bullseye"). + VersionCodename string `json:"versionCodename,omitempty"` + + // BuildID is a build identifier for the operating system. + BuildID string `json:"buildID,omitempty"` + + // ImageID is an identifier for container or cloud images. + ImageID string `json:"imageID,omitempty"` + + // ImageVersion is the version for container or cloud images. + ImageVersion string `json:"imageVersion,omitempty"` + + // Variant is the operating system variant name (e.g., "Server", "Workstation"). + Variant string `json:"variant,omitempty"` + + // VariantID is the lower-case operating system variant identifier. + VariantID string `json:"variantID,omitempty"` + + // HomeURL is the homepage URL for the operating system. + HomeURL string `json:"homeURL,omitempty"` + + // SupportURL is the support or help URL for the operating system. + SupportURL string `json:"supportURL,omitempty"` + + // BugReportURL is the bug reporting URL for the operating system. + BugReportURL string `json:"bugReportURL,omitempty"` + + // PrivacyPolicyURL is the privacy policy URL for the operating system. + PrivacyPolicyURL string `json:"privacyPolicyURL,omitempty"` + + // CPEName is the Common Platform Enumeration name for the operating system. + CPEName string `json:"cpeName,omitempty"` + + // SupportEnd is the end of support date or version identifier. + SupportEnd string `json:"supportEnd,omitempty"` + + // ExtendedSupport indicates whether extended security or support is available. + ExtendedSupport bool `json:"extendedSupport,omitempty"` } func (s *IDLikes) UnmarshalJSON(data []byte) error { diff --git a/syft/format/syftjson/model/package.go b/syft/format/syftjson/model/package.go index 420376e29..eb59e78a7 100644 --- a/syft/format/syftjson/model/package.go +++ b/syft/format/syftjson/model/package.go @@ -36,22 +36,40 @@ type PackageBasicData struct { PURL string `json:"purl"` } +// cpes is a collection of Common Platform Enumeration identifiers for a package. type cpes []CPE +// CPE represents a Common Platform Enumeration identifier used for matching packages to known vulnerabilities in security databases. type CPE struct { - Value string `json:"cpe"` + // Value is the CPE string identifier. + Value string `json:"cpe"` + + // Source is the source where this CPE was obtained or generated from. Source string `json:"source,omitempty"` } +// licenses is a collection of license findings associated with a package. type licenses []License +// License represents software license information discovered for a package, including SPDX expressions and supporting evidence locations. type License struct { - Value string `json:"value"` - SPDXExpression string `json:"spdxExpression"` - Type license.Type `json:"type"` - URLs []string `json:"urls"` - Locations []file.Location `json:"locations"` - Contents string `json:"contents,omitempty"` + // Value is the raw license identifier or expression as found. + Value string `json:"value"` + + // SPDXExpression is the parsed SPDX license expression. + SPDXExpression string `json:"spdxExpression"` + + // Type is the license type classification (e.g., declared, concluded, discovered). + Type license.Type `json:"type"` + + // URLs are URLs where license text or information can be found. + URLs []string `json:"urls"` + + // Locations are file locations where this license was discovered. + Locations []file.Location `json:"locations"` + + // Contents is the full license text content. + Contents string `json:"contents,omitempty"` } func newModelLicensesFromValues(licenses []string) (ml []License) { diff --git a/syft/format/syftjson/model/relationship.go b/syft/format/syftjson/model/relationship.go index 46f6da22d..e17a5bd97 100644 --- a/syft/format/syftjson/model/relationship.go +++ b/syft/format/syftjson/model/relationship.go @@ -1,8 +1,16 @@ package model +// Relationship represents a directed relationship between two artifacts in the SBOM, such as package-contains-file or package-depends-on-package. type Relationship struct { - Parent string `json:"parent"` - Child string `json:"child"` - Type string `json:"type"` + // Parent is the ID of the parent artifact in this relationship. + Parent string `json:"parent"` + + // Child is the ID of the child artifact in this relationship. + Child string `json:"child"` + + // Type is the relationship type (e.g., "contains", "dependency-of", "ancestor-of"). + Type string `json:"type"` + + // Metadata contains additional relationship-specific metadata. Metadata interface{} `json:"metadata,omitempty"` } diff --git a/syft/format/syftjson/model/source.go b/syft/format/syftjson/model/source.go index 750e31956..83a2d87f0 100644 --- a/syft/format/syftjson/model/source.go +++ b/syft/format/syftjson/model/source.go @@ -11,18 +11,25 @@ import ( "github.com/anchore/syft/syft/source" ) -// Source object represents the thing that was cataloged -// Note: syft currently makes no claims or runs any logic to determine the Supplier field below - -// Instead, the Supplier can be determined by the user of syft and passed as a config or flag to help fulfill -// the NTIA minimum elements. For mor information see the NTIA framing document below -// https://www.ntia.gov/files/ntia/publications/framingsbom_20191112.pdf +// Source represents the artifact that was analyzed to generate this SBOM, such as a container image, directory, or file archive. +// The Supplier field can be provided by users to fulfill NTIA minimum elements requirements. type Source struct { - ID string `json:"id"` - Name string `json:"name"` - Version string `json:"version"` - Supplier string `json:"supplier,omitempty"` - Type string `json:"type"` + // ID is a unique identifier for the analyzed source artifact. + ID string `json:"id"` + + // Name is the name of the analyzed artifact (e.g., image name, directory path). + Name string `json:"name"` + + // Version is the version of the analyzed artifact (e.g., image tag). + Version string `json:"version"` + + // Supplier is supplier information, which can be user-provided for NTIA minimum elements compliance. + Supplier string `json:"supplier,omitempty"` + + // Type is the source type (e.g., "image", "directory", "file"). + Type string `json:"type"` + + // Metadata contains additional source-specific metadata. Metadata interface{} `json:"metadata"` } diff --git a/syft/pkg/alpm.go b/syft/pkg/alpm.go index e716c26c2..dce03a281 100644 --- a/syft/pkg/alpm.go +++ b/syft/pkg/alpm.go @@ -58,6 +58,7 @@ type AlpmDBEntry struct { Depends []string `mapstructure:"depends" json:"depends,omitempty"` } +// AlpmFileRecord represents a single file entry within an Arch Linux package with its associated metadata tracked by pacman. type AlpmFileRecord struct { // Path is the file path relative to the filesystem root Path string `mapstruture:"path" json:"path,omitempty"` diff --git a/syft/pkg/microsoft.go b/syft/pkg/microsoft.go index 80c345c28..88dab5ba4 100644 --- a/syft/pkg/microsoft.go +++ b/syft/pkg/microsoft.go @@ -1,10 +1,7 @@ package pkg -// MicrosoftKbPatch is slightly odd in how it is expected to map onto data. -// This is critical to grasp because there is no MSRC cataloger. The `ProductID` -// field is expected to be the MSRC Product ID, for example: -// "Windows 10 Version 1703 for 32-bit Systems". -// `Kb` is expected to be the actual KB number, for example "5001028" +// MicrosoftKbPatch represents a Windows Knowledge Base patch identifier associated with a specific Microsoft product from the MSRC (Microsoft Security Response Center). +// This type captures both the product being patched and the KB article number for the update. type MicrosoftKbPatch struct { // ProductID is MSRC Product ID (e.g. "Windows 10 Version 1703 for 32-bit Systems") ProductID string `toml:"product_id" json:"product_id"` diff --git a/syft/pkg/npm.go b/syft/pkg/npm.go index d5fdf85d7..24d7f4d3a 100644 --- a/syft/pkg/npm.go +++ b/syft/pkg/npm.go @@ -48,6 +48,7 @@ type YarnLockEntry struct { Dependencies map[string]string `mapstructure:"dependencies" json:"dependencies"` } +// PnpmLockResolution contains package resolution metadata from pnpm lockfiles, including the integrity hash used for verification. type PnpmLockResolution struct { // Integrity is Subresource Integrity hash for verification (SRI format) Integrity string `mapstructure:"integrity" json:"integrity"`