Only consider packages uploaded prior to the given value. Accepts an ISO 8601 datetime (e.g., ‘2023-01-01T00:00:00Z’, uses local timezone if none specified) or a duration in days (e.g., ‘P3D’ for packages uploaded at least 3 days ago). Only effective when using indexes that provide upload-time metadata.
(environment variable: PIP_UPLOADED_PRIOR_TO)
It unclear what syntax convention it’s using. It would be clearer to add more examples that also is good security practice (2 weeks, 1 month).
I could contribute an update if someone points me to the syntax reference.
It’s obvious to me that it’s a subset of ISO 8601 durations. 2 weeks and 1 month would be around P45D. Over 1 week tends to be an overly long time for a cooldown.
The default suggestion of P3D is pretty good considering recent supply-chain attacks. While it might seem that longer is safer, there are many issues which come from being late to receive updates. The ideal would be to have a short (1 day) cooldown be default for all installs, then opt-in to longer or shorter durations based on the project and situation such as how uv lets one setup separate cooldowns for each dependency.
I’d suggest setting the PIP_UPLOADED_PRIOR_TO environment variable to either P1D, P3D, or P7D.
Anecdotally, I haven’t read many opinions that recommends a few days, the ones I’ve seen around supply chain attack articles (e.g., HackerNews) seem to tout a few weeks.
Furthermore, for slow churning apps in production, you aren’t redeploying your app multiple times a week.
Anecdotally, I haven’t read many opinions that recommends a few days, the ones I’ve seen around supply chain attack articles (e.g., HackerNews) seem to tout a few weeks.
I get my advice from articles discussing “dependency cooldowns” since these compare uploaded-prior-to to similar features in other languages. The pervasive exploitation of supply-chain attacks is new but these attacks were already a known problem resolved in other languages. After this onslaught of new attacks we now have a decent picture of what these attacks look like and how long they last.
Furthermore, for slow churning apps in production, you aren’t redeploying your app multiple times a week.
Some libraries need to keep up with changes and deprecations in dependencies, but apps can use a lockfile and only update dependencies for critical reasons. Malicious upstream changes which are undetected for a week could remain undetected for months so one solution for that is to never update dependencies at all unless necessary to do so.
Lockfiles and cooldowns are used together to keep these projects secure.
The first source used 7 days and then claims 14 days would’ve prevented more attacks.
The second article didn’t make a prescriptive recommendation but rather chose 1-3 days to match its small sample of three cases.
My interpretation is then, you should balance security with being up to date with features. Both would agree that something is better than nothing. With that I am still more comfortable recommending weeks over days.
FYI, this category is for Python documentation (the language and CPython implementation) , pip is an independent project: GitHub - pypa/pip: The Python package installer · GitHub, and so don’t expect pip maintainers like myself to be looking here.
I wrote that documentation, but the points have mostly been covered here, a couple of bits of context:
It’s very dependent per project as it’s a balance between avoiding supply chain attacks and being up to date on dependencies which may have security issues you want to patch. Anticipating users having issues with this I originally proposed 1 day, the PSF’s Security Developer-in-Residence suggested 7 days, and we came to a compromise of 3 days. But for you the correct answer might be 365 days, I’m not going to object.
P<n>D is indeed a subset of ISO 8601 duration syntax, but I didn’t want to make any claims as the simpler we could keep it the better, uv supports the same syntax with it’s --exclude-newer option.