uv-sbom 2.2.0

SBOM generation tool for uv projects - Generate CycloneDX SBOMs from uv.lock files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

use crate::ports::outbound::ProgressCallback;
use crate::sbom_generation::domain::vulnerability::PackageVulnerabilities;
use crate::sbom_generation::domain::Package;
use crate::shared::Result;
use async_trait::async_trait;

/// Port for fetching vulnerability information from external sources
///
/// This trait defines the interface for querying vulnerability databases
/// (e.g., OSV API) to check if packages have known security vulnerabilities.
///
/// # Security Considerations
/// - Implementations must not send internal/private package names to public APIs
/// - Implementations should implement rate limiting to prevent DoS
/// - Implementations should have timeout mechanisms
///
/// # Implementation Notes
/// - Use batch API calls when possible for efficiency (OSV API provides batch endpoint)
/// - Filter results to only include packages with vulnerabilities
/// - Empty result indicates no vulnerabilities found (not an error condition)
/// - All methods are async for efficient parallel vulnerability fetching
///
/// # Example
/// ```no_run
/// # use uv_sbom::ports::outbound::VulnerabilityRepository;
/// # use uv_sbom::sbom_generation::domain::Package;
/// # use async_trait::async_trait;
/// # struct MockRepo;
/// # #[async_trait]
/// # impl VulnerabilityRepository for MockRepo {
/// #     async fn fetch_vulnerabilities(
/// #         &self,
/// #         packages: Vec<Package>,
/// #     ) -> uv_sbom::shared::Result<Vec<uv_sbom::sbom_generation::domain::vulnerability::PackageVulnerabilities>> {
/// #         Ok(vec![])
/// #     }
/// # }
/// # async fn example() -> uv_sbom::shared::Result<()> {
/// # let repo = MockRepo;
/// let packages = vec![
///     Package::new("requests".to_string(), "2.31.0".to_string())?,
///     Package::new("urllib3".to_string(), "1.26.0".to_string())?,
/// ];
///
/// let vulnerabilities = repo.fetch_vulnerabilities(packages).await?;
/// // vulnerabilities contains only packages with known vulnerabilities
/// # Ok(())
/// # }
/// ```
#[async_trait]
pub trait VulnerabilityRepository: Send + Sync {
    /// Fetches vulnerability information for multiple packages
    ///
    /// # Arguments
    /// * `packages` - List of Package objects to check for vulnerabilities
    ///
    /// # Returns
    /// Vector of PackageVulnerabilities for packages that have vulnerabilities.
    /// Packages without vulnerabilities are not included in the result.
    ///
    /// # Errors
    /// Returns error if:
    /// - Network request fails
    /// - API response is invalid
    /// - Timeout occurs
    ///
    /// # Notes
    /// - Implementations should use batch API calls when possible for efficiency
    /// - Results should be filtered to only include packages with vulnerabilities
    /// - Empty result indicates no vulnerabilities found (not an error)
    ///
    /// # Performance
    /// - Batch requests are preferred over individual requests
    /// - Implementations should handle rate limiting gracefully
    /// - Timeouts should be reasonable (e.g., 30 seconds for batch requests)
    /// - Async implementation enables parallel fetching for better performance
    async fn fetch_vulnerabilities(
        &self,
        packages: Vec<Package>,
    ) -> Result<Vec<PackageVulnerabilities>>;

    /// Fetches vulnerability information with progress reporting
    ///
    /// Similar to `fetch_vulnerabilities`, but accepts a callback for progress updates.
    /// This allows the caller to display a progress indicator during the operation.
    ///
    /// # Arguments
    /// * `packages` - List of Package objects to check for vulnerabilities
    /// * `progress_callback` - Callback function that receives (current, total) progress updates
    ///
    /// # Default Implementation
    /// Calls `fetch_vulnerabilities` without progress reporting.
    /// Implementations should override this to provide progress updates.
    async fn fetch_vulnerabilities_with_progress(
        &self,
        packages: Vec<Package>,
        _progress_callback: ProgressCallback<'static>,
    ) -> Result<Vec<PackageVulnerabilities>> {
        // Default implementation: no progress reporting
        self.fetch_vulnerabilities(packages).await
    }
}

/// Dummy implementation of VulnerabilityRepository for unit type
/// This allows using Option<()> when no vulnerability checking is needed
#[async_trait]
impl VulnerabilityRepository for () {
    async fn fetch_vulnerabilities(
        &self,
        _packages: Vec<Package>,
    ) -> Result<Vec<PackageVulnerabilities>> {
        // Dummy implementation - should never be called since Option<()> will always be None
        unreachable!("VulnerabilityRepository not configured")
    }
}