Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify package usage #79

Open
wants to merge 1 commit into
base: latest
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 24 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,31 +7,46 @@ This package ensures that your application doesn't have installed dependencies w

## Installation

Add `"roave/security-advisories": "dev-latest"` to your `composer.json` `"require-dev"` section and you will
not be able to harm yourself with software with known security vulnerabilities.

```sh
composer require --dev roave/security-advisories:dev-latest
```

## Usage

This package does not provide any API or usable classes: its only purpose is to prevent installation of software
with known and documented security issues.
Simply add `"roave/security-advisories": "dev-latest"` to your `composer.json` `"require-dev"` section and you will
not be able to harm yourself with software with known security vulnerabilities.
with known and documented security issues. It provides a continuously updated
[list of these packages](composer.json),
causing Composer to show conflicts whenever a undesirable package version is to be installed.

The checks are executed automatically when adding a new dependency via `composer require`
or when running `composer update`.

Deploying an application with a valid `composer.lock` and via `composer install` won't trigger
any security versions checking.

For example, try following:
For example, try the following:

```sh
composer require --dev roave/security-advisories:dev-latest
# following commands will fail:
# following commands will fail due to a conflict with roave/security-advisories:
composer require symfony/symfony:2.5.2
composer require zendframework/zendframework:2.3.1
```

The checks are only executed when adding a new dependency via `composer require` or when running `composer update`:
deploying an application with a valid `composer.lock` and via `composer install` won't trigger any security versions
checking.
### Manual checks
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would rather say that these are for continuous integration

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean with "these". Replace the headline "Manual checks" with "Continuous integration"?


You may manually trigger a version check only by using the `--dry-run` flag on an update.

This requires Composer version 2 however, due to a wont-fix issue in deprecated Composer 1.x.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tool also works with composer:^1 - there are limitations with it, but it has worked since forever with it?

Copy link
Author

@pixelbrackets pixelbrackets Aug 13, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See linked issue #66, the manual check with existing composer.lock does not work with Composer 1.x. It needs Composer 2.

The other commands (compose require and composer update without dry-run) work fine with Composer 1. But this section is about the dry-run.

PS: The diff is a hard to to read → this is what the rendered version of the text change looks like:
https://github.com/pixelbrackets/SecurityAdvisories/blob/20210813_add-composer-version-requirement/README.md


```sh
composer update --dry-run roave/security-advisories
```

> You can manually trigger a version check by using the `--dry-run` switch on an update while not doing anything. Running `composer update --dry-run roave/security-advisories` is an effective way to manually trigger a security version check.
Conflicts with existing packages cause Composer to return a failure exit code.

## roave/security-advisories for enterprise

Expand Down