README

A Composer plugin designed to mitigate Supply Chain Attacks by enforcing a "soak time" (minimum age) on all installed package versions.

Recently published packages or updates can sometimes carry malicious code (zero-days or compromised maintainer accounts). This plugin acts as a shield by completely hiding recent releases from the Composer solver, ensuring you only install mature, community-vetted code.

💡 How it works

This plugin intercepts Composer's PRE_POOL_CREATE event. It analyzes the release dates of all requested packages (including deep transitive dependencies) and drops any version that is newer than your configured threshold.

Composer will then gracefully resolve your dependencies using older, safer versions, avoiding the "dependency hell" of manual conflict resolution.

📦 Installation

Install this plugin as a development dependency:

composer require --dev innobrain/soak-time

Or install it globally to protect all your local projects:

composer global require innobrain/soak-time

⚙️ Configuration

By default, the plugin enforces a minimum age of 168 hours (7 days).

Customize this in the extra section of your project's composer.json:

{
    "extra": {
        "soak-time-hours": 360
    }
}

Overriding the Soak Time per Run

You can override the configured soak time for a single command using the SOAK_TIME_HOURS environment variable. This value is specified in hours and takes precedence over soak-time-hours in composer.json:

Linux / macOS:

SOAK_TIME_HOURS=336 composer update

Windows (PowerShell):

$env:SOAK_TIME_HOURS=336; composer update

If the value isn't a non-negative integer (for example a typo), the plugin ignores it and prints a warning rather than silently disabling protection.

Whitelisting Packages

Some packages, like security advisories or internal company packages, need to be updated constantly and should bypass the soak time filter. You can allow them permanently by adding an array of package names to soak-time-whitelist in your composer.json:

{
    "extra": {
        "soak-time-hours": 168,
        "soak-time-whitelist": [
            "roave/security-advisories",
            "your-company/internal-package"
        ]
    }
}

🚨 Emergency Bypass (Security Patches)

If you need to install a critical security patch that was released just a few hours ago, you can bypass the filter using the SOAK_TIME_SKIP environment variable:

Linux / macOS:

SOAK_TIME_SKIP=1 composer update vendor/package-name

Windows (PowerShell):

$env:SOAK_TIME_SKIP=1; composer update vendor/package-name

Note: SOAK_TIME_SKIP disables the soak-time filter for every package in the run, not only the ones named on the command line. Use it deliberately and sparingly.

🔍 Debugging

To see exactly which versions are being dropped, run Composer with the verbose flag (-v). Dropped versions are grouped per package:

composer update -v

[Soak Time] Inspecting packages (minimum age: 168h)...
  monolog/monolog — dropped 3 version(s) newer than 168h: 3.8.2, 3.8.3, 3.8.4 (newest released 2026-05-20 14:30)
[Soak Time] Filtered out 3 recent version(s) across 1 package(s).

🧩 When Resolution Fails

If the soak time hides every available version of a required package, Composer can no longer resolve your dependencies. Rather than letting it fail with a cryptic solver error, the plugin detects this and warns you up front — naming the package responsible and how new its latest version is:

[Soak Time] Every version of "vendor/package" was filtered out (newest is only 6h old; soak time is 168h).
            If Composer now fails to resolve dependencies, this is the likely cause. Options:
              - Lower the soak time:  SOAK_TIME_HOURS=6 composer update
              - Whitelist it:         add "vendor/package" to extra.soak-time-whitelist
              - Emergency bypass:     SOAK_TIME_SKIP=1 composer update

Pick whichever fix suits the package: whitelist it if it legitimately needs frequent updates, or use the emergency bypass for a one-off install. Both are described above.

🙏 Credits

This package is a fork of cotonet/soak-time by Cotonet - Resiliência Digital. Huge thanks to the original authors for building such a thoughtful defense against supply chain attacks and for releasing it as open source — this fork simply builds on their excellent work.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Copyright belongs to the original authors, Cotonet - Resiliência Digital, and to Innobrain GmbH for the changes made in this fork.

innobrain / soak-time

Maintainers

Package info

Statistics

Security