Skip to main content
Version: v1

Dependency audit

A project carries 2 dependency trees, each audited by its own package manager: composer audit for the PHP packages and npm audit for the JavaScript packages. Both run locally and in the CI security audit workflow.

PHP dependencies​

composer audit checks the installed packages against published security advisories and reports abandoned packages.

Composer 2.10.0 introduced a unified config.policy setting that controls both security auditing (reporting known security vulnerabilities and abandoned packages) and version blocking (refusing to install or update affected packages). Vortex uses it to keep vulnerabilities visible without blocking day-to-day dependency work.

Usage​

Check your dependencies for security issues manually:

# Audit all installed packages
ahoy composer audit
# Audit only production dependencies (exclude dev)
ahoy composer audit --no-dev
# Audit packages from lock file (faster)
ahoy composer audit --locked
# Control abandoned package behavior
ahoy composer audit --abandoned=ignore  # Skip abandoned packages
ahoy composer audit --abandoned=report  # Show but don't fail

Configuration​

Configure the policy in your composer.json under the config section:

{
    "config": {
        "policy": {
            "advisories": {
                "block": false,
                "audit": "fail"
            },
            "abandoned": {
                "audit": "report"
            }
        }
    }
}

Vortex sets the following values:

  • advisories.block to false: security advisories don't block composer update, composer require, or composer remove, so dependency updates stay reproducible even when a new advisory is published upstream against an existing dependency. composer install resolves nothing from the lock file, so this setting never affects it. (Composer's own default is true.)
  • advisories.audit to fail: the composer audit command still fails when an advisory is found, keeping vulnerabilities visible locally and in CI.
  • abandoned.audit to report: abandoned packages are reported as warnings but don't fail the audit. (Composer's own default is fail.)

Each section accepts block (refuse affected versions during composer update/require/remove), audit (ignore, report, or fail for the composer audit command), and ignore/ignore-id/ignore-severity for assessed exceptions.

Composer 2.10+

config.policy requires Composer 2.10 or newer, which ships in the Vortex container images. On older Composer versions, use the legacy config.audit keys (block-insecure, abandoned) instead - they continue to work as a fallback.

Why advisories don't block dependency updates​

Coupling dependency resolution to advisory publication makes updates non-deterministic. A newly published advisory against an already-installed dependency can fail every composer update or composer require - including work unrelated to security - until the advisory is assessed and ignored. Vortex decouples resolution from advisory publication by setting advisories.block to false while keeping advisories.audit at fail. This keeps updates reproducible while composer audit and the CI security audit workflow still surface vulnerabilities.

If your project requires dependency resolution to hard-stop on advisories - for example, a production site with strict supply-chain controls - set advisories.block to true.

Ignoring​

When you've assessed an advisory and determined it doesn't affect your project, add it to the ignore-id list with a reason:

{
    "config": {
        "policy": {
            "advisories": {
                "ignore-id": {
                    "CVE-2024-1234": "Component is not used in our implementation.",
                    "GHSA-xxxx-yyyy-zzzz": "Patched via custom security fix."
                }
            }
        }
    }
}
Document your decisions

Record the reason for each ignored advisory in your Git commit message. This helps your team understand why a vulnerability was deemed acceptable and review the decision later.

Continuous integration​

Vortex runs composer audit --locked in the security audit workflow, so the audited set is exactly what composer.lock pins. Because advisories.audit is fail, the audit reports vulnerabilities and the workflow fails when any are found - even though installs and updates aren't blocked.

Ignoring failures​

Set the repository variable VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILURE to 1 to make the audit step run and report without failing that workflow - useful as a one-off bypass while a known advisory is being addressed.

➡️ See Ignore tool failures.

JavaScript dependencies​

npm audit checks the packages resolved from package-lock.json against the advisories published in the npm registry.

A project has 2 JavaScript dependency trees, each with its own package.json and lock file. The root one is for the custom modules' tooling and the test runner, and the custom theme's one is for the front-end build. They're audited separately.

Usage​

# Audit the root packages
ahoy cli "npm audit"
# Audit the theme packages
ahoy cli "npm audit --prefix=\${WEBROOT}/themes/custom/\${DRUPAL_THEME}"
# Audit from the lock file, without an installed tree
ahoy cli "npm audit --package-lock-only"

Severity threshold​

npm fails the audit on any advisory by default. A development dependency tree of this size carries low-severity advisories in transitive packages at most times, which would block every build, so Vortex raises the floor to high in .npmrc:

audit-level=high

npm reads the project configuration from the directory of the package.json it audits, so both .npmrc files carry the setting - one in the project root and one in the custom theme. The accepted values are info, low, moderate, high, critical, and none; lower the value to widen what fails the build.

The threshold is deliberately not a Vortex variable: it belongs to npm's own configuration, where a project changes it without a template variable existing for it.

Ignoring​

npm audit has no per-advisory ignore list, so an advisory is excluded by removing the affected version from the tree. When the advisory is in a transitive dependency and a patched version exists, pin it with an overrides entry in package.json:

{
    "overrides": {
        "vulnerable-package": "^2.1.4"
    }
}

npm then resolves every dependent to the pinned version. Run npm install to update the lock file, and commit both files.

Document your decisions

Record the advisory that each overrides entry addresses in your Git commit message, the same as for the Composer exceptions described earlier.

Continuous integration​

Vortex runs npm audit --package-lock-only in the security audit workflow for both dependency trees, so the audited set is exactly what the lock files pin and no installed tree is needed.

Ignoring failures​

Set the repository variable VORTEX_CI_NPM_AUDIT_IGNORE_FAILURE to 1 to make both audit steps run and report without failing that workflow - useful as a one-off bypass while a known advisory is being addressed. The finding is still printed, so a tolerated advisory stays visible in the job log.

➡️ See Ignore tool failures.