diff --git a/go.mod b/go.mod index eef14a38b..1bb2e36a9 100644 --- a/go.mod +++ b/go.mod @@ -177,7 +177,7 @@ require ( github.com/hashicorp/go-version v1.6.0 // indirect github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect github.com/huandu/xstrings v1.5.0 // indirect - github.com/iancoleman/orderedmap v0.0.0-20190318233801-ac98e3ecb4b0 // indirect + github.com/iancoleman/orderedmap v0.0.0-20190318233801-ac98e3ecb4b0 github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect github.com/kevinburke/ssh_config v1.2.0 // indirect diff --git a/schema/json/schema-16.0.40.json b/schema/json/schema-16.0.40.json index 3135b0f17..cd8198acb 100644 --- a/schema/json/schema-16.0.40.json +++ b/schema/json/schema-16.0.40.json @@ -6,58 +6,72 @@ "AlpmDbEntry": { "properties": { "basepackage": { - "type": "string" + "type": "string", + "description": "BasePackage is the base package name this package was built from (source package in Arch build system)" }, "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the desc file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the desc file" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture as defined in Arch architecture spec (e.g. x86_64, aarch64, or \"any\" for arch-independent packages)" }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the installed size in bytes" }, "packager": { - "type": "string" + "type": "string", + "description": "Packager is the name and email of the person who packaged this (RFC822 format)" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the upstream project URL" }, "validation": { - "type": "string" + "type": "string", + "description": "Validation is the validation method used for package integrity (e.g. pgp signature, sha256 checksum)" }, "reason": { - "type": "integer" + "type": "integer", + "description": "Reason is the installation reason tracked by pacman (0=explicitly installed by user, 1=installed as dependency)" }, "files": { "items": { "$ref": "#/$defs/AlpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" }, "backup": { "items": { "$ref": "#/$defs/AlpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Backup is the list of configuration files that pacman backs up before upgrades" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are virtual packages provided by this package (allows other packages to depend on capabilities rather than specific packages)" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the runtime dependencies required by this package" } }, "type": "object", @@ -74,37 +88,46 @@ "reason", "files", "backup" - ] + ], + "description": "AlpmDBEntry is a struct that represents the package data stored in the pacman flat-file stores for arch linux." }, "AlpmFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "type": { - "type": "string" + "type": "string", + "description": "Type is the file type (e.g. regular file, directory, symlink)" }, "uid": { - "type": "string" + "type": "string", + "description": "UID is the file owner user ID as recorded by pacman" }, "gid": { - "type": "string" + "type": "string", + "description": "GID is the file owner group ID as recorded by pacman" }, "time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Time is the file modification timestamp" }, "size": { - "type": "string" + "type": "string", + "description": "Size is the file size in bytes" }, "link": { - "type": "string" + "type": "string", + "description": "Link is the symlink target path if this is a symlink" }, "digest": { "items": { "$ref": "#/$defs/Digest" }, - "type": "array" + "type": "array", + "description": "Digests contains file content hashes for integrity verification" } }, "type": "object" @@ -112,55 +135,69 @@ "ApkDbEntry": { "properties": { "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the installed file" }, "originPackage": { - "type": "string" + "type": "string", + "description": "OriginPackage is the original source package name this binary was built from (used to track which aport/source built this)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is the package maintainer name and email" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the installed file" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the upstream project URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the package archive size in bytes (.apk file size)" }, "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is the total size of installed files in bytes" }, "pullDependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the runtime dependencies required by this package" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are virtual packages provided by this package (for capability-based dependencies)" }, "pullChecksum": { - "type": "string" + "type": "string", + "description": "Checksum is the package content checksum for integrity verification" }, "gitCommitOfApkPort": { - "type": "string" + "type": "string", + "description": "GitCommit is the git commit hash of the APK port definition in Alpine's aports repository" }, "files": { "items": { "$ref": "#/$defs/ApkFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" } }, "type": "object", @@ -179,30 +216,37 @@ "pullChecksum", "gitCommitOfApkPort", "files" - ] + ], + "description": "ApkDBEntry represents all captured data for the alpine linux package manager flat-file store." }, "ApkFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "ownerUid": { - "type": "string" + "type": "string", + "description": "OwnerUID is the file owner user ID" }, "ownerGid": { - "type": "string" + "type": "string", + "description": "OwnerGID is the file owner group ID" }, "permissions": { - "type": "string" + "type": "string", + "description": "Permissions is the file permission mode string (e.g. \"0755\", \"0644\")" }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest is the file content hash for integrity verification" } }, "type": "object", "required": [ "path" - ] + ], + "description": "ApkFileRecord represents a single file listing and metadata from a APK DB entry (which may have many of these file records)." }, "BinarySignature": { "properties": { @@ -216,33 +260,41 @@ "type": "object", "required": [ "matches" - ] + ], + "description": "BinarySignature represents a set of matched values within a binary file." }, "BitnamiSbomEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the Bitnami SPDX file" }, "arch": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture (amd64 or arm64 in Bitnami images)" }, "distro": { - "type": "string" + "type": "string", + "description": "Distro is the distribution name this package is for (base OS like debian, ubuntu, etc.)" }, "revision": { - "type": "string" + "type": "string", + "description": "Revision is the Bitnami-specific package revision number (incremented for Bitnami rebuilds of same upstream version)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the Bitnami SPDX file" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the installation path in the filesystem where the package is located" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files are the file paths owned by this package (tracked via SPDX relationships)" } }, "type": "object", @@ -254,105 +306,129 @@ "version", "path", "files" - ] + ], + "description": "BitnamiSBOMEntry represents all captured data from Bitnami packages described in Bitnami' SPDX files." }, "CConanFileEntry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConanfileEntry represents a single \"Requires\" entry from a conanfile.txt." }, "CConanInfoEntry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" }, "package_id": { - "type": "string" + "type": "string", + "description": "PackageID is a unique package variant identifier" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConaninfoEntry represents a single \"full_requires\" entry from a conaninfo.txt." }, "CConanLockEntry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" }, "package_id": { - "type": "string" + "type": "string", + "description": "PackageID is a unique package variant identifier computed from settings/options (static hash in Conan 1.x, can have collisions with complex dependency graphs)" }, "prev": { - "type": "string" + "type": "string", + "description": "Prev is the previous lock entry reference for versioning" }, "requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Requires are the runtime package dependencies" }, "build_requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "BuildRequires are the build-time dependencies (e.g. cmake, compilers)" }, "py_requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "PythonRequires are the Python dependencies needed for Conan recipes" }, "options": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "Options are package configuration options as key-value pairs (e.g. shared=True, fPIC=True)" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the filesystem path to the package in Conan cache" }, "context": { - "type": "string" + "type": "string", + "description": "Context is the build context information" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConanV1LockEntry represents a single \"node\" entry from a conan.lock V1 file." }, "CConanLockV2Entry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" }, "packageID": { - "type": "string" + "type": "string", + "description": "PackageID is a unique package variant identifier (dynamic in Conan 2.0, more accurate than V1)" }, "username": { - "type": "string" + "type": "string", + "description": "Username is the Conan user/organization name" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is the Conan channel name indicating stability/purpose (e.g. stable, testing, experimental)" }, "recipeRevision": { - "type": "string" + "type": "string", + "description": "RecipeRevision is a git-like revision hash (RREV) of the recipe" }, "packageRevision": { - "type": "string" + "type": "string", + "description": "PackageRevision is a git-like revision hash of the built binary package" }, "timestamp": { - "type": "string" + "type": "string", + "description": "TimeStamp is when this package was built/locked" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConanV2LockEntry represents a single \"node\" entry from a conan.lock V2 file." }, "CPE": { "properties": { @@ -381,104 +457,131 @@ "required": [ "classifier", "location" - ] + ], + "description": "ClassifierMatch represents a single matched value within a binary file and the \"class\" name the search pattern represents." }, "CocoaPodfileLockEntry": { "properties": { "checksum": { - "type": "string" + "type": "string", + "description": "Checksum is the SHA-1 hash of the podspec file for integrity verification (generated via `pod ipc spec ... | openssl sha1`), ensuring all team members use the same pod specification version" } }, "type": "object", "required": [ "checksum" - ] + ], + "description": "CocoaPodfileLockEntry represents a single entry from the \"Pods\" section of a Podfile.lock file." }, "CondaLink": { "properties": { "source": { - "type": "string" + "type": "string", + "description": "Source is the original path where the package was extracted from cache." }, "type": { - "type": "integer" + "type": "integer", + "description": "Type indicates the link type (1 for hard link, 2 for soft link, 3 for copy)." } }, "type": "object", "required": [ "source", "type" - ] + ], + "description": "CondaLink represents link metadata from a Conda package's link.json file describing package installation source." }, "CondaMetadataEntry": { "properties": { "arch": { - "type": "string" + "type": "string", + "description": "Arch is the target CPU architecture for the package (e.g., \"arm64\", \"x86_64\")." }, "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the conda-meta JSON file." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the conda-meta JSON file." }, "build": { - "type": "string" + "type": "string", + "description": "Build is the build string identifier (e.g., \"h90dfc92_1014\")." }, "build_number": { - "type": "integer" + "type": "integer", + "description": "BuildNumber is the sequential build number for this version." }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is the Conda channel URL where the package was retrieved from." }, "subdir": { - "type": "string" + "type": "string", + "description": "Subdir is the subdirectory within the channel (e.g., \"osx-arm64\", \"linux-64\")." }, "noarch": { - "type": "string" + "type": "string", + "description": "Noarch indicates if the package is platform-independent (e.g., \"python\", \"generic\")." }, "license": { - "type": "string" + "type": "string", + "description": "License is the package license identifier." }, "license_family": { - "type": "string" + "type": "string", + "description": "LicenseFamily is the general license category (e.g., \"MIT\", \"Apache\", \"GPL\")." }, "md5": { - "type": "string" + "type": "string", + "description": "MD5 is the MD5 hash of the package archive." }, "sha256": { - "type": "string" + "type": "string", + "description": "SHA256 is the SHA-256 hash of the package archive." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the package archive size in bytes." }, "timestamp": { - "type": "integer" + "type": "integer", + "description": "Timestamp is the Unix timestamp when the package was built." }, "fn": { - "type": "string" + "type": "string", + "description": "Filename is the original package archive filename (e.g., \"zlib-1.2.11-h90dfc92_1014.tar.bz2\")." }, "url": { - "type": "string" + "type": "string", + "description": "URL is the full download URL for the package archive." }, "extracted_package_dir": { - "type": "string" + "type": "string", + "description": "ExtractedPackageDir is the local cache directory where the package was extracted." }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends is the list of runtime dependencies with version constraints." }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files is the list of files installed by this package." }, "paths_data": { - "$ref": "#/$defs/CondaPathsData" + "$ref": "#/$defs/CondaPathsData", + "description": "PathsData contains detailed file metadata from the paths.json file." }, "link": { - "$ref": "#/$defs/CondaLink" + "$ref": "#/$defs/CondaLink", + "description": "Link contains installation source metadata from the link.json file." } }, "type": "object", @@ -487,24 +590,30 @@ "version", "build", "build_number" - ] + ], + "description": "CondaMetaPackage represents metadata for a Conda package extracted from the conda-meta/*.json files." }, "CondaPathData": { "properties": { "_path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the Conda environment root." }, "path_type": { - "type": "string" + "type": "string", + "description": "PathType indicates the link type for the file (e.g., \"hardlink\", \"softlink\", \"directory\")." }, "sha256": { - "type": "string" + "type": "string", + "description": "SHA256 is the SHA-256 hash of the file contents." }, "sha256_in_prefix": { - "type": "string" + "type": "string", + "description": "SHA256InPrefix is the SHA-256 hash of the file after prefix replacement during installation." }, "size_in_bytes": { - "type": "integer" + "type": "integer", + "description": "SizeInBytes is the file size in bytes." } }, "type": "object", @@ -514,103 +623,126 @@ "sha256", "sha256_in_prefix", "size_in_bytes" - ] + ], + "description": "CondaPathData represents metadata for a single file within a Conda package from the paths.json file." }, "CondaPathsData": { "properties": { "paths_version": { - "type": "integer" + "type": "integer", + "description": "PathsVersion is the schema version of the paths data format." }, "paths": { "items": { "$ref": "#/$defs/CondaPathData" }, - "type": "array" + "type": "array", + "description": "Paths is the list of file metadata entries for all files in the package." } }, "type": "object", "required": [ "paths_version", "paths" - ] + ], + "description": "CondaPathsData represents the paths.json file structure from a Conda package containing file metadata." }, "Coordinates": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "RealPath is the canonical absolute form of the path accessed (all symbolic links have been followed and relative path components like '.' and '..' have been removed)." }, "layerID": { - "type": "string" + "type": "string", + "description": "FileSystemID is an ID representing and entire filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank." } }, "type": "object", "required": [ "path" - ] + ], + "description": "Coordinates contains the minimal information needed to describe how to find a file within any possible source object (e.g." }, "DartPubspec": { "properties": { "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is the package homepage URL" }, "repository": { - "type": "string" + "type": "string", + "description": "Repository is the source code repository URL" }, "documentation": { - "type": "string" + "type": "string", + "description": "Documentation is the documentation site URL" }, "publish_to": { - "type": "string" + "type": "string", + "description": "PublishTo is the package repository to publish to, or \"none\" to prevent accidental publishing" }, "environment": { - "$ref": "#/$defs/DartPubspecEnvironment" + "$ref": "#/$defs/DartPubspecEnvironment", + "description": "Environment is SDK version constraints for Dart and Flutter" }, "platforms": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Platforms are the supported platforms (Android, iOS, web, etc.)" }, "ignored_advisories": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "IgnoredAdvisories are the security advisories to explicitly ignore for this package" } }, - "type": "object" + "type": "object", + "description": "DartPubspec is a struct that represents a package described in a pubspec.yaml file" }, "DartPubspecEnvironment": { "properties": { "sdk": { - "type": "string" + "type": "string", + "description": "SDK is the Dart SDK version constraint (e.g. \"\u003e=2.12.0 \u003c3.0.0\")" }, "flutter": { - "type": "string" + "type": "string", + "description": "Flutter is the Flutter SDK version constraint if this is a Flutter package" } }, - "type": "object" + "type": "object", + "description": "DartPubspecEnvironment represents SDK version constraints from the environment section of pubspec.yaml." }, "DartPubspecLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the pubspec.lock file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the pubspec.lock file" }, "hosted_url": { - "type": "string" + "type": "string", + "description": "HostedURL is the URL of the package repository for hosted packages (typically pub.dev, but can be custom repository identified by hosted-url). When PUB_HOSTED_URL environment variable changes, lockfile tracks the source." }, "vcs_url": { - "type": "string" + "type": "string", + "description": "VcsURL is the URL of the VCS repository for git/path dependencies (for packages fetched from version control systems like Git)" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "DartPubspecLockEntry is a struct that represents a single entry found in the \"packages\" section in a Dart pubspec.lock file." }, "Descriptor": { "properties": { @@ -626,22 +758,26 @@ "required": [ "name", "version" - ] + ], + "description": "Descriptor describes what created the document as well as surrounding metadata" }, "Digest": { "properties": { "algorithm": { - "type": "string" + "type": "string", + "description": "Algorithm specifies the hash algorithm used (e.g., \"sha256\", \"md5\")." }, "value": { - "type": "string" + "type": "string", + "description": "Value is the hexadecimal string representation of the hash." } }, "type": "object", "required": [ "algorithm", "value" - ] + ], + "description": "Digest represents a cryptographic hash of file contents." }, "Document": { "properties": { @@ -684,24 +820,30 @@ "distro", "descriptor", "schema" - ] + ], + "description": "Document represents the syft cataloging findings as a JSON document" }, "DotnetDepsEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the deps.json file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the deps.json file" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the relative path to the package within the deps structure (e.g. \"app.metrics/3.0.0\")" }, "sha512": { - "type": "string" + "type": "string", + "description": "Sha512 is the SHA-512 hash of the NuGet package content WITHOUT the signed content for verification (won't match hash from NuGet API or manual calculation of .nupkg file)" }, "hashPath": { - "type": "string" + "type": "string", + "description": "HashPath is the relative path to the .nupkg.sha512 hash file (e.g. \"app.metrics.3.0.0.nupkg.sha512\")" }, "executables": { "patternProperties": { @@ -709,7 +851,8 @@ "$ref": "#/$defs/DotnetPortableExecutableEntry" } }, - "type": "object" + "type": "object", + "description": "Executables are the map of .NET Portable Executable files within this package with their version resources" } }, "type": "object", @@ -719,21 +862,26 @@ "path", "sha512", "hashPath" - ] + ], + "description": "DotnetDepsEntry is a struct that represents a single entry found in the \"libraries\" section in a .NET [*.]deps.json file." }, "DotnetPackagesLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the packages.lock.json file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the packages.lock.json file" }, "contentHash": { - "type": "string" + "type": "string", + "description": "ContentHash is the hash of the package content for verification" }, "type": { - "type": "string" + "type": "string", + "description": "Type is the dependency type indicating how this dependency was added (Direct=explicit in project file, Transitive=pulled in by another package, Project=project reference)" } }, "type": "object", @@ -742,30 +890,38 @@ "version", "contentHash", "type" - ] + ], + "description": "DotnetPackagesLockEntry is a struct that represents a single entry found in the \"dependencies\" section in a .NET packages.lock.json file." }, "DotnetPortableExecutableEntry": { "properties": { "assemblyVersion": { - "type": "string" + "type": "string", + "description": "AssemblyVersion is the .NET assembly version number (strong-named version)" }, "legalCopyright": { - "type": "string" + "type": "string", + "description": "LegalCopyright is the copyright notice string" }, "comments": { - "type": "string" + "type": "string", + "description": "Comments are additional comments or description embedded in PE resources" }, "internalName": { - "type": "string" + "type": "string", + "description": "InternalName is the internal name of the file" }, "companyName": { - "type": "string" + "type": "string", + "description": "CompanyName is the company that produced the file" }, "productName": { - "type": "string" + "type": "string", + "description": "ProductName is the name of the product this file is part of" }, "productVersion": { - "type": "string" + "type": "string", + "description": "ProductVersion is the version of the product (may differ from AssemblyVersion)" } }, "type": "object", @@ -775,54 +931,66 @@ "companyName", "productName", "productVersion" - ] + ], + "description": "DotnetPortableExecutableEntry is a struct that represents a single entry found within \"VersionResources\" section of a .NET Portable Executable binary file." }, "DpkgArchiveEntry": { "properties": { "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the status file" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source package name this binary was built from (one source can produce multiple binary packages)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the binary package version as found in the status file" }, "sourceVersion": { - "type": "string" + "type": "string", + "description": "SourceVersion is the source package version (may differ from binary version when binNMU rebuilds occur)" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target architecture per Debian spec (specific arch like amd64/arm64, wildcard like any, architecture-independent \"all\", or \"source\" for source packages)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is the package maintainer's name and email in RFC822 format (name must come first, then email in angle brackets)" }, "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is the total size of installed files in kilobytes" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are the virtual packages provided by this package (allows other packages to depend on capabilities. Can include versioned provides like \"libdigest-md5-perl (= 2.55.01)\")" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the packages required for this package to function (will not be installed unless these requirements are met, creates strict ordering constraint)" }, "preDepends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "PreDepends are the packages that must be installed and configured BEFORE even starting installation of this package (stronger than Depends, discouraged unless absolutely necessary as it adds strict constraints for apt)" }, "files": { "items": { "$ref": "#/$defs/DpkgFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" } }, "type": "object", @@ -835,54 +1003,66 @@ "maintainer", "installedSize", "files" - ] + ], + "description": "DpkgArchiveEntry represents package metadata extracted from a .deb archive file." }, "DpkgDbEntry": { "properties": { "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the status file" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source package name this binary was built from (one source can produce multiple binary packages)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the binary package version as found in the status file" }, "sourceVersion": { - "type": "string" + "type": "string", + "description": "SourceVersion is the source package version (may differ from binary version when binNMU rebuilds occur)" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target architecture per Debian spec (specific arch like amd64/arm64, wildcard like any, architecture-independent \"all\", or \"source\" for source packages)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is the package maintainer's name and email in RFC822 format (name must come first, then email in angle brackets)" }, "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is the total size of installed files in kilobytes" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are the virtual packages provided by this package (allows other packages to depend on capabilities. Can include versioned provides like \"libdigest-md5-perl (= 2.55.01)\")" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the packages required for this package to function (will not be installed unless these requirements are met, creates strict ordering constraint)" }, "preDepends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "PreDepends are the packages that must be installed and configured BEFORE even starting installation of this package (stronger than Depends, discouraged unless absolutely necessary as it adds strict constraints for apt)" }, "files": { "items": { "$ref": "#/$defs/DpkgFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" } }, "type": "object", @@ -895,54 +1075,68 @@ "maintainer", "installedSize", "files" - ] + ], + "description": "DpkgDBEntry represents all captured data for a Debian package DB entry; available fields are described at http://manpages.ubuntu.com/manpages/xenial/man1/dpkg-query.1.html in the --showformat section." }, "DpkgFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest is the file content hash (typically MD5 for dpkg compatibility with legacy systems)" }, "isConfigFile": { - "type": "boolean" + "type": "boolean", + "description": "IsConfigFile is whether this file is marked as a configuration file (dpkg will preserve user modifications during upgrades)" } }, "type": "object", "required": [ "path", "isConfigFile" - ] + ], + "description": "DpkgFileRecord represents a single file attributed to a debian package." }, "ELFSecurityFeatures": { "properties": { "symbolTableStripped": { - "type": "boolean" + "type": "boolean", + "description": "SymbolTableStripped indicates whether debugging symbols have been removed." }, "stackCanary": { - "type": "boolean" + "type": "boolean", + "description": "StackCanary indicates whether stack smashing protection is enabled." }, "nx": { - "type": "boolean" + "type": "boolean", + "description": "NoExecutable indicates whether NX (no-execute) protection is enabled for the stack." }, "relRO": { - "type": "string" + "type": "string", + "description": "RelocationReadOnly indicates the RELRO protection level." }, "pie": { - "type": "boolean" + "type": "boolean", + "description": "PositionIndependentExecutable indicates whether the binary is compiled as PIE." }, "dso": { - "type": "boolean" + "type": "boolean", + "description": "DynamicSharedObject indicates whether the binary is a shared library." }, "safeStack": { - "type": "boolean" + "type": "boolean", + "description": "LlvmSafeStack represents a compiler-based security mechanism that separates the stack into a safe stack for storing return addresses and other critical data, and an unsafe stack for everything else, to mitigate stack-based memory corruption errors\nsee https://clang.llvm.org/docs/SafeStack.html" }, "cfi": { - "type": "boolean" + "type": "boolean", + "description": "ControlFlowIntegrity represents runtime checks to ensure a program's control flow adheres to the legal paths determined at compile time, thus protecting against various types of control-flow hijacking attacks\nsee https://clang.llvm.org/docs/ControlFlowIntegrity.html" }, "fortify": { - "type": "boolean" + "type": "boolean", + "description": "ClangFortifySource is a broad suite of extensions to libc aimed at catching misuses of common library functions\nsee https://android.googlesource.com/platform//bionic/+/d192dbecf0b2a371eb127c0871f77a9caf81c4d2/docs/clang_fortify_anatomy.md" } }, "type": "object", @@ -952,53 +1146,68 @@ "relRO", "pie", "dso" - ] + ], + "description": "ELFSecurityFeatures captures security hardening and protection mechanisms in ELF binaries." }, "ElfBinaryPackageNoteJsonPayload": { "properties": { "type": { - "type": "string" + "type": "string", + "description": "Type is the type of the package (e.g. \"rpm\", \"deb\", \"apk\", etc.)" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture of the binary package (e.g. \"amd64\", \"arm\", etc.)" }, "osCPE": { - "type": "string" + "type": "string", + "description": "OSCPE is a CPE name for the OS, typically corresponding to CPE_NAME in os-release (e.g. cpe:/o:fedoraproject:fedora:33)" }, "os": { - "type": "string" + "type": "string", + "description": "OS is the OS name, typically corresponding to ID in os-release (e.g. \"fedora\")" }, "osVersion": { - "type": "string" + "type": "string", + "description": "osVersion is the version of the OS, typically corresponding to VERSION_ID in os-release (e.g. \"33\")" }, "system": { - "type": "string" + "type": "string", + "description": "System is a context-specific name for the system that the binary package is intended to run on or a part of" }, "vendor": { - "type": "string" + "type": "string", + "description": "Vendor is the individual or organization that produced the source code for the binary" }, "sourceRepo": { - "type": "string" + "type": "string", + "description": "SourceRepo is the URL to the source repository for which the binary was built from" }, "commit": { - "type": "string" + "type": "string", + "description": "Commit is the commit hash of the source repository for which the binary was built from" } }, - "type": "object" + "type": "object", + "description": "ELFBinaryPackageNoteJSONPayload Represents metadata captured from the .note.package section of an ELF-formatted binary" }, "ElixirMixLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the mix.lock file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the mix.lock file" }, "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the outer checksum (SHA-256) of the entire Hex package tarball for integrity verification (preferred method, replaces deprecated inner checksum)" }, "pkgHashExt": { - "type": "string" + "type": "string", + "description": "PkgHashExt is the extended package hash format (inner checksum is deprecated - SHA-256 of concatenated file contents excluding CHECKSUM file, now replaced by outer checksum)" } }, "type": "object", @@ -1007,21 +1216,26 @@ "version", "pkgHash", "pkgHashExt" - ] + ], + "description": "ElixirMixLockEntry is a struct that represents a single entry in a mix.lock file" }, "ErlangRebarLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the rebar.lock file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the rebar.lock file" }, "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the outer checksum (SHA-256) of the entire Hex package tarball for integrity verification (preferred method over deprecated inner checksum)" }, "pkgHashExt": { - "type": "string" + "type": "string", + "description": "PkgHashExt is the extended package hash format (inner checksum deprecated - was SHA-256 of concatenated file contents)" } }, "type": "object", @@ -1030,27 +1244,33 @@ "version", "pkgHash", "pkgHashExt" - ] + ], + "description": "ErlangRebarLockEntry represents a single package entry from the \"deps\" section within an Erlang rebar.lock file." }, "Executable": { "properties": { "format": { - "type": "string" + "type": "string", + "description": "Format denotes either ELF, Mach-O, or PE" }, "hasExports": { - "type": "boolean" + "type": "boolean", + "description": "HasExports indicates whether the binary exports symbols." }, "hasEntrypoint": { - "type": "boolean" + "type": "boolean", + "description": "HasEntrypoint indicates whether the binary has an entry point function." }, "importedLibraries": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "ImportedLibraries lists the shared libraries required by this executable." }, "elfSecurityFeatures": { - "$ref": "#/$defs/ELFSecurityFeatures" + "$ref": "#/$defs/ELFSecurityFeatures", + "description": "ELFSecurityFeatures contains ELF-specific security hardening information when Format is ELF." } }, "type": "object", @@ -1059,7 +1279,8 @@ "hasExports", "hasEntrypoint", "importedLibraries" - ] + ], + "description": "Executable contains metadata about binary files and their security features." }, "File": { "properties": { @@ -1181,116 +1402,144 @@ "GithubActionsUseStatement": { "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value is the action reference (e.g. \"actions/checkout@v3\")" }, "comment": { - "type": "string" + "type": "string", + "description": "Comment is the inline comment associated with this uses statement" } }, "type": "object", "required": [ "value" - ] + ], + "description": "GitHubActionsUseStatement represents a single 'uses' statement in a GitHub Actions workflow file referencing an action or reusable workflow." }, "GoModuleBuildinfoEntry": { "properties": { "goBuildSettings": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "BuildSettings contains the Go build settings and flags used to compile the binary (e.g., GOARCH, GOOS, CGO_ENABLED)." }, "goCompiledVersion": { - "type": "string" + "type": "string", + "description": "GoCompiledVersion is the version of Go used to compile the binary." }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture for the binary (extracted from GOARCH build setting)." }, "h1Digest": { - "type": "string" + "type": "string", + "description": "H1Digest is the Go module hash in h1: format for the main module from go.sum." }, "mainModule": { - "type": "string" + "type": "string", + "description": "MainModule is the main module path for the binary (e.g., \"github.com/anchore/syft\")." }, "goCryptoSettings": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "GoCryptoSettings contains FIPS and cryptographic configuration settings if present." }, "goExperiments": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "GoExperiments lists experimental Go features enabled during compilation (e.g., \"arenas\", \"cgocheck2\")." } }, "type": "object", "required": [ "goCompiledVersion", "architecture" - ] + ], + "description": "GolangBinaryBuildinfoEntry represents all captured data for a Golang binary" }, "GoModuleEntry": { "properties": { "h1Digest": { - "type": "string" + "type": "string", + "description": "H1Digest is the Go module hash in h1: format from go.sum for verifying module contents." } }, - "type": "object" + "type": "object", + "description": "GolangModuleEntry represents all captured data for a Golang source scan with go.mod/go.sum" }, "GoSourceEntry": { "properties": { "h1Digest": { - "type": "string" + "type": "string", + "description": "H1Digest is the Go module hash in h1: format from go.sum for verifying module contents." }, "os": { - "type": "string" + "type": "string", + "description": "OperatingSystem is the target OS for build constraints (e.g., \"linux\", \"darwin\", \"windows\")." }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture for build constraints (e.g., \"amd64\", \"arm64\")." }, "buildTags": { - "type": "string" + "type": "string", + "description": "BuildTags are the build tags used to conditionally compile code (e.g., \"integration,debug\")." }, "cgoEnabled": { - "type": "boolean" + "type": "boolean", + "description": "CgoEnabled indicates whether CGO was enabled for this package." } }, "type": "object", "required": [ "cgoEnabled" - ] + ], + "description": "GolangSourceEntry represents all captured data for a Golang package found through source analysis" }, "HaskellHackageStackEntry": { "properties": { "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the package content hash for verification" } }, - "type": "object" + "type": "object", + "description": "HackageStackYamlEntry represents a single entry from the \"extra-deps\" section of a stack.yaml file." }, "HaskellHackageStackLockEntry": { "properties": { "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the package content hash for verification" }, "snapshotURL": { - "type": "string" + "type": "string", + "description": "SnapshotURL is the URL to the Stack snapshot this package came from" } }, - "type": "object" + "type": "object", + "description": "HackageStackYamlLockEntry represents a single entry from the \"packages\" section of a stack.yaml.lock file." }, "HomebrewFormula": { "properties": { "tap": { - "type": "string" + "type": "string", + "description": "Tap is Homebrew tap this formula belongs to (e.g. \"homebrew/core\")" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is the upstream project homepage URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable formula description" } }, - "type": "object" + "type": "object", + "description": "HomebrewFormula represents metadata about a Homebrew formula package extracted from formula JSON files." }, "IDLikes": { "items": { @@ -1301,71 +1550,86 @@ "JavaArchive": { "properties": { "virtualPath": { - "type": "string" + "type": "string", + "description": "VirtualPath is path within the archive hierarchy, where nested entries are delimited with ':' (for nested JARs)" }, "manifest": { - "$ref": "#/$defs/JavaManifest" + "$ref": "#/$defs/JavaManifest", + "description": "Manifest is parsed META-INF/MANIFEST.MF contents" }, "pomProperties": { - "$ref": "#/$defs/JavaPomProperties" + "$ref": "#/$defs/JavaPomProperties", + "description": "PomProperties is parsed pom.properties file contents" }, "pomProject": { - "$ref": "#/$defs/JavaPomProject" + "$ref": "#/$defs/JavaPomProject", + "description": "PomProject is parsed pom.xml file contents" }, "digest": { "items": { "$ref": "#/$defs/Digest" }, - "type": "array" + "type": "array", + "description": "ArchiveDigests is cryptographic hashes of the archive file" } }, "type": "object", "required": [ "virtualPath" - ] + ], + "description": "JavaArchive encapsulates all Java ecosystem metadata for a package as well as an (optional) parent relationship." }, "JavaJvmInstallation": { "properties": { "release": { - "$ref": "#/$defs/JavaVMRelease" + "$ref": "#/$defs/JavaVMRelease", + "description": "Release is JVM release information and version details" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files are the list of files that are part of this JVM installation" } }, "type": "object", "required": [ "release", "files" - ] + ], + "description": "JavaVMInstallation represents a Java Virtual Machine installation discovered on the system with its release information and file list." }, "JavaManifest": { "properties": { "main": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "Main is main manifest attributes as key-value pairs" }, "sections": { "items": { "$ref": "#/$defs/KeyValues" }, - "type": "array" + "type": "array", + "description": "Sections are the named sections from the manifest (e.g. per-entry attributes)" } }, - "type": "object" + "type": "object", + "description": "JavaManifest represents the fields of interest extracted from a Java archive's META-INF/MANIFEST.MF file." }, "JavaPomParent": { "properties": { "groupId": { - "type": "string" + "type": "string", + "description": "GroupID is the parent Maven group identifier" }, "artifactId": { - "type": "string" + "type": "string", + "description": "ArtifactID is the parent Maven artifact identifier" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the parent version (child inherits configuration from this specific version of parent POM)" } }, "type": "object", @@ -1373,33 +1637,42 @@ "groupId", "artifactId", "version" - ] + ], + "description": "JavaPomParent contains the fields within the \u003cparent\u003e tag in a pom.xml file" }, "JavaPomProject": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the pom.xml file within the archive" }, "parent": { - "$ref": "#/$defs/JavaPomParent" + "$ref": "#/$defs/JavaPomParent", + "description": "Parent is the parent POM reference for inheritance (child POMs inherit configuration from parent)" }, "groupId": { - "type": "string" + "type": "string", + "description": "GroupID is Maven group identifier (reversed domain name like org.apache.maven)" }, "artifactId": { - "type": "string" + "type": "string", + "description": "ArtifactID is Maven artifact identifier (project name)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is project version (together with groupId and artifactId forms Maven coordinates groupId:artifactId:version)" }, "name": { - "type": "string" + "type": "string", + "description": "Name is a human-readable project name (displayed in Maven-generated documentation)" }, "description": { - "type": "string" + "type": "string", + "description": "Description is detailed project description" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the project URL (typically project website or repository)" } }, "type": "object", @@ -1409,27 +1682,34 @@ "artifactId", "version", "name" - ] + ], + "description": "JavaPomProject represents fields of interest extracted from a Java archive's pom.xml file." }, "JavaPomProperties": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the pom.properties file within the archive" }, "name": { - "type": "string" + "type": "string", + "description": "Name is the project name" }, "groupId": { - "type": "string" + "type": "string", + "description": "GroupID is Maven group identifier uniquely identifying the project across all projects (follows reversed domain name convention like com.company.project)" }, "artifactId": { - "type": "string" + "type": "string", + "description": "ArtifactID is Maven artifact identifier, the name of the jar/artifact (unique within the groupId scope)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is artifact version" }, "scope": { - "type": "string" + "type": "string", + "description": "Scope is dependency scope determining when dependency is available (compile=default all phases, test=test compilation/execution only, runtime=runtime and test not compile, provided=expected from JDK or container)" }, "extraFields": { "patternProperties": { @@ -1437,7 +1717,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Extra is additional custom properties not in standard Maven coordinates" } }, "type": "object", @@ -1447,101 +1728,131 @@ "groupId", "artifactId", "version" - ] + ], + "description": "JavaPomProperties represents the fields of interest extracted from a Java archive's pom.properties file." }, "JavaVMRelease": { "properties": { "implementor": { - "type": "string" + "type": "string", + "description": "Implementor is extracted with the `java.vendor` JVM property" }, "implementorVersion": { - "type": "string" + "type": "string", + "description": "ImplementorVersion is extracted with the `java.vendor.version` JVM property" }, "javaRuntimeVersion": { - "type": "string" + "type": "string", + "description": "JavaRuntimeVersion is extracted from the 'java.runtime.version' JVM property" }, "javaVersion": { - "type": "string" + "type": "string", + "description": "JavaVersion matches that from `java -version` command output" }, "javaVersionDate": { - "type": "string" + "type": "string", + "description": "JavaVersionDate is extracted from the 'java.version.date' JVM property" }, "libc": { - "type": "string" + "type": "string", + "description": "Libc can either be 'glibc' or 'musl'" }, "modules": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Modules is a list of JVM modules that are packaged" }, "osArch": { - "type": "string" + "type": "string", + "description": "OsArch is the target CPU architecture" }, "osName": { - "type": "string" + "type": "string", + "description": "OsName is the name of the target runtime operating system environment" }, "osVersion": { - "type": "string" + "type": "string", + "description": "OsVersion is the version of the target runtime operating system environment" }, "source": { - "type": "string" + "type": "string", + "description": "Source refers to the origin repository of OpenJDK source" }, "buildSource": { - "type": "string" + "type": "string", + "description": "BuildSource Git SHA of the build repository" }, "buildSourceRepo": { - "type": "string" + "type": "string", + "description": "BuildSourceRepo refers to rhe repository URL for the build source" }, "sourceRepo": { - "type": "string" + "type": "string", + "description": "SourceRepo refers to the OpenJDK repository URL" }, "fullVersion": { - "type": "string" + "type": "string", + "description": "FullVersion is extracted from the 'java.runtime.version' JVM property" }, "semanticVersion": { - "type": "string" + "type": "string", + "description": "SemanticVersion is derived from the OpenJDK version" }, "buildInfo": { - "type": "string" + "type": "string", + "description": "BuildInfo contains additional build information" }, "jvmVariant": { - "type": "string" + "type": "string", + "description": "JvmVariant specifies the JVM variant (e.g., Hotspot or OpenJ9)" }, "jvmVersion": { - "type": "string" + "type": "string", + "description": "JvmVersion is extracted from the 'java.vm.version' JVM property" }, "imageType": { - "type": "string" + "type": "string", + "description": "ImageType can be 'JDK' or 'JRE'" }, "buildType": { - "type": "string" + "type": "string", + "description": "BuildType can be 'commercial' (used in some older oracle JDK distributions)" } }, - "type": "object" + "type": "object", + "description": "JavaVMRelease represents JVM version and build information extracted from the release file in a Java installation." }, "JavascriptNpmPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in package.json" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in package.json" }, "author": { - "type": "string" + "type": "string", + "description": "Author is package author name" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "url": { - "type": "string" + "type": "string", + "description": "URL is repository or project URL" }, "private": { - "type": "boolean" + "type": "boolean", + "description": "Private is whether this is a private package" } }, "type": "object", @@ -1553,58 +1864,69 @@ "description", "url", "private" - ] + ], + "description": "NpmPackage represents the contents of a javascript package.json file." }, "JavascriptNpmPackageLockEntry": { "properties": { "resolved": { - "type": "string" + "type": "string", + "description": "Resolved is URL where this package was downloaded from (registry source)" }, "integrity": { - "type": "string" + "type": "string", + "description": "Integrity is Subresource Integrity hash for verification using standard SRI format (sha512-... or sha1-...). npm changed from SHA-1 to SHA-512 in newer versions. For registry sources this is the integrity from registry, for remote tarballs it's SHA-512 of the file. npm verifies tarball matches this hash before unpacking, throwing EINTEGRITY error if mismatch detected." } }, "type": "object", "required": [ "resolved", "integrity" - ] + ], + "description": "NpmPackageLockEntry represents a single entry within the \"packages\" section of a package-lock.json file." }, "JavascriptYarnLockEntry": { "properties": { "resolved": { - "type": "string" + "type": "string", + "description": "Resolved is URL where this package was downloaded from" }, "integrity": { - "type": "string" + "type": "string", + "description": "Integrity is Subresource Integrity hash for verification (SRI format)" } }, "type": "object", "required": [ "resolved", "integrity" - ] + ], + "description": "YarnLockEntry represents a single entry section of a yarn.lock file." }, "KeyValue": { "properties": { "key": { - "type": "string" + "type": "string", + "description": "Key is the key name" }, "value": { - "type": "string" + "type": "string", + "description": "Value is the value associated with the key" } }, "type": "object", "required": [ "key", "value" - ] + ], + "description": "KeyValue represents a single key-value pair." }, "KeyValues": { "items": { "$ref": "#/$defs/KeyValue" }, - "type": "array" + "type": "array", + "description": "KeyValues represents an ordered collection of key-value pairs that preserves insertion order." }, "License": { "properties": { @@ -1645,37 +1967,48 @@ "LinuxKernelArchive": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is kernel name (typically \"Linux\")" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture" }, "version": { - "type": "string" + "type": "string", + "description": "Version is kernel version string" }, "extendedVersion": { - "type": "string" + "type": "string", + "description": "ExtendedVersion is additional version information" }, "buildTime": { - "type": "string" + "type": "string", + "description": "BuildTime is when the kernel was built" }, "author": { - "type": "string" + "type": "string", + "description": "Author is who built the kernel" }, "format": { - "type": "string" + "type": "string", + "description": "Format is kernel image format (e.g. bzImage, zImage)" }, "rwRootFS": { - "type": "boolean" + "type": "boolean", + "description": "RWRootFS is whether root filesystem is mounted read-write" }, "swapDevice": { - "type": "integer" + "type": "integer", + "description": "SwapDevice is swap device number" }, "rootDevice": { - "type": "integer" + "type": "integer", + "description": "RootDevice is root device number" }, "videoMode": { - "type": "string" + "type": "string", + "description": "VideoMode is default video mode setting" } }, "type": "object", @@ -1683,36 +2016,46 @@ "name", "architecture", "version" - ] + ], + "description": "LinuxKernel represents all captured data for a Linux kernel" }, "LinuxKernelModule": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is module name" }, "version": { - "type": "string" + "type": "string", + "description": "Version is module version string" }, "sourceVersion": { - "type": "string" + "type": "string", + "description": "SourceVersion is the source code version identifier" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the filesystem path to the .ko kernel object file (absolute path)" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable module description" }, "author": { - "type": "string" + "type": "string", + "description": "Author is module author name and email" }, "license": { - "type": "string" + "type": "string", + "description": "License is module license (e.g. GPL, BSD) which must be compatible with kernel" }, "kernelVersion": { - "type": "string" + "type": "string", + "description": "KernelVersion is kernel version this module was built for" }, "versionMagic": { - "type": "string" + "type": "string", + "description": "VersionMagic is version magic string for compatibility checking (includes kernel version, SMP status, module loading capabilities like \"3.17.4-302.fc21.x86_64 SMP mod_unload modversions\"). Module will NOT load if vermagic doesn't match running kernel." }, "parameters": { "patternProperties": { @@ -1720,21 +2063,26 @@ "$ref": "#/$defs/LinuxKernelModuleParameter" } }, - "type": "object" + "type": "object", + "description": "Parameters are the module parameters that can be configured at load time (user-settable values like module options)" } }, - "type": "object" + "type": "object", + "description": "LinuxKernelModule represents a loadable kernel module (.ko file) with its metadata, parameters, and dependencies." }, "LinuxKernelModuleParameter": { "properties": { "type": { - "type": "string" + "type": "string", + "description": "Type is parameter data type (e.g. int, string, bool, array types)" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable parameter description explaining what the parameter controls" } }, - "type": "object" + "type": "object", + "description": "LinuxKernelModuleParameter represents a configurable parameter for a kernel module with its type and description." }, "LinuxRelease": { "properties": { @@ -1801,13 +2149,16 @@ "Location": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "RealPath is the canonical absolute form of the path accessed (all symbolic links have been followed and relative path components like '.' and '..' have been removed)." }, "layerID": { - "type": "string" + "type": "string", + "description": "FileSystemID is an ID representing and entire filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank." }, "accessPath": { - "type": "string" + "type": "string", + "description": "AccessPath is the path used to retrieve file contents (which may or may not have hardlinks / symlinks in the path)" }, "annotations": { "patternProperties": { @@ -1822,27 +2173,34 @@ "required": [ "path", "accessPath" - ] + ], + "description": "Location represents a path relative to a particular filesystem resolved to a specific file.Reference." }, "LuarocksPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the .rockspec file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the .rockspec file" }, "license": { - "type": "string" + "type": "string", + "description": "License is license identifier" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the source download URL" }, "dependencies": { "patternProperties": { @@ -1850,7 +2208,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Dependencies are the map of dependency names to version constraints" } }, "type": "object", @@ -1862,117 +2221,142 @@ "description", "url", "dependencies" - ] + ], + "description": "LuaRocksPackage represents a Lua package managed by the LuaRocks package manager with metadata from .rockspec files." }, "MicrosoftKbPatch": { "properties": { "product_id": { - "type": "string" + "type": "string", + "description": "ProductID is MSRC Product ID (e.g. \"Windows 10 Version 1703 for 32-bit Systems\")" }, "kb": { - "type": "string" + "type": "string", + "description": "Kb is Knowledge Base article number (e.g. \"5001028\")" } }, "type": "object", "required": [ "product_id", "kb" - ] + ], + "description": "MicrosoftKbPatch is slightly odd in how it is expected to map onto data." }, "NixDerivation": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the .drv file in Nix store" }, "system": { - "type": "string" + "type": "string", + "description": "System is target system string indicating where derivation can be built (e.g. \"x86_64-linux\", \"aarch64-darwin\"). Must match current system for local builds." }, "inputDerivations": { "items": { "$ref": "#/$defs/NixDerivationReference" }, - "type": "array" + "type": "array", + "description": "InputDerivations are the list of other derivations that were inputs to this build (dependencies)" }, "inputSources": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "InputSources are the list of source file paths that were inputs to this build" } }, - "type": "object" + "type": "object", + "description": "NixDerivation represents a Nix .drv file that describes how to build a package including inputs, outputs, and build instructions." }, "NixDerivationReference": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the referenced .drv file" }, "outputs": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Outputs are which outputs of the referenced derivation were used (e.g. [\"out\"], [\"bin\", \"dev\"])" } }, - "type": "object" + "type": "object", + "description": "NixDerivationReference represents a reference to another derivation used as a build input or runtime dependency." }, "NixStoreEntry": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is full store path for this output (e.g. /nix/store/abc123...-package-1.0)" }, "output": { - "type": "string" + "type": "string", + "description": "Output is the specific output name for multi-output packages (empty string for default \"out\" output, can be \"bin\", \"dev\", \"doc\", etc.)" }, "outputHash": { - "type": "string" + "type": "string", + "description": "OutputHash is hash prefix of the store path basename (first part before the dash)" }, "derivation": { - "$ref": "#/$defs/NixDerivation" + "$ref": "#/$defs/NixDerivation", + "description": "Derivation is information about the .drv file that describes how this package was built" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files are the list of files under the nix/store path for this package" } }, "type": "object", "required": [ "outputHash" - ] + ], + "description": "NixStoreEntry represents a package in the Nix store (/nix/store) with its derivation information and metadata." }, "OpamPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the .opam file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the .opam file" }, "licenses": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Licenses are the list of applicable licenses" }, "url": { - "type": "string" + "type": "string", + "description": "URL is download URL for the package source" }, "checksum": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Checksums are the list of checksums for verification" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the list of required dependencies" } }, "type": "object", @@ -1984,7 +2368,8 @@ "checksum", "homepage", "dependencies" - ] + ], + "description": "OpamPackage represents an OCaml package managed by the OPAM package manager with metadata from .opam files." }, "Package": { "properties": { @@ -2224,49 +2609,60 @@ "language", "cpes", "purl" - ] + ], + "description": "Package represents a pkg.Package object specialized for JSON marshaling and unmarshalling." }, "PeBinary": { "properties": { "VersionResources": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "VersionResources contains key-value pairs extracted from the PE file's version resource section (e.g., FileVersion, ProductName, CompanyName)." } }, "type": "object", "required": [ "VersionResources" - ] + ], + "description": "PEBinary represents metadata captured from a Portable Executable formatted binary (dll, exe, etc.)" }, "PhpComposerAuthors": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is author's full name" }, "email": { - "type": "string" + "type": "string", + "description": "Email is author's email address" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is author's personal or company website" } }, "type": "object", "required": [ "name" - ] + ], + "description": "PhpComposerAuthors represents author information for a PHP Composer package from the authors field in composer.json." }, "PhpComposerExternalReference": { "properties": { "type": { - "type": "string" + "type": "string", + "description": "Type is reference type (git for source VCS, zip/tar for dist archives)" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the URL to the resource (git repository URL or archive download URL)" }, "reference": { - "type": "string" + "type": "string", + "description": "Reference is git commit hash or version tag for source, or archive version for dist" }, "shasum": { - "type": "string" + "type": "string", + "description": "Shasum is SHA hash of the archive file for integrity verification (dist only)" } }, "type": "object", @@ -2274,21 +2670,26 @@ "type", "url", "reference" - ] + ], + "description": "PhpComposerExternalReference represents source or distribution information for a PHP package, indicating where the package code is retrieved from." }, "PhpComposerInstalledEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is package name in vendor/package format (e.g. symfony/console)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "source": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Source is the source repository information for development (typically git repo, used when passing --prefer-source). Originates from source code repository." }, "dist": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Dist is distribution archive information for production (typically zip/tar, default install method). Packaged version of released code." }, "require": { "patternProperties": { @@ -2296,7 +2697,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Require is runtime dependencies with version constraints (package will not install unless these requirements can be met)" }, "provide": { "patternProperties": { @@ -2304,7 +2706,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Provide is virtual packages/functionality provided by this package (allows other packages to depend on capabilities)" }, "require-dev": { "patternProperties": { @@ -2312,7 +2715,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "RequireDev is development-only dependencies (not installed in production, only when developing this package or running tests)" }, "suggest": { "patternProperties": { @@ -2320,46 +2724,56 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Suggest is optional but recommended dependencies (suggestions for packages that would extend functionality)" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of license identifiers (SPDX format)" }, "type": { - "type": "string" + "type": "string", + "description": "Type is package type indicating purpose (library=reusable code, project=application, metapackage=aggregates dependencies, etc.)" }, "notification-url": { - "type": "string" + "type": "string", + "description": "NotificationURL is the URL to notify when package is installed (for tracking/statistics)" }, "bin": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Bin is the list of binary/executable files that should be added to PATH" }, "authors": { "items": { "$ref": "#/$defs/PhpComposerAuthors" }, - "type": "array" + "type": "array", + "description": "Authors are the list of package authors with name/email/homepage" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "keywords": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Keywords are the list of keywords for package discovery/search" }, "time": { - "type": "string" + "type": "string", + "description": "Time is timestamp when this package version was released" } }, "type": "object", @@ -2368,21 +2782,26 @@ "version", "source", "dist" - ] + ], + "description": "PhpComposerInstalledEntry represents a single package entry from a composer v1/v2 \"installed.json\" files (very similar to composer.lock files)." }, "PhpComposerLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is package name in vendor/package format (e.g. symfony/console)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "source": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Source is the source repository information for development (typically git repo, used when passing --prefer-source). Originates from source code repository." }, "dist": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Dist is distribution archive information for production (typically zip/tar, default install method). Packaged version of released code." }, "require": { "patternProperties": { @@ -2390,7 +2809,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Require is runtime dependencies with version constraints (package will not install unless these requirements can be met)" }, "provide": { "patternProperties": { @@ -2398,7 +2818,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Provide is virtual packages/functionality provided by this package (allows other packages to depend on capabilities)" }, "require-dev": { "patternProperties": { @@ -2406,7 +2827,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "RequireDev is development-only dependencies (not installed in production, only when developing this package or running tests)" }, "suggest": { "patternProperties": { @@ -2414,46 +2836,56 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Suggest is optional but recommended dependencies (suggestions for packages that would extend functionality)" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of license identifiers (SPDX format)" }, "type": { - "type": "string" + "type": "string", + "description": "Type is package type indicating purpose (library=reusable code, project=application, metapackage=aggregates dependencies, etc.)" }, "notification-url": { - "type": "string" + "type": "string", + "description": "NotificationURL is the URL to notify when package is installed (for tracking/statistics)" }, "bin": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Bin is the list of binary/executable files that should be added to PATH" }, "authors": { "items": { "$ref": "#/$defs/PhpComposerAuthors" }, - "type": "array" + "type": "array", + "description": "Authors are the list of package authors with name/email/homepage" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "keywords": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Keywords are the list of keywords for package discovery/search" }, "time": { - "type": "string" + "type": "string", + "description": "Time is timestamp when this package version was released" } }, "type": "object", @@ -2462,189 +2894,230 @@ "version", "source", "dist" - ] + ], + "description": "PhpComposerLockEntry represents a single package entry found from a composer.lock file." }, "PhpPearEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is PEAR channel this package is from" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of applicable licenses" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "PhpPearEntry represents a single package entry found within php pear metadata files." }, "PhpPeclEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is PEAR channel this package is from" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of applicable licenses" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "PhpPeclEntry represents a single package entry found within php pecl metadata files." }, "PortageDbEntry": { "properties": { "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is total size of installed files in bytes" }, "licenses": { - "type": "string" + "type": "string", + "description": "Licenses is license string which may be an expression (e.g. \"GPL-2 OR Apache-2.0\")" }, "files": { "items": { "$ref": "#/$defs/PortageFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package (tracked in CONTENTS file)" } }, "type": "object", "required": [ "installedSize", "files" - ] + ], + "description": "PortageEntry represents a single package entry in the portage DB flat-file store." }, "PortageFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest is file content hash (MD5 for regular files in CONTENTS format: \"obj filename md5hash mtime\")" } }, "type": "object", "required": [ "path" - ] + ], + "description": "PortageFileRecord represents a single file attributed to a portage package." }, "PythonDirectURLOriginInfo": { "properties": { "url": { - "type": "string" + "type": "string", + "description": "URL is the source URL from which the package was installed." }, "commitId": { - "type": "string" + "type": "string", + "description": "CommitID is the VCS commit hash if installed from version control." }, "vcs": { - "type": "string" + "type": "string", + "description": "VCS is the version control system type (e.g., \"git\", \"hg\")." } }, "type": "object", "required": [ "url" - ] + ], + "description": "PythonDirectURLOriginInfo represents installation source metadata from direct_url.json for packages installed from VCS or direct URLs." }, "PythonFileDigest": { "properties": { "algorithm": { - "type": "string" + "type": "string", + "description": "Algorithm is the hash algorithm used (e.g., \"sha256\")." }, "value": { - "type": "string" + "type": "string", + "description": "Value is the hex-encoded hash digest value." } }, "type": "object", "required": [ "algorithm", "value" - ] + ], + "description": "PythonFileDigest represents the file metadata for a single file attributed to a python package." }, "PythonFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the installed file path from the RECORD file." }, "digest": { - "$ref": "#/$defs/PythonFileDigest" + "$ref": "#/$defs/PythonFileDigest", + "description": "Digest contains the hash algorithm and value for file integrity verification." }, "size": { - "type": "string" + "type": "string", + "description": "Size is the file size in bytes as a string." } }, "type": "object", "required": [ "path" - ] + ], + "description": "PythonFileRecord represents a single entry within a RECORD file for a python wheel or egg package" }, "PythonPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name from the Name field in PKG-INFO or METADATA." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version from the Version field in PKG-INFO or METADATA." }, "author": { - "type": "string" + "type": "string", + "description": "Author is the package author name from the Author field." }, "authorEmail": { - "type": "string" + "type": "string", + "description": "AuthorEmail is the package author's email address from the Author-Email field." }, "platform": { - "type": "string" + "type": "string", + "description": "Platform indicates the target platform for the package (e.g., \"any\", \"linux\", \"win32\")." }, "files": { "items": { "$ref": "#/$defs/PythonFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the installed files listed in the RECORD file for wheels or installed-files.txt for eggs." }, "sitePackagesRootPath": { - "type": "string" + "type": "string", + "description": "SitePackagesRootPath is the root directory path containing the package (e.g., \"/usr/lib/python3.9/site-packages\")." }, "topLevelPackages": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "TopLevelPackages are the top-level Python module names from top_level.txt file." }, "directUrlOrigin": { - "$ref": "#/$defs/PythonDirectURLOriginInfo" + "$ref": "#/$defs/PythonDirectURLOriginInfo", + "description": "DirectURLOrigin contains VCS or direct URL installation information from direct_url.json." }, "requiresPython": { - "type": "string" + "type": "string", + "description": "RequiresPython specifies the Python version requirement (e.g., \"\u003e=3.6\")." }, "requiresDist": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "RequiresDist lists the package dependencies with version specifiers from Requires-Dist fields." }, "providesExtra": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "ProvidesExtra lists optional feature names that can be installed via extras (e.g., \"dev\", \"test\")." } }, "type": "object", @@ -2655,34 +3128,41 @@ "authorEmail", "platform", "sitePackagesRootPath" - ] + ], + "description": "PythonPackage represents all captured data for a python egg or wheel package (specifically as outlined in the PyPA core metadata specification https://packaging.python.org/en/latest/specifications/core-metadata/)." }, "PythonPipRequirementsEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name from the requirements file." }, "extras": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Extras are the optional features to install from the package (e.g., package[dev,test])." }, "versionConstraint": { - "type": "string" + "type": "string", + "description": "VersionConstraint specifies version requirements (e.g., \"\u003e=1.0,\u003c2.0\")." }, "url": { - "type": "string" + "type": "string", + "description": "URL is the direct download URL or VCS URL if specified instead of a PyPI package." }, "markers": { - "type": "string" + "type": "string", + "description": "Markers are environment marker expressions for conditional installation (e.g., \"python_version \u003e= '3.8'\")." } }, "type": "object", "required": [ "name", "versionConstraint" - ] + ], + "description": "PythonRequirementsEntry represents a single entry within a [*-]requirements.txt file." }, "PythonPipfileLockEntry": { "properties": { @@ -2690,37 +3170,45 @@ "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Hashes are the package file hash values in the format \"algorithm:digest\" for integrity verification." }, "index": { - "type": "string" + "type": "string", + "description": "Index is the PyPI index name where the package should be fetched from." } }, "type": "object", "required": [ "hashes", "index" - ] + ], + "description": "PythonPipfileLockEntry represents a single package entry within a Pipfile.lock file." }, "PythonPoetryLockDependencyEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the dependency package name." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the locked version or version constraint for the dependency." }, "optional": { - "type": "boolean" + "type": "boolean", + "description": "Optional indicates whether this dependency is optional (only needed for certain extras)." }, "markers": { - "type": "string" + "type": "string", + "description": "Markers are environment marker expressions that conditionally enable the dependency (e.g., \"python_version \u003e= '3.8'\")." }, "extras": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Extras are the optional feature names from the dependency that should be installed." } }, "type": "object", @@ -2728,165 +3216,197 @@ "name", "version", "optional" - ] + ], + "description": "PythonPoetryLockDependencyEntry represents a single dependency entry within a Poetry lock file." }, "PythonPoetryLockEntry": { "properties": { "index": { - "type": "string" + "type": "string", + "description": "Index is the package repository name where the package should be fetched from." }, "dependencies": { "items": { "$ref": "#/$defs/PythonPoetryLockDependencyEntry" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package's runtime dependencies with version constraints." }, "extras": { "items": { "$ref": "#/$defs/PythonPoetryLockExtraEntry" }, - "type": "array" + "type": "array", + "description": "Extras are optional feature groups that include additional dependencies." } }, "type": "object", "required": [ "index", "dependencies" - ] + ], + "description": "PythonPoetryLockEntry represents a single package entry within a Pipfile.lock file." }, "PythonPoetryLockExtraEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the optional feature name (e.g., \"dev\", \"test\")." }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package names required when this extra is installed." } }, "type": "object", "required": [ "name", "dependencies" - ] + ], + "description": "PythonPoetryLockExtraEntry represents an optional feature group in a Poetry lock file." }, "PythonUvLockDependencyEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the dependency package name." }, "optional": { - "type": "boolean" + "type": "boolean", + "description": "Optional indicates whether this dependency is optional (only needed for certain extras)." }, "markers": { - "type": "string" + "type": "string", + "description": "Markers are environment marker expressions that conditionally enable the dependency (e.g., \"python_version \u003e= '3.8'\")." }, "extras": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Extras are the optional feature names from the dependency that should be installed." } }, "type": "object", "required": [ "name", "optional" - ] + ], + "description": "PythonUvLockDependencyEntry represents a single dependency entry within a uv lock file." }, "PythonUvLockEntry": { "properties": { "index": { - "type": "string" + "type": "string", + "description": "Index is the package repository name where the package should be fetched from." }, "dependencies": { "items": { "$ref": "#/$defs/PythonUvLockDependencyEntry" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package's runtime dependencies with version constraints." }, "extras": { "items": { "$ref": "#/$defs/PythonUvLockExtraEntry" }, - "type": "array" + "type": "array", + "description": "Extras are optional feature groups that include additional dependencies." } }, "type": "object", "required": [ "index", "dependencies" - ] + ], + "description": "PythonUvLockEntry represents a single package entry within a uv.lock file." }, "PythonUvLockExtraEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the optional feature name (e.g., \"dev\", \"test\")." }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package names required when this extra is installed." } }, "type": "object", "required": [ "name", "dependencies" - ] + ], + "description": "PythonUvLockExtraEntry represents an optional feature group in a uv lock file." }, "RDescription": { "properties": { "title": { - "type": "string" + "type": "string", + "description": "Title is short one-line package title" }, "description": { - "type": "string" + "type": "string", + "description": "Description is detailed package description" }, "author": { - "type": "string" + "type": "string", + "description": "Author is package author(s)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is current package maintainer" }, "url": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "URL is the list of related URLs" }, "repository": { - "type": "string" + "type": "string", + "description": "Repository is CRAN or other repository name" }, "built": { - "type": "string" + "type": "string", + "description": "Built is R version and platform this was built with" }, "needsCompilation": { - "type": "boolean" + "type": "boolean", + "description": "NeedsCompilation is whether this package requires compilation" }, "imports": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Imports are the packages imported in the NAMESPACE" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the packages this package depends on" }, "suggests": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Suggests are the optional packages that extend functionality" } }, - "type": "object" + "type": "object", + "description": "RDescription represents metadata from an R package DESCRIPTION file containing package information, dependencies, and author details." }, "Relationship": { "properties": { @@ -2911,15 +3431,18 @@ "RpmArchive": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the RPM package name as found in the RPM database." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the upstream version of the package." }, "epoch": { "oneOf": [ { - "type": "integer" + "type": "integer", + "description": "Epoch is the version epoch used to force upgrade ordering (null if not set)." }, { "type": "null" @@ -2927,46 +3450,56 @@ ] }, "architecture": { - "type": "string" + "type": "string", + "description": "Arch is the target CPU architecture (e.g., \"x86_64\", \"aarch64\", \"noarch\")." }, "release": { - "type": "string" + "type": "string", + "description": "Release is the package release number or distribution-specific version suffix." }, "sourceRpm": { - "type": "string" + "type": "string", + "description": "SourceRpm is the source RPM filename that was used to build this package." }, "signatures": { "items": { "$ref": "#/$defs/RpmSignature" }, - "type": "array" + "type": "array", + "description": "Signatures contains GPG signature metadata for package verification." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the total installed size of the package in bytes." }, "vendor": { - "type": "string" + "type": "string", + "description": "Vendor is the organization that packaged the software." }, "modularityLabel": { - "type": "string" + "type": "string", + "description": "ModularityLabel identifies the module stream for modular RPM packages (e.g., \"nodejs:12:20200101\")." }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides lists the virtual packages and capabilities this package provides." }, "requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Requires lists the dependencies required by this package." }, "files": { "items": { "$ref": "#/$defs/RpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the file records for all files owned by this package." } }, "type": "object", @@ -2980,20 +3513,24 @@ "size", "vendor", "files" - ] + ], + "description": "RpmArchive represents package metadata extracted directly from a .rpm archive file, containing the same information as an RPM database entry." }, "RpmDbEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the RPM package name as found in the RPM database." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the upstream version of the package." }, "epoch": { "oneOf": [ { - "type": "integer" + "type": "integer", + "description": "Epoch is the version epoch used to force upgrade ordering (null if not set)." }, { "type": "null" @@ -3001,46 +3538,56 @@ ] }, "architecture": { - "type": "string" + "type": "string", + "description": "Arch is the target CPU architecture (e.g., \"x86_64\", \"aarch64\", \"noarch\")." }, "release": { - "type": "string" + "type": "string", + "description": "Release is the package release number or distribution-specific version suffix." }, "sourceRpm": { - "type": "string" + "type": "string", + "description": "SourceRpm is the source RPM filename that was used to build this package." }, "signatures": { "items": { "$ref": "#/$defs/RpmSignature" }, - "type": "array" + "type": "array", + "description": "Signatures contains GPG signature metadata for package verification." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the total installed size of the package in bytes." }, "vendor": { - "type": "string" + "type": "string", + "description": "Vendor is the organization that packaged the software." }, "modularityLabel": { - "type": "string" + "type": "string", + "description": "ModularityLabel identifies the module stream for modular RPM packages (e.g., \"nodejs:12:20200101\")." }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides lists the virtual packages and capabilities this package provides." }, "requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Requires lists the dependencies required by this package." }, "files": { "items": { "$ref": "#/$defs/RpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the file records for all files owned by this package." } }, "type": "object", @@ -3054,30 +3601,38 @@ "size", "vendor", "files" - ] + ], + "description": "RpmDBEntry represents all captured data from a RPM DB package entry." }, "RpmFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the absolute file path where the file is installed." }, "mode": { - "type": "integer" + "type": "integer", + "description": "Mode is the file permission mode bits following Unix stat.h conventions." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the file size in bytes." }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest contains the hash algorithm and value for file integrity verification." }, "userName": { - "type": "string" + "type": "string", + "description": "UserName is the owner username for the file." }, "groupName": { - "type": "string" + "type": "string", + "description": "GroupName is the group name for the file." }, "flags": { - "type": "string" + "type": "string", + "description": "Flags indicates the file type (e.g., \"%config\", \"%doc\", \"%ghost\")." } }, "type": "object", @@ -3089,21 +3644,26 @@ "userName", "groupName", "flags" - ] + ], + "description": "RpmFileRecord represents the file metadata for a single file attributed to a RPM package." }, "RpmSignature": { "properties": { "algo": { - "type": "string" + "type": "string", + "description": "PublicKeyAlgorithm is the public key algorithm used for signing (e.g., \"RSA\")." }, "hash": { - "type": "string" + "type": "string", + "description": "HashAlgorithm is the hash algorithm used for the signature (e.g., \"SHA256\")." }, "created": { - "type": "string" + "type": "string", + "description": "Created is the timestamp when the signature was created." }, "issuer": { - "type": "string" + "type": "string", + "description": "IssuerKeyID is the GPG key ID that created the signature." } }, "type": "object", @@ -3112,48 +3672,58 @@ "hash", "created", "issuer" - ] + ], + "description": "RpmSignature represents a GPG signature for an RPM package used for authenticity verification." }, "RubyGemspec": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is gem name as specified in the gemspec" }, "version": { - "type": "string" + "type": "string", + "description": "Version is gem version as specified in the gemspec" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files is logical list of files in the gem (NOT directly usable as filesystem paths. Example: bundler gem lists \"lib/bundler/vendor/uri/lib/uri/ldap.rb\" but actual path is \"/usr/local/lib/ruby/3.2.0/bundler/vendor/uri/lib/uri/ldap.rb\". Would need gem installation path, ruby version, and env vars like GEM_HOME to resolve actual paths.)" }, "authors": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Authors are the list of gem authors (stored as array regardless of using `author` or `authors` method in gemspec)" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "RubyGemspec represents all metadata parsed from the *.gemspec file" }, "RustCargoAuditEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is crate name as specified in audit section of the build binary" }, "version": { - "type": "string" + "type": "string", + "description": "Version is crate version as specified in audit section of the build binary" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source registry or repository where this crate came from" } }, "type": "object", @@ -3161,27 +3731,33 @@ "name", "version", "source" - ] + ], + "description": "RustBinaryAuditEntry represents Rust crate metadata extracted from a compiled binary using cargo-auditable format." }, "RustCargoLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is crate name as specified in Cargo.toml" }, "version": { - "type": "string" + "type": "string", + "description": "Version is crate version as specified in Cargo.toml" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source registry or repository URL in format \"registry+https://github.com/rust-lang/crates.io-index\" for registry packages" }, "checksum": { - "type": "string" + "type": "string", + "description": "Checksum is content checksum for registry packages only (hexadecimal string). Cargo doesn't require or include checksums for git dependencies. Used to detect MITM attacks by verifying downloaded crate matches lockfile checksum." }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the list of dependencies with version constraints" } }, "type": "object", @@ -3191,7 +3767,8 @@ "source", "checksum", "dependencies" - ] + ], + "description": "RustCargoLockEntry represents a locked dependency from a Cargo.lock file with precise version and checksum information." }, "Schema": { "properties": { @@ -3211,19 +3788,24 @@ "SnapEntry": { "properties": { "snapType": { - "type": "string" + "type": "string", + "description": "SnapType indicates the snap type (base, kernel, app, gadget, or snapd)." }, "base": { - "type": "string" + "type": "string", + "description": "Base is the base snap name that this snap depends on (e.g., \"core20\", \"core22\")." }, "snapName": { - "type": "string" + "type": "string", + "description": "SnapName is the snap package name." }, "snapVersion": { - "type": "string" + "type": "string", + "description": "SnapVersion is the snap package version." }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture (e.g., \"amd64\", \"arm64\")." } }, "type": "object", @@ -3233,7 +3815,8 @@ "snapName", "snapVersion", "architecture" - ] + ], + "description": "SnapEntry represents metadata for a Snap package extracted from snap.yaml or snapcraft.yaml files." }, "Source": { "properties": { @@ -3261,47 +3844,58 @@ "version", "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." }, "SwiftPackageManagerLockEntry": { "properties": { "revision": { - "type": "string" + "type": "string", + "description": "Revision is git commit hash of the resolved package" } }, "type": "object", "required": [ "revision" - ] + ], + "description": "SwiftPackageManagerResolvedEntry represents a resolved dependency from a Package.resolved file with its locked version and source location." }, "SwiplpackPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the .toml file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the .toml file" }, "author": { - "type": "string" + "type": "string", + "description": "Author is author name" }, "authorEmail": { - "type": "string" + "type": "string", + "description": "AuthorEmail is author email address" }, "packager": { - "type": "string" + "type": "string", + "description": "Packager is packager name (if different from author)" }, "packagerEmail": { - "type": "string" + "type": "string", + "description": "PackagerEmail is packager email address" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the list of required dependencies" } }, "type": "object", @@ -3314,24 +3908,29 @@ "packagerEmail", "homepage", "dependencies" - ] + ], + "description": "SwiplPackEntry represents a SWI-Prolog package from the pack system with metadata about the package and its dependencies." }, "TerraformLockProviderEntry": { "properties": { "url": { - "type": "string" + "type": "string", + "description": "URL is the provider source address (e.g., \"registry.terraform.io/hashicorp/aws\")." }, "constraints": { - "type": "string" + "type": "string", + "description": "Constraints specifies the version constraints for the provider (e.g., \"~\u003e 4.0\")." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the locked provider version selected during terraform init." }, "hashes": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Hashes are cryptographic checksums for the provider plugin archives across different platforms." } }, "type": "object", @@ -3340,24 +3939,29 @@ "constraints", "version", "hashes" - ] + ], + "description": "TerraformLockProviderEntry represents a single provider entry in a Terraform dependency lock file (.terraform.lock.hcl)." }, "WordpressPluginEntry": { "properties": { "pluginInstallDirectory": { - "type": "string" + "type": "string", + "description": "PluginInstallDirectory is directory name where the plugin is installed" }, "author": { - "type": "string" + "type": "string", + "description": "Author is plugin author name" }, "authorUri": { - "type": "string" + "type": "string", + "description": "AuthorURI is author's website URL" } }, "type": "object", "required": [ "pluginInstallDirectory" - ] + ], + "description": "WordpressPluginEntry represents all metadata parsed from the wordpress plugin file" }, "cpes": { "items": { diff --git a/schema/json/schema-latest.json b/schema/json/schema-latest.json index 3135b0f17..cd8198acb 100644 --- a/schema/json/schema-latest.json +++ b/schema/json/schema-latest.json @@ -6,58 +6,72 @@ "AlpmDbEntry": { "properties": { "basepackage": { - "type": "string" + "type": "string", + "description": "BasePackage is the base package name this package was built from (source package in Arch build system)" }, "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the desc file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the desc file" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture as defined in Arch architecture spec (e.g. x86_64, aarch64, or \"any\" for arch-independent packages)" }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the installed size in bytes" }, "packager": { - "type": "string" + "type": "string", + "description": "Packager is the name and email of the person who packaged this (RFC822 format)" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the upstream project URL" }, "validation": { - "type": "string" + "type": "string", + "description": "Validation is the validation method used for package integrity (e.g. pgp signature, sha256 checksum)" }, "reason": { - "type": "integer" + "type": "integer", + "description": "Reason is the installation reason tracked by pacman (0=explicitly installed by user, 1=installed as dependency)" }, "files": { "items": { "$ref": "#/$defs/AlpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" }, "backup": { "items": { "$ref": "#/$defs/AlpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Backup is the list of configuration files that pacman backs up before upgrades" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are virtual packages provided by this package (allows other packages to depend on capabilities rather than specific packages)" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the runtime dependencies required by this package" } }, "type": "object", @@ -74,37 +88,46 @@ "reason", "files", "backup" - ] + ], + "description": "AlpmDBEntry is a struct that represents the package data stored in the pacman flat-file stores for arch linux." }, "AlpmFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "type": { - "type": "string" + "type": "string", + "description": "Type is the file type (e.g. regular file, directory, symlink)" }, "uid": { - "type": "string" + "type": "string", + "description": "UID is the file owner user ID as recorded by pacman" }, "gid": { - "type": "string" + "type": "string", + "description": "GID is the file owner group ID as recorded by pacman" }, "time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Time is the file modification timestamp" }, "size": { - "type": "string" + "type": "string", + "description": "Size is the file size in bytes" }, "link": { - "type": "string" + "type": "string", + "description": "Link is the symlink target path if this is a symlink" }, "digest": { "items": { "$ref": "#/$defs/Digest" }, - "type": "array" + "type": "array", + "description": "Digests contains file content hashes for integrity verification" } }, "type": "object" @@ -112,55 +135,69 @@ "ApkDbEntry": { "properties": { "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the installed file" }, "originPackage": { - "type": "string" + "type": "string", + "description": "OriginPackage is the original source package name this binary was built from (used to track which aport/source built this)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is the package maintainer name and email" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the installed file" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the upstream project URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the package archive size in bytes (.apk file size)" }, "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is the total size of installed files in bytes" }, "pullDependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the runtime dependencies required by this package" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are virtual packages provided by this package (for capability-based dependencies)" }, "pullChecksum": { - "type": "string" + "type": "string", + "description": "Checksum is the package content checksum for integrity verification" }, "gitCommitOfApkPort": { - "type": "string" + "type": "string", + "description": "GitCommit is the git commit hash of the APK port definition in Alpine's aports repository" }, "files": { "items": { "$ref": "#/$defs/ApkFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" } }, "type": "object", @@ -179,30 +216,37 @@ "pullChecksum", "gitCommitOfApkPort", "files" - ] + ], + "description": "ApkDBEntry represents all captured data for the alpine linux package manager flat-file store." }, "ApkFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "ownerUid": { - "type": "string" + "type": "string", + "description": "OwnerUID is the file owner user ID" }, "ownerGid": { - "type": "string" + "type": "string", + "description": "OwnerGID is the file owner group ID" }, "permissions": { - "type": "string" + "type": "string", + "description": "Permissions is the file permission mode string (e.g. \"0755\", \"0644\")" }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest is the file content hash for integrity verification" } }, "type": "object", "required": [ "path" - ] + ], + "description": "ApkFileRecord represents a single file listing and metadata from a APK DB entry (which may have many of these file records)." }, "BinarySignature": { "properties": { @@ -216,33 +260,41 @@ "type": "object", "required": [ "matches" - ] + ], + "description": "BinarySignature represents a set of matched values within a binary file." }, "BitnamiSbomEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the Bitnami SPDX file" }, "arch": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture (amd64 or arm64 in Bitnami images)" }, "distro": { - "type": "string" + "type": "string", + "description": "Distro is the distribution name this package is for (base OS like debian, ubuntu, etc.)" }, "revision": { - "type": "string" + "type": "string", + "description": "Revision is the Bitnami-specific package revision number (incremented for Bitnami rebuilds of same upstream version)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the Bitnami SPDX file" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the installation path in the filesystem where the package is located" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files are the file paths owned by this package (tracked via SPDX relationships)" } }, "type": "object", @@ -254,105 +306,129 @@ "version", "path", "files" - ] + ], + "description": "BitnamiSBOMEntry represents all captured data from Bitnami packages described in Bitnami' SPDX files." }, "CConanFileEntry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConanfileEntry represents a single \"Requires\" entry from a conanfile.txt." }, "CConanInfoEntry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" }, "package_id": { - "type": "string" + "type": "string", + "description": "PackageID is a unique package variant identifier" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConaninfoEntry represents a single \"full_requires\" entry from a conaninfo.txt." }, "CConanLockEntry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" }, "package_id": { - "type": "string" + "type": "string", + "description": "PackageID is a unique package variant identifier computed from settings/options (static hash in Conan 1.x, can have collisions with complex dependency graphs)" }, "prev": { - "type": "string" + "type": "string", + "description": "Prev is the previous lock entry reference for versioning" }, "requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Requires are the runtime package dependencies" }, "build_requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "BuildRequires are the build-time dependencies (e.g. cmake, compilers)" }, "py_requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "PythonRequires are the Python dependencies needed for Conan recipes" }, "options": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "Options are package configuration options as key-value pairs (e.g. shared=True, fPIC=True)" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the filesystem path to the package in Conan cache" }, "context": { - "type": "string" + "type": "string", + "description": "Context is the build context information" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConanV1LockEntry represents a single \"node\" entry from a conan.lock V1 file." }, "CConanLockV2Entry": { "properties": { "ref": { - "type": "string" + "type": "string", + "description": "Ref is the package reference string in format name/version@user/channel" }, "packageID": { - "type": "string" + "type": "string", + "description": "PackageID is a unique package variant identifier (dynamic in Conan 2.0, more accurate than V1)" }, "username": { - "type": "string" + "type": "string", + "description": "Username is the Conan user/organization name" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is the Conan channel name indicating stability/purpose (e.g. stable, testing, experimental)" }, "recipeRevision": { - "type": "string" + "type": "string", + "description": "RecipeRevision is a git-like revision hash (RREV) of the recipe" }, "packageRevision": { - "type": "string" + "type": "string", + "description": "PackageRevision is a git-like revision hash of the built binary package" }, "timestamp": { - "type": "string" + "type": "string", + "description": "TimeStamp is when this package was built/locked" } }, "type": "object", "required": [ "ref" - ] + ], + "description": "ConanV2LockEntry represents a single \"node\" entry from a conan.lock V2 file." }, "CPE": { "properties": { @@ -381,104 +457,131 @@ "required": [ "classifier", "location" - ] + ], + "description": "ClassifierMatch represents a single matched value within a binary file and the \"class\" name the search pattern represents." }, "CocoaPodfileLockEntry": { "properties": { "checksum": { - "type": "string" + "type": "string", + "description": "Checksum is the SHA-1 hash of the podspec file for integrity verification (generated via `pod ipc spec ... | openssl sha1`), ensuring all team members use the same pod specification version" } }, "type": "object", "required": [ "checksum" - ] + ], + "description": "CocoaPodfileLockEntry represents a single entry from the \"Pods\" section of a Podfile.lock file." }, "CondaLink": { "properties": { "source": { - "type": "string" + "type": "string", + "description": "Source is the original path where the package was extracted from cache." }, "type": { - "type": "integer" + "type": "integer", + "description": "Type indicates the link type (1 for hard link, 2 for soft link, 3 for copy)." } }, "type": "object", "required": [ "source", "type" - ] + ], + "description": "CondaLink represents link metadata from a Conda package's link.json file describing package installation source." }, "CondaMetadataEntry": { "properties": { "arch": { - "type": "string" + "type": "string", + "description": "Arch is the target CPU architecture for the package (e.g., \"arm64\", \"x86_64\")." }, "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the conda-meta JSON file." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the conda-meta JSON file." }, "build": { - "type": "string" + "type": "string", + "description": "Build is the build string identifier (e.g., \"h90dfc92_1014\")." }, "build_number": { - "type": "integer" + "type": "integer", + "description": "BuildNumber is the sequential build number for this version." }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is the Conda channel URL where the package was retrieved from." }, "subdir": { - "type": "string" + "type": "string", + "description": "Subdir is the subdirectory within the channel (e.g., \"osx-arm64\", \"linux-64\")." }, "noarch": { - "type": "string" + "type": "string", + "description": "Noarch indicates if the package is platform-independent (e.g., \"python\", \"generic\")." }, "license": { - "type": "string" + "type": "string", + "description": "License is the package license identifier." }, "license_family": { - "type": "string" + "type": "string", + "description": "LicenseFamily is the general license category (e.g., \"MIT\", \"Apache\", \"GPL\")." }, "md5": { - "type": "string" + "type": "string", + "description": "MD5 is the MD5 hash of the package archive." }, "sha256": { - "type": "string" + "type": "string", + "description": "SHA256 is the SHA-256 hash of the package archive." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the package archive size in bytes." }, "timestamp": { - "type": "integer" + "type": "integer", + "description": "Timestamp is the Unix timestamp when the package was built." }, "fn": { - "type": "string" + "type": "string", + "description": "Filename is the original package archive filename (e.g., \"zlib-1.2.11-h90dfc92_1014.tar.bz2\")." }, "url": { - "type": "string" + "type": "string", + "description": "URL is the full download URL for the package archive." }, "extracted_package_dir": { - "type": "string" + "type": "string", + "description": "ExtractedPackageDir is the local cache directory where the package was extracted." }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends is the list of runtime dependencies with version constraints." }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files is the list of files installed by this package." }, "paths_data": { - "$ref": "#/$defs/CondaPathsData" + "$ref": "#/$defs/CondaPathsData", + "description": "PathsData contains detailed file metadata from the paths.json file." }, "link": { - "$ref": "#/$defs/CondaLink" + "$ref": "#/$defs/CondaLink", + "description": "Link contains installation source metadata from the link.json file." } }, "type": "object", @@ -487,24 +590,30 @@ "version", "build", "build_number" - ] + ], + "description": "CondaMetaPackage represents metadata for a Conda package extracted from the conda-meta/*.json files." }, "CondaPathData": { "properties": { "_path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the Conda environment root." }, "path_type": { - "type": "string" + "type": "string", + "description": "PathType indicates the link type for the file (e.g., \"hardlink\", \"softlink\", \"directory\")." }, "sha256": { - "type": "string" + "type": "string", + "description": "SHA256 is the SHA-256 hash of the file contents." }, "sha256_in_prefix": { - "type": "string" + "type": "string", + "description": "SHA256InPrefix is the SHA-256 hash of the file after prefix replacement during installation." }, "size_in_bytes": { - "type": "integer" + "type": "integer", + "description": "SizeInBytes is the file size in bytes." } }, "type": "object", @@ -514,103 +623,126 @@ "sha256", "sha256_in_prefix", "size_in_bytes" - ] + ], + "description": "CondaPathData represents metadata for a single file within a Conda package from the paths.json file." }, "CondaPathsData": { "properties": { "paths_version": { - "type": "integer" + "type": "integer", + "description": "PathsVersion is the schema version of the paths data format." }, "paths": { "items": { "$ref": "#/$defs/CondaPathData" }, - "type": "array" + "type": "array", + "description": "Paths is the list of file metadata entries for all files in the package." } }, "type": "object", "required": [ "paths_version", "paths" - ] + ], + "description": "CondaPathsData represents the paths.json file structure from a Conda package containing file metadata." }, "Coordinates": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "RealPath is the canonical absolute form of the path accessed (all symbolic links have been followed and relative path components like '.' and '..' have been removed)." }, "layerID": { - "type": "string" + "type": "string", + "description": "FileSystemID is an ID representing and entire filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank." } }, "type": "object", "required": [ "path" - ] + ], + "description": "Coordinates contains the minimal information needed to describe how to find a file within any possible source object (e.g." }, "DartPubspec": { "properties": { "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is the package homepage URL" }, "repository": { - "type": "string" + "type": "string", + "description": "Repository is the source code repository URL" }, "documentation": { - "type": "string" + "type": "string", + "description": "Documentation is the documentation site URL" }, "publish_to": { - "type": "string" + "type": "string", + "description": "PublishTo is the package repository to publish to, or \"none\" to prevent accidental publishing" }, "environment": { - "$ref": "#/$defs/DartPubspecEnvironment" + "$ref": "#/$defs/DartPubspecEnvironment", + "description": "Environment is SDK version constraints for Dart and Flutter" }, "platforms": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Platforms are the supported platforms (Android, iOS, web, etc.)" }, "ignored_advisories": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "IgnoredAdvisories are the security advisories to explicitly ignore for this package" } }, - "type": "object" + "type": "object", + "description": "DartPubspec is a struct that represents a package described in a pubspec.yaml file" }, "DartPubspecEnvironment": { "properties": { "sdk": { - "type": "string" + "type": "string", + "description": "SDK is the Dart SDK version constraint (e.g. \"\u003e=2.12.0 \u003c3.0.0\")" }, "flutter": { - "type": "string" + "type": "string", + "description": "Flutter is the Flutter SDK version constraint if this is a Flutter package" } }, - "type": "object" + "type": "object", + "description": "DartPubspecEnvironment represents SDK version constraints from the environment section of pubspec.yaml." }, "DartPubspecLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the pubspec.lock file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the pubspec.lock file" }, "hosted_url": { - "type": "string" + "type": "string", + "description": "HostedURL is the URL of the package repository for hosted packages (typically pub.dev, but can be custom repository identified by hosted-url). When PUB_HOSTED_URL environment variable changes, lockfile tracks the source." }, "vcs_url": { - "type": "string" + "type": "string", + "description": "VcsURL is the URL of the VCS repository for git/path dependencies (for packages fetched from version control systems like Git)" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "DartPubspecLockEntry is a struct that represents a single entry found in the \"packages\" section in a Dart pubspec.lock file." }, "Descriptor": { "properties": { @@ -626,22 +758,26 @@ "required": [ "name", "version" - ] + ], + "description": "Descriptor describes what created the document as well as surrounding metadata" }, "Digest": { "properties": { "algorithm": { - "type": "string" + "type": "string", + "description": "Algorithm specifies the hash algorithm used (e.g., \"sha256\", \"md5\")." }, "value": { - "type": "string" + "type": "string", + "description": "Value is the hexadecimal string representation of the hash." } }, "type": "object", "required": [ "algorithm", "value" - ] + ], + "description": "Digest represents a cryptographic hash of file contents." }, "Document": { "properties": { @@ -684,24 +820,30 @@ "distro", "descriptor", "schema" - ] + ], + "description": "Document represents the syft cataloging findings as a JSON document" }, "DotnetDepsEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the deps.json file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the deps.json file" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the relative path to the package within the deps structure (e.g. \"app.metrics/3.0.0\")" }, "sha512": { - "type": "string" + "type": "string", + "description": "Sha512 is the SHA-512 hash of the NuGet package content WITHOUT the signed content for verification (won't match hash from NuGet API or manual calculation of .nupkg file)" }, "hashPath": { - "type": "string" + "type": "string", + "description": "HashPath is the relative path to the .nupkg.sha512 hash file (e.g. \"app.metrics.3.0.0.nupkg.sha512\")" }, "executables": { "patternProperties": { @@ -709,7 +851,8 @@ "$ref": "#/$defs/DotnetPortableExecutableEntry" } }, - "type": "object" + "type": "object", + "description": "Executables are the map of .NET Portable Executable files within this package with their version resources" } }, "type": "object", @@ -719,21 +862,26 @@ "path", "sha512", "hashPath" - ] + ], + "description": "DotnetDepsEntry is a struct that represents a single entry found in the \"libraries\" section in a .NET [*.]deps.json file." }, "DotnetPackagesLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the packages.lock.json file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the packages.lock.json file" }, "contentHash": { - "type": "string" + "type": "string", + "description": "ContentHash is the hash of the package content for verification" }, "type": { - "type": "string" + "type": "string", + "description": "Type is the dependency type indicating how this dependency was added (Direct=explicit in project file, Transitive=pulled in by another package, Project=project reference)" } }, "type": "object", @@ -742,30 +890,38 @@ "version", "contentHash", "type" - ] + ], + "description": "DotnetPackagesLockEntry is a struct that represents a single entry found in the \"dependencies\" section in a .NET packages.lock.json file." }, "DotnetPortableExecutableEntry": { "properties": { "assemblyVersion": { - "type": "string" + "type": "string", + "description": "AssemblyVersion is the .NET assembly version number (strong-named version)" }, "legalCopyright": { - "type": "string" + "type": "string", + "description": "LegalCopyright is the copyright notice string" }, "comments": { - "type": "string" + "type": "string", + "description": "Comments are additional comments or description embedded in PE resources" }, "internalName": { - "type": "string" + "type": "string", + "description": "InternalName is the internal name of the file" }, "companyName": { - "type": "string" + "type": "string", + "description": "CompanyName is the company that produced the file" }, "productName": { - "type": "string" + "type": "string", + "description": "ProductName is the name of the product this file is part of" }, "productVersion": { - "type": "string" + "type": "string", + "description": "ProductVersion is the version of the product (may differ from AssemblyVersion)" } }, "type": "object", @@ -775,54 +931,66 @@ "companyName", "productName", "productVersion" - ] + ], + "description": "DotnetPortableExecutableEntry is a struct that represents a single entry found within \"VersionResources\" section of a .NET Portable Executable binary file." }, "DpkgArchiveEntry": { "properties": { "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the status file" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source package name this binary was built from (one source can produce multiple binary packages)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the binary package version as found in the status file" }, "sourceVersion": { - "type": "string" + "type": "string", + "description": "SourceVersion is the source package version (may differ from binary version when binNMU rebuilds occur)" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target architecture per Debian spec (specific arch like amd64/arm64, wildcard like any, architecture-independent \"all\", or \"source\" for source packages)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is the package maintainer's name and email in RFC822 format (name must come first, then email in angle brackets)" }, "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is the total size of installed files in kilobytes" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are the virtual packages provided by this package (allows other packages to depend on capabilities. Can include versioned provides like \"libdigest-md5-perl (= 2.55.01)\")" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the packages required for this package to function (will not be installed unless these requirements are met, creates strict ordering constraint)" }, "preDepends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "PreDepends are the packages that must be installed and configured BEFORE even starting installation of this package (stronger than Depends, discouraged unless absolutely necessary as it adds strict constraints for apt)" }, "files": { "items": { "$ref": "#/$defs/DpkgFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" } }, "type": "object", @@ -835,54 +1003,66 @@ "maintainer", "installedSize", "files" - ] + ], + "description": "DpkgArchiveEntry represents package metadata extracted from a .deb archive file." }, "DpkgDbEntry": { "properties": { "package": { - "type": "string" + "type": "string", + "description": "Package is the package name as found in the status file" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source package name this binary was built from (one source can produce multiple binary packages)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the binary package version as found in the status file" }, "sourceVersion": { - "type": "string" + "type": "string", + "description": "SourceVersion is the source package version (may differ from binary version when binNMU rebuilds occur)" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target architecture per Debian spec (specific arch like amd64/arm64, wildcard like any, architecture-independent \"all\", or \"source\" for source packages)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is the package maintainer's name and email in RFC822 format (name must come first, then email in angle brackets)" }, "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is the total size of installed files in kilobytes" }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides are the virtual packages provided by this package (allows other packages to depend on capabilities. Can include versioned provides like \"libdigest-md5-perl (= 2.55.01)\")" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the packages required for this package to function (will not be installed unless these requirements are met, creates strict ordering constraint)" }, "preDepends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "PreDepends are the packages that must be installed and configured BEFORE even starting installation of this package (stronger than Depends, discouraged unless absolutely necessary as it adds strict constraints for apt)" }, "files": { "items": { "$ref": "#/$defs/DpkgFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package" } }, "type": "object", @@ -895,54 +1075,68 @@ "maintainer", "installedSize", "files" - ] + ], + "description": "DpkgDBEntry represents all captured data for a Debian package DB entry; available fields are described at http://manpages.ubuntu.com/manpages/xenial/man1/dpkg-query.1.html in the --showformat section." }, "DpkgFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest is the file content hash (typically MD5 for dpkg compatibility with legacy systems)" }, "isConfigFile": { - "type": "boolean" + "type": "boolean", + "description": "IsConfigFile is whether this file is marked as a configuration file (dpkg will preserve user modifications during upgrades)" } }, "type": "object", "required": [ "path", "isConfigFile" - ] + ], + "description": "DpkgFileRecord represents a single file attributed to a debian package." }, "ELFSecurityFeatures": { "properties": { "symbolTableStripped": { - "type": "boolean" + "type": "boolean", + "description": "SymbolTableStripped indicates whether debugging symbols have been removed." }, "stackCanary": { - "type": "boolean" + "type": "boolean", + "description": "StackCanary indicates whether stack smashing protection is enabled." }, "nx": { - "type": "boolean" + "type": "boolean", + "description": "NoExecutable indicates whether NX (no-execute) protection is enabled for the stack." }, "relRO": { - "type": "string" + "type": "string", + "description": "RelocationReadOnly indicates the RELRO protection level." }, "pie": { - "type": "boolean" + "type": "boolean", + "description": "PositionIndependentExecutable indicates whether the binary is compiled as PIE." }, "dso": { - "type": "boolean" + "type": "boolean", + "description": "DynamicSharedObject indicates whether the binary is a shared library." }, "safeStack": { - "type": "boolean" + "type": "boolean", + "description": "LlvmSafeStack represents a compiler-based security mechanism that separates the stack into a safe stack for storing return addresses and other critical data, and an unsafe stack for everything else, to mitigate stack-based memory corruption errors\nsee https://clang.llvm.org/docs/SafeStack.html" }, "cfi": { - "type": "boolean" + "type": "boolean", + "description": "ControlFlowIntegrity represents runtime checks to ensure a program's control flow adheres to the legal paths determined at compile time, thus protecting against various types of control-flow hijacking attacks\nsee https://clang.llvm.org/docs/ControlFlowIntegrity.html" }, "fortify": { - "type": "boolean" + "type": "boolean", + "description": "ClangFortifySource is a broad suite of extensions to libc aimed at catching misuses of common library functions\nsee https://android.googlesource.com/platform//bionic/+/d192dbecf0b2a371eb127c0871f77a9caf81c4d2/docs/clang_fortify_anatomy.md" } }, "type": "object", @@ -952,53 +1146,68 @@ "relRO", "pie", "dso" - ] + ], + "description": "ELFSecurityFeatures captures security hardening and protection mechanisms in ELF binaries." }, "ElfBinaryPackageNoteJsonPayload": { "properties": { "type": { - "type": "string" + "type": "string", + "description": "Type is the type of the package (e.g. \"rpm\", \"deb\", \"apk\", etc.)" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture of the binary package (e.g. \"amd64\", \"arm\", etc.)" }, "osCPE": { - "type": "string" + "type": "string", + "description": "OSCPE is a CPE name for the OS, typically corresponding to CPE_NAME in os-release (e.g. cpe:/o:fedoraproject:fedora:33)" }, "os": { - "type": "string" + "type": "string", + "description": "OS is the OS name, typically corresponding to ID in os-release (e.g. \"fedora\")" }, "osVersion": { - "type": "string" + "type": "string", + "description": "osVersion is the version of the OS, typically corresponding to VERSION_ID in os-release (e.g. \"33\")" }, "system": { - "type": "string" + "type": "string", + "description": "System is a context-specific name for the system that the binary package is intended to run on or a part of" }, "vendor": { - "type": "string" + "type": "string", + "description": "Vendor is the individual or organization that produced the source code for the binary" }, "sourceRepo": { - "type": "string" + "type": "string", + "description": "SourceRepo is the URL to the source repository for which the binary was built from" }, "commit": { - "type": "string" + "type": "string", + "description": "Commit is the commit hash of the source repository for which the binary was built from" } }, - "type": "object" + "type": "object", + "description": "ELFBinaryPackageNoteJSONPayload Represents metadata captured from the .note.package section of an ELF-formatted binary" }, "ElixirMixLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the mix.lock file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the mix.lock file" }, "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the outer checksum (SHA-256) of the entire Hex package tarball for integrity verification (preferred method, replaces deprecated inner checksum)" }, "pkgHashExt": { - "type": "string" + "type": "string", + "description": "PkgHashExt is the extended package hash format (inner checksum is deprecated - SHA-256 of concatenated file contents excluding CHECKSUM file, now replaced by outer checksum)" } }, "type": "object", @@ -1007,21 +1216,26 @@ "version", "pkgHash", "pkgHashExt" - ] + ], + "description": "ElixirMixLockEntry is a struct that represents a single entry in a mix.lock file" }, "ErlangRebarLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the rebar.lock file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the rebar.lock file" }, "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the outer checksum (SHA-256) of the entire Hex package tarball for integrity verification (preferred method over deprecated inner checksum)" }, "pkgHashExt": { - "type": "string" + "type": "string", + "description": "PkgHashExt is the extended package hash format (inner checksum deprecated - was SHA-256 of concatenated file contents)" } }, "type": "object", @@ -1030,27 +1244,33 @@ "version", "pkgHash", "pkgHashExt" - ] + ], + "description": "ErlangRebarLockEntry represents a single package entry from the \"deps\" section within an Erlang rebar.lock file." }, "Executable": { "properties": { "format": { - "type": "string" + "type": "string", + "description": "Format denotes either ELF, Mach-O, or PE" }, "hasExports": { - "type": "boolean" + "type": "boolean", + "description": "HasExports indicates whether the binary exports symbols." }, "hasEntrypoint": { - "type": "boolean" + "type": "boolean", + "description": "HasEntrypoint indicates whether the binary has an entry point function." }, "importedLibraries": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "ImportedLibraries lists the shared libraries required by this executable." }, "elfSecurityFeatures": { - "$ref": "#/$defs/ELFSecurityFeatures" + "$ref": "#/$defs/ELFSecurityFeatures", + "description": "ELFSecurityFeatures contains ELF-specific security hardening information when Format is ELF." } }, "type": "object", @@ -1059,7 +1279,8 @@ "hasExports", "hasEntrypoint", "importedLibraries" - ] + ], + "description": "Executable contains metadata about binary files and their security features." }, "File": { "properties": { @@ -1181,116 +1402,144 @@ "GithubActionsUseStatement": { "properties": { "value": { - "type": "string" + "type": "string", + "description": "Value is the action reference (e.g. \"actions/checkout@v3\")" }, "comment": { - "type": "string" + "type": "string", + "description": "Comment is the inline comment associated with this uses statement" } }, "type": "object", "required": [ "value" - ] + ], + "description": "GitHubActionsUseStatement represents a single 'uses' statement in a GitHub Actions workflow file referencing an action or reusable workflow." }, "GoModuleBuildinfoEntry": { "properties": { "goBuildSettings": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "BuildSettings contains the Go build settings and flags used to compile the binary (e.g., GOARCH, GOOS, CGO_ENABLED)." }, "goCompiledVersion": { - "type": "string" + "type": "string", + "description": "GoCompiledVersion is the version of Go used to compile the binary." }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture for the binary (extracted from GOARCH build setting)." }, "h1Digest": { - "type": "string" + "type": "string", + "description": "H1Digest is the Go module hash in h1: format for the main module from go.sum." }, "mainModule": { - "type": "string" + "type": "string", + "description": "MainModule is the main module path for the binary (e.g., \"github.com/anchore/syft\")." }, "goCryptoSettings": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "GoCryptoSettings contains FIPS and cryptographic configuration settings if present." }, "goExperiments": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "GoExperiments lists experimental Go features enabled during compilation (e.g., \"arenas\", \"cgocheck2\")." } }, "type": "object", "required": [ "goCompiledVersion", "architecture" - ] + ], + "description": "GolangBinaryBuildinfoEntry represents all captured data for a Golang binary" }, "GoModuleEntry": { "properties": { "h1Digest": { - "type": "string" + "type": "string", + "description": "H1Digest is the Go module hash in h1: format from go.sum for verifying module contents." } }, - "type": "object" + "type": "object", + "description": "GolangModuleEntry represents all captured data for a Golang source scan with go.mod/go.sum" }, "GoSourceEntry": { "properties": { "h1Digest": { - "type": "string" + "type": "string", + "description": "H1Digest is the Go module hash in h1: format from go.sum for verifying module contents." }, "os": { - "type": "string" + "type": "string", + "description": "OperatingSystem is the target OS for build constraints (e.g., \"linux\", \"darwin\", \"windows\")." }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture for build constraints (e.g., \"amd64\", \"arm64\")." }, "buildTags": { - "type": "string" + "type": "string", + "description": "BuildTags are the build tags used to conditionally compile code (e.g., \"integration,debug\")." }, "cgoEnabled": { - "type": "boolean" + "type": "boolean", + "description": "CgoEnabled indicates whether CGO was enabled for this package." } }, "type": "object", "required": [ "cgoEnabled" - ] + ], + "description": "GolangSourceEntry represents all captured data for a Golang package found through source analysis" }, "HaskellHackageStackEntry": { "properties": { "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the package content hash for verification" } }, - "type": "object" + "type": "object", + "description": "HackageStackYamlEntry represents a single entry from the \"extra-deps\" section of a stack.yaml file." }, "HaskellHackageStackLockEntry": { "properties": { "pkgHash": { - "type": "string" + "type": "string", + "description": "PkgHash is the package content hash for verification" }, "snapshotURL": { - "type": "string" + "type": "string", + "description": "SnapshotURL is the URL to the Stack snapshot this package came from" } }, - "type": "object" + "type": "object", + "description": "HackageStackYamlLockEntry represents a single entry from the \"packages\" section of a stack.yaml.lock file." }, "HomebrewFormula": { "properties": { "tap": { - "type": "string" + "type": "string", + "description": "Tap is Homebrew tap this formula belongs to (e.g. \"homebrew/core\")" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is the upstream project homepage URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable formula description" } }, - "type": "object" + "type": "object", + "description": "HomebrewFormula represents metadata about a Homebrew formula package extracted from formula JSON files." }, "IDLikes": { "items": { @@ -1301,71 +1550,86 @@ "JavaArchive": { "properties": { "virtualPath": { - "type": "string" + "type": "string", + "description": "VirtualPath is path within the archive hierarchy, where nested entries are delimited with ':' (for nested JARs)" }, "manifest": { - "$ref": "#/$defs/JavaManifest" + "$ref": "#/$defs/JavaManifest", + "description": "Manifest is parsed META-INF/MANIFEST.MF contents" }, "pomProperties": { - "$ref": "#/$defs/JavaPomProperties" + "$ref": "#/$defs/JavaPomProperties", + "description": "PomProperties is parsed pom.properties file contents" }, "pomProject": { - "$ref": "#/$defs/JavaPomProject" + "$ref": "#/$defs/JavaPomProject", + "description": "PomProject is parsed pom.xml file contents" }, "digest": { "items": { "$ref": "#/$defs/Digest" }, - "type": "array" + "type": "array", + "description": "ArchiveDigests is cryptographic hashes of the archive file" } }, "type": "object", "required": [ "virtualPath" - ] + ], + "description": "JavaArchive encapsulates all Java ecosystem metadata for a package as well as an (optional) parent relationship." }, "JavaJvmInstallation": { "properties": { "release": { - "$ref": "#/$defs/JavaVMRelease" + "$ref": "#/$defs/JavaVMRelease", + "description": "Release is JVM release information and version details" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files are the list of files that are part of this JVM installation" } }, "type": "object", "required": [ "release", "files" - ] + ], + "description": "JavaVMInstallation represents a Java Virtual Machine installation discovered on the system with its release information and file list." }, "JavaManifest": { "properties": { "main": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "Main is main manifest attributes as key-value pairs" }, "sections": { "items": { "$ref": "#/$defs/KeyValues" }, - "type": "array" + "type": "array", + "description": "Sections are the named sections from the manifest (e.g. per-entry attributes)" } }, - "type": "object" + "type": "object", + "description": "JavaManifest represents the fields of interest extracted from a Java archive's META-INF/MANIFEST.MF file." }, "JavaPomParent": { "properties": { "groupId": { - "type": "string" + "type": "string", + "description": "GroupID is the parent Maven group identifier" }, "artifactId": { - "type": "string" + "type": "string", + "description": "ArtifactID is the parent Maven artifact identifier" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the parent version (child inherits configuration from this specific version of parent POM)" } }, "type": "object", @@ -1373,33 +1637,42 @@ "groupId", "artifactId", "version" - ] + ], + "description": "JavaPomParent contains the fields within the \u003cparent\u003e tag in a pom.xml file" }, "JavaPomProject": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the pom.xml file within the archive" }, "parent": { - "$ref": "#/$defs/JavaPomParent" + "$ref": "#/$defs/JavaPomParent", + "description": "Parent is the parent POM reference for inheritance (child POMs inherit configuration from parent)" }, "groupId": { - "type": "string" + "type": "string", + "description": "GroupID is Maven group identifier (reversed domain name like org.apache.maven)" }, "artifactId": { - "type": "string" + "type": "string", + "description": "ArtifactID is Maven artifact identifier (project name)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is project version (together with groupId and artifactId forms Maven coordinates groupId:artifactId:version)" }, "name": { - "type": "string" + "type": "string", + "description": "Name is a human-readable project name (displayed in Maven-generated documentation)" }, "description": { - "type": "string" + "type": "string", + "description": "Description is detailed project description" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the project URL (typically project website or repository)" } }, "type": "object", @@ -1409,27 +1682,34 @@ "artifactId", "version", "name" - ] + ], + "description": "JavaPomProject represents fields of interest extracted from a Java archive's pom.xml file." }, "JavaPomProperties": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the pom.properties file within the archive" }, "name": { - "type": "string" + "type": "string", + "description": "Name is the project name" }, "groupId": { - "type": "string" + "type": "string", + "description": "GroupID is Maven group identifier uniquely identifying the project across all projects (follows reversed domain name convention like com.company.project)" }, "artifactId": { - "type": "string" + "type": "string", + "description": "ArtifactID is Maven artifact identifier, the name of the jar/artifact (unique within the groupId scope)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is artifact version" }, "scope": { - "type": "string" + "type": "string", + "description": "Scope is dependency scope determining when dependency is available (compile=default all phases, test=test compilation/execution only, runtime=runtime and test not compile, provided=expected from JDK or container)" }, "extraFields": { "patternProperties": { @@ -1437,7 +1717,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Extra is additional custom properties not in standard Maven coordinates" } }, "type": "object", @@ -1447,101 +1728,131 @@ "groupId", "artifactId", "version" - ] + ], + "description": "JavaPomProperties represents the fields of interest extracted from a Java archive's pom.properties file." }, "JavaVMRelease": { "properties": { "implementor": { - "type": "string" + "type": "string", + "description": "Implementor is extracted with the `java.vendor` JVM property" }, "implementorVersion": { - "type": "string" + "type": "string", + "description": "ImplementorVersion is extracted with the `java.vendor.version` JVM property" }, "javaRuntimeVersion": { - "type": "string" + "type": "string", + "description": "JavaRuntimeVersion is extracted from the 'java.runtime.version' JVM property" }, "javaVersion": { - "type": "string" + "type": "string", + "description": "JavaVersion matches that from `java -version` command output" }, "javaVersionDate": { - "type": "string" + "type": "string", + "description": "JavaVersionDate is extracted from the 'java.version.date' JVM property" }, "libc": { - "type": "string" + "type": "string", + "description": "Libc can either be 'glibc' or 'musl'" }, "modules": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Modules is a list of JVM modules that are packaged" }, "osArch": { - "type": "string" + "type": "string", + "description": "OsArch is the target CPU architecture" }, "osName": { - "type": "string" + "type": "string", + "description": "OsName is the name of the target runtime operating system environment" }, "osVersion": { - "type": "string" + "type": "string", + "description": "OsVersion is the version of the target runtime operating system environment" }, "source": { - "type": "string" + "type": "string", + "description": "Source refers to the origin repository of OpenJDK source" }, "buildSource": { - "type": "string" + "type": "string", + "description": "BuildSource Git SHA of the build repository" }, "buildSourceRepo": { - "type": "string" + "type": "string", + "description": "BuildSourceRepo refers to rhe repository URL for the build source" }, "sourceRepo": { - "type": "string" + "type": "string", + "description": "SourceRepo refers to the OpenJDK repository URL" }, "fullVersion": { - "type": "string" + "type": "string", + "description": "FullVersion is extracted from the 'java.runtime.version' JVM property" }, "semanticVersion": { - "type": "string" + "type": "string", + "description": "SemanticVersion is derived from the OpenJDK version" }, "buildInfo": { - "type": "string" + "type": "string", + "description": "BuildInfo contains additional build information" }, "jvmVariant": { - "type": "string" + "type": "string", + "description": "JvmVariant specifies the JVM variant (e.g., Hotspot or OpenJ9)" }, "jvmVersion": { - "type": "string" + "type": "string", + "description": "JvmVersion is extracted from the 'java.vm.version' JVM property" }, "imageType": { - "type": "string" + "type": "string", + "description": "ImageType can be 'JDK' or 'JRE'" }, "buildType": { - "type": "string" + "type": "string", + "description": "BuildType can be 'commercial' (used in some older oracle JDK distributions)" } }, - "type": "object" + "type": "object", + "description": "JavaVMRelease represents JVM version and build information extracted from the release file in a Java installation." }, "JavascriptNpmPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in package.json" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in package.json" }, "author": { - "type": "string" + "type": "string", + "description": "Author is package author name" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "url": { - "type": "string" + "type": "string", + "description": "URL is repository or project URL" }, "private": { - "type": "boolean" + "type": "boolean", + "description": "Private is whether this is a private package" } }, "type": "object", @@ -1553,58 +1864,69 @@ "description", "url", "private" - ] + ], + "description": "NpmPackage represents the contents of a javascript package.json file." }, "JavascriptNpmPackageLockEntry": { "properties": { "resolved": { - "type": "string" + "type": "string", + "description": "Resolved is URL where this package was downloaded from (registry source)" }, "integrity": { - "type": "string" + "type": "string", + "description": "Integrity is Subresource Integrity hash for verification using standard SRI format (sha512-... or sha1-...). npm changed from SHA-1 to SHA-512 in newer versions. For registry sources this is the integrity from registry, for remote tarballs it's SHA-512 of the file. npm verifies tarball matches this hash before unpacking, throwing EINTEGRITY error if mismatch detected." } }, "type": "object", "required": [ "resolved", "integrity" - ] + ], + "description": "NpmPackageLockEntry represents a single entry within the \"packages\" section of a package-lock.json file." }, "JavascriptYarnLockEntry": { "properties": { "resolved": { - "type": "string" + "type": "string", + "description": "Resolved is URL where this package was downloaded from" }, "integrity": { - "type": "string" + "type": "string", + "description": "Integrity is Subresource Integrity hash for verification (SRI format)" } }, "type": "object", "required": [ "resolved", "integrity" - ] + ], + "description": "YarnLockEntry represents a single entry section of a yarn.lock file." }, "KeyValue": { "properties": { "key": { - "type": "string" + "type": "string", + "description": "Key is the key name" }, "value": { - "type": "string" + "type": "string", + "description": "Value is the value associated with the key" } }, "type": "object", "required": [ "key", "value" - ] + ], + "description": "KeyValue represents a single key-value pair." }, "KeyValues": { "items": { "$ref": "#/$defs/KeyValue" }, - "type": "array" + "type": "array", + "description": "KeyValues represents an ordered collection of key-value pairs that preserves insertion order." }, "License": { "properties": { @@ -1645,37 +1967,48 @@ "LinuxKernelArchive": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is kernel name (typically \"Linux\")" }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture" }, "version": { - "type": "string" + "type": "string", + "description": "Version is kernel version string" }, "extendedVersion": { - "type": "string" + "type": "string", + "description": "ExtendedVersion is additional version information" }, "buildTime": { - "type": "string" + "type": "string", + "description": "BuildTime is when the kernel was built" }, "author": { - "type": "string" + "type": "string", + "description": "Author is who built the kernel" }, "format": { - "type": "string" + "type": "string", + "description": "Format is kernel image format (e.g. bzImage, zImage)" }, "rwRootFS": { - "type": "boolean" + "type": "boolean", + "description": "RWRootFS is whether root filesystem is mounted read-write" }, "swapDevice": { - "type": "integer" + "type": "integer", + "description": "SwapDevice is swap device number" }, "rootDevice": { - "type": "integer" + "type": "integer", + "description": "RootDevice is root device number" }, "videoMode": { - "type": "string" + "type": "string", + "description": "VideoMode is default video mode setting" } }, "type": "object", @@ -1683,36 +2016,46 @@ "name", "architecture", "version" - ] + ], + "description": "LinuxKernel represents all captured data for a Linux kernel" }, "LinuxKernelModule": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is module name" }, "version": { - "type": "string" + "type": "string", + "description": "Version is module version string" }, "sourceVersion": { - "type": "string" + "type": "string", + "description": "SourceVersion is the source code version identifier" }, "path": { - "type": "string" + "type": "string", + "description": "Path is the filesystem path to the .ko kernel object file (absolute path)" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable module description" }, "author": { - "type": "string" + "type": "string", + "description": "Author is module author name and email" }, "license": { - "type": "string" + "type": "string", + "description": "License is module license (e.g. GPL, BSD) which must be compatible with kernel" }, "kernelVersion": { - "type": "string" + "type": "string", + "description": "KernelVersion is kernel version this module was built for" }, "versionMagic": { - "type": "string" + "type": "string", + "description": "VersionMagic is version magic string for compatibility checking (includes kernel version, SMP status, module loading capabilities like \"3.17.4-302.fc21.x86_64 SMP mod_unload modversions\"). Module will NOT load if vermagic doesn't match running kernel." }, "parameters": { "patternProperties": { @@ -1720,21 +2063,26 @@ "$ref": "#/$defs/LinuxKernelModuleParameter" } }, - "type": "object" + "type": "object", + "description": "Parameters are the module parameters that can be configured at load time (user-settable values like module options)" } }, - "type": "object" + "type": "object", + "description": "LinuxKernelModule represents a loadable kernel module (.ko file) with its metadata, parameters, and dependencies." }, "LinuxKernelModuleParameter": { "properties": { "type": { - "type": "string" + "type": "string", + "description": "Type is parameter data type (e.g. int, string, bool, array types)" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable parameter description explaining what the parameter controls" } }, - "type": "object" + "type": "object", + "description": "LinuxKernelModuleParameter represents a configurable parameter for a kernel module with its type and description." }, "LinuxRelease": { "properties": { @@ -1801,13 +2149,16 @@ "Location": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "RealPath is the canonical absolute form of the path accessed (all symbolic links have been followed and relative path components like '.' and '..' have been removed)." }, "layerID": { - "type": "string" + "type": "string", + "description": "FileSystemID is an ID representing and entire filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank." }, "accessPath": { - "type": "string" + "type": "string", + "description": "AccessPath is the path used to retrieve file contents (which may or may not have hardlinks / symlinks in the path)" }, "annotations": { "patternProperties": { @@ -1822,27 +2173,34 @@ "required": [ "path", "accessPath" - ] + ], + "description": "Location represents a path relative to a particular filesystem resolved to a specific file.Reference." }, "LuarocksPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the .rockspec file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the .rockspec file" }, "license": { - "type": "string" + "type": "string", + "description": "License is license identifier" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the source download URL" }, "dependencies": { "patternProperties": { @@ -1850,7 +2208,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Dependencies are the map of dependency names to version constraints" } }, "type": "object", @@ -1862,117 +2221,142 @@ "description", "url", "dependencies" - ] + ], + "description": "LuaRocksPackage represents a Lua package managed by the LuaRocks package manager with metadata from .rockspec files." }, "MicrosoftKbPatch": { "properties": { "product_id": { - "type": "string" + "type": "string", + "description": "ProductID is MSRC Product ID (e.g. \"Windows 10 Version 1703 for 32-bit Systems\")" }, "kb": { - "type": "string" + "type": "string", + "description": "Kb is Knowledge Base article number (e.g. \"5001028\")" } }, "type": "object", "required": [ "product_id", "kb" - ] + ], + "description": "MicrosoftKbPatch is slightly odd in how it is expected to map onto data." }, "NixDerivation": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the .drv file in Nix store" }, "system": { - "type": "string" + "type": "string", + "description": "System is target system string indicating where derivation can be built (e.g. \"x86_64-linux\", \"aarch64-darwin\"). Must match current system for local builds." }, "inputDerivations": { "items": { "$ref": "#/$defs/NixDerivationReference" }, - "type": "array" + "type": "array", + "description": "InputDerivations are the list of other derivations that were inputs to this build (dependencies)" }, "inputSources": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "InputSources are the list of source file paths that were inputs to this build" } }, - "type": "object" + "type": "object", + "description": "NixDerivation represents a Nix .drv file that describes how to build a package including inputs, outputs, and build instructions." }, "NixDerivationReference": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is path to the referenced .drv file" }, "outputs": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Outputs are which outputs of the referenced derivation were used (e.g. [\"out\"], [\"bin\", \"dev\"])" } }, - "type": "object" + "type": "object", + "description": "NixDerivationReference represents a reference to another derivation used as a build input or runtime dependency." }, "NixStoreEntry": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is full store path for this output (e.g. /nix/store/abc123...-package-1.0)" }, "output": { - "type": "string" + "type": "string", + "description": "Output is the specific output name for multi-output packages (empty string for default \"out\" output, can be \"bin\", \"dev\", \"doc\", etc.)" }, "outputHash": { - "type": "string" + "type": "string", + "description": "OutputHash is hash prefix of the store path basename (first part before the dash)" }, "derivation": { - "$ref": "#/$defs/NixDerivation" + "$ref": "#/$defs/NixDerivation", + "description": "Derivation is information about the .drv file that describes how this package was built" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files are the list of files under the nix/store path for this package" } }, "type": "object", "required": [ "outputHash" - ] + ], + "description": "NixStoreEntry represents a package in the Nix store (/nix/store) with its derivation information and metadata." }, "OpamPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the .opam file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the .opam file" }, "licenses": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Licenses are the list of applicable licenses" }, "url": { - "type": "string" + "type": "string", + "description": "URL is download URL for the package source" }, "checksum": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Checksums are the list of checksums for verification" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the list of required dependencies" } }, "type": "object", @@ -1984,7 +2368,8 @@ "checksum", "homepage", "dependencies" - ] + ], + "description": "OpamPackage represents an OCaml package managed by the OPAM package manager with metadata from .opam files." }, "Package": { "properties": { @@ -2224,49 +2609,60 @@ "language", "cpes", "purl" - ] + ], + "description": "Package represents a pkg.Package object specialized for JSON marshaling and unmarshalling." }, "PeBinary": { "properties": { "VersionResources": { - "$ref": "#/$defs/KeyValues" + "$ref": "#/$defs/KeyValues", + "description": "VersionResources contains key-value pairs extracted from the PE file's version resource section (e.g., FileVersion, ProductName, CompanyName)." } }, "type": "object", "required": [ "VersionResources" - ] + ], + "description": "PEBinary represents metadata captured from a Portable Executable formatted binary (dll, exe, etc.)" }, "PhpComposerAuthors": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is author's full name" }, "email": { - "type": "string" + "type": "string", + "description": "Email is author's email address" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is author's personal or company website" } }, "type": "object", "required": [ "name" - ] + ], + "description": "PhpComposerAuthors represents author information for a PHP Composer package from the authors field in composer.json." }, "PhpComposerExternalReference": { "properties": { "type": { - "type": "string" + "type": "string", + "description": "Type is reference type (git for source VCS, zip/tar for dist archives)" }, "url": { - "type": "string" + "type": "string", + "description": "URL is the URL to the resource (git repository URL or archive download URL)" }, "reference": { - "type": "string" + "type": "string", + "description": "Reference is git commit hash or version tag for source, or archive version for dist" }, "shasum": { - "type": "string" + "type": "string", + "description": "Shasum is SHA hash of the archive file for integrity verification (dist only)" } }, "type": "object", @@ -2274,21 +2670,26 @@ "type", "url", "reference" - ] + ], + "description": "PhpComposerExternalReference represents source or distribution information for a PHP package, indicating where the package code is retrieved from." }, "PhpComposerInstalledEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is package name in vendor/package format (e.g. symfony/console)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "source": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Source is the source repository information for development (typically git repo, used when passing --prefer-source). Originates from source code repository." }, "dist": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Dist is distribution archive information for production (typically zip/tar, default install method). Packaged version of released code." }, "require": { "patternProperties": { @@ -2296,7 +2697,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Require is runtime dependencies with version constraints (package will not install unless these requirements can be met)" }, "provide": { "patternProperties": { @@ -2304,7 +2706,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Provide is virtual packages/functionality provided by this package (allows other packages to depend on capabilities)" }, "require-dev": { "patternProperties": { @@ -2312,7 +2715,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "RequireDev is development-only dependencies (not installed in production, only when developing this package or running tests)" }, "suggest": { "patternProperties": { @@ -2320,46 +2724,56 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Suggest is optional but recommended dependencies (suggestions for packages that would extend functionality)" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of license identifiers (SPDX format)" }, "type": { - "type": "string" + "type": "string", + "description": "Type is package type indicating purpose (library=reusable code, project=application, metapackage=aggregates dependencies, etc.)" }, "notification-url": { - "type": "string" + "type": "string", + "description": "NotificationURL is the URL to notify when package is installed (for tracking/statistics)" }, "bin": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Bin is the list of binary/executable files that should be added to PATH" }, "authors": { "items": { "$ref": "#/$defs/PhpComposerAuthors" }, - "type": "array" + "type": "array", + "description": "Authors are the list of package authors with name/email/homepage" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "keywords": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Keywords are the list of keywords for package discovery/search" }, "time": { - "type": "string" + "type": "string", + "description": "Time is timestamp when this package version was released" } }, "type": "object", @@ -2368,21 +2782,26 @@ "version", "source", "dist" - ] + ], + "description": "PhpComposerInstalledEntry represents a single package entry from a composer v1/v2 \"installed.json\" files (very similar to composer.lock files)." }, "PhpComposerLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is package name in vendor/package format (e.g. symfony/console)" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "source": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Source is the source repository information for development (typically git repo, used when passing --prefer-source). Originates from source code repository." }, "dist": { - "$ref": "#/$defs/PhpComposerExternalReference" + "$ref": "#/$defs/PhpComposerExternalReference", + "description": "Dist is distribution archive information for production (typically zip/tar, default install method). Packaged version of released code." }, "require": { "patternProperties": { @@ -2390,7 +2809,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Require is runtime dependencies with version constraints (package will not install unless these requirements can be met)" }, "provide": { "patternProperties": { @@ -2398,7 +2818,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Provide is virtual packages/functionality provided by this package (allows other packages to depend on capabilities)" }, "require-dev": { "patternProperties": { @@ -2406,7 +2827,8 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "RequireDev is development-only dependencies (not installed in production, only when developing this package or running tests)" }, "suggest": { "patternProperties": { @@ -2414,46 +2836,56 @@ "type": "string" } }, - "type": "object" + "type": "object", + "description": "Suggest is optional but recommended dependencies (suggestions for packages that would extend functionality)" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of license identifiers (SPDX format)" }, "type": { - "type": "string" + "type": "string", + "description": "Type is package type indicating purpose (library=reusable code, project=application, metapackage=aggregates dependencies, etc.)" }, "notification-url": { - "type": "string" + "type": "string", + "description": "NotificationURL is the URL to notify when package is installed (for tracking/statistics)" }, "bin": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Bin is the list of binary/executable files that should be added to PATH" }, "authors": { "items": { "$ref": "#/$defs/PhpComposerAuthors" }, - "type": "array" + "type": "array", + "description": "Authors are the list of package authors with name/email/homepage" }, "description": { - "type": "string" + "type": "string", + "description": "Description is a human-readable package description" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "keywords": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Keywords are the list of keywords for package discovery/search" }, "time": { - "type": "string" + "type": "string", + "description": "Time is timestamp when this package version was released" } }, "type": "object", @@ -2462,189 +2894,230 @@ "version", "source", "dist" - ] + ], + "description": "PhpComposerLockEntry represents a single package entry found from a composer.lock file." }, "PhpPearEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is PEAR channel this package is from" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of applicable licenses" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "PhpPearEntry represents a single package entry found within php pear metadata files." }, "PhpPeclEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name" }, "channel": { - "type": "string" + "type": "string", + "description": "Channel is PEAR channel this package is from" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version" }, "license": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "License is the list of applicable licenses" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "PhpPeclEntry represents a single package entry found within php pecl metadata files." }, "PortageDbEntry": { "properties": { "installedSize": { - "type": "integer" + "type": "integer", + "description": "InstalledSize is total size of installed files in bytes" }, "licenses": { - "type": "string" + "type": "string", + "description": "Licenses is license string which may be an expression (e.g. \"GPL-2 OR Apache-2.0\")" }, "files": { "items": { "$ref": "#/$defs/PortageFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the files installed by this package (tracked in CONTENTS file)" } }, "type": "object", "required": [ "installedSize", "files" - ] + ], + "description": "PortageEntry represents a single package entry in the portage DB flat-file store." }, "PortageFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the file path relative to the filesystem root" }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest is file content hash (MD5 for regular files in CONTENTS format: \"obj filename md5hash mtime\")" } }, "type": "object", "required": [ "path" - ] + ], + "description": "PortageFileRecord represents a single file attributed to a portage package." }, "PythonDirectURLOriginInfo": { "properties": { "url": { - "type": "string" + "type": "string", + "description": "URL is the source URL from which the package was installed." }, "commitId": { - "type": "string" + "type": "string", + "description": "CommitID is the VCS commit hash if installed from version control." }, "vcs": { - "type": "string" + "type": "string", + "description": "VCS is the version control system type (e.g., \"git\", \"hg\")." } }, "type": "object", "required": [ "url" - ] + ], + "description": "PythonDirectURLOriginInfo represents installation source metadata from direct_url.json for packages installed from VCS or direct URLs." }, "PythonFileDigest": { "properties": { "algorithm": { - "type": "string" + "type": "string", + "description": "Algorithm is the hash algorithm used (e.g., \"sha256\")." }, "value": { - "type": "string" + "type": "string", + "description": "Value is the hex-encoded hash digest value." } }, "type": "object", "required": [ "algorithm", "value" - ] + ], + "description": "PythonFileDigest represents the file metadata for a single file attributed to a python package." }, "PythonFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the installed file path from the RECORD file." }, "digest": { - "$ref": "#/$defs/PythonFileDigest" + "$ref": "#/$defs/PythonFileDigest", + "description": "Digest contains the hash algorithm and value for file integrity verification." }, "size": { - "type": "string" + "type": "string", + "description": "Size is the file size in bytes as a string." } }, "type": "object", "required": [ "path" - ] + ], + "description": "PythonFileRecord represents a single entry within a RECORD file for a python wheel or egg package" }, "PythonPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name from the Name field in PKG-INFO or METADATA." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version from the Version field in PKG-INFO or METADATA." }, "author": { - "type": "string" + "type": "string", + "description": "Author is the package author name from the Author field." }, "authorEmail": { - "type": "string" + "type": "string", + "description": "AuthorEmail is the package author's email address from the Author-Email field." }, "platform": { - "type": "string" + "type": "string", + "description": "Platform indicates the target platform for the package (e.g., \"any\", \"linux\", \"win32\")." }, "files": { "items": { "$ref": "#/$defs/PythonFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the installed files listed in the RECORD file for wheels or installed-files.txt for eggs." }, "sitePackagesRootPath": { - "type": "string" + "type": "string", + "description": "SitePackagesRootPath is the root directory path containing the package (e.g., \"/usr/lib/python3.9/site-packages\")." }, "topLevelPackages": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "TopLevelPackages are the top-level Python module names from top_level.txt file." }, "directUrlOrigin": { - "$ref": "#/$defs/PythonDirectURLOriginInfo" + "$ref": "#/$defs/PythonDirectURLOriginInfo", + "description": "DirectURLOrigin contains VCS or direct URL installation information from direct_url.json." }, "requiresPython": { - "type": "string" + "type": "string", + "description": "RequiresPython specifies the Python version requirement (e.g., \"\u003e=3.6\")." }, "requiresDist": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "RequiresDist lists the package dependencies with version specifiers from Requires-Dist fields." }, "providesExtra": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "ProvidesExtra lists optional feature names that can be installed via extras (e.g., \"dev\", \"test\")." } }, "type": "object", @@ -2655,34 +3128,41 @@ "authorEmail", "platform", "sitePackagesRootPath" - ] + ], + "description": "PythonPackage represents all captured data for a python egg or wheel package (specifically as outlined in the PyPA core metadata specification https://packaging.python.org/en/latest/specifications/core-metadata/)." }, "PythonPipRequirementsEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name from the requirements file." }, "extras": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Extras are the optional features to install from the package (e.g., package[dev,test])." }, "versionConstraint": { - "type": "string" + "type": "string", + "description": "VersionConstraint specifies version requirements (e.g., \"\u003e=1.0,\u003c2.0\")." }, "url": { - "type": "string" + "type": "string", + "description": "URL is the direct download URL or VCS URL if specified instead of a PyPI package." }, "markers": { - "type": "string" + "type": "string", + "description": "Markers are environment marker expressions for conditional installation (e.g., \"python_version \u003e= '3.8'\")." } }, "type": "object", "required": [ "name", "versionConstraint" - ] + ], + "description": "PythonRequirementsEntry represents a single entry within a [*-]requirements.txt file." }, "PythonPipfileLockEntry": { "properties": { @@ -2690,37 +3170,45 @@ "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Hashes are the package file hash values in the format \"algorithm:digest\" for integrity verification." }, "index": { - "type": "string" + "type": "string", + "description": "Index is the PyPI index name where the package should be fetched from." } }, "type": "object", "required": [ "hashes", "index" - ] + ], + "description": "PythonPipfileLockEntry represents a single package entry within a Pipfile.lock file." }, "PythonPoetryLockDependencyEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the dependency package name." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the locked version or version constraint for the dependency." }, "optional": { - "type": "boolean" + "type": "boolean", + "description": "Optional indicates whether this dependency is optional (only needed for certain extras)." }, "markers": { - "type": "string" + "type": "string", + "description": "Markers are environment marker expressions that conditionally enable the dependency (e.g., \"python_version \u003e= '3.8'\")." }, "extras": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Extras are the optional feature names from the dependency that should be installed." } }, "type": "object", @@ -2728,165 +3216,197 @@ "name", "version", "optional" - ] + ], + "description": "PythonPoetryLockDependencyEntry represents a single dependency entry within a Poetry lock file." }, "PythonPoetryLockEntry": { "properties": { "index": { - "type": "string" + "type": "string", + "description": "Index is the package repository name where the package should be fetched from." }, "dependencies": { "items": { "$ref": "#/$defs/PythonPoetryLockDependencyEntry" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package's runtime dependencies with version constraints." }, "extras": { "items": { "$ref": "#/$defs/PythonPoetryLockExtraEntry" }, - "type": "array" + "type": "array", + "description": "Extras are optional feature groups that include additional dependencies." } }, "type": "object", "required": [ "index", "dependencies" - ] + ], + "description": "PythonPoetryLockEntry represents a single package entry within a Pipfile.lock file." }, "PythonPoetryLockExtraEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the optional feature name (e.g., \"dev\", \"test\")." }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package names required when this extra is installed." } }, "type": "object", "required": [ "name", "dependencies" - ] + ], + "description": "PythonPoetryLockExtraEntry represents an optional feature group in a Poetry lock file." }, "PythonUvLockDependencyEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the dependency package name." }, "optional": { - "type": "boolean" + "type": "boolean", + "description": "Optional indicates whether this dependency is optional (only needed for certain extras)." }, "markers": { - "type": "string" + "type": "string", + "description": "Markers are environment marker expressions that conditionally enable the dependency (e.g., \"python_version \u003e= '3.8'\")." }, "extras": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Extras are the optional feature names from the dependency that should be installed." } }, "type": "object", "required": [ "name", "optional" - ] + ], + "description": "PythonUvLockDependencyEntry represents a single dependency entry within a uv lock file." }, "PythonUvLockEntry": { "properties": { "index": { - "type": "string" + "type": "string", + "description": "Index is the package repository name where the package should be fetched from." }, "dependencies": { "items": { "$ref": "#/$defs/PythonUvLockDependencyEntry" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package's runtime dependencies with version constraints." }, "extras": { "items": { "$ref": "#/$defs/PythonUvLockExtraEntry" }, - "type": "array" + "type": "array", + "description": "Extras are optional feature groups that include additional dependencies." } }, "type": "object", "required": [ "index", "dependencies" - ] + ], + "description": "PythonUvLockEntry represents a single package entry within a uv.lock file." }, "PythonUvLockExtraEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the optional feature name (e.g., \"dev\", \"test\")." }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the package names required when this extra is installed." } }, "type": "object", "required": [ "name", "dependencies" - ] + ], + "description": "PythonUvLockExtraEntry represents an optional feature group in a uv lock file." }, "RDescription": { "properties": { "title": { - "type": "string" + "type": "string", + "description": "Title is short one-line package title" }, "description": { - "type": "string" + "type": "string", + "description": "Description is detailed package description" }, "author": { - "type": "string" + "type": "string", + "description": "Author is package author(s)" }, "maintainer": { - "type": "string" + "type": "string", + "description": "Maintainer is current package maintainer" }, "url": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "URL is the list of related URLs" }, "repository": { - "type": "string" + "type": "string", + "description": "Repository is CRAN or other repository name" }, "built": { - "type": "string" + "type": "string", + "description": "Built is R version and platform this was built with" }, "needsCompilation": { - "type": "boolean" + "type": "boolean", + "description": "NeedsCompilation is whether this package requires compilation" }, "imports": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Imports are the packages imported in the NAMESPACE" }, "depends": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Depends are the packages this package depends on" }, "suggests": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Suggests are the optional packages that extend functionality" } }, - "type": "object" + "type": "object", + "description": "RDescription represents metadata from an R package DESCRIPTION file containing package information, dependencies, and author details." }, "Relationship": { "properties": { @@ -2911,15 +3431,18 @@ "RpmArchive": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the RPM package name as found in the RPM database." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the upstream version of the package." }, "epoch": { "oneOf": [ { - "type": "integer" + "type": "integer", + "description": "Epoch is the version epoch used to force upgrade ordering (null if not set)." }, { "type": "null" @@ -2927,46 +3450,56 @@ ] }, "architecture": { - "type": "string" + "type": "string", + "description": "Arch is the target CPU architecture (e.g., \"x86_64\", \"aarch64\", \"noarch\")." }, "release": { - "type": "string" + "type": "string", + "description": "Release is the package release number or distribution-specific version suffix." }, "sourceRpm": { - "type": "string" + "type": "string", + "description": "SourceRpm is the source RPM filename that was used to build this package." }, "signatures": { "items": { "$ref": "#/$defs/RpmSignature" }, - "type": "array" + "type": "array", + "description": "Signatures contains GPG signature metadata for package verification." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the total installed size of the package in bytes." }, "vendor": { - "type": "string" + "type": "string", + "description": "Vendor is the organization that packaged the software." }, "modularityLabel": { - "type": "string" + "type": "string", + "description": "ModularityLabel identifies the module stream for modular RPM packages (e.g., \"nodejs:12:20200101\")." }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides lists the virtual packages and capabilities this package provides." }, "requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Requires lists the dependencies required by this package." }, "files": { "items": { "$ref": "#/$defs/RpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the file records for all files owned by this package." } }, "type": "object", @@ -2980,20 +3513,24 @@ "size", "vendor", "files" - ] + ], + "description": "RpmArchive represents package metadata extracted directly from a .rpm archive file, containing the same information as an RPM database entry." }, "RpmDbEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the RPM package name as found in the RPM database." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the upstream version of the package." }, "epoch": { "oneOf": [ { - "type": "integer" + "type": "integer", + "description": "Epoch is the version epoch used to force upgrade ordering (null if not set)." }, { "type": "null" @@ -3001,46 +3538,56 @@ ] }, "architecture": { - "type": "string" + "type": "string", + "description": "Arch is the target CPU architecture (e.g., \"x86_64\", \"aarch64\", \"noarch\")." }, "release": { - "type": "string" + "type": "string", + "description": "Release is the package release number or distribution-specific version suffix." }, "sourceRpm": { - "type": "string" + "type": "string", + "description": "SourceRpm is the source RPM filename that was used to build this package." }, "signatures": { "items": { "$ref": "#/$defs/RpmSignature" }, - "type": "array" + "type": "array", + "description": "Signatures contains GPG signature metadata for package verification." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the total installed size of the package in bytes." }, "vendor": { - "type": "string" + "type": "string", + "description": "Vendor is the organization that packaged the software." }, "modularityLabel": { - "type": "string" + "type": "string", + "description": "ModularityLabel identifies the module stream for modular RPM packages (e.g., \"nodejs:12:20200101\")." }, "provides": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Provides lists the virtual packages and capabilities this package provides." }, "requires": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Requires lists the dependencies required by this package." }, "files": { "items": { "$ref": "#/$defs/RpmFileRecord" }, - "type": "array" + "type": "array", + "description": "Files are the file records for all files owned by this package." } }, "type": "object", @@ -3054,30 +3601,38 @@ "size", "vendor", "files" - ] + ], + "description": "RpmDBEntry represents all captured data from a RPM DB package entry." }, "RpmFileRecord": { "properties": { "path": { - "type": "string" + "type": "string", + "description": "Path is the absolute file path where the file is installed." }, "mode": { - "type": "integer" + "type": "integer", + "description": "Mode is the file permission mode bits following Unix stat.h conventions." }, "size": { - "type": "integer" + "type": "integer", + "description": "Size is the file size in bytes." }, "digest": { - "$ref": "#/$defs/Digest" + "$ref": "#/$defs/Digest", + "description": "Digest contains the hash algorithm and value for file integrity verification." }, "userName": { - "type": "string" + "type": "string", + "description": "UserName is the owner username for the file." }, "groupName": { - "type": "string" + "type": "string", + "description": "GroupName is the group name for the file." }, "flags": { - "type": "string" + "type": "string", + "description": "Flags indicates the file type (e.g., \"%config\", \"%doc\", \"%ghost\")." } }, "type": "object", @@ -3089,21 +3644,26 @@ "userName", "groupName", "flags" - ] + ], + "description": "RpmFileRecord represents the file metadata for a single file attributed to a RPM package." }, "RpmSignature": { "properties": { "algo": { - "type": "string" + "type": "string", + "description": "PublicKeyAlgorithm is the public key algorithm used for signing (e.g., \"RSA\")." }, "hash": { - "type": "string" + "type": "string", + "description": "HashAlgorithm is the hash algorithm used for the signature (e.g., \"SHA256\")." }, "created": { - "type": "string" + "type": "string", + "description": "Created is the timestamp when the signature was created." }, "issuer": { - "type": "string" + "type": "string", + "description": "IssuerKeyID is the GPG key ID that created the signature." } }, "type": "object", @@ -3112,48 +3672,58 @@ "hash", "created", "issuer" - ] + ], + "description": "RpmSignature represents a GPG signature for an RPM package used for authenticity verification." }, "RubyGemspec": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is gem name as specified in the gemspec" }, "version": { - "type": "string" + "type": "string", + "description": "Version is gem version as specified in the gemspec" }, "files": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files is logical list of files in the gem (NOT directly usable as filesystem paths. Example: bundler gem lists \"lib/bundler/vendor/uri/lib/uri/ldap.rb\" but actual path is \"/usr/local/lib/ruby/3.2.0/bundler/vendor/uri/lib/uri/ldap.rb\". Would need gem installation path, ruby version, and env vars like GEM_HOME to resolve actual paths.)" }, "authors": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Authors are the list of gem authors (stored as array regardless of using `author` or `authors` method in gemspec)" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" } }, "type": "object", "required": [ "name", "version" - ] + ], + "description": "RubyGemspec represents all metadata parsed from the *.gemspec file" }, "RustCargoAuditEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is crate name as specified in audit section of the build binary" }, "version": { - "type": "string" + "type": "string", + "description": "Version is crate version as specified in audit section of the build binary" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source registry or repository where this crate came from" } }, "type": "object", @@ -3161,27 +3731,33 @@ "name", "version", "source" - ] + ], + "description": "RustBinaryAuditEntry represents Rust crate metadata extracted from a compiled binary using cargo-auditable format." }, "RustCargoLockEntry": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is crate name as specified in Cargo.toml" }, "version": { - "type": "string" + "type": "string", + "description": "Version is crate version as specified in Cargo.toml" }, "source": { - "type": "string" + "type": "string", + "description": "Source is the source registry or repository URL in format \"registry+https://github.com/rust-lang/crates.io-index\" for registry packages" }, "checksum": { - "type": "string" + "type": "string", + "description": "Checksum is content checksum for registry packages only (hexadecimal string). Cargo doesn't require or include checksums for git dependencies. Used to detect MITM attacks by verifying downloaded crate matches lockfile checksum." }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the list of dependencies with version constraints" } }, "type": "object", @@ -3191,7 +3767,8 @@ "source", "checksum", "dependencies" - ] + ], + "description": "RustCargoLockEntry represents a locked dependency from a Cargo.lock file with precise version and checksum information." }, "Schema": { "properties": { @@ -3211,19 +3788,24 @@ "SnapEntry": { "properties": { "snapType": { - "type": "string" + "type": "string", + "description": "SnapType indicates the snap type (base, kernel, app, gadget, or snapd)." }, "base": { - "type": "string" + "type": "string", + "description": "Base is the base snap name that this snap depends on (e.g., \"core20\", \"core22\")." }, "snapName": { - "type": "string" + "type": "string", + "description": "SnapName is the snap package name." }, "snapVersion": { - "type": "string" + "type": "string", + "description": "SnapVersion is the snap package version." }, "architecture": { - "type": "string" + "type": "string", + "description": "Architecture is the target CPU architecture (e.g., \"amd64\", \"arm64\")." } }, "type": "object", @@ -3233,7 +3815,8 @@ "snapName", "snapVersion", "architecture" - ] + ], + "description": "SnapEntry represents metadata for a Snap package extracted from snap.yaml or snapcraft.yaml files." }, "Source": { "properties": { @@ -3261,47 +3844,58 @@ "version", "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." }, "SwiftPackageManagerLockEntry": { "properties": { "revision": { - "type": "string" + "type": "string", + "description": "Revision is git commit hash of the resolved package" } }, "type": "object", "required": [ "revision" - ] + ], + "description": "SwiftPackageManagerResolvedEntry represents a resolved dependency from a Package.resolved file with its locked version and source location." }, "SwiplpackPackage": { "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the package name as found in the .toml file" }, "version": { - "type": "string" + "type": "string", + "description": "Version is the package version as found in the .toml file" }, "author": { - "type": "string" + "type": "string", + "description": "Author is author name" }, "authorEmail": { - "type": "string" + "type": "string", + "description": "AuthorEmail is author email address" }, "packager": { - "type": "string" + "type": "string", + "description": "Packager is packager name (if different from author)" }, "packagerEmail": { - "type": "string" + "type": "string", + "description": "PackagerEmail is packager email address" }, "homepage": { - "type": "string" + "type": "string", + "description": "Homepage is project homepage URL" }, "dependencies": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Dependencies are the list of required dependencies" } }, "type": "object", @@ -3314,24 +3908,29 @@ "packagerEmail", "homepage", "dependencies" - ] + ], + "description": "SwiplPackEntry represents a SWI-Prolog package from the pack system with metadata about the package and its dependencies." }, "TerraformLockProviderEntry": { "properties": { "url": { - "type": "string" + "type": "string", + "description": "URL is the provider source address (e.g., \"registry.terraform.io/hashicorp/aws\")." }, "constraints": { - "type": "string" + "type": "string", + "description": "Constraints specifies the version constraints for the provider (e.g., \"~\u003e 4.0\")." }, "version": { - "type": "string" + "type": "string", + "description": "Version is the locked provider version selected during terraform init." }, "hashes": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Hashes are cryptographic checksums for the provider plugin archives across different platforms." } }, "type": "object", @@ -3340,24 +3939,29 @@ "constraints", "version", "hashes" - ] + ], + "description": "TerraformLockProviderEntry represents a single provider entry in a Terraform dependency lock file (.terraform.lock.hcl)." }, "WordpressPluginEntry": { "properties": { "pluginInstallDirectory": { - "type": "string" + "type": "string", + "description": "PluginInstallDirectory is directory name where the plugin is installed" }, "author": { - "type": "string" + "type": "string", + "description": "Author is plugin author name" }, "authorUri": { - "type": "string" + "type": "string", + "description": "AuthorURI is author's website URL" } }, "type": "object", "required": [ "pluginInstallDirectory" - ] + ], + "description": "WordpressPluginEntry represents all metadata parsed from the wordpress plugin file" }, "cpes": { "items": { diff --git a/syft/file/coordinate_set.go b/syft/file/coordinate_set.go index c5ea0be94..5342f6de2 100644 --- a/syft/file/coordinate_set.go +++ b/syft/file/coordinate_set.go @@ -7,6 +7,7 @@ import ( "github.com/scylladb/go-set/strset" ) +// CoordinateSet provides a unique collection of Coordinates with set operations. type CoordinateSet struct { set map[Coordinates]struct{} } diff --git a/syft/file/coordinates.go b/syft/file/coordinates.go index 0f76a71c1..afeda5b13 100644 --- a/syft/file/coordinates.go +++ b/syft/file/coordinates.go @@ -9,8 +9,11 @@ import ( // Coordinates contains the minimal information needed to describe how to find a file within any possible source object (e.g. image and directory sources) type Coordinates struct { - RealPath string `json:"path" cyclonedx:"path"` // The path where all path ancestors have no hardlinks / symlinks - FileSystemID string `json:"layerID,omitempty" cyclonedx:"layerID"` // An ID representing the filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank. + // RealPath is the canonical absolute form of the path accessed (all symbolic links have been followed and relative path components like '.' and '..' have been removed). + RealPath string `json:"path" cyclonedx:"path"` + + // FileSystemID is an ID representing and entire filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank. + FileSystemID string `json:"layerID,omitempty" cyclonedx:"layerID"` } func NewCoordinates(realPath, fsID string) Coordinates { diff --git a/syft/file/digest.go b/syft/file/digest.go index 87b53dbb8..931504434 100644 --- a/syft/file/digest.go +++ b/syft/file/digest.go @@ -1,6 +1,10 @@ package file +// Digest represents a cryptographic hash of file contents. type Digest struct { + // Algorithm specifies the hash algorithm used (e.g., "sha256", "md5"). Algorithm string `json:"algorithm"` - Value string `json:"value"` + + // Value is the hexadecimal string representation of the hash. + Value string `json:"value"` } diff --git a/syft/file/executable.go b/syft/file/executable.go index dc0990b5d..454b1bf9f 100644 --- a/syft/file/executable.go +++ b/syft/file/executable.go @@ -1,40 +1,60 @@ package file type ( - ExecutableFormat string + // ExecutableFormat represents the binary executable format type. + ExecutableFormat string + + // RelocationReadOnly indicates the RELRO security protection level applied to an ELF binary. RelocationReadOnly string ) const ( - ELF ExecutableFormat = "elf" - MachO ExecutableFormat = "macho" - PE ExecutableFormat = "pe" + ELF ExecutableFormat = "elf" // Executable and Linkable Format used on Unix-like systems + MachO ExecutableFormat = "macho" // Mach object file format used on macOS and iOS + PE ExecutableFormat = "pe" // Portable Executable format used on Windows - RelocationReadOnlyNone RelocationReadOnly = "none" - RelocationReadOnlyPartial RelocationReadOnly = "partial" - RelocationReadOnlyFull RelocationReadOnly = "full" + RelocationReadOnlyNone RelocationReadOnly = "none" // no RELRO protection + RelocationReadOnlyPartial RelocationReadOnly = "partial" // partial RELRO protection + RelocationReadOnlyFull RelocationReadOnly = "full" // full RELRO protection ) +// Executable contains metadata about binary files and their security features. type Executable struct { // Format denotes either ELF, Mach-O, or PE Format ExecutableFormat `json:"format" yaml:"format" mapstructure:"format"` - HasExports bool `json:"hasExports" yaml:"hasExports" mapstructure:"hasExports"` - HasEntrypoint bool `json:"hasEntrypoint" yaml:"hasEntrypoint" mapstructure:"hasEntrypoint"` - ImportedLibraries []string `json:"importedLibraries" yaml:"importedLibraries" mapstructure:"importedLibraries"` + // HasExports indicates whether the binary exports symbols. + HasExports bool `json:"hasExports" yaml:"hasExports" mapstructure:"hasExports"` + + // HasEntrypoint indicates whether the binary has an entry point function. + HasEntrypoint bool `json:"hasEntrypoint" yaml:"hasEntrypoint" mapstructure:"hasEntrypoint"` + + // ImportedLibraries lists the shared libraries required by this executable. + ImportedLibraries []string `json:"importedLibraries" yaml:"importedLibraries" mapstructure:"importedLibraries"` + + // ELFSecurityFeatures contains ELF-specific security hardening information when Format is ELF. ELFSecurityFeatures *ELFSecurityFeatures `json:"elfSecurityFeatures,omitempty" yaml:"elfSecurityFeatures" mapstructure:"elfSecurityFeatures"` } +// ELFSecurityFeatures captures security hardening and protection mechanisms in ELF binaries. type ELFSecurityFeatures struct { + // SymbolTableStripped indicates whether debugging symbols have been removed. SymbolTableStripped bool `json:"symbolTableStripped" yaml:"symbolTableStripped" mapstructure:"symbolTableStripped"` - // classic protections + // StackCanary indicates whether stack smashing protection is enabled. + StackCanary *bool `json:"stackCanary,omitempty" yaml:"stackCanary" mapstructure:"stackCanary"` - StackCanary *bool `json:"stackCanary,omitempty" yaml:"stackCanary" mapstructure:"stackCanary"` - NoExecutable bool `json:"nx" yaml:"nx" mapstructure:"nx"` - RelocationReadOnly RelocationReadOnly `json:"relRO" yaml:"relRO" mapstructure:"relRO"` - PositionIndependentExecutable bool `json:"pie" yaml:"pie" mapstructure:"pie"` - DynamicSharedObject bool `json:"dso" yaml:"dso" mapstructure:"dso"` + // NoExecutable indicates whether NX (no-execute) protection is enabled for the stack. + NoExecutable bool `json:"nx" yaml:"nx" mapstructure:"nx"` + + // RelocationReadOnly indicates the RELRO protection level. + RelocationReadOnly RelocationReadOnly `json:"relRO" yaml:"relRO" mapstructure:"relRO"` + + // PositionIndependentExecutable indicates whether the binary is compiled as PIE. + PositionIndependentExecutable bool `json:"pie" yaml:"pie" mapstructure:"pie"` + + // DynamicSharedObject indicates whether the binary is a shared library. + DynamicSharedObject bool `json:"dso" yaml:"dso" mapstructure:"dso"` // LlvmSafeStack represents a compiler-based security mechanism that separates the stack into a safe stack for storing return addresses and other critical data, and an unsafe stack for everything else, to mitigate stack-based memory corruption errors // see https://clang.llvm.org/docs/SafeStack.html diff --git a/syft/file/license.go b/syft/file/license.go index ea0dc6e9a..43b4690d5 100644 --- a/syft/file/license.go +++ b/syft/file/license.go @@ -5,18 +5,33 @@ import ( "github.com/anchore/syft/syft/license" ) +// License represents license information discovered within a file. type License struct { - Value string - SPDXExpression string - Type license.Type - LicenseEvidence *LicenseEvidence // evidence from license classifier - Contents string `hash:"ignore"` + // Value is the raw license string as found in the file. + Value string + + // SPDXExpression is the parsed SPDX license expression if available. + SPDXExpression string + + // Type categorizes how the license was determined (e.g., declared, concluded -- following the same semantics as SPDX). + Type license.Type + + LicenseEvidence *LicenseEvidence + + // Contents optionally stores the full license text. + Contents string `hash:"ignore"` } +// LicenseEvidence contains details from license classifier analysis. type LicenseEvidence struct { + // Confidence is a score indicating certainty of the license match. Confidence int - Offset int - Extent int + + // Offset is the byte position where the license text begins in the file. + Offset int + + // Extent is the length in bytes of the matched license text. + Extent int } func NewLicense(value string) License { diff --git a/syft/file/location.go b/syft/file/location.go index a70fe5d72..910ad5d1e 100644 --- a/syft/file/location.go +++ b/syft/file/location.go @@ -27,18 +27,24 @@ type Location struct { LocationMetadata `cyclonedx:""` } +// LocationData contains the core identifying information for a file location. type LocationData struct { Coordinates `cyclonedx:""` // Empty string here means there is no intermediate property name, e.g. syft:locations:0:path without "coordinates" // note: it is IMPORTANT to ignore anything but the coordinates for a Location when considering the ID (hash value) // since the coordinates are the minimally correct ID for a location (symlinks should not come into play) - AccessPath string `hash:"ignore" json:"accessPath"` // The path to the file which may or may not have hardlinks / symlinks - ref file.Reference `hash:"ignore"` // The file reference relative to the stereoscope.FileCatalog that has more information about this location. + + // AccessPath is the path used to retrieve file contents (which may or may not have hardlinks / symlinks in the path) + AccessPath string `hash:"ignore" json:"accessPath"` + + // ref is the stereoscope file reference relative to the stereoscope.FileCatalog that has more information about this location. + ref file.Reference `hash:"ignore"` } func (l LocationData) Reference() file.Reference { return l.ref } +// LocationMetadata provides additional contextual information about a file location. type LocationMetadata struct { Annotations map[string]string `json:"annotations,omitempty"` // Arbitrary key-value pairs that can be used to annotate a location } diff --git a/syft/file/location_read_closer.go b/syft/file/location_read_closer.go index 480a0b50f..2f1ac5e49 100644 --- a/syft/file/location_read_closer.go +++ b/syft/file/location_read_closer.go @@ -2,6 +2,7 @@ package file import "io" +// LocationReadCloser combines a Location with a ReadCloser for accessing file content with location metadata. type LocationReadCloser struct { Location io.ReadCloser diff --git a/syft/file/location_set.go b/syft/file/location_set.go index 9ee3a236a..52beb9e51 100644 --- a/syft/file/location_set.go +++ b/syft/file/location_set.go @@ -9,6 +9,7 @@ import ( "github.com/anchore/syft/internal/log" ) +// LocationSet provides a unique collection of Locations with metadata and set operations. type LocationSet struct { set map[LocationData]LocationMetadata } diff --git a/syft/file/locations.go b/syft/file/locations.go index f7836b5ea..3f7be072d 100644 --- a/syft/file/locations.go +++ b/syft/file/locations.go @@ -8,6 +8,7 @@ import ( var locationSorterWithoutLayers = LocationSorter(nil) +// Locations is a sortable slice of Location values. type Locations []Location func (l Locations) Len() int { diff --git a/syft/file/resolver.go b/syft/file/resolver.go index c3c942351..ac4652fcf 100644 --- a/syft/file/resolver.go +++ b/syft/file/resolver.go @@ -18,6 +18,7 @@ type ContentResolver interface { FileContentsByLocation(Location) (io.ReadCloser, error) } +// MetadataResolver provides file metadata lookup by location. type MetadataResolver interface { FileMetadataByLocation(Location) (Metadata, error) } @@ -51,6 +52,7 @@ type PathResolver interface { RelativeFileByPath(_ Location, path string) *Location } +// LocationResolver provides iteration over all file locations in a source. type LocationResolver interface { // AllLocations returns a channel of all file references from the underlying source. // The implementation for this may vary, however, generally the following considerations should be made: @@ -59,6 +61,7 @@ type LocationResolver interface { AllLocations(ctx context.Context) <-chan Location } +// WritableResolver extends Resolver with the ability to write file content. type WritableResolver interface { Resolver diff --git a/syft/file/search_result.go b/syft/file/search_result.go index dc12d14df..ff80a4368 100644 --- a/syft/file/search_result.go +++ b/syft/file/search_result.go @@ -4,13 +4,25 @@ import ( "fmt" ) +// SearchResult represents a match found during content scanning, such as secret detection. type SearchResult struct { + // Classification identifies the type or category of the matched content. Classification string `json:"classification"` - LineNumber int64 `json:"lineNumber"` - LineOffset int64 `json:"lineOffset"` - SeekPosition int64 `json:"seekPosition"` - Length int64 `json:"length"` - Value string `json:"value,omitempty"` + + // LineNumber is the 1-indexed line number where the match was found. + LineNumber int64 `json:"lineNumber"` + + // LineOffset is the character offset from the start of the line where the match begins. + LineOffset int64 `json:"lineOffset"` + + // SeekPosition is the absolute byte offset from the start of the file. + SeekPosition int64 `json:"seekPosition"` + + // Length is the size in bytes of the matched content. + Length int64 `json:"length"` + + // Value optionally contains the actual matched content. + Value string `json:"value,omitempty"` } func (s SearchResult) String() string { diff --git a/syft/file/selection.go b/syft/file/selection.go index fb7f46f99..86e323d52 100644 --- a/syft/file/selection.go +++ b/syft/file/selection.go @@ -1,9 +1,10 @@ package file const ( - NoFilesSelection Selection = "none" - FilesOwnedByPackageSelection Selection = "owned-by-package" - AllFilesSelection Selection = "all" + NoFilesSelection Selection = "none" // no files are selected + FilesOwnedByPackageSelection Selection = "owned-by-package" // only files owned by packages are selected + AllFilesSelection Selection = "all" // all files are selected ) +// Selection defines which files should be included during cataloging operations. type Selection string diff --git a/syft/internal/jsonschema/comments.go b/syft/internal/jsonschema/comments.go new file mode 100644 index 000000000..0a2b08df6 --- /dev/null +++ b/syft/internal/jsonschema/comments.go @@ -0,0 +1,159 @@ +package main + +import ( + "fmt" + "go/ast" + "go/parser" + "go/token" + "os" + "path/filepath" + "strings" + + "github.com/invopop/jsonschema" +) + +func copyAliasFieldComments(commentMap map[string]string, repoRoot string) { + // find all type aliases by parsing Go source files + aliases := findTypeAliases(repoRoot) + + // for each alias, copy field comments from the source type + for aliasName, sourceName := range aliases { + // find all field comments for the source type + for key, comment := range commentMap { + // check if this is a field comment for the source type + // format: "github.com/anchore/syft/syft/pkg.SourceType.FieldName" + if strings.Contains(key, "."+sourceName+".") { + // create the corresponding key for the alias + aliasKey := strings.Replace(key, "."+sourceName+".", "."+aliasName+".", 1) + commentMap[aliasKey] = comment + } + } + } +} + +func findTypeAliases(repoRoot string) map[string]string { + aliases := make(map[string]string) + fset := token.NewFileSet() + + // walk through all Go files in the repo + err := filepath.Walk(repoRoot, func(path string, info os.FileInfo, err error) error { + if err != nil || info.IsDir() || !strings.HasSuffix(path, ".go") { + return nil + } + + // parse the file + file, err := parser.ParseFile(fset, path, nil, parser.ParseComments) + if err != nil { + return nil + } + + // look for type alias declarations + ast.Inspect(file, func(n ast.Node) bool { + typeSpec, ok := n.(*ast.TypeSpec) + if !ok { + return true + } + + // check if this is a type alias (e.g., type A B where B is an identifier) + ident, ok := typeSpec.Type.(*ast.Ident) + if !ok { + return true + } + + // store the alias mapping: aliasName -> sourceName + aliases[typeSpec.Name.Name] = ident.Name + return true + }) + + return nil + }) + + if err != nil { + fmt.Fprintf(os.Stderr, "error: failed to find type aliases: %v\n", err) + panic(err) + } + + return aliases +} + +func hasDescriptionInAlternatives(schema *jsonschema.Schema) bool { + // check oneOf alternatives + for _, alt := range schema.OneOf { + if alt.Description != "" { + return true + } + } + // check anyOf alternatives + for _, alt := range schema.AnyOf { + if alt.Description != "" { + return true + } + } + return false +} + +func warnMissingDescriptions(schema *jsonschema.Schema, metadataNames []string) { //nolint:gocognit + var missingTypeDescriptions []string + var missingFieldDescriptions []string + + // check metadata types for missing descriptions + for _, name := range metadataNames { + def, ok := schema.Definitions[name] + if !ok { + continue + } + + // check if type has a description + if def.Description == "" { + missingTypeDescriptions = append(missingTypeDescriptions, name) + } + + // check if fields have descriptions + if def.Properties != nil { + for _, fieldName := range def.Properties.Keys() { + fieldSchemaRaw, _ := def.Properties.Get(fieldName) + fieldSchema, ok := fieldSchemaRaw.(*jsonschema.Schema) + if !ok { + continue + } + + // skip if field has a description + if fieldSchema.Description != "" { + continue + } + + // skip if field is a reference (descriptions come from the referenced type) + if fieldSchema.Ref != "" { + continue + } + + // skip if field is an array/object with items that are references + if fieldSchema.Items != nil && fieldSchema.Items.Ref != "" { + continue + } + + // skip if field uses oneOf/anyOf with descriptions in the alternatives + if hasDescriptionInAlternatives(fieldSchema) { + continue + } + + missingFieldDescriptions = append(missingFieldDescriptions, fmt.Sprintf("%s.%s", name, fieldName)) + } + } + } + + // report findings + if len(missingTypeDescriptions) > 0 { + fmt.Fprintf(os.Stderr, "\nwarning: %d metadata types are missing descriptions:\n", len(missingTypeDescriptions)) + for _, name := range missingTypeDescriptions { + fmt.Fprintf(os.Stderr, " - %s\n", name) + } + } + + if len(missingFieldDescriptions) > 0 { + fmt.Fprintf(os.Stderr, "\nwarning: %d fields are missing descriptions:\n", len(missingFieldDescriptions)) + for _, field := range missingFieldDescriptions { + fmt.Fprintf(os.Stderr, " - %s\n", field) + } + } +} diff --git a/syft/internal/jsonschema/comments_test.go b/syft/internal/jsonschema/comments_test.go new file mode 100644 index 000000000..2d0f4fa2c --- /dev/null +++ b/syft/internal/jsonschema/comments_test.go @@ -0,0 +1,382 @@ +package main + +import ( + "os" + "path/filepath" + "testing" + + "github.com/iancoleman/orderedmap" + "github.com/invopop/jsonschema" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestCopyAliasFieldComments verifies that field comments from source types are correctly copied to alias types. +// This is important for type aliases like `type RpmArchive RpmDBEntry` where the alias should inherit all field descriptions. +func TestCopyAliasFieldComments(t *testing.T) { + tests := []struct { + name string + commentMap map[string]string + aliases map[string]string + wantComments map[string]string + }{ + { + name: "copies field comments from source type to alias", + commentMap: map[string]string{ + "github.com/anchore/syft/syft/pkg.RpmDBEntry": "RpmDBEntry represents all captured data from a RPM DB package entry.", + "github.com/anchore/syft/syft/pkg.RpmDBEntry.Name": "Name is the RPM package name.", + "github.com/anchore/syft/syft/pkg.RpmDBEntry.Epoch": "Epoch is the version epoch.", + }, + aliases: map[string]string{ + "RpmArchive": "RpmDBEntry", + }, + wantComments: map[string]string{ + "github.com/anchore/syft/syft/pkg.RpmDBEntry": "RpmDBEntry represents all captured data from a RPM DB package entry.", + "github.com/anchore/syft/syft/pkg.RpmDBEntry.Name": "Name is the RPM package name.", + "github.com/anchore/syft/syft/pkg.RpmDBEntry.Epoch": "Epoch is the version epoch.", + "github.com/anchore/syft/syft/pkg.RpmArchive.Name": "Name is the RPM package name.", + "github.com/anchore/syft/syft/pkg.RpmArchive.Epoch": "Epoch is the version epoch.", + }, + }, + { + name: "handles multiple aliases", + commentMap: map[string]string{ + "github.com/anchore/syft/syft/pkg.DpkgDBEntry": "DpkgDBEntry represents data from dpkg.", + "github.com/anchore/syft/syft/pkg.DpkgDBEntry.Package": "Package is the package name.", + "github.com/anchore/syft/syft/pkg.DpkgDBEntry.Architecture": "Architecture is the target arch.", + }, + aliases: map[string]string{ + "DpkgArchiveEntry": "DpkgDBEntry", + "DpkgSnapshot": "DpkgDBEntry", + }, + wantComments: map[string]string{ + "github.com/anchore/syft/syft/pkg.DpkgDBEntry": "DpkgDBEntry represents data from dpkg.", + "github.com/anchore/syft/syft/pkg.DpkgDBEntry.Package": "Package is the package name.", + "github.com/anchore/syft/syft/pkg.DpkgDBEntry.Architecture": "Architecture is the target arch.", + "github.com/anchore/syft/syft/pkg.DpkgArchiveEntry.Package": "Package is the package name.", + "github.com/anchore/syft/syft/pkg.DpkgArchiveEntry.Architecture": "Architecture is the target arch.", + "github.com/anchore/syft/syft/pkg.DpkgSnapshot.Package": "Package is the package name.", + "github.com/anchore/syft/syft/pkg.DpkgSnapshot.Architecture": "Architecture is the target arch.", + }, + }, + { + name: "does not copy non-field comments", + commentMap: map[string]string{ + "github.com/anchore/syft/syft/pkg.SomeType": "SomeType struct comment.", + "github.com/anchore/syft/syft/pkg.SomeType.Field": "Field comment.", + }, + aliases: map[string]string{ + "AliasType": "SomeType", + }, + wantComments: map[string]string{ + "github.com/anchore/syft/syft/pkg.SomeType": "SomeType struct comment.", + "github.com/anchore/syft/syft/pkg.SomeType.Field": "Field comment.", + "github.com/anchore/syft/syft/pkg.AliasType.Field": "Field comment.", + }, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // create temp dir for testing + tmpDir := t.TempDir() + + // create a test go file with type aliases + testFile := filepath.Join(tmpDir, "test.go") + content := "package test\n\n" + for alias, source := range tt.aliases { + content += "type " + alias + " " + source + "\n" + } + err := os.WriteFile(testFile, []byte(content), 0644) + require.NoError(t, err) + + // make a copy of the comment map since the function modifies it + commentMap := make(map[string]string) + for k, v := range tt.commentMap { + commentMap[k] = v + } + + // run the function + copyAliasFieldComments(commentMap, tmpDir) + + // verify results + assert.Equal(t, tt.wantComments, commentMap) + }) + } +} + +func TestFindTypeAliases(t *testing.T) { + tests := []struct { + name string + fileContent string + wantAliases map[string]string + }{ + { + name: "finds simple type alias", + fileContent: `package test + +type RpmArchive RpmDBEntry +type DpkgArchiveEntry DpkgDBEntry +`, + wantAliases: map[string]string{ + "RpmArchive": "RpmDBEntry", + "DpkgArchiveEntry": "DpkgDBEntry", + }, + }, + { + name: "ignores struct definitions", + fileContent: `package test + +type MyStruct struct { + Field string +} + +type AliasType BaseType +`, + wantAliases: map[string]string{ + "AliasType": "BaseType", + }, + }, + { + name: "ignores interface definitions", + fileContent: `package test + +type MyInterface interface { + Method() +} + +type AliasType BaseType +`, + wantAliases: map[string]string{ + "AliasType": "BaseType", + }, + }, + { + name: "handles multiple files", + fileContent: `package test + +type Alias1 Base1 +type Alias2 Base2 +`, + wantAliases: map[string]string{ + "Alias1": "Base1", + "Alias2": "Base2", + }, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // create temp dir + tmpDir := t.TempDir() + + // write test file + testFile := filepath.Join(tmpDir, "test.go") + err := os.WriteFile(testFile, []byte(tt.fileContent), 0644) + require.NoError(t, err) + + // run function + aliases := findTypeAliases(tmpDir) + + // verify + assert.Equal(t, tt.wantAliases, aliases) + }) + } +} + +func TestHasDescriptionInAlternatives(t *testing.T) { + tests := []struct { + name string + schema *jsonschema.Schema + want bool + }{ + { + name: "returns true when oneOf has description", + schema: &jsonschema.Schema{ + OneOf: []*jsonschema.Schema{ + {Description: "First alternative"}, + {Type: "null"}, + }, + }, + want: true, + }, + { + name: "returns true when anyOf has description", + schema: &jsonschema.Schema{ + AnyOf: []*jsonschema.Schema{ + {Description: "First alternative"}, + {Type: "null"}, + }, + }, + want: true, + }, + { + name: "returns false when no alternatives have descriptions", + schema: &jsonschema.Schema{ + OneOf: []*jsonschema.Schema{ + {Type: "integer"}, + {Type: "null"}, + }, + }, + want: false, + }, + { + name: "returns false when no oneOf or anyOf", + schema: &jsonschema.Schema{ + Type: "string", + }, + want: false, + }, + { + name: "returns true when any alternative in oneOf has description", + schema: &jsonschema.Schema{ + OneOf: []*jsonschema.Schema{ + {Type: "integer"}, + {Type: "string", Description: "Second alternative"}, + {Type: "null"}, + }, + }, + want: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := hasDescriptionInAlternatives(tt.schema) + assert.Equal(t, tt.want, got) + }) + } +} + +func TestWarnMissingDescriptions(t *testing.T) { + tests := []struct { + name string + schema *jsonschema.Schema + metadataNames []string + wantTypeWarnings int + wantFieldWarnings int + }{ + { + name: "no warnings when all types have descriptions", + schema: &jsonschema.Schema{ + Definitions: map[string]*jsonschema.Schema{ + "TypeA": { + Description: "Type A description", + Properties: newOrderedMap(map[string]*jsonschema.Schema{ + "field1": {Type: "string", Description: "Field 1"}, + }), + }, + }, + }, + metadataNames: []string{"TypeA"}, + wantTypeWarnings: 0, + wantFieldWarnings: 0, + }, + { + name: "warns about missing type description", + schema: &jsonschema.Schema{ + Definitions: map[string]*jsonschema.Schema{ + "TypeA": { + Properties: newOrderedMap(map[string]*jsonschema.Schema{ + "field1": {Type: "string", Description: "Field 1"}, + }), + }, + }, + }, + metadataNames: []string{"TypeA"}, + wantTypeWarnings: 1, + wantFieldWarnings: 0, + }, + { + name: "warns about missing field description", + schema: &jsonschema.Schema{ + Definitions: map[string]*jsonschema.Schema{ + "TypeA": { + Description: "Type A description", + Properties: newOrderedMap(map[string]*jsonschema.Schema{ + "field1": {Type: "string"}, + }), + }, + }, + }, + metadataNames: []string{"TypeA"}, + wantTypeWarnings: 0, + wantFieldWarnings: 1, + }, + { + name: "skips fields with references", + schema: &jsonschema.Schema{ + Definitions: map[string]*jsonschema.Schema{ + "TypeA": { + Description: "Type A description", + Properties: newOrderedMap(map[string]*jsonschema.Schema{ + "field1": {Ref: "#/$defs/OtherType"}, + }), + }, + }, + }, + metadataNames: []string{"TypeA"}, + wantTypeWarnings: 0, + wantFieldWarnings: 0, + }, + { + name: "skips fields with items that are references", + schema: &jsonschema.Schema{ + Definitions: map[string]*jsonschema.Schema{ + "TypeA": { + Description: "Type A description", + Properties: newOrderedMap(map[string]*jsonschema.Schema{ + "field1": { + Type: "array", + Items: &jsonschema.Schema{Ref: "#/$defs/OtherType"}, + }, + }), + }, + }, + }, + metadataNames: []string{"TypeA"}, + wantTypeWarnings: 0, + wantFieldWarnings: 0, + }, + { + name: "skips fields with oneOf containing descriptions", + schema: &jsonschema.Schema{ + Definitions: map[string]*jsonschema.Schema{ + "TypeA": { + Description: "Type A description", + Properties: newOrderedMap(map[string]*jsonschema.Schema{ + "field1": { + OneOf: []*jsonschema.Schema{ + {Type: "integer", Description: "Integer value"}, + {Type: "null"}, + }, + }, + }), + }, + }, + }, + metadataNames: []string{"TypeA"}, + wantTypeWarnings: 0, + wantFieldWarnings: 0, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // capture stderr output would require more complex testing + // for now, just verify the function runs without panicking + require.NotPanics(t, func() { + warnMissingDescriptions(tt.schema, tt.metadataNames) + }) + }) + } +} + +// helper to create an ordered map from a regular map +func newOrderedMap(m map[string]*jsonschema.Schema) *orderedmap.OrderedMap { + om := orderedmap.New() + for k, v := range m { + om.Set(k, v) + } + return om +} diff --git a/syft/internal/jsonschema/main.go b/syft/internal/jsonschema/main.go index 731ffd917..6ba80cf0c 100644 --- a/syft/internal/jsonschema/main.go +++ b/syft/internal/jsonschema/main.go @@ -78,6 +78,33 @@ func build() *jsonschema.Schema { Namer: func(r reflect.Type) string { return strings.TrimPrefix(r.Name(), "JSON") }, + CommentMap: make(map[string]string), + } + + // extract comments from Go source files to enrich schema descriptions + // + // note: AddGoComments parses from the module root and creates keys like "syft/pkg.TypeName", + // but the reflector expects fully qualified paths like "github.com/anchore/syft/syft/pkg.TypeName". + // We fix up the keys after extraction to match the expected format. + if err := reflector.AddGoComments("github.com/anchore/syft", "../../.."); err != nil { + fmt.Fprintf(os.Stderr, "warning: failed to extract Go comments: %v\n", err) + } else { + // fix up comment map keys to use fully qualified import paths + fixedMap := make(map[string]string) + for k, v := range reflector.CommentMap { + newKey := k + if !strings.HasPrefix(k, "github.com/") { + newKey = "github.com/anchore/syft/" + k + } + fixedMap[newKey] = v + } + reflector.CommentMap = fixedMap + + // copy field comments for type aliases (e.g., type RpmArchive RpmDBEntry) + repoRoot, err := packagemetadata.RepoRoot() + if err == nil { + copyAliasFieldComments(reflector.CommentMap, repoRoot) + } } pkgMetadataContainer, pkgMetadataMapping := assembleTypeContainer(packagemetadata.AllTypes()) @@ -130,6 +157,9 @@ func build() *jsonschema.Schema { "anyOf": metadataTypes, }) + // warn about missing descriptions + warnMissingDescriptions(documentSchema, metadataNames) + return documentSchema } diff --git a/syft/internal/packagemetadata/discover_type_names.go b/syft/internal/packagemetadata/discover_type_names.go index 647753eb0..f9783db10 100644 --- a/syft/internal/packagemetadata/discover_type_names.go +++ b/syft/internal/packagemetadata/discover_type_names.go @@ -24,7 +24,7 @@ var knownNonMetadataTypeNames = strset.New( // these are names that would be removed due to common convention (e.g. used within another metadata type) but are // known to be metadata types themselves. Adding to this list will prevent the removal of the type from the schema. -var knownMetadaTypeNames = strset.New( +var knownMetadataTypeNames = strset.New( "DotnetPortableExecutableEntry", ) @@ -72,7 +72,7 @@ func findMetadataDefinitionNames(paths ...string) ([]string, error) { } // any definition that is used within another struct should not be considered a top-level metadata definition - removeNames := strset.Difference(usedNames, knownMetadaTypeNames) + removeNames := strset.Difference(usedNames, knownMetadataTypeNames) names.Remove(removeNames.List()...) // remove known exceptions, that is, types exported in the pkg Package that are not used diff --git a/syft/pkg/alpm.go b/syft/pkg/alpm.go index 3a8cf8b16..e716c26c2 100644 --- a/syft/pkg/alpm.go +++ b/syft/pkg/alpm.go @@ -13,32 +13,74 @@ var _ FileOwner = (*AlpmDBEntry)(nil) const AlpmDBGlob = "**/var/lib/pacman/local/**/desc" -// AlpmDBEntry is a struct that represents the package data stored in the pacman fla-filet stores for arch linux. +// AlpmDBEntry is a struct that represents the package data stored in the pacman flat-file stores for arch linux. type AlpmDBEntry struct { - BasePackage string `mapstructure:"base" json:"basepackage" cyclonedx:"basepackage"` - Package string `mapstructure:"name" json:"package" cyclonedx:"package"` - Version string `mapstructure:"version" json:"version" cyclonedx:"version"` - Description string `mapstructure:"desc" json:"description" cyclonedx:"description"` - Architecture string `mapstructure:"arch" json:"architecture" cyclonedx:"architecture"` - Size int `mapstructure:"size" json:"size" cyclonedx:"size"` - Packager string `mapstructure:"packager" json:"packager"` - URL string `mapstructure:"url" json:"url"` - Validation string `mapstructure:"validation" json:"validation"` - Reason int `mapstructure:"reason" json:"reason"` - Files []AlpmFileRecord `mapstructure:"files" json:"files"` - Backup []AlpmFileRecord `mapstructure:"backup" json:"backup"` - Provides []string `mapstructure:"provides" json:"provides,omitempty"` - Depends []string `mapstructure:"depends" json:"depends,omitempty"` + // BasePackage is the base package name this package was built from (source package in Arch build system) + BasePackage string `mapstructure:"base" json:"basepackage" cyclonedx:"basepackage"` + + // Package is the package name as found in the desc file + Package string `mapstructure:"name" json:"package" cyclonedx:"package"` + + // Version is the package version as found in the desc file + Version string `mapstructure:"version" json:"version" cyclonedx:"version"` + + // Description is a human-readable package description + Description string `mapstructure:"desc" json:"description" cyclonedx:"description"` + + // Architecture is the target CPU architecture as defined in Arch architecture spec (e.g. x86_64, aarch64, or "any" for arch-independent packages) + Architecture string `mapstructure:"arch" json:"architecture" cyclonedx:"architecture"` + + // Size is the installed size in bytes + Size int `mapstructure:"size" json:"size" cyclonedx:"size"` + + // Packager is the name and email of the person who packaged this (RFC822 format) + Packager string `mapstructure:"packager" json:"packager"` + + // URL is the upstream project URL + URL string `mapstructure:"url" json:"url"` + + // Validation is the validation method used for package integrity (e.g. pgp signature, sha256 checksum) + Validation string `mapstructure:"validation" json:"validation"` + + // Reason is the installation reason tracked by pacman (0=explicitly installed by user, 1=installed as dependency) + Reason int `mapstructure:"reason" json:"reason"` + + // Files are the files installed by this package + Files []AlpmFileRecord `mapstructure:"files" json:"files"` + + // Backup is the list of configuration files that pacman backs up before upgrades + Backup []AlpmFileRecord `mapstructure:"backup" json:"backup"` + + // Provides are virtual packages provided by this package (allows other packages to depend on capabilities rather than specific packages) + Provides []string `mapstructure:"provides" json:"provides,omitempty"` + + // Depends are the runtime dependencies required by this package + Depends []string `mapstructure:"depends" json:"depends,omitempty"` } type AlpmFileRecord struct { - Path string `mapstruture:"path" json:"path,omitempty"` - Type string `mapstructure:"type" json:"type,omitempty"` - UID string `mapstructure:"uid" json:"uid,omitempty"` - GID string `mapstructure:"gid" json:"gid,omitempty"` - Time time.Time `mapstructure:"time" json:"time,omitempty"` - Size string `mapstructure:"size" json:"size,omitempty"` - Link string `mapstructure:"link" json:"link,omitempty"` + // Path is the file path relative to the filesystem root + Path string `mapstruture:"path" json:"path,omitempty"` + + // Type is the file type (e.g. regular file, directory, symlink) + Type string `mapstructure:"type" json:"type,omitempty"` + + // UID is the file owner user ID as recorded by pacman + UID string `mapstructure:"uid" json:"uid,omitempty"` + + // GID is the file owner group ID as recorded by pacman + GID string `mapstructure:"gid" json:"gid,omitempty"` + + // Time is the file modification timestamp + Time time.Time `mapstructure:"time" json:"time,omitempty"` + + // Size is the file size in bytes + Size string `mapstructure:"size" json:"size,omitempty"` + + // Link is the symlink target path if this is a symlink + Link string `mapstructure:"link" json:"link,omitempty"` + + // Digests contains file content hashes for integrity verification Digests []file.Digest `mapstructure:"digests" json:"digest,omitempty"` } diff --git a/syft/pkg/apk.go b/syft/pkg/apk.go index 8d2aea12c..6fe2a923c 100644 --- a/syft/pkg/apk.go +++ b/syft/pkg/apk.go @@ -23,22 +23,50 @@ var _ FileOwner = (*ApkDBEntry)(nil) // - https://git.alpinelinux.org/apk-tools/tree/src/package.c // - https://git.alpinelinux.org/apk-tools/tree/src/database.c type ApkDBEntry struct { - Package string `mapstructure:"P" json:"package"` - OriginPackage string `mapstructure:"o" json:"originPackage" cyclonedx:"originPackage"` - Maintainer string `mapstructure:"m" json:"maintainer"` - Version string `mapstructure:"V" json:"version"` - Architecture string `mapstructure:"A" json:"architecture"` - URL string `mapstructure:"U" json:"url"` - Description string `mapstructure:"T" json:"description"` - Size int `mapstructure:"S" json:"size" cyclonedx:"size"` - InstalledSize int `mapstructure:"I" json:"installedSize" cyclonedx:"installedSize"` - Dependencies []string `mapstructure:"D" json:"pullDependencies" cyclonedx:"pullDependencies"` - Provides []string `mapstructure:"p" json:"provides" cyclonedx:"provides"` - Checksum string `mapstructure:"C" json:"pullChecksum" cyclonedx:"pullChecksum"` - GitCommit string `mapstructure:"c" json:"gitCommitOfApkPort" cyclonedx:"gitCommitOfApkPort"` - Files []ApkFileRecord `json:"files"` + // Package is the package name as found in the installed file + Package string `mapstructure:"P" json:"package"` + + // OriginPackage is the original source package name this binary was built from (used to track which aport/source built this) + OriginPackage string `mapstructure:"o" json:"originPackage" cyclonedx:"originPackage"` + + // Maintainer is the package maintainer name and email + Maintainer string `mapstructure:"m" json:"maintainer"` + + // Version is the package version as found in the installed file + Version string `mapstructure:"V" json:"version"` + + // Architecture is the target CPU architecture + Architecture string `mapstructure:"A" json:"architecture"` + + // URL is the upstream project URL + URL string `mapstructure:"U" json:"url"` + + // Description is a human-readable package description + Description string `mapstructure:"T" json:"description"` + + // Size is the package archive size in bytes (.apk file size) + Size int `mapstructure:"S" json:"size" cyclonedx:"size"` + + // InstalledSize is the total size of installed files in bytes + InstalledSize int `mapstructure:"I" json:"installedSize" cyclonedx:"installedSize"` + + // Dependencies are the runtime dependencies required by this package + Dependencies []string `mapstructure:"D" json:"pullDependencies" cyclonedx:"pullDependencies"` + + // Provides are virtual packages provided by this package (for capability-based dependencies) + Provides []string `mapstructure:"p" json:"provides" cyclonedx:"provides"` + + // Checksum is the package content checksum for integrity verification + Checksum string `mapstructure:"C" json:"pullChecksum" cyclonedx:"pullChecksum"` + + // GitCommit is the git commit hash of the APK port definition in Alpine's aports repository + GitCommit string `mapstructure:"c" json:"gitCommitOfApkPort" cyclonedx:"gitCommitOfApkPort"` + + // Files are the files installed by this package + Files []ApkFileRecord `json:"files"` } +// spaceDelimitedStringSlice is an internal helper type for unmarshaling space-delimited strings from JSON into a string slice. type spaceDelimitedStringSlice []string func (m *ApkDBEntry) UnmarshalJSON(data []byte) error { @@ -95,11 +123,20 @@ func (a *spaceDelimitedStringSlice) UnmarshalJSON(data []byte) error { // ApkFileRecord represents a single file listing and metadata from a APK DB entry (which may have many of these file records). type ApkFileRecord struct { - Path string `json:"path"` - OwnerUID string `json:"ownerUid,omitempty"` - OwnerGID string `json:"ownerGid,omitempty"` - Permissions string `json:"permissions,omitempty"` - Digest *file.Digest `json:"digest,omitempty"` + // Path is the file path relative to the filesystem root + Path string `json:"path"` + + // OwnerUID is the file owner user ID + OwnerUID string `json:"ownerUid,omitempty"` + + // OwnerGID is the file owner group ID + OwnerGID string `json:"ownerGid,omitempty"` + + // Permissions is the file permission mode string (e.g. "0755", "0644") + Permissions string `json:"permissions,omitempty"` + + // Digest is the file content hash for integrity verification + Digest *file.Digest `json:"digest,omitempty"` } func (m ApkDBEntry) OwnedFiles() (result []string) { diff --git a/syft/pkg/binary.go b/syft/pkg/binary.go index bdfafe1ae..b16c9a4b6 100644 --- a/syft/pkg/binary.go +++ b/syft/pkg/binary.go @@ -13,9 +13,9 @@ type ClassifierMatch struct { Location file.Location `mapstructure:"Location" json:"location"` } -// ELFBinaryPackageNoteJSONPayload Represents metadata captured from the .note.package section of the binary +// ELFBinaryPackageNoteJSONPayload Represents metadata captured from the .note.package section of an ELF-formatted binary type ELFBinaryPackageNoteJSONPayload struct { - // these are well-known fields as defined by systemd ELF package metadata "spec" https://systemd.io/ELF_PACKAGE_METADATA/ + // (these are well-known fields as defined by systemd ELF package metadata "spec" https://systemd.io/ELF_PACKAGE_METADATA/) // Type is the type of the package (e.g. "rpm", "deb", "apk", etc.) Type string `json:"type,omitempty"` @@ -23,7 +23,7 @@ type ELFBinaryPackageNoteJSONPayload struct { // Architecture of the binary package (e.g. "amd64", "arm", etc.) Architecture string `json:"architecture,omitempty"` - // OS CPE is a CPE name for the OS, typically corresponding to CPE_NAME in os-release (e.g. cpe:/o:fedoraproject:fedora:33) + // OSCPE is a CPE name for the OS, typically corresponding to CPE_NAME in os-release (e.g. cpe:/o:fedoraproject:fedora:33) OSCPE string `json:"osCPE,omitempty"` // OS is the OS name, typically corresponding to ID in os-release (e.g. "fedora") @@ -32,7 +32,8 @@ type ELFBinaryPackageNoteJSONPayload struct { // osVersion is the version of the OS, typically corresponding to VERSION_ID in os-release (e.g. "33") OSVersion string `json:"osVersion,omitempty"` - // these are additional fields that are not part of the systemd spec + ///////////////////////////////////////////////////////////////////////////////// + // (these are additional fields that are not part of the systemd spec) // System is a context-specific name for the system that the binary package is intended to run on or a part of System string `json:"system,omitempty"` @@ -49,5 +50,6 @@ type ELFBinaryPackageNoteJSONPayload struct { // PEBinary represents metadata captured from a Portable Executable formatted binary (dll, exe, etc.) type PEBinary struct { + // VersionResources contains key-value pairs extracted from the PE file's version resource section (e.g., FileVersion, ProductName, CompanyName). VersionResources KeyValues } diff --git a/syft/pkg/bitnami.go b/syft/pkg/bitnami.go index 195a4ba50..e1517196f 100644 --- a/syft/pkg/bitnami.go +++ b/syft/pkg/bitnami.go @@ -3,13 +3,26 @@ package pkg // BitnamiSBOMEntry represents all captured data from Bitnami packages // described in Bitnami' SPDX files. type BitnamiSBOMEntry struct { - Name string `mapstructure:"name" json:"name"` - Architecture string `mapstructure:"arch" json:"arch"` - Distro string `mapstructure:"distro" json:"distro"` - Revision string `mapstructure:"revision" json:"revision"` - Version string `mapstructure:"version" json:"version"` - Path string `mapstructure:"path" json:"path"` - Files []string `mapstructure:"files" json:"files"` + // Name is the package name as found in the Bitnami SPDX file + Name string `mapstructure:"name" json:"name"` + + // Architecture is the target CPU architecture (amd64 or arm64 in Bitnami images) + Architecture string `mapstructure:"arch" json:"arch"` + + // Distro is the distribution name this package is for (base OS like debian, ubuntu, etc.) + Distro string `mapstructure:"distro" json:"distro"` + + // Revision is the Bitnami-specific package revision number (incremented for Bitnami rebuilds of same upstream version) + Revision string `mapstructure:"revision" json:"revision"` + + // Version is the package version as found in the Bitnami SPDX file + Version string `mapstructure:"version" json:"version"` + + // Path is the installation path in the filesystem where the package is located + Path string `mapstructure:"path" json:"path"` + + // Files are the file paths owned by this package (tracked via SPDX relationships) + Files []string `mapstructure:"files" json:"files"` } func (b BitnamiSBOMEntry) OwnedFiles() (result []string) { diff --git a/syft/pkg/cocoapods.go b/syft/pkg/cocoapods.go index 58ce99c5c..6789e981f 100644 --- a/syft/pkg/cocoapods.go +++ b/syft/pkg/cocoapods.go @@ -2,5 +2,6 @@ package pkg // CocoaPodfileLockEntry represents a single entry from the "Pods" section of a Podfile.lock file. type CocoaPodfileLockEntry struct { + // Checksum is the SHA-1 hash of the podspec file for integrity verification (generated via `pod ipc spec ... | openssl sha1`), ensuring all team members use the same pod specification version Checksum string `mapstructure:"checksum" json:"checksum"` } diff --git a/syft/pkg/conan.go b/syft/pkg/conan.go index 87cdb9c9d..a1be8f6fd 100644 --- a/syft/pkg/conan.go +++ b/syft/pkg/conan.go @@ -2,35 +2,69 @@ package pkg // ConanV1LockEntry represents a single "node" entry from a conan.lock V1 file. type ConanV1LockEntry struct { - Ref string `json:"ref"` - PackageID string `json:"package_id,omitempty"` - Prev string `json:"prev,omitempty"` - Requires []string `json:"requires,omitempty"` - BuildRequires []string `json:"build_requires,omitempty"` - PythonRequires []string `json:"py_requires,omitempty"` - Options KeyValues `json:"options,omitempty"` - Path string `json:"path,omitempty"` - Context string `json:"context,omitempty"` + // Ref is the package reference string in format name/version@user/channel + Ref string `json:"ref"` + + // PackageID is a unique package variant identifier computed from settings/options (static hash in Conan 1.x, can have collisions with complex dependency graphs) + PackageID string `json:"package_id,omitempty"` + + // Prev is the previous lock entry reference for versioning + Prev string `json:"prev,omitempty"` + + // Requires are the runtime package dependencies + Requires []string `json:"requires,omitempty"` + + // BuildRequires are the build-time dependencies (e.g. cmake, compilers) + BuildRequires []string `json:"build_requires,omitempty"` + + // PythonRequires are the Python dependencies needed for Conan recipes + PythonRequires []string `json:"py_requires,omitempty"` + + // Options are package configuration options as key-value pairs (e.g. shared=True, fPIC=True) + Options KeyValues `json:"options,omitempty"` + + // Path is the filesystem path to the package in Conan cache + Path string `json:"path,omitempty"` + + // Context is the build context information + Context string `json:"context,omitempty"` } // ConanV2LockEntry represents a single "node" entry from a conan.lock V2 file. type ConanV2LockEntry struct { - Ref string `json:"ref"` - PackageID string `json:"packageID,omitempty"` - Username string `json:"username,omitempty"` - Channel string `json:"channel,omitempty"` - RecipeRevision string `json:"recipeRevision,omitempty"` + // Ref is the package reference string in format name/version@user/channel + Ref string `json:"ref"` + + // PackageID is a unique package variant identifier (dynamic in Conan 2.0, more accurate than V1) + PackageID string `json:"packageID,omitempty"` + + // Username is the Conan user/organization name + Username string `json:"username,omitempty"` + + // Channel is the Conan channel name indicating stability/purpose (e.g. stable, testing, experimental) + Channel string `json:"channel,omitempty"` + + // RecipeRevision is a git-like revision hash (RREV) of the recipe + RecipeRevision string `json:"recipeRevision,omitempty"` + + // PackageRevision is a git-like revision hash of the built binary package PackageRevision string `json:"packageRevision,omitempty"` - TimeStamp string `json:"timestamp,omitempty"` + + // TimeStamp is when this package was built/locked + TimeStamp string `json:"timestamp,omitempty"` } // ConanfileEntry represents a single "Requires" entry from a conanfile.txt. type ConanfileEntry struct { + // Ref is the package reference string in format name/version@user/channel Ref string `mapstructure:"ref" json:"ref"` } // ConaninfoEntry represents a single "full_requires" entry from a conaninfo.txt. type ConaninfoEntry struct { - Ref string `json:"ref"` + // Ref is the package reference string in format name/version@user/channel + Ref string `json:"ref"` + + // PackageID is a unique package variant identifier PackageID string `json:"package_id,omitempty"` } diff --git a/syft/pkg/conda.go b/syft/pkg/conda.go index 9d9d3ad43..aacd3e251 100644 --- a/syft/pkg/conda.go +++ b/syft/pkg/conda.go @@ -6,46 +6,106 @@ import ( "github.com/scylladb/go-set/strset" ) +// CondaPathData represents metadata for a single file within a Conda package from the paths.json file. type CondaPathData struct { - Path string `json:"_path"` - PathType string `json:"path_type"` - SHA256 string `json:"sha256"` + // Path is the file path relative to the Conda environment root. + Path string `json:"_path"` + + // PathType indicates the link type for the file (e.g., "hardlink", "softlink", "directory"). + PathType string `json:"path_type"` + + // SHA256 is the SHA-256 hash of the file contents. + SHA256 string `json:"sha256"` + + // SHA256InPrefix is the SHA-256 hash of the file after prefix replacement during installation. SHA256InPrefix string `json:"sha256_in_prefix"` - SizeInBytes int64 `json:"size_in_bytes"` + + // SizeInBytes is the file size in bytes. + SizeInBytes int64 `json:"size_in_bytes"` } +// CondaPathsData represents the paths.json file structure from a Conda package containing file metadata. type CondaPathsData struct { - PathsVersion int `json:"paths_version"` - Paths []CondaPathData `json:"paths"` + // PathsVersion is the schema version of the paths data format. + PathsVersion int `json:"paths_version"` + + // Paths is the list of file metadata entries for all files in the package. + Paths []CondaPathData `json:"paths"` } +// CondaLink represents link metadata from a Conda package's link.json file describing package installation source. type CondaLink struct { + // Source is the original path where the package was extracted from cache. Source string `json:"source"` - Type int `json:"type"` + + // Type indicates the link type (1 for hard link, 2 for soft link, 3 for copy). + Type int `json:"type"` } +// CondaMetaPackage represents metadata for a Conda package extracted from the conda-meta/*.json files. type CondaMetaPackage struct { - Arch string `json:"arch,omitempty"` - Name string `json:"name"` - Version string `json:"version"` - Build string `json:"build"` - BuildNumber int `json:"build_number"` - Channel string `json:"channel,omitempty"` - Subdir string `json:"subdir,omitempty"` - Noarch string `json:"noarch,omitempty"` - License string `json:"license,omitempty"` - LicenseFamily string `json:"license_family,omitempty"` - MD5 string `json:"md5,omitempty"` - SHA256 string `json:"sha256,omitempty"` - Size int64 `json:"size,omitempty"` - Timestamp int64 `json:"timestamp,omitempty"` - Filename string `json:"fn,omitempty"` - URL string `json:"url,omitempty"` - ExtractedPackageDir string `json:"extracted_package_dir,omitempty"` - Depends []string `json:"depends,omitempty"` - Files []string `json:"files,omitempty"` - PathsData *CondaPathsData `json:"paths_data,omitempty"` - Link *CondaLink `json:"link,omitempty"` + // Arch is the target CPU architecture for the package (e.g., "arm64", "x86_64"). + Arch string `json:"arch,omitempty"` + + // Name is the package name as found in the conda-meta JSON file. + Name string `json:"name"` + + // Version is the package version as found in the conda-meta JSON file. + Version string `json:"version"` + + // Build is the build string identifier (e.g., "h90dfc92_1014"). + Build string `json:"build"` + + // BuildNumber is the sequential build number for this version. + BuildNumber int `json:"build_number"` + + // Channel is the Conda channel URL where the package was retrieved from. + Channel string `json:"channel,omitempty"` + + // Subdir is the subdirectory within the channel (e.g., "osx-arm64", "linux-64"). + Subdir string `json:"subdir,omitempty"` + + // Noarch indicates if the package is platform-independent (e.g., "python", "generic"). + Noarch string `json:"noarch,omitempty"` + + // License is the package license identifier. + License string `json:"license,omitempty"` + + // LicenseFamily is the general license category (e.g., "MIT", "Apache", "GPL"). + LicenseFamily string `json:"license_family,omitempty"` + + // MD5 is the MD5 hash of the package archive. + MD5 string `json:"md5,omitempty"` + + // SHA256 is the SHA-256 hash of the package archive. + SHA256 string `json:"sha256,omitempty"` + + // Size is the package archive size in bytes. + Size int64 `json:"size,omitempty"` + + // Timestamp is the Unix timestamp when the package was built. + Timestamp int64 `json:"timestamp,omitempty"` + + // Filename is the original package archive filename (e.g., "zlib-1.2.11-h90dfc92_1014.tar.bz2"). + Filename string `json:"fn,omitempty"` + + // URL is the full download URL for the package archive. + URL string `json:"url,omitempty"` + + // ExtractedPackageDir is the local cache directory where the package was extracted. + ExtractedPackageDir string `json:"extracted_package_dir,omitempty"` + + // Depends is the list of runtime dependencies with version constraints. + Depends []string `json:"depends,omitempty"` + + // Files is the list of files installed by this package. + Files []string `json:"files,omitempty"` + + // PathsData contains detailed file metadata from the paths.json file. + PathsData *CondaPathsData `json:"paths_data,omitempty"` + + // Link contains installation source metadata from the link.json file. + Link *CondaLink `json:"link,omitempty"` } func (m CondaMetaPackage) OwnedFiles() (result []string) { diff --git a/syft/pkg/dart.go b/syft/pkg/dart.go index cff51c421..d15a23a35 100644 --- a/syft/pkg/dart.go +++ b/syft/pkg/dart.go @@ -2,24 +2,48 @@ package pkg // DartPubspecLockEntry is a struct that represents a single entry found in the "packages" section in a Dart pubspec.lock file. type DartPubspecLockEntry struct { - Name string `mapstructure:"name" json:"name"` - Version string `mapstructure:"version" json:"version"` + // Name is the package name as found in the pubspec.lock file + Name string `mapstructure:"name" json:"name"` + + // Version is the package version as found in the pubspec.lock file + Version string `mapstructure:"version" json:"version"` + + // HostedURL is the URL of the package repository for hosted packages (typically pub.dev, but can be custom repository identified by hosted-url). When PUB_HOSTED_URL environment variable changes, lockfile tracks the source. HostedURL string `mapstructure:"hosted_url" json:"hosted_url,omitempty"` - VcsURL string `mapstructure:"vcs_url" json:"vcs_url,omitempty"` + + // VcsURL is the URL of the VCS repository for git/path dependencies (for packages fetched from version control systems like Git) + VcsURL string `mapstructure:"vcs_url" json:"vcs_url,omitempty"` } // DartPubspec is a struct that represents a package described in a pubspec.yaml file type DartPubspec struct { - Homepage string `mapstructure:"homepage" json:"homepage,omitempty"` - Repository string `mapstructure:"repository" json:"repository,omitempty"` - Documentation string `mapstructure:"documentation" json:"documentation,omitempty"` - PublishTo string `mapstructure:"publish_to" json:"publish_to,omitempty"` - Environment *DartPubspecEnvironment `mapstructure:"environment" json:"environment,omitempty"` - Platforms []string `mapstructure:"platforms" json:"platforms,omitempty"` - IgnoredAdvisories []string `mapstructure:"ignored_advisories" json:"ignored_advisories,omitempty"` + // Homepage is the package homepage URL + Homepage string `mapstructure:"homepage" json:"homepage,omitempty"` + + // Repository is the source code repository URL + Repository string `mapstructure:"repository" json:"repository,omitempty"` + + // Documentation is the documentation site URL + Documentation string `mapstructure:"documentation" json:"documentation,omitempty"` + + // PublishTo is the package repository to publish to, or "none" to prevent accidental publishing + PublishTo string `mapstructure:"publish_to" json:"publish_to,omitempty"` + + // Environment is SDK version constraints for Dart and Flutter + Environment *DartPubspecEnvironment `mapstructure:"environment" json:"environment,omitempty"` + + // Platforms are the supported platforms (Android, iOS, web, etc.) + Platforms []string `mapstructure:"platforms" json:"platforms,omitempty"` + + // IgnoredAdvisories are the security advisories to explicitly ignore for this package + IgnoredAdvisories []string `mapstructure:"ignored_advisories" json:"ignored_advisories,omitempty"` } +// DartPubspecEnvironment represents SDK version constraints from the environment section of pubspec.yaml. type DartPubspecEnvironment struct { - SDK string `mapstructure:"sdk" json:"sdk,omitempty"` + // SDK is the Dart SDK version constraint (e.g. ">=2.12.0 <3.0.0") + SDK string `mapstructure:"sdk" json:"sdk,omitempty"` + + // Flutter is the Flutter SDK version constraint if this is a Flutter package Flutter string `mapstructure:"flutter" json:"flutter,omitempty"` } diff --git a/syft/pkg/dotnet.go b/syft/pkg/dotnet.go index 47aca15d6..10e7851c8 100644 --- a/syft/pkg/dotnet.go +++ b/syft/pkg/dotnet.go @@ -2,30 +2,60 @@ package pkg // DotnetDepsEntry is a struct that represents a single entry found in the "libraries" section in a .NET [*.]deps.json file. type DotnetDepsEntry struct { - Name string `mapstructure:"name" json:"name"` - Version string `mapstructure:"version" json:"version"` - Path string `mapstructure:"path" json:"path"` - Sha512 string `mapstructure:"sha512" json:"sha512"` + // Name is the package name as found in the deps.json file + Name string `mapstructure:"name" json:"name"` + + // Version is the package version as found in the deps.json file + Version string `mapstructure:"version" json:"version"` + + // Path is the relative path to the package within the deps structure (e.g. "app.metrics/3.0.0") + Path string `mapstructure:"path" json:"path"` + + // Sha512 is the SHA-512 hash of the NuGet package content WITHOUT the signed content for verification (won't match hash from NuGet API or manual calculation of .nupkg file) + Sha512 string `mapstructure:"sha512" json:"sha512"` + + // HashPath is the relative path to the .nupkg.sha512 hash file (e.g. "app.metrics.3.0.0.nupkg.sha512") HashPath string `mapstructure:"hashPath" json:"hashPath"` + // Executables are the map of .NET Portable Executable files within this package with their version resources Executables map[string]DotnetPortableExecutableEntry `json:"executables,omitempty"` } // DotnetPackagesLockEntry is a struct that represents a single entry found in the "dependencies" section in a .NET packages.lock.json file. type DotnetPackagesLockEntry struct { - Name string `mapstructure:"name" json:"name"` - Version string `mapstructure:"version" json:"version"` + // Name is the package name as found in the packages.lock.json file + Name string `mapstructure:"name" json:"name"` + + // Version is the package version as found in the packages.lock.json file + Version string `mapstructure:"version" json:"version"` + + // ContentHash is the hash of the package content for verification ContentHash string `mapstructure:"contentHash" json:"contentHash"` - Type string `mapstructure:"type" json:"type"` + + // Type is the dependency type indicating how this dependency was added (Direct=explicit in project file, Transitive=pulled in by another package, Project=project reference) + Type string `mapstructure:"type" json:"type"` } // DotnetPortableExecutableEntry is a struct that represents a single entry found within "VersionResources" section of a .NET Portable Executable binary file. type DotnetPortableExecutableEntry struct { + // AssemblyVersion is the .NET assembly version number (strong-named version) AssemblyVersion string `json:"assemblyVersion"` - LegalCopyright string `json:"legalCopyright"` - Comments string `json:"comments,omitempty"` - InternalName string `json:"internalName,omitempty"` - CompanyName string `json:"companyName"` - ProductName string `json:"productName"` - ProductVersion string `json:"productVersion"` + + // LegalCopyright is the copyright notice string + LegalCopyright string `json:"legalCopyright"` + + // Comments are additional comments or description embedded in PE resources + Comments string `json:"comments,omitempty"` + + // InternalName is the internal name of the file + InternalName string `json:"internalName,omitempty"` + + // CompanyName is the company that produced the file + CompanyName string `json:"companyName"` + + // ProductName is the name of the product this file is part of + ProductName string `json:"productName"` + + // ProductVersion is the version of the product (may differ from AssemblyVersion) + ProductVersion string `json:"productVersion"` } diff --git a/syft/pkg/dpkg.go b/syft/pkg/dpkg.go index 7f6ef6076..818f8bcce 100644 --- a/syft/pkg/dpkg.go +++ b/syft/pkg/dpkg.go @@ -12,6 +12,7 @@ const DpkgDBGlob = "**/var/lib/dpkg/{status,status.d/**}" var _ FileOwner = (*DpkgDBEntry)(nil) +// DpkgArchiveEntry represents package metadata extracted from a .deb archive file. type DpkgArchiveEntry DpkgDBEntry // DpkgDBEntry represents all captured data for a Debian package DB entry; available fields are described @@ -22,49 +23,53 @@ type DpkgArchiveEntry DpkgDBEntry // - https://www.debian.org/doc/debian-policy/ch-binary.html#s-virtual-pkg // - https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual type DpkgDBEntry struct { - Package string `json:"package"` - Source string `json:"source" cyclonedx:"source"` - Version string `json:"version"` + // Package is the package name as found in the status file + Package string `json:"package"` + + // Source is the source package name this binary was built from (one source can produce multiple binary packages) + Source string `json:"source" cyclonedx:"source"` + + // Version is the binary package version as found in the status file + Version string `json:"version"` + + // SourceVersion is the source package version (may differ from binary version when binNMU rebuilds occur) SourceVersion string `json:"sourceVersion" cyclonedx:"sourceVersion"` - // Architecture can include the following sets of values depending on context and the control file used: - // - a unique single word identifying a Debian machine architecture as described in Architecture specification string (https://www.debian.org/doc/debian-policy/ch-customized-programs.html#s-arch-spec) . - // - an architecture wildcard identifying a set of Debian machine architectures, see Architecture wildcards (https://www.debian.org/doc/debian-policy/ch-customized-programs.html#s-arch-wildcard-spec). any matches all Debian machine architectures and is the most frequently used. - // - "all", which indicates an architecture-independent package. - // - "source", which indicates a source package. + // Architecture is the target architecture per Debian spec (specific arch like amd64/arm64, wildcard like any, architecture-independent "all", or "source" for source packages) Architecture string `json:"architecture"` - // Maintainer is the package maintainer’s name and email address. The name must come first, then the email - // address inside angle brackets <> (in RFC822 format). + // Maintainer is the package maintainer's name and email in RFC822 format (name must come first, then email in angle brackets) Maintainer string `json:"maintainer"` + // InstalledSize is the total size of installed files in kilobytes InstalledSize int `json:"installedSize" cyclonedx:"installedSize"` - // Description contains a description of the binary package, consisting of two parts, the synopsis or the short - // description, and the long description (in a multiline format). + // Description is a human-readable package description with synopsis (first line) and long description (multiline format) Description string `hash:"ignore" json:"-"` - // Provides is a virtual package that is provided by one or more packages. A virtual package is one which appears - // in the Provides control field of another package. The effect is as if the package(s) which provide a particular - // virtual package name had been listed by name everywhere the virtual package name appears. (See also Virtual packages) + // Provides are the virtual packages provided by this package (allows other packages to depend on capabilities. Can include versioned provides like "libdigest-md5-perl (= 2.55.01)") Provides []string `json:"provides,omitempty"` - // Depends This declares an absolute dependency. A package will not be configured unless all of the packages listed in - // its Depends field have been correctly configured (unless there is a circular dependency). + // Depends are the packages required for this package to function (will not be installed unless these requirements are met, creates strict ordering constraint) Depends []string `json:"depends,omitempty"` - // PreDepends is like Depends, except that it also forces dpkg to complete installation of the packages named - // before even starting the installation of the package which declares the pre-dependency. + // PreDepends are the packages that must be installed and configured BEFORE even starting installation of this package (stronger than Depends, discouraged unless absolutely necessary as it adds strict constraints for apt) PreDepends []string `json:"preDepends,omitempty"` + // Files are the files installed by this package Files []DpkgFileRecord `json:"files"` } // DpkgFileRecord represents a single file attributed to a debian package. type DpkgFileRecord struct { - Path string `json:"path"` - Digest *file.Digest `json:"digest,omitempty"` - IsConfigFile bool `json:"isConfigFile"` + // Path is the file path relative to the filesystem root + Path string `json:"path"` + + // Digest is the file content hash (typically MD5 for dpkg compatibility with legacy systems) + Digest *file.Digest `json:"digest,omitempty"` + + // IsConfigFile is whether this file is marked as a configuration file (dpkg will preserve user modifications during upgrades) + IsConfigFile bool `json:"isConfigFile"` } func (m DpkgDBEntry) OwnedFiles() (result []string) { diff --git a/syft/pkg/elixir.go b/syft/pkg/elixir.go index ac556cd87..b13d04d1f 100644 --- a/syft/pkg/elixir.go +++ b/syft/pkg/elixir.go @@ -2,8 +2,15 @@ package pkg // ElixirMixLockEntry is a struct that represents a single entry in a mix.lock file type ElixirMixLockEntry struct { - Name string `mapstructure:"name" json:"name"` - Version string `mapstructure:"version" json:"version"` - PkgHash string `mapstructure:"pkgHash" json:"pkgHash"` + // Name is the package name as found in the mix.lock file + Name string `mapstructure:"name" json:"name"` + + // Version is the package version as found in the mix.lock file + Version string `mapstructure:"version" json:"version"` + + // PkgHash is the outer checksum (SHA-256) of the entire Hex package tarball for integrity verification (preferred method, replaces deprecated inner checksum) + PkgHash string `mapstructure:"pkgHash" json:"pkgHash"` + + // PkgHashExt is the extended package hash format (inner checksum is deprecated - SHA-256 of concatenated file contents excluding CHECKSUM file, now replaced by outer checksum) PkgHashExt string `mapstructure:"pkgHashExt" json:"pkgHashExt"` } diff --git a/syft/pkg/erlang.go b/syft/pkg/erlang.go index d74ff680e..eb1987a9b 100644 --- a/syft/pkg/erlang.go +++ b/syft/pkg/erlang.go @@ -2,8 +2,15 @@ package pkg // ErlangRebarLockEntry represents a single package entry from the "deps" section within an Erlang rebar.lock file. type ErlangRebarLockEntry struct { - Name string `mapstructure:"name" json:"name"` - Version string `mapstructure:"version" json:"version"` - PkgHash string `mapstructure:"pkgHash" json:"pkgHash"` + // Name is the package name as found in the rebar.lock file + Name string `mapstructure:"name" json:"name"` + + // Version is the package version as found in the rebar.lock file + Version string `mapstructure:"version" json:"version"` + + // PkgHash is the outer checksum (SHA-256) of the entire Hex package tarball for integrity verification (preferred method over deprecated inner checksum) + PkgHash string `mapstructure:"pkgHash" json:"pkgHash"` + + // PkgHashExt is the extended package hash format (inner checksum deprecated - was SHA-256 of concatenated file contents) PkgHashExt string `mapstructure:"pkgHashExt" json:"pkgHashExt"` } diff --git a/syft/pkg/github.go b/syft/pkg/github.go index 8ffabea3b..1f5c9876b 100644 --- a/syft/pkg/github.go +++ b/syft/pkg/github.go @@ -1,6 +1,10 @@ package pkg +// GitHubActionsUseStatement represents a single 'uses' statement in a GitHub Actions workflow file referencing an action or reusable workflow. type GitHubActionsUseStatement struct { - Value string `json:"value"` + // Value is the action reference (e.g. "actions/checkout@v3") + Value string `json:"value"` + + // Comment is the inline comment associated with this uses statement Comment string `json:"comment,omitempty"` } diff --git a/syft/pkg/golang.go b/syft/pkg/golang.go index ae53e2f96..9656f83b1 100644 --- a/syft/pkg/golang.go +++ b/syft/pkg/golang.go @@ -2,25 +2,48 @@ package pkg // GolangBinaryBuildinfoEntry represents all captured data for a Golang binary type GolangBinaryBuildinfoEntry struct { - BuildSettings KeyValues `json:"goBuildSettings,omitempty" cyclonedx:"goBuildSettings"` - GoCompiledVersion string `json:"goCompiledVersion" cyclonedx:"goCompiledVersion"` - Architecture string `json:"architecture" cyclonedx:"architecture"` - H1Digest string `json:"h1Digest,omitempty" cyclonedx:"h1Digest"` - MainModule string `json:"mainModule,omitempty" cyclonedx:"mainModule"` - GoCryptoSettings []string `json:"goCryptoSettings,omitempty" cyclonedx:"goCryptoSettings"` - GoExperiments []string `json:"goExperiments,omitempty" cyclonedx:"goExperiments"` + // BuildSettings contains the Go build settings and flags used to compile the binary (e.g., GOARCH, GOOS, CGO_ENABLED). + BuildSettings KeyValues `json:"goBuildSettings,omitempty" cyclonedx:"goBuildSettings"` + + // GoCompiledVersion is the version of Go used to compile the binary. + GoCompiledVersion string `json:"goCompiledVersion" cyclonedx:"goCompiledVersion"` + + // Architecture is the target CPU architecture for the binary (extracted from GOARCH build setting). + Architecture string `json:"architecture" cyclonedx:"architecture"` + + // H1Digest is the Go module hash in h1: format for the main module from go.sum. + H1Digest string `json:"h1Digest,omitempty" cyclonedx:"h1Digest"` + + // MainModule is the main module path for the binary (e.g., "github.com/anchore/syft"). + MainModule string `json:"mainModule,omitempty" cyclonedx:"mainModule"` + + // GoCryptoSettings contains FIPS and cryptographic configuration settings if present. + GoCryptoSettings []string `json:"goCryptoSettings,omitempty" cyclonedx:"goCryptoSettings"` + + // GoExperiments lists experimental Go features enabled during compilation (e.g., "arenas", "cgocheck2"). + GoExperiments []string `json:"goExperiments,omitempty" cyclonedx:"goExperiments"` } // GolangModuleEntry represents all captured data for a Golang source scan with go.mod/go.sum type GolangModuleEntry struct { + // H1Digest is the Go module hash in h1: format from go.sum for verifying module contents. H1Digest string `json:"h1Digest,omitempty" cyclonedx:"h1Digest"` } // GolangSourceEntry represents all captured data for a Golang package found through source analysis type GolangSourceEntry struct { - H1Digest string `json:"h1Digest,omitempty" cyclonedx:"h1Digest"` + // H1Digest is the Go module hash in h1: format from go.sum for verifying module contents. + H1Digest string `json:"h1Digest,omitempty" cyclonedx:"h1Digest"` + + // OperatingSystem is the target OS for build constraints (e.g., "linux", "darwin", "windows"). OperatingSystem string `json:"os,omitempty" cyclonedx:"os"` - Architecture string `json:"architecture,omitempty" cyclonedx:"architecture"` - BuildTags string `json:"buildTags,omitempty" cyclonedx:"buildTags"` - CgoEnabled bool `json:"cgoEnabled" cyclonedx:"cgoEnabled"` + + // Architecture is the target CPU architecture for build constraints (e.g., "amd64", "arm64"). + Architecture string `json:"architecture,omitempty" cyclonedx:"architecture"` + + // BuildTags are the build tags used to conditionally compile code (e.g., "integration,debug"). + BuildTags string `json:"buildTags,omitempty" cyclonedx:"buildTags"` + + // CgoEnabled indicates whether CGO was enabled for this package. + CgoEnabled bool `json:"cgoEnabled" cyclonedx:"cgoEnabled"` } diff --git a/syft/pkg/hackage.go b/syft/pkg/hackage.go index 50e7d7eb6..3e1a2ed1b 100644 --- a/syft/pkg/hackage.go +++ b/syft/pkg/hackage.go @@ -2,11 +2,15 @@ package pkg // HackageStackYamlLockEntry represents a single entry from the "packages" section of a stack.yaml.lock file. type HackageStackYamlLockEntry struct { - PkgHash string `mapstructure:"pkgHash" json:"pkgHash,omitempty"` + // PkgHash is the package content hash for verification + PkgHash string `mapstructure:"pkgHash" json:"pkgHash,omitempty"` + + // SnapshotURL is the URL to the Stack snapshot this package came from SnapshotURL string `mapstructure:"snapshotURL" json:"snapshotURL,omitempty"` } // HackageStackYamlEntry represents a single entry from the "extra-deps" section of a stack.yaml file. type HackageStackYamlEntry struct { + // PkgHash is the package content hash for verification PkgHash string `mapstructure:"pkgHash" json:"pkgHash,omitempty"` } diff --git a/syft/pkg/homebrew.go b/syft/pkg/homebrew.go index 8abc567ee..574e0d871 100644 --- a/syft/pkg/homebrew.go +++ b/syft/pkg/homebrew.go @@ -1,7 +1,13 @@ package pkg +// HomebrewFormula represents metadata about a Homebrew formula package extracted from formula JSON files. type HomebrewFormula struct { - Tap string `json:"tap,omitempty"` - Homepage string `json:"homepage,omitempty"` + // Tap is Homebrew tap this formula belongs to (e.g. "homebrew/core") + Tap string `json:"tap,omitempty"` + + // Homepage is the upstream project homepage URL + Homepage string `json:"homepage,omitempty"` + + // Description is a human-readable formula description Description string `json:"description,omitempty"` } diff --git a/syft/pkg/java.go b/syft/pkg/java.go index 3bba12d19..dc8bc06c1 100644 --- a/syft/pkg/java.go +++ b/syft/pkg/java.go @@ -18,15 +18,20 @@ var jenkinsPluginPomPropertiesGroupIDs = []string{ "com.cloudbees.jenkins.plugins", } +// JavaVMInstallation represents a Java Virtual Machine installation discovered on the system with its release information and file list. type JavaVMInstallation struct { + // Release is JVM release information and version details Release JavaVMRelease `json:"release"` - Files []string `json:"files"` + + // Files are the list of files that are part of this JVM installation + Files []string `json:"files"` } func (m JavaVMInstallation) OwnedFiles() []string { return m.Files } +// JavaVMRelease represents JVM version and build information extracted from the release file in a Java installation. type JavaVMRelease struct { // Implementor is extracted with the `java.vendor` JVM property Implementor string `mapstructure:"IMPLEMENTOR,omitempty" json:"implementor,omitempty"` @@ -94,42 +99,86 @@ type JavaVMRelease struct { // JavaArchive encapsulates all Java ecosystem metadata for a package as well as an (optional) parent relationship. type JavaArchive struct { - VirtualPath string `json:"virtualPath" cyclonedx:"virtualPath"` // we need to include the virtual path in cyclonedx documents to prevent deduplication of jars within jars - Manifest *JavaManifest `mapstructure:"Manifest" json:"manifest,omitempty"` - PomProperties *JavaPomProperties `mapstructure:"PomProperties" json:"pomProperties,omitempty" cyclonedx:"-"` - PomProject *JavaPomProject `mapstructure:"PomProject" json:"pomProject,omitempty"` - ArchiveDigests []file.Digest `hash:"ignore" json:"digest,omitempty"` - Parent *Package `hash:"ignore" json:"-"` // note: the parent cannot be included in the minimal definition of uniqueness since this field is not reproducible in an encode-decode cycle (is lossy). + // VirtualPath is path within the archive hierarchy, where nested entries are delimited with ':' (for nested JARs) + VirtualPath string `json:"virtualPath" cyclonedx:"virtualPath"` + + // Manifest is parsed META-INF/MANIFEST.MF contents + Manifest *JavaManifest `mapstructure:"Manifest" json:"manifest,omitempty"` + + // PomProperties is parsed pom.properties file contents + PomProperties *JavaPomProperties `mapstructure:"PomProperties" json:"pomProperties,omitempty" cyclonedx:"-"` + + // PomProject is parsed pom.xml file contents + PomProject *JavaPomProject `mapstructure:"PomProject" json:"pomProject,omitempty"` + + // ArchiveDigests is cryptographic hashes of the archive file + ArchiveDigests []file.Digest `hash:"ignore" json:"digest,omitempty"` + + // Parent is reference to parent package (for nested archives) + Parent *Package `hash:"ignore" json:"-"` } // JavaPomProperties represents the fields of interest extracted from a Java archive's pom.properties file. type JavaPomProperties struct { - Path string `mapstructure:"path" json:"path"` - Name string `mapstructure:"name" json:"name"` - GroupID string `mapstructure:"groupId" json:"groupId" cyclonedx:"groupID"` - ArtifactID string `mapstructure:"artifactId" json:"artifactId" cyclonedx:"artifactID"` - Version string `mapstructure:"version" json:"version"` - Scope string `mapstructure:"scope" json:"scope,omitempty"` - Extra map[string]string `mapstructure:",remain" json:"extraFields,omitempty"` + // Path is path to the pom.properties file within the archive + Path string `mapstructure:"path" json:"path"` + + // Name is the project name + Name string `mapstructure:"name" json:"name"` + + // GroupID is Maven group identifier uniquely identifying the project across all projects (follows reversed domain name convention like com.company.project) + GroupID string `mapstructure:"groupId" json:"groupId" cyclonedx:"groupID"` + + // ArtifactID is Maven artifact identifier, the name of the jar/artifact (unique within the groupId scope) + ArtifactID string `mapstructure:"artifactId" json:"artifactId" cyclonedx:"artifactID"` + + // Version is artifact version + Version string `mapstructure:"version" json:"version"` + + // Scope is dependency scope determining when dependency is available (compile=default all phases, test=test compilation/execution only, runtime=runtime and test not compile, provided=expected from JDK or container) + Scope string `mapstructure:"scope" json:"scope,omitempty"` + + // Extra is additional custom properties not in standard Maven coordinates + Extra map[string]string `mapstructure:",remain" json:"extraFields,omitempty"` } // JavaPomProject represents fields of interest extracted from a Java archive's pom.xml file. See https://maven.apache.org/ref/3.6.3/maven-model/maven.html for more details. type JavaPomProject struct { - Path string `json:"path"` - Parent *JavaPomParent `json:"parent,omitempty"` - GroupID string `json:"groupId"` - ArtifactID string `json:"artifactId"` - Version string `json:"version"` - Name string `json:"name"` - Description string `json:"description,omitempty"` - URL string `json:"url,omitempty"` + // Path is path to the pom.xml file within the archive + Path string `json:"path"` + + // Parent is the parent POM reference for inheritance (child POMs inherit configuration from parent) + Parent *JavaPomParent `json:"parent,omitempty"` + + // GroupID is Maven group identifier (reversed domain name like org.apache.maven) + GroupID string `json:"groupId"` + + // ArtifactID is Maven artifact identifier (project name) + ArtifactID string `json:"artifactId"` + + // Version is project version (together with groupId and artifactId forms Maven coordinates groupId:artifactId:version) + Version string `json:"version"` + + // Name is a human-readable project name (displayed in Maven-generated documentation) + Name string `json:"name"` + + // Description is detailed project description + Description string `json:"description,omitempty"` + + // URL is the project URL (typically project website or repository) + URL string `json:"url,omitempty"` } // JavaPomParent contains the fields within the tag in a pom.xml file type JavaPomParent struct { - GroupID string `json:"groupId"` + // GroupID is the parent Maven group identifier + GroupID string `json:"groupId"` + + // ArtifactID is the parent Maven artifact identifier ArtifactID string `json:"artifactId"` - Version string `json:"version"` + + // Version is the parent version (child inherits configuration from this specific version of parent POM) + Version string `json:"version"` } // PkgTypeIndicated returns the package Type indicated by the data contained in the JavaPomProperties. @@ -143,7 +192,10 @@ func (p JavaPomProperties) PkgTypeIndicated() Type { // JavaManifest represents the fields of interest extracted from a Java archive's META-INF/MANIFEST.MF file. type JavaManifest struct { - Main KeyValues `json:"main,omitempty"` + // Main is main manifest attributes as key-value pairs + Main KeyValues `json:"main,omitempty"` + + // Sections are the named sections from the manifest (e.g. per-entry attributes) Sections []KeyValues `json:"sections,omitempty"` } diff --git a/syft/pkg/key_value.go b/syft/pkg/key_value.go index 52337be75..dd6f6759c 100644 --- a/syft/pkg/key_value.go +++ b/syft/pkg/key_value.go @@ -6,11 +6,16 @@ import ( "sort" ) +// KeyValue represents a single key-value pair. type KeyValue struct { - Key string `json:"key"` + // Key is the key name + Key string `json:"key"` + + // Value is the value associated with the key Value string `json:"value"` } +// KeyValues represents an ordered collection of key-value pairs that preserves insertion order. type KeyValues []KeyValue func (k KeyValues) Get(key string) (string, bool) { diff --git a/syft/pkg/license.go b/syft/pkg/license.go index 8075035b6..2f863dc4e 100644 --- a/syft/pkg/license.go +++ b/syft/pkg/license.go @@ -22,28 +22,38 @@ import ( var _ sort.Interface = (*Licenses)(nil) -// License represents an SPDX Expression or license value extracted from a package's metadata -// We want to ignore URLs and Location since we merge these fields across equal licenses. -// A License is a unique combination of value, expression and type, where -// its sources are always considered merged and additions to the evidence -// of where it was found and how it was sourced. -// This is different from how we treat a package since we consider package paths -// in order to distinguish if packages should be kept separate -// this is different for licenses since we're only looking for evidence -// of where a license was declared/concluded for a given package. -// If a license is given as it's full text in the metadata rather than it's value or SPDX expression. -// The Contents field is used to represent this data. -// A Concluded License type is the license the SBOM creator believes governs the package (human crafted or altered SBOM). -// The Declared License is what the authors of a project believe govern the package. This is the default type syft declares. +// License represents an SPDX Expression or license value extracted from a package's metadata. +// A License is a unique combination of value, expression and type, where its sources are always +// considered merged and additions to the evidence of where it was found and how it was sourced. +// This is different from how we treat a package since we consider package paths in order to +// distinguish if packages should be kept separate. This is different for licenses since we're +// only looking for evidence of where a license was declared/concluded for a given package. type License struct { + // SPDXExpression is parsed SPDX license expression (e.g. "MIT OR Apache-2.0") SPDXExpression string - Value string - Type license.Type - Contents string `hash:"ignore"` // we want to ignore the contents here so we can drop contents in the post-processing step - URLs []string `hash:"ignore"` // TODO: there is such thing as a url-only license, but we aren't hashing on this, which means overwriting could occur in the license set - Locations file.LocationSet `hash:"ignore"` + + // Value is original raw license string as found in metadata (e.g. "mit or apache-2") + Value string + + // Type is classification of how this license was discovered (declared, concluded, etc.). + // A Concluded License type is the license the SBOM creator believes governs the package (human crafted or altered SBOM). + // The Declared License is what the authors of a project believe govern the package (this is the default type syft uses). + Type license.Type + + // Contents is full license text if available. If a license is given as its full text in the + // metadata rather than its value or SPDX expression, this field is used to represent that data. + Contents string `hash:"ignore"` + + // URLs are the list of URLs where license information was found. These are ignored for uniqueness + // since we merge these fields across equal licenses. + URLs []string `hash:"ignore"` + + // Locations are the file locations where this license was discovered. These are ignored for uniqueness + // since we merge these fields across equal licenses. + Locations file.LocationSet `hash:"ignore"` } +// Licenses is a sortable collection of License objects implementing sort.Interface. type Licenses []License func (l Licenses) Len() int { @@ -190,12 +200,18 @@ func (s License) Merge(l License) (*License, error) { return &s, nil } +// licenseBuilder is an internal builder for constructing License objects with validation and normalization. type licenseBuilder struct { - values []string - contents []io.ReadCloser + // values are raw license strings or SPDX expressions to process. + values []string + // contents are readers for full license text content. + contents []io.ReadCloser + // locations are file locations where license information was discovered. locations []file.Location - urls []string - tp license.Type + // urls are web URLs where license information can be found. + urls []string + // tp is the license type classification (declared, concluded, etc.). + tp license.Type } func newLicenseBuilder() *licenseBuilder { diff --git a/syft/pkg/linux_kernel.go b/syft/pkg/linux_kernel.go index e2aeb7cd0..15f30e1e2 100644 --- a/syft/pkg/linux_kernel.go +++ b/syft/pkg/linux_kernel.go @@ -2,33 +2,78 @@ package pkg // LinuxKernel represents all captured data for a Linux kernel type LinuxKernel struct { - Name string `mapstructure:"name" json:"name" cyclonedx:"name"` - Architecture string `mapstructure:"architecture" json:"architecture" cyclonedx:"architecture"` - Version string `mapstructure:"version" json:"version" cyclonedx:"version"` + // Name is kernel name (typically "Linux") + Name string `mapstructure:"name" json:"name" cyclonedx:"name"` + + // Architecture is the target CPU architecture + Architecture string `mapstructure:"architecture" json:"architecture" cyclonedx:"architecture"` + + // Version is kernel version string + Version string `mapstructure:"version" json:"version" cyclonedx:"version"` + + // ExtendedVersion is additional version information ExtendedVersion string `mapstructure:"extendedVersion" json:"extendedVersion,omitempty" cyclonedx:"extendedVersion"` - BuildTime string `mapstructure:"buildTime" json:"buildTime,omitempty" cyclonedx:"buildTime"` - Author string `mapstructure:"author" json:"author,omitempty" cyclonedx:"author"` - Format string `mapstructure:"format" json:"format,omitempty" cyclonedx:"format"` - RWRootFS bool `mapstructure:"rwRootFS" json:"rwRootFS,omitempty" cyclonedx:"rwRootFS"` - SwapDevice int `mapstructure:"swapDevice" json:"swapDevice,omitempty" cyclonedx:"swapDevice"` - RootDevice int `mapstructure:"rootDevice" json:"rootDevice,omitempty" cyclonedx:"rootDevice"` - VideoMode string `mapstructure:"videoMode" json:"videoMode,omitempty" cyclonedx:"videoMode"` + + // BuildTime is when the kernel was built + BuildTime string `mapstructure:"buildTime" json:"buildTime,omitempty" cyclonedx:"buildTime"` + + // Author is who built the kernel + Author string `mapstructure:"author" json:"author,omitempty" cyclonedx:"author"` + + // Format is kernel image format (e.g. bzImage, zImage) + Format string `mapstructure:"format" json:"format,omitempty" cyclonedx:"format"` + + // RWRootFS is whether root filesystem is mounted read-write + RWRootFS bool `mapstructure:"rwRootFS" json:"rwRootFS,omitempty" cyclonedx:"rwRootFS"` + + // SwapDevice is swap device number + SwapDevice int `mapstructure:"swapDevice" json:"swapDevice,omitempty" cyclonedx:"swapDevice"` + + // RootDevice is root device number + RootDevice int `mapstructure:"rootDevice" json:"rootDevice,omitempty" cyclonedx:"rootDevice"` + + // VideoMode is default video mode setting + VideoMode string `mapstructure:"videoMode" json:"videoMode,omitempty" cyclonedx:"videoMode"` } +// LinuxKernelModule represents a loadable kernel module (.ko file) with its metadata, parameters, and dependencies. type LinuxKernelModule struct { - Name string `mapstructure:"name" json:"name,omitempty" cyclonedx:"name"` - Version string `mapstructure:"version" json:"version,omitempty" cyclonedx:"version"` - SourceVersion string `mapstructure:"sourceVersion" json:"sourceVersion,omitempty" cyclonedx:"sourceVersion"` - Path string `mapstructure:"path" json:"path,omitempty" cyclonedx:"path"` - Description string `mapstructure:"description" json:"description,omitempty" cyclonedx:"description"` - Author string `mapstructure:"author" json:"author,omitempty" cyclonedx:"author"` - License string `mapstructure:"license" json:"license,omitempty" cyclonedx:"license"` - KernelVersion string `mapstructure:"kernelVersion" json:"kernelVersion,omitempty" cyclonedx:"kernelVersion"` - VersionMagic string `mapstructure:"versionMagic" json:"versionMagic,omitempty" cyclonedx:"versionMagic"` - Parameters map[string]LinuxKernelModuleParameter `mapstructure:"parameters" json:"parameters,omitempty" cyclonedx:"parameters"` + // Name is module name + Name string `mapstructure:"name" json:"name,omitempty" cyclonedx:"name"` + + // Version is module version string + Version string `mapstructure:"version" json:"version,omitempty" cyclonedx:"version"` + + // SourceVersion is the source code version identifier + SourceVersion string `mapstructure:"sourceVersion" json:"sourceVersion,omitempty" cyclonedx:"sourceVersion"` + + // Path is the filesystem path to the .ko kernel object file (absolute path) + Path string `mapstructure:"path" json:"path,omitempty" cyclonedx:"path"` + + // Description is a human-readable module description + Description string `mapstructure:"description" json:"description,omitempty" cyclonedx:"description"` + + // Author is module author name and email + Author string `mapstructure:"author" json:"author,omitempty" cyclonedx:"author"` + + // License is module license (e.g. GPL, BSD) which must be compatible with kernel + License string `mapstructure:"license" json:"license,omitempty" cyclonedx:"license"` + + // KernelVersion is kernel version this module was built for + KernelVersion string `mapstructure:"kernelVersion" json:"kernelVersion,omitempty" cyclonedx:"kernelVersion"` + + // VersionMagic is version magic string for compatibility checking (includes kernel version, SMP status, module loading capabilities like "3.17.4-302.fc21.x86_64 SMP mod_unload modversions"). Module will NOT load if vermagic doesn't match running kernel. + VersionMagic string `mapstructure:"versionMagic" json:"versionMagic,omitempty" cyclonedx:"versionMagic"` + + // Parameters are the module parameters that can be configured at load time (user-settable values like module options) + Parameters map[string]LinuxKernelModuleParameter `mapstructure:"parameters" json:"parameters,omitempty" cyclonedx:"parameters"` } +// LinuxKernelModuleParameter represents a configurable parameter for a kernel module with its type and description. type LinuxKernelModuleParameter struct { - Type string `mapstructure:"type" json:"type,omitempty" cyclonedx:"type"` + // Type is parameter data type (e.g. int, string, bool, array types) + Type string `mapstructure:"type" json:"type,omitempty" cyclonedx:"type"` + + // Description is a human-readable parameter description explaining what the parameter controls Description string `mapstructure:"description" json:"description,omitempty" cyclonedx:"description"` } diff --git a/syft/pkg/microsoft.go b/syft/pkg/microsoft.go index c80229f8c..80c345c28 100644 --- a/syft/pkg/microsoft.go +++ b/syft/pkg/microsoft.go @@ -6,6 +6,9 @@ package pkg // "Windows 10 Version 1703 for 32-bit Systems". // `Kb` is expected to be the actual KB number, for example "5001028" 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"` - Kb string `toml:"kb" json:"kb"` + + // Kb is Knowledge Base article number (e.g. "5001028") + Kb string `toml:"kb" json:"kb"` } diff --git a/syft/pkg/nix.go b/syft/pkg/nix.go index 61ee27170..1160f9c13 100644 --- a/syft/pkg/nix.go +++ b/syft/pkg/nix.go @@ -6,43 +6,45 @@ import ( "github.com/scylladb/go-set/strset" ) +// NixStoreEntry represents a package in the Nix store (/nix/store) with its derivation information and metadata. type NixStoreEntry struct { - // Path is the store path for this output + // Path is full store path for this output (e.g. /nix/store/abc123...-package-1.0) Path string `mapstructure:"path" json:"path,omitempty"` - // Output allows for optionally specifying the specific nix package output this package represents (for packages that support multiple outputs). - // Note: the default output for a package is an empty string, so will not be present in the output. + // Output is the specific output name for multi-output packages (empty string for default "out" output, can be "bin", "dev", "doc", etc.) Output string `mapstructure:"output" json:"output,omitempty"` - // OutputHash is the prefix of the nix store basename path + // OutputHash is hash prefix of the store path basename (first part before the dash) OutputHash string `mapstructure:"outputHash" json:"outputHash"` - // Derivation is any information about the derivation file that was used to build this package + // Derivation is information about the .drv file that describes how this package was built Derivation NixDerivation `mapstructure:"derivation" json:"derivation,omitempty"` - // Files is a listing a files that are under the nix/store path for this package + // Files are the list of files under the nix/store path for this package Files []string `mapstructure:"files" json:"files,omitempty"` } +// NixDerivation represents a Nix .drv file that describes how to build a package including inputs, outputs, and build instructions. type NixDerivation struct { - // Path is the path to the derivation file + // Path is path to the .drv file in Nix store Path string `mapstructure:"path" json:"path,omitempty"` - // System is the nix system string that this derivation was built for + // System is target system string indicating where derivation can be built (e.g. "x86_64-linux", "aarch64-darwin"). Must match current system for local builds. System string `mapstructure:"system" json:"system,omitempty"` - // InputDerivations is a list of derivation paths that were used to build this package + // InputDerivations are the list of other derivations that were inputs to this build (dependencies) InputDerivations []NixDerivationReference `mapstructure:"inputDerivations" json:"inputDerivations,omitempty"` - // InputSources is a list of source paths that were used to build this package + // InputSources are the list of source file paths that were inputs to this build InputSources []string `mapstructure:"inputSources" json:"inputSources,omitempty"` } +// NixDerivationReference represents a reference to another derivation used as a build input or runtime dependency. type NixDerivationReference struct { - // Path is the path to the derivation file + // Path is path to the referenced .drv file Path string `mapstructure:"path" json:"path,omitempty"` - // Outputs is a list of output names that were used to build this package + // Outputs are which outputs of the referenced derivation were used (e.g. ["out"], ["bin", "dev"]) Outputs []string `mapstructure:"outputs" json:"outputs,omitempty"` } diff --git a/syft/pkg/npm.go b/syft/pkg/npm.go index c39539bd6..a5068139c 100644 --- a/syft/pkg/npm.go +++ b/syft/pkg/npm.go @@ -2,23 +2,42 @@ package pkg // NpmPackage represents the contents of a javascript package.json file. type NpmPackage struct { - Name string `mapstructure:"name" json:"name"` - Version string `mapstructure:"version" json:"version"` - Author string `mapstructure:"author" json:"author"` - Homepage string `mapstructure:"homepage" json:"homepage"` + // Name is the package name as found in package.json + Name string `mapstructure:"name" json:"name"` + + // Version is the package version as found in package.json + Version string `mapstructure:"version" json:"version"` + + // Author is package author name + Author string `mapstructure:"author" json:"author"` + + // Homepage is project homepage URL + Homepage string `mapstructure:"homepage" json:"homepage"` + + // Description is a human-readable package description Description string `mapstructure:"description" json:"description"` - URL string `mapstructure:"url" json:"url"` - Private bool `mapstructure:"private" json:"private"` + + // URL is repository or project URL + URL string `mapstructure:"url" json:"url"` + + // Private is whether this is a private package + Private bool `mapstructure:"private" json:"private"` } // NpmPackageLockEntry represents a single entry within the "packages" section of a package-lock.json file. type NpmPackageLockEntry struct { - Resolved string `mapstructure:"resolved" json:"resolved"` + // Resolved is URL where this package was downloaded from (registry source) + Resolved string `mapstructure:"resolved" json:"resolved"` + + // Integrity is Subresource Integrity hash for verification using standard SRI format (sha512-... or sha1-...). npm changed from SHA-1 to SHA-512 in newer versions. For registry sources this is the integrity from registry, for remote tarballs it's SHA-512 of the file. npm verifies tarball matches this hash before unpacking, throwing EINTEGRITY error if mismatch detected. Integrity string `mapstructure:"integrity" json:"integrity"` } // YarnLockEntry represents a single entry section of a yarn.lock file. type YarnLockEntry struct { - Resolved string `mapstructure:"resolved" json:"resolved"` + // Resolved is URL where this package was downloaded from + Resolved string `mapstructure:"resolved" json:"resolved"` + + // Integrity is Subresource Integrity hash for verification (SRI format) Integrity string `mapstructure:"integrity" json:"integrity"` } diff --git a/syft/pkg/ocaml.go b/syft/pkg/ocaml.go index 350d04339..7003069a5 100644 --- a/syft/pkg/ocaml.go +++ b/syft/pkg/ocaml.go @@ -1,11 +1,25 @@ package pkg +// OpamPackage represents an OCaml package managed by the OPAM package manager with metadata from .opam files. type OpamPackage struct { - Name string `toml:"name" json:"name"` - Version string `toml:"version" json:"version"` - Licenses []string `mapstructure:"licenses" json:"licenses"` - URL string `mapstructure:"url" json:"url"` - Checksums []string `mapstructure:"checksums" json:"checksum"` - Homepage string `json:"homepage"` + // Name is the package name as found in the .opam file + Name string `toml:"name" json:"name"` + + // Version is the package version as found in the .opam file + Version string `toml:"version" json:"version"` + + // Licenses are the list of applicable licenses + Licenses []string `mapstructure:"licenses" json:"licenses"` + + // URL is download URL for the package source + URL string `mapstructure:"url" json:"url"` + + // Checksums are the list of checksums for verification + Checksums []string `mapstructure:"checksums" json:"checksum"` + + // Homepage is project homepage URL + Homepage string `json:"homepage"` + + // Dependencies are the list of required dependencies Dependencies []string `toml:"dependencies" json:"dependencies"` } diff --git a/syft/pkg/package.go b/syft/pkg/package.go index a9fc65317..546c91f5c 100644 --- a/syft/pkg/package.go +++ b/syft/pkg/package.go @@ -17,17 +17,38 @@ import ( // Package represents an application or library that has been bundled into a distributable format. // TODO: if we ignore FoundBy for ID generation should we merge the field to show it was found in two places? type Package struct { - id artifact.ID `hash:"ignore"` - Name string // the package name - Version string // the version of the package - FoundBy string `hash:"ignore" cyclonedx:"foundBy"` // the specific cataloger that discovered this package - Locations file.LocationSet // the locations that lead to the discovery of this package (note: this is not necessarily the locations that make up this package) - Licenses LicenseSet // licenses discovered with the package metadata - Language Language `hash:"ignore" cyclonedx:"language"` // the language ecosystem this package belongs to (e.g. JavaScript, Python, etc) - Type Type `cyclonedx:"type"` // the package type (e.g. Npm, Yarn, Python, Rpm, Deb, etc) - CPEs []cpe.CPE `hash:"ignore"` // all possible Common Platform Enumerators (note: this is NOT included in the definition of the ID since all fields on a CPE are derived from other fields) - PURL string `hash:"ignore"` // the Package URL (see https://github.com/package-url/purl-spec) - Metadata any // additional data found while parsing the package source + // id is a content-addressable identifier for this package, computed from most attribute values (applied recursively) + id artifact.ID `hash:"ignore"` + + // Name is the package name + Name string + + // Version is the package version + Version string + + // FoundBy is the specific cataloger that discovered this package + FoundBy string `hash:"ignore" cyclonedx:"foundBy"` + + // Locations are the locations that lead to the discovery of this package (note: not necessarily the locations that make up the package) + Locations file.LocationSet + + // Licenses are the licenses discovered from the package metadata + Licenses LicenseSet + + // Language is the language this package was written in (e.g. JavaScript, Python, etc) + Language Language `hash:"ignore" cyclonedx:"language"` + + // Type is the ecosystem the package belongs to (e.g. Npm, Yarn, Python, Rpm, Deb, etc) + Type Type `cyclonedx:"type"` + + // CPEs are all possible Common Platform Enumerators (note: NOT included in ID since derived from other fields) + CPEs []cpe.CPE `hash:"ignore"` + + // PURL is the Package URL (see https://github.com/package-url/purl-spec) + PURL string `hash:"ignore"` + + // Metadata is additional data found while parsing the package source + Metadata any } func (p *Package) OverrideID(id artifact.ID) { diff --git a/syft/pkg/php.go b/syft/pkg/php.go index 2759a229c..1864ed9ef 100644 --- a/syft/pkg/php.go +++ b/syft/pkg/php.go @@ -5,35 +5,82 @@ type PhpComposerInstalledEntry PhpComposerLockEntry // PhpComposerLockEntry represents a single package entry found from a composer.lock file. type PhpComposerLockEntry struct { - Name string `json:"name"` - Version string `json:"version"` - Source PhpComposerExternalReference `json:"source"` - Dist PhpComposerExternalReference `json:"dist"` - Require map[string]string `json:"require,omitempty"` - Provide map[string]string `json:"provide,omitempty"` - RequireDev map[string]string `json:"require-dev,omitempty"` - Suggest map[string]string `json:"suggest,omitempty"` - License []string `json:"license,omitempty"` - Type string `json:"type,omitempty"` - NotificationURL string `json:"notification-url,omitempty"` - Bin []string `json:"bin,omitempty"` - Authors []PhpComposerAuthors `json:"authors,omitempty"` - Description string `json:"description,omitempty"` - Homepage string `json:"homepage,omitempty"` - Keywords []string `json:"keywords,omitempty"` - Time string `json:"time,omitempty"` + // Name is package name in vendor/package format (e.g. symfony/console) + Name string `json:"name"` + + // Version is the package version + Version string `json:"version"` + + // Source is the source repository information for development (typically git repo, used when passing --prefer-source). Originates from source code repository. + Source PhpComposerExternalReference `json:"source"` + + // Dist is distribution archive information for production (typically zip/tar, default install method). Packaged version of released code. + Dist PhpComposerExternalReference `json:"dist"` + + // Require is runtime dependencies with version constraints (package will not install unless these requirements can be met) + Require map[string]string `json:"require,omitempty"` + + // Provide is virtual packages/functionality provided by this package (allows other packages to depend on capabilities) + Provide map[string]string `json:"provide,omitempty"` + + // RequireDev is development-only dependencies (not installed in production, only when developing this package or running tests) + RequireDev map[string]string `json:"require-dev,omitempty"` + + // Suggest is optional but recommended dependencies (suggestions for packages that would extend functionality) + Suggest map[string]string `json:"suggest,omitempty"` + + // License is the list of license identifiers (SPDX format) + License []string `json:"license,omitempty"` + + // Type is package type indicating purpose (library=reusable code, project=application, metapackage=aggregates dependencies, etc.) + Type string `json:"type,omitempty"` + + // NotificationURL is the URL to notify when package is installed (for tracking/statistics) + NotificationURL string `json:"notification-url,omitempty"` + + // Bin is the list of binary/executable files that should be added to PATH + Bin []string `json:"bin,omitempty"` + + // Authors are the list of package authors with name/email/homepage + Authors []PhpComposerAuthors `json:"authors,omitempty"` + + // Description is a human-readable package description + Description string `json:"description,omitempty"` + + // Homepage is project homepage URL + Homepage string `json:"homepage,omitempty"` + + // Keywords are the list of keywords for package discovery/search + Keywords []string `json:"keywords,omitempty"` + + // Time is timestamp when this package version was released + Time string `json:"time,omitempty"` } +// PhpComposerExternalReference represents source or distribution information for a PHP package, indicating where the package code is retrieved from. type PhpComposerExternalReference struct { - Type string `json:"type"` - URL string `json:"url"` + // Type is reference type (git for source VCS, zip/tar for dist archives) + Type string `json:"type"` + + // URL is the URL to the resource (git repository URL or archive download URL) + URL string `json:"url"` + + // Reference is git commit hash or version tag for source, or archive version for dist Reference string `json:"reference"` - Shasum string `json:"shasum,omitempty"` + + // Shasum is SHA hash of the archive file for integrity verification (dist only) + Shasum string `json:"shasum,omitempty"` } +// PhpComposerAuthors represents author information for a PHP Composer package from the authors field in composer.json. type PhpComposerAuthors struct { - Name string `json:"name"` - Email string `json:"email,omitempty"` + // Name is author's full name + Name string `json:"name"` + + // Email is author's email address + Email string `json:"email,omitempty"` + + // Homepage is author's personal or company website Homepage string `json:"homepage,omitempty"` } @@ -43,8 +90,15 @@ type PhpPeclEntry PhpPearEntry // PhpPearEntry represents a single package entry found within php pear metadata files. type PhpPearEntry struct { - Name string `json:"name"` - Channel string `json:"channel,omitempty"` - Version string `json:"version"` + // Name is the package name + Name string `json:"name"` + + // Channel is PEAR channel this package is from + Channel string `json:"channel,omitempty"` + + // Version is the package version + Version string `json:"version"` + + // License is the list of applicable licenses License []string `json:"license,omitempty"` } diff --git a/syft/pkg/portage.go b/syft/pkg/portage.go index 35a556a70..eaf6c05e8 100644 --- a/syft/pkg/portage.go +++ b/syft/pkg/portage.go @@ -12,14 +12,22 @@ var _ FileOwner = (*PortageEntry)(nil) // PortageEntry represents a single package entry in the portage DB flat-file store. type PortageEntry struct { - InstalledSize int `json:"installedSize" cyclonedx:"installedSize"` - Licenses string `json:"licenses,omitempty"` - Files []PortageFileRecord `json:"files"` + // InstalledSize is total size of installed files in bytes + InstalledSize int `json:"installedSize" cyclonedx:"installedSize"` + + // Licenses is license string which may be an expression (e.g. "GPL-2 OR Apache-2.0") + Licenses string `json:"licenses,omitempty"` + + // Files are the files installed by this package (tracked in CONTENTS file) + Files []PortageFileRecord `json:"files"` } // PortageFileRecord represents a single file attributed to a portage package. type PortageFileRecord struct { - Path string `json:"path"` + // Path is the file path relative to the filesystem root + Path string `json:"path"` + + // Digest is file content hash (MD5 for regular files in CONTENTS format: "obj filename md5hash mtime") Digest *file.Digest `json:"digest,omitempty"` } diff --git a/syft/pkg/python.go b/syft/pkg/python.go index c6bd23ef9..8b1fdbd6a 100644 --- a/syft/pkg/python.go +++ b/syft/pkg/python.go @@ -13,37 +13,58 @@ var _ FileOwner = (*PythonPackage)(nil) // Historically these were defined in PEPs 345, 314, and 241, but have been superseded by PEP 566. This means that this // struct can (partially) express at least versions 1.0, 1.1, 1.2, 2.1, 2.2, and 2.3 of the metadata format. type PythonPackage struct { - Name string `json:"name" mapstructure:"Name"` - Version string `json:"version" mapstructure:"Version"` - Author string `json:"author" mapstructure:"Author"` - AuthorEmail string `json:"authorEmail" mapstructure:"AuthorEmail"` - Platform string `json:"platform" mapstructure:"Platform"` - Files []PythonFileRecord `json:"files,omitempty"` - SitePackagesRootPath string `json:"sitePackagesRootPath"` - TopLevelPackages []string `json:"topLevelPackages,omitempty"` - DirectURLOrigin *PythonDirectURLOriginInfo `json:"directUrlOrigin,omitempty"` - RequiresPython string `json:"requiresPython,omitempty" mapstructure:"RequiresPython"` - RequiresDist []string `json:"requiresDist,omitempty" mapstructure:"RequiresDist"` - ProvidesExtra []string `json:"providesExtra,omitempty" mapstructure:"ProvidesExtra"` + // Name is the package name from the Name field in PKG-INFO or METADATA. + Name string `json:"name" mapstructure:"Name"` + // Version is the package version from the Version field in PKG-INFO or METADATA. + Version string `json:"version" mapstructure:"Version"` + // Author is the package author name from the Author field. + Author string `json:"author" mapstructure:"Author"` + // AuthorEmail is the package author's email address from the Author-Email field. + AuthorEmail string `json:"authorEmail" mapstructure:"AuthorEmail"` + // Platform indicates the target platform for the package (e.g., "any", "linux", "win32"). + Platform string `json:"platform" mapstructure:"Platform"` + // Files are the installed files listed in the RECORD file for wheels or installed-files.txt for eggs. + Files []PythonFileRecord `json:"files,omitempty"` + // SitePackagesRootPath is the root directory path containing the package (e.g., "/usr/lib/python3.9/site-packages"). + SitePackagesRootPath string `json:"sitePackagesRootPath"` + // TopLevelPackages are the top-level Python module names from top_level.txt file. + TopLevelPackages []string `json:"topLevelPackages,omitempty"` + // DirectURLOrigin contains VCS or direct URL installation information from direct_url.json. + DirectURLOrigin *PythonDirectURLOriginInfo `json:"directUrlOrigin,omitempty"` + // RequiresPython specifies the Python version requirement (e.g., ">=3.6"). + RequiresPython string `json:"requiresPython,omitempty" mapstructure:"RequiresPython"` + // RequiresDist lists the package dependencies with version specifiers from Requires-Dist fields. + RequiresDist []string `json:"requiresDist,omitempty" mapstructure:"RequiresDist"` + // ProvidesExtra lists optional feature names that can be installed via extras (e.g., "dev", "test"). + ProvidesExtra []string `json:"providesExtra,omitempty" mapstructure:"ProvidesExtra"` } // PythonFileDigest represents the file metadata for a single file attributed to a python package. type PythonFileDigest struct { + // Algorithm is the hash algorithm used (e.g., "sha256"). Algorithm string `json:"algorithm"` - Value string `json:"value"` + // Value is the hex-encoded hash digest value. + Value string `json:"value"` } // PythonFileRecord represents a single entry within a RECORD file for a python wheel or egg package type PythonFileRecord struct { - Path string `json:"path"` + // Path is the installed file path from the RECORD file. + Path string `json:"path"` + // Digest contains the hash algorithm and value for file integrity verification. Digest *PythonFileDigest `json:"digest,omitempty"` - Size string `json:"size,omitempty"` + // Size is the file size in bytes as a string. + Size string `json:"size,omitempty"` } +// PythonDirectURLOriginInfo represents installation source metadata from direct_url.json for packages installed from VCS or direct URLs. type PythonDirectURLOriginInfo struct { - URL string `json:"url"` + // URL is the source URL from which the package was installed. + URL string `json:"url"` + // CommitID is the VCS commit hash if installed from version control. CommitID string `json:"commitId,omitempty"` - VCS string `json:"vcs,omitempty"` + // VCS is the version control system type (e.g., "git", "hg"). + VCS string `json:"vcs,omitempty"` } func (m PythonPackage) OwnedFiles() (result []string) { @@ -60,53 +81,84 @@ func (m PythonPackage) OwnedFiles() (result []string) { // PythonPipfileLockEntry represents a single package entry within a Pipfile.lock file. type PythonPipfileLockEntry struct { + // Hashes are the package file hash values in the format "algorithm:digest" for integrity verification. Hashes []string `mapstructure:"hashes" json:"hashes"` - Index string `mapstructure:"index" json:"index"` + // Index is the PyPI index name where the package should be fetched from. + Index string `mapstructure:"index" json:"index"` } // PythonPoetryLockEntry represents a single package entry within a Pipfile.lock file. type PythonPoetryLockEntry struct { - Index string `mapstructure:"index" json:"index"` + // Index is the package repository name where the package should be fetched from. + Index string `mapstructure:"index" json:"index"` + // Dependencies are the package's runtime dependencies with version constraints. Dependencies []PythonPoetryLockDependencyEntry `json:"dependencies"` - Extras []PythonPoetryLockExtraEntry `json:"extras,omitempty"` + // Extras are optional feature groups that include additional dependencies. + Extras []PythonPoetryLockExtraEntry `json:"extras,omitempty"` } +// PythonPoetryLockDependencyEntry represents a single dependency entry within a Poetry lock file. type PythonPoetryLockDependencyEntry struct { - Name string `json:"name"` - Version string `json:"version"` - Optional bool `json:"optional"` - Markers string `json:"markers,omitempty"` - Extras []string `json:"extras,omitempty"` + // Name is the dependency package name. + Name string `json:"name"` + // Version is the locked version or version constraint for the dependency. + Version string `json:"version"` + // Optional indicates whether this dependency is optional (only needed for certain extras). + Optional bool `json:"optional"` + // Markers are environment marker expressions that conditionally enable the dependency (e.g., "python_version >= '3.8'"). + Markers string `json:"markers,omitempty"` + // Extras are the optional feature names from the dependency that should be installed. + Extras []string `json:"extras,omitempty"` } +// PythonPoetryLockExtraEntry represents an optional feature group in a Poetry lock file. type PythonPoetryLockExtraEntry struct { - Name string `json:"name"` + // Name is the optional feature name (e.g., "dev", "test"). + Name string `json:"name"` + // Dependencies are the package names required when this extra is installed. Dependencies []string `json:"dependencies"` } // PythonRequirementsEntry represents a single entry within a [*-]requirements.txt file. type PythonRequirementsEntry struct { - Name string `json:"name" mapstructure:"Name"` - Extras []string `json:"extras,omitempty" mapstructure:"Extras"` - VersionConstraint string `json:"versionConstraint" mapstructure:"VersionConstraint"` - URL string `json:"url,omitempty" mapstructure:"URL"` - Markers string `json:"markers,omitempty" mapstructure:"Markers"` + // Name is the package name from the requirements file. + Name string `json:"name" mapstructure:"Name"` + // Extras are the optional features to install from the package (e.g., package[dev,test]). + Extras []string `json:"extras,omitempty" mapstructure:"Extras"` + // VersionConstraint specifies version requirements (e.g., ">=1.0,<2.0"). + VersionConstraint string `json:"versionConstraint" mapstructure:"VersionConstraint"` + // URL is the direct download URL or VCS URL if specified instead of a PyPI package. + URL string `json:"url,omitempty" mapstructure:"URL"` + // Markers are environment marker expressions for conditional installation (e.g., "python_version >= '3.8'"). + Markers string `json:"markers,omitempty" mapstructure:"Markers"` } +// PythonUvLockDependencyEntry represents a single dependency entry within a uv lock file. type PythonUvLockDependencyEntry struct { - Name string `json:"name"` - Optional bool `json:"optional"` - Markers string `json:"markers,omitempty"` - Extras []string `json:"extras,omitempty"` + // Name is the dependency package name. + Name string `json:"name"` + // Optional indicates whether this dependency is optional (only needed for certain extras). + Optional bool `json:"optional"` + // Markers are environment marker expressions that conditionally enable the dependency (e.g., "python_version >= '3.8'"). + Markers string `json:"markers,omitempty"` + // Extras are the optional feature names from the dependency that should be installed. + Extras []string `json:"extras,omitempty"` } +// PythonUvLockExtraEntry represents an optional feature group in a uv lock file. type PythonUvLockExtraEntry struct { - Name string `json:"name"` + // Name is the optional feature name (e.g., "dev", "test"). + Name string `json:"name"` + // Dependencies are the package names required when this extra is installed. Dependencies []string `json:"dependencies"` } +// PythonUvLockEntry represents a single package entry within a uv.lock file. type PythonUvLockEntry struct { - Index string `mapstructure:"index" json:"index"` + // Index is the package repository name where the package should be fetched from. + Index string `mapstructure:"index" json:"index"` + // Dependencies are the package's runtime dependencies with version constraints. Dependencies []PythonUvLockDependencyEntry `json:"dependencies"` - Extras []PythonUvLockExtraEntry `json:"extras,omitempty"` + // Extras are optional feature groups that include additional dependencies. + Extras []PythonUvLockExtraEntry `json:"extras,omitempty"` } diff --git a/syft/pkg/r.go b/syft/pkg/r.go index c10c11d0e..04563406e 100644 --- a/syft/pkg/r.go +++ b/syft/pkg/r.go @@ -1,23 +1,44 @@ package pkg -type RDescription struct { - /* - Fields chosen by: - docker run --rm -it rocker/r-ver bash - $ install2.r ggplot2 # has a lot of dependencies - $ find /usr/local/lib/R -name DESCRIPTION | xargs cat | grep -v '^\s' | cut -d ':' -f 1 | sort | uniq -c | sort -nr +// Fields chosen by: +// docker run --rm -it rocker/r-ver bash +// $ install2.r ggplot2 # has a lot of dependencies +// $ find /usr/local/lib/R -name DESCRIPTION | xargs cat | grep -v '^\s' | cut -d ':' -f 1 | sort | uniq -c | sort -nr +// +// For more information on the DESCRIPTION file see https://r-pkgs.org/description.html - For more information on the DESCRIPTION file see https://r-pkgs.org/description.html - */ - Title string `json:"title,omitempty"` - Description string `json:"description,omitempty"` - Author string `json:"author,omitempty"` - Maintainer string `json:"maintainer,omitempty"` - URL []string `json:"url,omitempty"` - Repository string `json:"repository,omitempty"` - Built string `json:"built,omitempty"` - NeedsCompilation bool `json:"needsCompilation,omitempty"` - Imports []string `json:"imports,omitempty"` - Depends []string `json:"depends,omitempty"` - Suggests []string `json:"suggests,omitempty"` +// RDescription represents metadata from an R package DESCRIPTION file containing package information, dependencies, and author details. +type RDescription struct { + // Title is short one-line package title + Title string `json:"title,omitempty"` + + // Description is detailed package description + Description string `json:"description,omitempty"` + + // Author is package author(s) + Author string `json:"author,omitempty"` + + // Maintainer is current package maintainer + Maintainer string `json:"maintainer,omitempty"` + + // URL is the list of related URLs + URL []string `json:"url,omitempty"` + + // Repository is CRAN or other repository name + Repository string `json:"repository,omitempty"` + + // Built is R version and platform this was built with + Built string `json:"built,omitempty"` + + // NeedsCompilation is whether this package requires compilation + NeedsCompilation bool `json:"needsCompilation,omitempty"` + + // Imports are the packages imported in the NAMESPACE + Imports []string `json:"imports,omitempty"` + + // Depends are the packages this package depends on + Depends []string `json:"depends,omitempty"` + + // Suggests are the optional packages that extend functionality + Suggests []string `json:"suggests,omitempty"` } diff --git a/syft/pkg/rockspec.go b/syft/pkg/rockspec.go index 05ca74f7c..05ae5d2ed 100644 --- a/syft/pkg/rockspec.go +++ b/syft/pkg/rockspec.go @@ -1,11 +1,25 @@ package pkg +// LuaRocksPackage represents a Lua package managed by the LuaRocks package manager with metadata from .rockspec files. type LuaRocksPackage struct { - Name string `json:"name"` - Version string `json:"version"` - License string `json:"license"` - Homepage string `json:"homepage"` - Description string `json:"description"` - URL string `json:"url"` + // Name is the package name as found in the .rockspec file + Name string `json:"name"` + + // Version is the package version as found in the .rockspec file + Version string `json:"version"` + + // License is license identifier + License string `json:"license"` + + // Homepage is project homepage URL + Homepage string `json:"homepage"` + + // Description is a human-readable package description + Description string `json:"description"` + + // URL is the source download URL + URL string `json:"url"` + + // Dependencies are the map of dependency names to version constraints Dependencies map[string]string `json:"dependencies"` } diff --git a/syft/pkg/rpm.go b/syft/pkg/rpm.go index 14669666e..3e8b67ba1 100644 --- a/syft/pkg/rpm.go +++ b/syft/pkg/rpm.go @@ -22,31 +22,64 @@ const RpmManifestGlob = "**/var/lib/rpmmanifest/container-manifest-2" var _ FileOwner = (*RpmDBEntry)(nil) -// RpmArchive represents all captured data from a RPM package archive. +// RpmArchive represents package metadata extracted directly from a .rpm archive file, containing the same information as an RPM database entry. type RpmArchive RpmDBEntry // RpmDBEntry represents all captured data from a RPM DB package entry. type RpmDBEntry struct { - Name string `json:"name"` - Version string `json:"version"` - Epoch *int `json:"epoch" cyclonedx:"epoch" jsonschema:"nullable"` - Arch string `json:"architecture"` - Release string `json:"release" cyclonedx:"release"` - SourceRpm string `json:"sourceRpm" cyclonedx:"sourceRpm"` - Signatures []RpmSignature `json:"signatures,omitempty" cyclonedx:"signatures"` - Size int `json:"size" cyclonedx:"size"` - Vendor string `json:"vendor"` - ModularityLabel *string `json:"modularityLabel,omitempty" cyclonedx:"modularityLabel"` - Provides []string `json:"provides,omitempty"` - Requires []string `json:"requires,omitempty"` - Files []RpmFileRecord `json:"files"` + // Name is the RPM package name as found in the RPM database. + Name string `json:"name"` + + // Version is the upstream version of the package. + Version string `json:"version"` + + // Epoch is the version epoch used to force upgrade ordering (null if not set). + Epoch *int `json:"epoch" cyclonedx:"epoch" jsonschema:"nullable"` + + // Arch is the target CPU architecture (e.g., "x86_64", "aarch64", "noarch"). + Arch string `json:"architecture"` + + // Release is the package release number or distribution-specific version suffix. + Release string `json:"release" cyclonedx:"release"` + + // SourceRpm is the source RPM filename that was used to build this package. + SourceRpm string `json:"sourceRpm" cyclonedx:"sourceRpm"` + + // Signatures contains GPG signature metadata for package verification. + Signatures []RpmSignature `json:"signatures,omitempty" cyclonedx:"signatures"` + + // Size is the total installed size of the package in bytes. + Size int `json:"size" cyclonedx:"size"` + + // Vendor is the organization that packaged the software. + Vendor string `json:"vendor"` + + // ModularityLabel identifies the module stream for modular RPM packages (e.g., "nodejs:12:20200101"). + ModularityLabel *string `json:"modularityLabel,omitempty" cyclonedx:"modularityLabel"` + + // Provides lists the virtual packages and capabilities this package provides. + Provides []string `json:"provides,omitempty"` + + // Requires lists the dependencies required by this package. + Requires []string `json:"requires,omitempty"` + + // Files are the file records for all files owned by this package. + Files []RpmFileRecord `json:"files"` } +// RpmSignature represents a GPG signature for an RPM package used for authenticity verification. type RpmSignature struct { + // PublicKeyAlgorithm is the public key algorithm used for signing (e.g., "RSA"). PublicKeyAlgorithm string `json:"algo"` - HashAlgorithm string `json:"hash"` - Created string `json:"created"` - IssuerKeyID string `json:"issuer"` + + // HashAlgorithm is the hash algorithm used for the signature (e.g., "SHA256"). + HashAlgorithm string `json:"hash"` + + // Created is the timestamp when the signature was created. + Created string `json:"created"` + + // IssuerKeyID is the GPG key ID that created the signature. + IssuerKeyID string `json:"issuer"` } func (s RpmSignature) String() string { @@ -60,13 +93,26 @@ func (s RpmSignature) String() string { // RpmFileRecord represents the file metadata for a single file attributed to a RPM package. type RpmFileRecord struct { - Path string `json:"path"` - Mode RpmFileMode `json:"mode"` - Size int `json:"size"` - Digest file.Digest `json:"digest"` - UserName string `json:"userName"` - GroupName string `json:"groupName"` - Flags string `json:"flags"` + // Path is the absolute file path where the file is installed. + Path string `json:"path"` + + // Mode is the file permission mode bits following Unix stat.h conventions. + Mode RpmFileMode `json:"mode"` + + // Size is the file size in bytes. + Size int `json:"size"` + + // Digest contains the hash algorithm and value for file integrity verification. + Digest file.Digest `json:"digest"` + + // UserName is the owner username for the file. + UserName string `json:"userName"` + + // GroupName is the group name for the file. + GroupName string `json:"groupName"` + + // Flags indicates the file type (e.g., "%config", "%doc", "%ghost"). + Flags string `json:"flags"` } // RpmFileMode is the raw file mode for a single file. This can be interpreted as the linux stat.h mode (see https://pubs.opengroup.org/onlinepubs/007908799/xsh/sysstat.h.html) diff --git a/syft/pkg/ruby.go b/syft/pkg/ruby.go index 81280c540..a4d8db661 100644 --- a/syft/pkg/ruby.go +++ b/syft/pkg/ruby.go @@ -2,24 +2,18 @@ package pkg // RubyGemspec represents all metadata parsed from the *.gemspec file type RubyGemspec struct { - Name string `mapstructure:"name" json:"name"` + // Name is gem name as specified in the gemspec + Name string `mapstructure:"name" json:"name"` + + // Version is gem version as specified in the gemspec Version string `mapstructure:"version" json:"version"` - // note regarding if Files can contribute to GemMetadata being able to implement FileOwner: this list is a - // "logical" list of files, not a list of paths that can be used to find the files without additional processing. - // - // For example: The "bundler" gem has a file entry of: - // "lib/bundler/vendor/uri/lib/uri/ldap.rb" - // but the actual file is located at: - // "/usr/local/lib/ruby/3.2.0/bundler/vendor/uri/lib/uri/ldap.rb" - // which do not match (the "lib" prefix is missing even for relative processing). - // - // without additional information about: - // - the gem installation path - // - the ruby installation path - // - the ruby version - // - environment variables (e.g. GEM_HOME) that may affect the gem installation path - // ... we can't reliably determine the full path to the file on disk, thus cannot implement FileOwner (...yet...). - Files []string `mapstructure:"files" json:"files,omitempty"` - Authors []string `mapstructure:"authors" json:"authors,omitempty"` - Homepage string `mapstructure:"homepage" json:"homepage,omitempty"` + + // Files is logical list of files in the gem (NOT directly usable as filesystem paths. Example: bundler gem lists "lib/bundler/vendor/uri/lib/uri/ldap.rb" but actual path is "/usr/local/lib/ruby/3.2.0/bundler/vendor/uri/lib/uri/ldap.rb". Would need gem installation path, ruby version, and env vars like GEM_HOME to resolve actual paths.) + Files []string `mapstructure:"files" json:"files,omitempty"` + + // Authors are the list of gem authors (stored as array regardless of using `author` or `authors` method in gemspec) + Authors []string `mapstructure:"authors" json:"authors,omitempty"` + + // Homepage is project homepage URL + Homepage string `mapstructure:"homepage" json:"homepage,omitempty"` } diff --git a/syft/pkg/rust.go b/syft/pkg/rust.go index c06c65fe7..b37e7d848 100644 --- a/syft/pkg/rust.go +++ b/syft/pkg/rust.go @@ -1,15 +1,31 @@ package pkg +// RustCargoLockEntry represents a locked dependency from a Cargo.lock file with precise version and checksum information. type RustCargoLockEntry struct { - Name string `toml:"name" json:"name"` - Version string `toml:"version" json:"version"` - Source string `toml:"source" json:"source"` - Checksum string `toml:"checksum" json:"checksum"` + // Name is crate name as specified in Cargo.toml + Name string `toml:"name" json:"name"` + + // Version is crate version as specified in Cargo.toml + Version string `toml:"version" json:"version"` + + // Source is the source registry or repository URL in format "registry+https://github.com/rust-lang/crates.io-index" for registry packages + Source string `toml:"source" json:"source"` + + // Checksum is content checksum for registry packages only (hexadecimal string). Cargo doesn't require or include checksums for git dependencies. Used to detect MITM attacks by verifying downloaded crate matches lockfile checksum. + Checksum string `toml:"checksum" json:"checksum"` + + // Dependencies are the list of dependencies with version constraints Dependencies []string `toml:"dependencies" json:"dependencies"` } +// RustBinaryAuditEntry represents Rust crate metadata extracted from a compiled binary using cargo-auditable format. type RustBinaryAuditEntry struct { - Name string `toml:"name" json:"name"` + // Name is crate name as specified in audit section of the build binary + Name string `toml:"name" json:"name"` + + // Version is crate version as specified in audit section of the build binary Version string `toml:"version" json:"version"` - Source string `toml:"source" json:"source"` + + // Source is the source registry or repository where this crate came from + Source string `toml:"source" json:"source"` } diff --git a/syft/pkg/snap.go b/syft/pkg/snap.go index 02e5f8528..b9b421c2e 100644 --- a/syft/pkg/snap.go +++ b/syft/pkg/snap.go @@ -8,11 +8,21 @@ const ( SnapTypeSnapd = "snapd" ) +// SnapEntry represents metadata for a Snap package extracted from snap.yaml or snapcraft.yaml files. type SnapEntry struct { - SnapType string `json:"snapType" yaml:"snapType"` // base, kernel, system, gadget, snapd - Base string `json:"base" yaml:"base"` // base snap name (e.g., core20, core22) - SnapName string `json:"snapName" yaml:"snapName"` // name of the snap - SnapVersion string `json:"snapVersion" yaml:"snapVersion"` // version of the snap + // SnapType indicates the snap type (base, kernel, app, gadget, or snapd). + SnapType string `json:"snapType" yaml:"snapType"` // base, kernel, system, gadget, snapd + + // Base is the base snap name that this snap depends on (e.g., "core20", "core22"). + Base string `json:"base" yaml:"base"` // base snap name (e.g., core20, core22) + + // SnapName is the snap package name. + SnapName string `json:"snapName" yaml:"snapName"` // name of the snap + + // SnapVersion is the snap package version. + SnapVersion string `json:"snapVersion" yaml:"snapVersion"` // version of the snap + + // Architecture is the target CPU architecture (e.g., "amd64", "arm64"). Architecture string `json:"architecture" yaml:"architecture"` // architecture (amd64, arm64, etc.) } diff --git a/syft/pkg/swift.go b/syft/pkg/swift.go index 3df696c1c..7dcf0137a 100644 --- a/syft/pkg/swift.go +++ b/syft/pkg/swift.go @@ -1,5 +1,7 @@ package pkg +// SwiftPackageManagerResolvedEntry represents a resolved dependency from a Package.resolved file with its locked version and source location. type SwiftPackageManagerResolvedEntry struct { + // Revision is git commit hash of the resolved package Revision string `mapstructure:"revision" json:"revision"` } diff --git a/syft/pkg/swipl.go b/syft/pkg/swipl.go index c4e1c4a86..80a646d39 100644 --- a/syft/pkg/swipl.go +++ b/syft/pkg/swipl.go @@ -1,12 +1,28 @@ package pkg +// SwiplPackEntry represents a SWI-Prolog package from the pack system with metadata about the package and its dependencies. type SwiplPackEntry struct { - Name string `toml:"name" json:"name"` - Version string `toml:"version" json:"version"` - Author string `json:"author" mapstructure:"Author"` - AuthorEmail string `json:"authorEmail" mapstructure:"AuthorEmail"` - Packager string `json:"packager" mapstructure:"Packager"` - PackagerEmail string `json:"packagerEmail" mapstructure:"PackagerEmail"` - Homepage string `json:"homepage"` - Dependencies []string `toml:"dependencies" json:"dependencies"` + // Name is the package name as found in the .toml file + Name string `toml:"name" json:"name"` + + // Version is the package version as found in the .toml file + Version string `toml:"version" json:"version"` + + // Author is author name + Author string `json:"author" mapstructure:"Author"` + + // AuthorEmail is author email address + AuthorEmail string `json:"authorEmail" mapstructure:"AuthorEmail"` + + // Packager is packager name (if different from author) + Packager string `json:"packager" mapstructure:"Packager"` + + // PackagerEmail is packager email address + PackagerEmail string `json:"packagerEmail" mapstructure:"PackagerEmail"` + + // Homepage is project homepage URL + Homepage string `json:"homepage"` + + // Dependencies are the list of required dependencies + Dependencies []string `toml:"dependencies" json:"dependencies"` } diff --git a/syft/pkg/terraform.go b/syft/pkg/terraform.go index 30b191838..1e66f3402 100644 --- a/syft/pkg/terraform.go +++ b/syft/pkg/terraform.go @@ -2,8 +2,12 @@ package pkg // TerraformLockProviderEntry represents a single provider entry in a Terraform dependency lock file (.terraform.lock.hcl). type TerraformLockProviderEntry struct { - URL string `hcl:",label" json:"url"` - Constraints string `hcl:"constraints,optional" json:"constraints"` - Version string `hcl:"version" json:"version"` - Hashes []string `hcl:"hashes" json:"hashes"` + // URL is the provider source address (e.g., "registry.terraform.io/hashicorp/aws"). + URL string `hcl:",label" json:"url"` + // Constraints specifies the version constraints for the provider (e.g., "~> 4.0"). + Constraints string `hcl:"constraints,optional" json:"constraints"` + // Version is the locked provider version selected during terraform init. + Version string `hcl:"version" json:"version"` + // Hashes are cryptographic checksums for the provider plugin archives across different platforms. + Hashes []string `hcl:"hashes" json:"hashes"` } diff --git a/syft/pkg/wordpress.go b/syft/pkg/wordpress.go index deeb61883..fb219bd23 100644 --- a/syft/pkg/wordpress.go +++ b/syft/pkg/wordpress.go @@ -2,7 +2,12 @@ package pkg // WordpressPluginEntry represents all metadata parsed from the wordpress plugin file type WordpressPluginEntry struct { + // PluginInstallDirectory is directory name where the plugin is installed PluginInstallDirectory string `mapstructure:"pluginInstallDirectory" json:"pluginInstallDirectory"` - Author string `mapstructure:"author" json:"author,omitempty"` - AuthorURI string `mapstructure:"authorUri" json:"authorUri,omitempty"` + + // Author is plugin author name + Author string `mapstructure:"author" json:"author,omitempty"` + + // AuthorURI is author's website URL + AuthorURI string `mapstructure:"authorUri" json:"authorUri,omitempty"` }