Vulnerability information

Sürüm 6.7'den başlayarak NuGet istemcisi, geri yükleme işlemleri sırasında paketleri denetleme gibi senaryolarda kullanmak üzere bilinen paket güvenlik açığı bilgilerini indirebilir. Paket meta veri kaynağı bilinen güvenlik açığı bilgilerini de içerir ancak bir uygulamanın bilinen güvenlik açıkları için çok sayıda paketi denetlemesi gerekiyorsa, çok sayıda HTTP isteği yapmak yerine bilinen güvenlik açıklarından oluşan bir dosyayı indirmek ve yerel olarak aramak çok daha hızlıdır. Örneğin bu, NuGet Geri Yükleme'nin bilinen güvenlik açıkları için geri yüklenen paketleri hızla denetlemesine olanak tanır ve bu da paket meta veri kaynağından paket ayrıntılarını hiçbir zaman indirmez.

API en az iki dosyadan oluşur: güvenlik açığı dizini ve bir veya daha fazla güvenlik açığı sayfası dosyası. Bilinen güvenlik açığı verileri birden çok dosyaya bölümlenebilir ve güvenlik açığı dizini istemcilere dosyaları önbelleğe almak ve önbelleği verimli bir şekilde güncelleştirmek için gereken bilgileri sağlar.

Bu URL'yi oluşturmak için kullanılan kaynak, VulnerabilityInfobulunan kaynağıdır.

Önerilen bölümleme stratejisi

Güvenlik açığı dizininde listelenen sayfalar ideal olarak önbelleğe almayı en üst düzeye çıkarmak ve dolayısıyla büyük dosyalara yönelik güncelleştirmeleri en aza indirmek için iyileştirilmelidir. Bu, istemcilerin güncelleştirmeleri indirmek için ihtiyaç duyduğu sıklığı en aza indirmesine olanak tanır.

Güvenlik açığı verilerini bölümleme için önerilen bir strateji, base.json ve updates.jsonolmak üzere iki sayfaya sahip olmaktır. Dosya base.json düzenli aralıklarla (örneğin ayda bir kez) güncelleştirilir ve dosya yeniden oluşturulurken bilinen tüm güvenlik açıklarını içerir. Dosya, updates.json en son yeniden oluşturulduktan sonra base.json yayımlanan yeni önerileri içermelidir. Bu, istemcilerin büyük base.json dosyaları seyrek indirmesine olanak tanırken, sık değişen updates.json dosya her zaman nispeten küçüktür.

NuGet istemcileri birden çok dosyadaki verileri ek olarak birleştirir ve dosyaları herhangi bir sırada yükleyebilir. Veri dosyası şeması, bilinen güvenlik açığının başka bir dosyadan değiştirilmesine veya yeniden düzenlenmesine izin vermez. Bu nedenle, bir sunucunun güvenlik açığı veri kaynağı (örneğin GitHub Danışmanları Veritabanı) mevcut bir öneriyi değiştirirse, NuGet sunucusunun güvenlik açığı bilgilerinin daha önce bildirildiği sayfayı değiştirmesi gerekir. Önerilen bölüm düzeniyle bunu başarma yollarından biri, tüm güvenlik açığı değişikliklerini ve silme işlemlerini dosyanın tamamını base.json yeniden oluşturmak ve boş updates.jsonbir tetikleyici olarak işlemektir.

Nuget.org'un güvenlik açığı verilerini kendi NuGet sunucu uygulamanızda kullanmayı planlıyorsanız, nuget.org doğrudan erişimi olmayan geliştiricileri dikkate almanız gerekir. Daha fazla ayrıntı için uygulama kılavuzumuza bakın.

Versioning

Aşağıdaki @type değerleri kullanılır:

@type değer	Notes
VulnerabilityInfo/6.7.0	İlk sürüm

Vulnerability index

Güvenlik açığı dizini, aşağıdaki özelliklere sahip bir JSON nesne dizisidir:

Name	Type	Required	Notes
@name	string	yes	Önbellek anahtarı olarak kullanılan dosya için kısa bir ad.
@id	string	yes	Güvenlik açığı veri dosyasının tam (mutlak) URL'si.
@updated	string	yes	Dosyanın en son güncelleştirilen tarih ve saati temsil eden iso 8601 dizesi ideal olarak UTC saat dilimiyle.
comment	string	no	İsteğe bağlı açıklayıcı bir dize.

Aşağıdaki kısıtlamalar geçerlidir:

• Dizin, 1 ile 16 arasında öğe içeren bir nesne dizisi olmalıdır. Sunucuda herhangi bir güvenlik açığı verisi (sıfır sayfa) yoksa kaynağı öğesinden ServiceIndexkaldırması VulnerabilityInfo gerekir.
• @namedizin içinde benzersiz olmalı, 1 ile 32 karakter uzunluğunda olmalıdır ve yalnızca , için , az0 ile 9, -veya _karakterlerini AZkullanabilir.
• @id göreli URL değil mutlak bir URL olmalıdır.

Vulnerability page

Güvenlik açığı sayfa dosyaları, sözlük olarak kullanılan bir JSON nesnesidir. Özellik anahtarları küçük harf paket kimliğidir ve özellik değerleri aşağıdaki özelliklere sahip aşağıdaki nesnenin bir dizisidir:

Name	Type	Required	Notes
severity	integer	yes	0 düşük, 1 orta, 2 yüksek, 3 kritik anlamına gelir.
url	string	yes	Kullanıcıların güvenlik açığı hakkında daha fazla bilgi edinebileceği URL.
versions	string	yes	NuGet'in sürüm aralığı söz dizimi kullanılarak güvenlik açığı bulunan sürüm aralığı.

Paket kimlikleri (kök nesnenin anahtarları) ile String.ToLowerInvariantküçük harfe dönüştürülmelidir.

Bir paket için bilinen güvenlik açıkları listesi, sürüm aralığının en yüksek sürümünün azalan düzeninde sıralanmalı, ardından en düşük sürümün azalan sürümü ve ardından URL'nin artan düzeni sıralanmalıdır. Bir sürüm aralığında null min veya max sürümleri (sınırsız) olan aralıklar null olmayan (sınırlanmış) sürümlerden önceye sıralanmalıdır.

Bilinen güvenlik açıkları sağlamayan boş bir sayfa boş bir JSON dizisi ([] olmalıdır).

Samples

Güvenlik açığı dizini örneği aşağıda verilmiştir:

[
    {
        "@name": "base",
        "@id": "https://nuget.contoso.com/v3/vulnerabilities/3bb6b300-2f74-45bc-af06-746fd21c024b.json",
        "@updated": "2023-06-01T06:14:58.4159909Z",
        "comment": "The base data for vulnerability update periodically"
    },
    {
        "@name": "update",
        "@id": "https://nuget.contoso.com/v3/vulnerabilities/ffd572cd-33f3-4372-8714-a9cab2e86b45.json",
        "@updated": "2023-06-14T11:35:30.3155764Z",
        "comment": "The patch data for the vulnerability. Contains all the vulnerabilities since base was last updated."
    }
]

Güvenlik açığı veri dosyası örneği aşağıda verilmiştir:

{
    "contoso.library": [
        {
            "url": "https://cve.contoso.com/advisories/1",
            "severity": 1,
            "versions": "(, 2.0.0)"
        },
        {
            "url": "https://cve.contoso.com/advisories/2",
            "severity": 2,
            "versions": "(1.0.0, 2.0.0)"
        }
    ],
    "contoso.utilities": [
        {
            "url": "https://cve.contoso.com/advisories/3",
            "severity": 3,
            "versions": "(, 1.0.0)"
        }
    ]
}